企业官网建设流程全解析

1. 项目概述：构建你的首个本地AI智能体团队

如果你对AI智能体（Agent）的概念着迷，特别是那些能够自主协作、像一个小型团队一样工作的智能体，但又被复杂的部署和协调工作劝退，那么这个项目正是为你准备的。onizuka-openclaw-autonomous-team-starter是一个为 Windows 环境量身打造的“开箱即用”式启动套件，它基于 OpenClaw 和 Podman，让你能在自己的电脑上快速搭建并运行一个由多个 AI 智能体组成的、具备基本自主协作能力的本地团队。想象一下，你不再是与一个单一的 AI 对话，而是拥有了一个分工明确、可以内部讨论、甚至能通过聊天室向你汇报工作的小型“数字团队”。这个项目将复杂的容器编排、智能体身份定义和团队通信机制打包成了一套清晰的脚本和配置，让开发者、研究者和技术爱好者能够跳过繁琐的底层搭建，直接进入探索多智能体协作的奇妙世界。

项目的核心价值在于其“一体化”和“可复现”的设计。它不仅仅是将 OpenClaw 和 Podman 简单组合，而是精心设计了一套从智能体个体创建（包括独立的工作空间和人格文件）、到团队通信基础设施（内置 Mattermost 聊天室）、再到自动化运行和监控的完整工作流。无论你是想研究多智能体系统的交互模式，还是希望构建一个能够处理复杂、多步骤任务的自动化助手集群，这个项目都提供了一个坚实且易于上手的起点。它特别适合那些熟悉 Windows 开发环境，希望利用本地大语言模型（如通过 Ollama 运行的 Gemma 或 GLM）来构建私有、可控的 AI 应用场景的用户。

2. 核心架构与设计理念拆解

2.1 为什么选择 Podman 与“一智能体一容器”模式？

在容器化技术中，Docker 广为人知，但 Podman 以其无需守护进程（daemonless）、更好的安全性和与 Kubernetes 原生兼容的pod概念而受到青睐。本项目选择 Podman 的kube play功能，正是看中了其通过标准的 Kubernetes Pod YAML 文件来定义和运行容器组的能力。这带来了几个关键优势：

隔离性与可管理性：采用“一智能体一容器（Pod）”的模式，意味着每个 AI 智能体都运行在完全独立的沙箱环境中。它们拥有各自独立的文件系统、环境变量、端口映射和依赖库。这种隔离确保了智能体之间不会相互干扰，例如，一个智能体的崩溃或异常行为不会影响其他智能体。同时，这也使得对单个智能体的调试、日志查看和资源限制变得非常清晰和直接。

配置即代码：每个智能体的运行环境（包括 OpenClaw 的配置openclaw.json、容器定义pod.yaml和环境变量文件control.env）都以文件形式存储在.openclaw/instances/<agent_id>/目录下。这种设计使得智能体的整个运行状态是可版本控制、可复现的。你可以轻松地备份、迁移或复制一个智能体的配置来创建新的实例。

Windows 友好性：项目明确针对 Windows 环境优化。Podman 在 Windows 上通常通过 WSL2 后端运行，项目中的脚本（如doctor.ps1）会处理 Windows 主机与 Podman 容器网络之间的特殊地址解析问题（例如，将host.containers.internal自动转换为实际的网关 IP，如172.27.208.1），这省去了用户手动配置网络的麻烦。

2.2 人格脚手架：赋予智能体“灵魂”与“角色”

一个只会调用 API 的 AI 模型并不能称为“智能体”。智能体的核心在于其能够根据预设的“人格”（Persona）和“目标”（Goal）进行自主决策和行动。本项目通过一套精心设计的“人格脚手架”文件，系统地定义了每个智能体的个性、职责和行为模式。

这些文件位于每个智能体的workspace/目录下，是智能体自我认知和行为的蓝图：

• SOUL.md：定义了智能体的核心性格、沟通风格和协作倾向。例如，是严谨细致型，还是创意发散型？是主动推进型，还是稳健支持型？这决定了智能体在团队对话中的“语气”。
• IDENTITY.md：明确了智能体的职能角色、头衔和在团队中的定位。例如，“系统部署负责人”、“文档构建专家”或“质量验证哨兵”。这直接关联到智能体被分配的任务类型。
• USER.md：描述了智能体所服务的“用户”画像。这有助于智能体从正确的视角理解任务和生成内容，确保其输出对最终用户是有用的。
• HEARTBEAT.md：这是自主性的关键。它定义了智能体在每次“心跳”（定期触发的自检循环）中应该执行哪些例行检查或动作。例如，“检查 Mattermost 频道是否有新消息需要处理”。
• TOOLS.md与BOOTSTRAP.md：前者是智能体可用的工具和命令速查表，后者是智能体首次启动时的自我引导指令，帮助它熟悉环境和初始化状态。
• AGENTS.md：定义了智能体之间的协作规则和协议，是团队的“宪法”。

实操心得：不要将这些脚手架文件视为一次性模板。它们是活的文档。在实际运行中，你应该根据智能体在任务中表现出的倾向，回头迭代修改这些文件。例如，如果你发现某个智能体在代码审查时过于严苛，可以调整其SOUL.md中的“严谨度”描述，或在其IDENTITY.md中增加“平衡风险与效率”的职责。这种“调参”过程，是塑造高效 AI 团队的核心工作。

2.3 内置通信实验室：Mattermost 的价值

多智能体系统的核心挑战之一是协调与通信。项目内置了 Mattermost（一个开源的、Slack 风格的企业协作平台）作为团队的“指挥中心”或“公共休息室”。这并非锦上添花，而是实现真正“团队”协作的基础设施。

集中化的交互界面：所有智能体（以及你作为人类操作员）都加入同一个 Mattermost 频道（默认是openclaw:triad-lab）。你可以通过@提及的方式直接向特定智能体下达指令，智能体之间也可以通过发帖和回复进行讨论。这提供了一个统一、可审计的交互日志，远比查看分散的容器日志直观。

实现自主协作的触发器：HEARTBEAT.md与 Mattermost 的结合，是实现智能体自主性的技术关键。当启用“休息室（lounge）自治”模式后，每个智能体在心跳周期内，会主动调用scripts/mattermost_tools/下的工具脚本，去检查 Mattermost 频道状态。例如，检查是否有未被回复的提问、是否需要跟进某个任务线程，然后执行一个“帮助动作”（如回复消息、添加反应）。这就模拟了一个团队在无人直接指令时，仍能基于上下文进行有限度协作的场景。

烟测试与集成验证：项目提供的mattermost.ps1 smoke命令，本质上是一个端到端的集成测试。它验证了从智能体启动、登录 Mattermost、接收消息到回复消息的整个链条是否畅通。这对于确保整个系统基础功能正常至关重要。

3. 从零开始：详细部署与配置指南

3.1 前期环境准备与依赖安装

在运行任何脚本之前，我们需要一个干净、可用的基础环境。以下是基于 Windows 11 的详细步骤：

1. 安装 WSL2 与 Podman：

   • 确保已启用 Windows 的“适用于 Linux 的 Windows 子系统”功能，并安装一个 Linux 发行版（如 Ubuntu）。
   • 访问 Podman Desktop 官网或使用 Winget 命令winget install RedHat.Podman-Desktop进行安装。Podman Desktop 会自动配置 WSL2 后端。
   • 安装完成后，打开 PowerShell，运行podman version和podman machine list来验证安装。你应该能看到一个名为podman-machine-default的虚拟机正在运行。

2. 安装 Ollama（如需使用本地模型）：

   • 从 Ollama 官网下载 Windows 安装包。安装后，Ollama 会作为服务运行。
   • 在 PowerShell 中，运行ollama run gemma4:e2b来拉取并测试一个较小的模型。这将验证 Ollama 服务是否正常。记住 Ollama 服务的地址，通常是http://localhost:11434，但在 Podman 容器内部，需要通过特殊的主机地址访问。

3. 安装 Python 与 UV：

   • 建议使用 Python 3.11 或更高版本。你可以从微软商店安装 Python，或使用官方安装包。
   • UV 是一个极快的 Python 包安装器和解析器。通过 PowerShell 安装：pip install uv。
   • 验证安装：uv --version。

4. 克隆项目仓库：

   # 选择一个合适的工作目录，例如 D:\Prj\ cd D:\Prj\ git clone https://github.com/Sunwood-ai-labs/onizuka-openclaw-autonomous-team-starter.git cd onizuka-openclaw-autonomous-team-starter

3.2 核心配置文件详解与定制

项目的配置主要通过.env文件和环境变量完成。理解每个配置项的作用是成功部署的关键。

1. 初始化环境文件：

   # 复制示例配置文件 Copy-Item .env.example .env # 用你喜欢的编辑器打开并编辑 notepad .env

2. 关键配置项解析：

   • OPENCLAW_OLLAMA_BASE_URL：这是容器内部访问 Ollama 服务的地址。在 Windows + WSL2 的 Podman 环境下，容器无法直接通过localhost访问主机服务。项目默认使用host.containers.internal，这是一个由 Podman 提供的特殊域名，通常能解析到主机。如果遇到连接问题，scripts\doctor.ps1脚本会尝试检测并给出正确的 IP（如172.27.208.1）。最稳妥的做法是运行一次doctor.ps1，看它提示的可达地址是什么，然后手动修改.env文件。
   • OPENCLAW_MODEL：指定默认使用的模型。例如ollama/gemma4:e2b。确保 Ollama 中已经拉取了对应的模型。
   • OPENCLAW_MATTERMOST_BOT_TOKEN等：这些是在初始化 Mattermost 后，为每个机器人账号生成的令牌。在首次运行mattermost.ps1 init和seed后，这些值会被自动填入.env文件。注意：不要预先填写这些值，它们应由初始化流程生成。
   • ZAI_API_KEY：如果你计划使用智谱 AI（Z.AI）的在线模型zai/glm-5-turbo，需要在此处填写你的 API 密钥。否则，可以留空。

   注意事项：.env文件包含敏感信息（如 API 密钥、令牌），务必将其添加到.gitignore中，避免意外提交到版本库。项目本身的.gitignore已经排除了.env文件。

3.3 逐步构建你的三人AI团队

现在，让我们按照逻辑顺序，一步步启动一个完整的三人团队。

第一步：初始化智能体实例与人格脚手架

# 同步 Python 项目依赖 uv sync # 初始化三个智能体的配置和工作空间 .\scripts\init.ps1 --count 3

这个命令执行了以下关键操作：

• 在.openclaw/instances/下创建agent_1,agent_2,agent_3三个目录。
• 为每个智能体生成独立的openclaw.json（主配置）、pod.yaml（容器定义）和control.env。
• 在每个智能体的workspace/目录下，从模板创建全套人格脚手架文件（SOUL.md,IDENTITY.md等）。
• 为三个智能体预设了不同的角色（系统负责人、构建专家、验证哨兵）和日文代号（いおり、つむぎ、さく）。

第二步：运行环境健康检查

.\scripts\doctor.ps1

务必认真查看此命令的输出！它会检查：

• Podman 是否可用。
• .env文件中的 Ollama 地址是否可访问。
• 必要的端口是否被占用。
• 项目目录结构是否完整。
• 任何检查失败都会给出明确的错误信息，这是排查问题的第一道关口。

第三步：启动 Mattermost 通信实验室

# 初始化 Mattermost 的 Pod 配置和数据卷 .\scripts\mattermost.ps1 init # 启动 Mattermost 容器 .\scripts\mattermost.ps1 launch # 为三个智能体创建对应的 Mattermost 机器人账号和令牌，并让它们加入默认频道 .\scripts\mattermost.ps1 seed --count 3

执行后，你可以打开浏览器访问http://127.0.0.1:8065，使用默认管理员账号（在mattermost.ps1 init输出中查看）登录，就能看到名为openclaw:triad-lab的频道，以及三个机器人用户。

第四步：启动 AI 智能体团队

# 使用 --dry-run 先预览将要执行的 Podman 命令 .\scripts\launch.ps1 --count 3 --dry-run # 确认无误后，实际启动三个智能体 Pod .\scripts\launch.ps1 --count 3

此时，Podman 会创建三个独立的 Pod，每个 Pod 内运行一个 OpenClaw 容器。你可以通过.\scripts\status.ps1 --count 3查看它们的状态和映射的端口（例如127.0.0.1:18789, 18791, 18793）。

第五步：进行端到端通信测试

.\scripts\mattermost.ps1 smoke --count 3

这个“烟测试”脚本会模拟一个完整流程：通过 Mattermost API 在频道里 @ 提及三个机器人，然后检查每个智能体的 OpenClaw 日志，确认它们是否收到了消息并做出了响应。这是验证“智能体-通信平台-智能体”回路是否打通的关键一步。

至此，一个具备基本通信能力的本地 AI 智能体团队就已经在后台运行了。你可以随时在 Mattermost 的triad-lab频道里 @ 它们中的任何一个下达指令。

4. 深入操作：管理、监控与高级功能

4.1 智能体团队的日常运维命令

一旦团队运行起来，你需要一套工具来管理其生命周期。

• 查看状态：.\scripts\status.ps1 --count 3会以表格形式列出所有实例的 ID、名称、状态、创建时间和端口映射，一目了然。
• 跟踪日志：.\scripts\logs.ps1 --instance 2 -Follow会实时流式输出第二个智能体容器的日志。-Follow参数类似于tail -f，对于调试和观察智能体行为至关重要。你可以看到 OpenClaw 的心跳执行、工具调用以及和 Mattermost 交互的详细信息。
• 停止与清理：

  # 停止运行但不删除容器（可重新启动） .\scripts\stop.ps1 --count 3 # 停止并彻底删除容器和 Pod .\scripts\stop.ps1 --count 3 --remove

• 环境变量检查：.\scripts\print-env.ps1 --instance 1可以打印出指定智能体运行时实际加载的环境变量，对于确认配置是否正确注入非常有用。

4.2 启用自主心跳协作

默认情况下，智能体只会在被 @ 提及时才在 Mattermost 中响应。要解锁其“自主性”，需要启用休息室（lounge）自治模式。

# 为所有智能体启用自治模式 .\scripts\mattermost.ps1 lounge enable --count 3 # 检查各智能体的自治功能状态 .\scripts\mattermost.ps1 lounge status --count 3 # 手动触发一次所有智能体的立即心跳执行，并等待15秒观察结果 .\scripts\mattermost.ps1 lounge run-now --count 3 --wait-seconds 15

这个功能是如何工作的？

1. lounge enable会修改每个智能体workspace/HEARTBEAT.md文件，在其中加入检查 Mattermost 并执行“帮助动作”的指令。
2. OpenClaw 会定期（根据其配置的心跳间隔）执行HEARTBEAT.md中的指令。
3. 智能体在心跳周期内，会调用其容器内预置的工具脚本（位于/home/node/.openclaw/mattermost-tools/），去读取 Mattermost 频道的最新状态。
4. 根据预定义的逻辑（例如，“如果频道里有未回复的、非自己发出的问题，则尝试回答”），智能体可能会执行发布消息、添加表情反应等操作。
5. lounge run-now是绕过定时器，直接通过 OpenClaw 的管理 API 触发一次心跳，用于即时测试。

实操心得：自主协作是一把双刃剑。在开启前，务必在HEARTBEAT.md和AGENTS.md中设定清晰、保守的规则，避免智能体陷入无意义的对话循环或产生垃圾信息。建议先从简单的“每周总结频道活跃度”或“发现错误信息时添加⚠️表情”这类低风险任务开始。

4.3 使用 Python CLI 进行精细控制

除了 PowerShell 脚本，项目还提供了一个基于 Python 的命令行工具openclaw-podman，它通过uv run执行，功能更全，适合集成到其他自动化流程中。

# 初始化实例 uv run openclaw-podman init --count 3 # 启动实例（干跑模式） uv run openclaw-podman launch --count 3 --dry-run # 查看特定实例的环境变量 uv run openclaw-podman print-env --instance 2 # 操作 Mattermost 模块 uv run openclaw-podman mattermost seed --count 3 uv run openclaw-podman mattermost lounge enable --count 3

Python CLI 的参数与 PowerShell 脚本基本对应，但提供了更统一的入口，并且其代码位于src/openclaw_podman_starter/下，方便有经验的用户进行二次开发或定制。

5. 故障排查与常见问题实录

即使按照步骤操作，也可能会遇到问题。以下是一些常见情况及其解决方法。

5.1 智能体容器启动失败

• 症状：launch.ps1执行后，status.ps1显示某个 Pod 状态为Error或Exited。
• 排查步骤：
  1. 查看详细日志：.\scripts\logs.ps1 --instance <编号>查看具体错误信息。
  2. 检查模型连接：最常见的错误是 OpenClaw 无法连接到 Ollama。运行.\scripts\doctor.ps1，确认它报告的 Ollama API 地址是可达的。然后检查该智能体实例目录下的openclaw.json，看其中的"baseURL"字段是否是正确的地址。务必注意：容器内使用的地址是host.containers.internal或172.xx.xx.1这种主机网关 IP，而不是localhost。
  3. 检查端口冲突：默认端口18789,18791,18793可能被其他程序占用。你可以修改scripts/目录下的相关脚本，或在生成配置后手动修改pod.yaml文件中的hostPort字段。
  4. 检查资源限制：较大的模型（如gemma4:e4b）可能需要更多内存。确保你的 WSL2 分配了足够的内存（可在%USERPROFILE%\.wslconfig中配置）。也可以在pod.yaml中为容器增加资源限制。

5.2 Mattermost 通信测试失败

• 症状：mattermost.ps1 smoke测试失败，机器人没有回复。
• 排查步骤：
  1. 确认 Mattermost 服务正常：访问http://127.0.0.1:8065能否正常登录？检查.\scripts\mattermost.ps1 status。
  2. 检查机器人令牌：确认.env文件中的OPENCLAW_MATTERMOST_BOT_TOKEN_1等令牌变量已正确生成且未被修改。令牌是在mattermost.ps1 seed时生成的。
  3. 检查智能体配置：查看智能体的openclaw.json，确认mattermost配置块中的botToken是否正确引用了环境变量（如${OPENCLAW_MATTERMOST_BOT_TOKEN_1}），以及serverUrl是否是容器网络内的地址（http://mattermost:8065）。
  4. 查看智能体日志：在运行 smoke 测试时，用logs.ps1 --instance 1 -Follow实时跟踪日志，看智能体是否收到了 Mattermost 的 Webhook 事件，以及是否尝试处理。
  5. 检查网络连通性：确保 Mattermost 容器和 OpenClaw 容器在同一个 Podman 网络（openclaw-starter）中。可以进入容器内部执行ping mattermost测试。

5.3 自主心跳（Lounge）功能不工作

• 症状：已启用lounge enable，但智能体在 Mattermost 中没有任何自主动作。
• 排查步骤：
  1. 确认 HEARTBEAT.md 已更新：进入智能体的workspace目录，检查HEARTBEAT.md文件末尾是否增加了调用 Mattermost 工具脚本的指令。
  2. 检查心跳执行日志：在 OpenClaw 的日志中搜索 “Heartbeat” 或 “mattermost_tools”，看是否有执行记录或错误信息。心跳可能因为之前的错误而处于“冷却”状态。
  3. 检查工具脚本权限：确认容器内的/home/node/.openclaw/mattermost-tools/目录下的 Python 脚本具有可执行权限，并且依赖的 Python 包已安装。
  4. 手动测试工具脚本：可以尝试通过podman exec进入容器，手动执行一个工具脚本（如python3 /home/node/.openclaw/mattermost-tools/get_state.py），看是否能正确与 Mattermost API 交互。

5.4 性能问题与优化建议

• 多个智能体同时运行资源占用高：每个 OpenClaw 容器都会占用一定的内存和 CPU。如果运行 3 个以上智能体感觉系统卡顿，可以考虑：
  • 为 Pod 设置资源限制（在pod.yaml中配置resources）。
  • 使用更轻量级的模型（如gemma4:e2b相比e4b）。
  • 调整 OpenClaw 的心跳间隔，降低活动频率。
• Mattermost 响应慢：Mattermost 容器默认配置可能不高。如果团队活动频繁，可以考虑为其分配更多资源，或者优化数据库配置。

6. 项目扩展与定制化思路

这个启动套件是一个强大的基础，你可以在此基础上进行深度定制，构建属于自己的专属 AI 团队。

6.1 创建自定义的人格与角色

默认的三个角色（系统、构建、验证）是一个很好的起点。你可以通过修改init.ps1脚本引用的模板，或直接修改已生成的workspace/下的文件，来创建全新的角色。

例如，你可以创建一个“数据分析师”角色：

• 在IDENTITY.md中定义：角色是“团队数据分析师”，擅长从日志、数据中提炼洞察。
• 在SOUL.md中定义：性格严谨、注重数据准确性，沟通风格偏向用图表和数字说话。
• 在HEARTBEAT.md中定义：定期检查指定的数据源（可以挂载一个包含日志的卷到容器），生成每日/每周活动报告，并自动发布到 Mattermost 的一个特定频道。
• 在TOOLS.md中提供：处理 CSV/JSON 的 Python 脚本命令、绘制简单图表的指令等。

6.2 集成外部工具与 API

OpenClaw 的强大之处在于其工具调用能力。你可以为智能体扩展TOOLS.md，教导它们使用新的 CLI 工具或调用外部 REST API。

1. 在容器内安装额外工具：你需要定制pod.yaml，在构建镜像时安装额外的软件包，或者将主机上的工具目录挂载到容器内。
2. 在 OpenClaw 配置中声明工具：修改openclaw.json中的tools配置段，为新的命令行工具或 API 调用添加定义，包括名称、描述、参数 schema 和执行命令。
3. 更新 TOOLS.md：在智能体的工作空间文件中，用自然语言描述新工具的用途和使用示例，让智能体学会在什么场景下调用它。

例如，为“构建专家”智能体添加一个“代码质量扫描”工具，让它能在收到代码片段后，自动调用一个本地的静态分析工具并返回结果。

6.3 基于此项目启动衍生项目

项目文档中提到了ONI-CADIA作为一个衍生用例。这展示了一个标准流程：Fork 或基于此 starter 模板创建一个新的仓库，然后进行品牌化和功能特化。

你可以这样做：

1. 克隆本仓库作为起点。
2. 修改项目名称、描述和所有脚本中的元数据（如openclaw-podman这个 CLI 名称）。
3. 定制默认的人格脚手架模板，使其更符合你新项目的领域（例如，一个专注于网络安全监控的 AI 团队，或一个辅助创意写作的 AI 小组）。
4. 添加项目特定的工具脚本和配置。
5. 更新 Mattermost 的插件或主题（mattermost-plugins/目录），打造独特的团队协作界面。

这种模式让你能复用所有底层的容器编排、通信和生命周期管理逻辑，而只需专注于上层 AI 智能体的职能设计。

6.4 模型切换与多模型策略

项目默认支持 Ollama 和 Z.AI。你可以轻松切换模型：

• 切换 Ollama 模型：在.env中修改OPENCLAW_MODEL，例如改为ollama/llama3.2:latest。确保 Ollama 已拉取该模型。
• 使用其他 API 提供商：OpenClaw 支持众多模型提供商。你需要参考 OpenClaw 文档，在openclaw.json中配置对应 provider 的baseURL和apiKey（通过环境变量传入）。例如，配置使用 OpenAI 或 Anthropic 的模型。
• 混合模型团队：一个有趣的实验是让团队中的不同智能体使用不同特性的模型。例如，让“创意构建”智能体使用能力更强的模型，而“日志监控”智能体使用更轻快的模型。这可以通过为不同实例生成不同的openclaw.json配置来实现。

我在实际搭建和实验过程中，最大的体会是“迭代”和“观察”的重要性。不要指望一次性就定义出完美的智能体人格和协作规则。最好的方式是：先快速按照默认配置跑通整个流程，建立一个可以工作的基线系统。然后，通过 Mattermost 与它们互动，观察它们的反应和日志。接着，回头去微调SOUL.md和HEARTBEAT.md中的描述，往往一两个词的改动，就能显著改变智能体的行为倾向。把这个系统当作一个活的、可编程的组织来培育，你会从中获得远超单个 AI 对话的体验和洞察。最后，记得充分利用scripts/目录下的所有工具，它们是你管理这个数字团队的瑞士军刀，多看看它们的源码，能帮助你更好地理解整个系统的运作机理。