OpenMOSS 入门：用多 Agent 协作把 AI 变成24小时持续运行的公司团队

难度：入门 | 时长：30 分钟 | 收获：理解 OpenMOSS 四角色协作体系，搭建自己的 AI 公司团队

---

目标读者

你已经在用 OpenClaw，感受过单 Agent 的能力——它能聊天、能写代码、能执行任务。但你可能也发现了：一旦任务变复杂，或者需要多步协作，单独一个 Agent 很容易在某个环节卡住，然后就"死"在那里，等你来催。

OpenMOSS 想解决的就是这个问题。它的思路很简单：不要让一个 Agent 独自扛所有事，而是给 AI 装上一套组织架构。规划者负责拆需求，执行者负责干活，审查者负责质量把关，巡查者负责盯梢——四个角色各司其职，通过定时唤醒自主运转，形成一套闭环的 AI 公司团队。

OpenMOSS 本身是一个中间件，它不管具体业务，只管调度协作。你给它配什么 Skill，它就能自动协作完成什么任务。

本文适合：

• 已在用 OpenClaw，想体验多 Agent 协作
• 需要 AI 自动持续运转，不需要人工盯守
• 想搭建内容生产流水线、自动化运维、代码审查等工作流

---

核心依赖与环境

GitHub 仓库：https://github.com/uluckyXH/OpenMOSS

---

完整项目结构

OpenMOSS/
├── app/                          # FastAPI 后端
│   ├── main.py                   # 入口：路由注册、中间件、SPA 静态服务
│   ├── config.py                 # 配置加载
│   ├── database.py               # 数据库初始化（SQLAlchemy）
│   ├── models/                  # 数据模型（10 张表）
│   ├── routers/                 # API 路由
│   ├── services/                # 业务逻辑层
│   └── schemas/                 # Pydantic 序列化模型
├── webui/                        # Vue 3 前端源码（需要构建）
├── static/                       # 前端构建产物（后端直接服务）
├── prompts/                      # Agent 角色提示词模板
│   ├── templates/                # 角色基础模板
│   ├── agents/                   # Agent 提示词示例
│   └── tool/                    # 工具调用提示词
├── skills/                        # OpenClaw Agent Skill 定义
│   ├── task-cli.py              # 各 Skill 共用的 API 调用脚本
│   ├── task-planner-skill/      # 规划者 Skill
│   ├── task-executor-skill/      # 执行者 Skill
│   ├── task-reviewer-skill/     # 审查者 Skill
│   ├── task-patrol-skill/       # 巡查者 Skill
│   └── dist/                    # 打包后的 Skill .zip 包
├── config.example.yaml            # 配置文件模板
├── requirements.txt              # Python 依赖
├── Dockerfile
└── docker-compose.yml

---

手把手步骤

Step 1：克隆项目并安装依赖

# 克隆项目
git clone https://github.com/uluckyXH/OpenMOSS.git openmoss
cd openmoss

# 安装 Python 依赖
pip install -r requirements.txt

如果你的仓库里没有 static/ 目录（前端未构建），还需要构建前端：

cd webui
npm install
npm run build

# 把构建产物拷贝到 static/ 目录
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

---

Step 2：配置 config.yaml

首次启动时，OpenMOSS 会自动从 config.example.yaml 生成 config.yaml。建议直接复制模板再修改：

cp config.example.yaml config.yaml

然后编辑 config.yaml，以下几个字段必须配置：

# 管理员密码（首次启动后自动加密）
admin:
  password: "your-secure-password-here"

# Agent 注册令牌（Agent 注册时需要用到，建议随机生成）
agent:
  registration_token: "your-random-token-here"
  allow_registration: true

# 工作目录（Agent 产出物的存放位置）
workspace:
  root: "/home/your-user/TaskWork"

# 服务外网地址（Agent 对接时需要访问的地址）
server:
  external_url: "http://your-server-ip:6565"

---

Step 3：启动服务并完成初始化向导

python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

首次启动会自动：

1. 生成 config.yaml（如果还没有）
2. 初始化 SQLite 数据库（data/tasks.db）
3. 自动挂载前端（如果 static/ 目录存在）

打开浏览器访问 http://localhost:6565，会跳转到初始化向导，引导你完成：

• 设置管理员密码
• 配置项目名称
• 生成 Agent 注册令牌
• 可选配置通知渠道

完成后显示服务地址：

---

Step 4：登录 WebUI 熟悉后台

初始化完成后，用管理员账号登录 WebUI，你会看到以下页面：

刚启动时，Agent 列表是空的——我们还没有注册任何 Agent。接下来 Step 5 开始创建。

---

Step 5：创建四个 Agent 并注册到 OpenClaw

OpenMOSS 的四角色分别对应不同的职责：

每个 Agent 本质上是一个运行 OpenClaw 的实例。我们以创建 planner 为例，其他三个角色的流程完全相同。

方式一：通过 WebUI 注册（推荐）

1. 在 WebUI 的 Agent 页面点击「注册 Agent」
2. 填写基本信息：

角色: planner
名称: OpenMOSS-Planner
注册令牌: （填写 config.yaml 里的 agent.registration_token）

1. 提交后，WebUI 会返回：
   • Agent 的 API Key（请保存好，只显示一次）
   • Agent 的 SKILL.md 和 task-cli.py 下载地址
   • 对接指引（包含注册命令、配置方法）

方式二：通过 API 注册

curl -X POST http://localhost:6565/api/agents/register \
  -H "X-Registration-Token: your-registration-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenMOSS-Planner",
    "role": "planner"
  }'

返回内容包含 API Key、注册命令和 Skill 下载地址：

{
  "api_key": "om_xxxxxxxxxxxxxxxxxxxx",
  "skill_cli_url": "http://localhost:6565/skills/task-cli.py",
  "skill_url": "http://localhost:6565/skills/task-planner-skill/SKILL.md",
  "register_command": "openclaw agents add ..."
}

用同样方式注册其余三个 Agent：

executor → task-executor-skill
reviewer → task-reviewer-skill
patrol   → task-patrol-skill

---

Step 6：配置 Agent Skill

每个 Agent 注册成功后，会得到两个关键文件：

• task-cli.py — 各角色共用的 OpenMOSS API 调用脚本
• SKILL.md — 该角色的专属 Skill 定义

把它们放到 OpenClaw 能读取到的目录下（通常和 Agent 的 prompt 放在一起）：

# 假设 OpenClaw Agent 配置目录
mkdir -p ~/.openclaw/agents/openmoss-planner/skills

# 下载 Skill 文件
curl -o ~/.openclaw/agents/openmoss-planner/skills/task-cli.py \
  http://localhost:6565/skills/task-cli.py

curl -o ~/.openclaw/agents/openmoss-planner/skills/SKILL.md \
  http://localhost:6565/skills/task-planner-skill/SKILL.md

然后在 OpenClaw 的 Agent 配置里，把 SKILL.md 的路径加入 Agent 的 Prompt 或 Skill 配置中，让 Agent 知道它能调用 OpenMOSS 的哪些 API。

---

Step 7：配置 cron 定时唤醒，让 Agent 自动"上班"

这是 OpenMOSS 和普通单 Agent 最大的区别：Agent 不是等你发消息才行动的，而是像员工一样定时打卡上班。

在 OpenClaw 的 Agent 配置里，为每个 Agent 设置 cron 定时任务：

planner（规划者）— 每30分钟检查一次新任务：

{
  "cron": "*/30 * * * *",
  "task": "检查 OpenMOSS 任务队列，如果有未规划的新任务，执行规划流程"
}

executor（执行者）— 每15分钟检查一次待领取任务：

{
  "cron": "*/15 * * * *",
  "task": "检查 OpenMOSS 子任务队列，认领并执行"
}

reviewer（审查者）— 每20分钟检查一次待审查交付物：

{
  "cron": "*/20 * * * *",
  "task": "检查 OpenMOSS 审查队列，处理待审查的交付物"
}

patrol（巡查者）— 每10分钟巡检一次系统状态：

{
  "cron": "*/10 * * * *",
  "task": "检查 OpenMOSS 系统状态，标记阻塞任务，发现异常立即告警"
}

Agent 被唤醒后的工作流程是固定的：

1. 调用 OpenMOSS API 获取当前状态
2. 根据自身角色执行相应操作
3. 将结果回写到 OpenMOSS
4. 进入休眠，等待下次唤醒

整个过程完全不需要人工介入。

---

Step 8：下达第一个任务，验证四角色协作闭环

在 WebUI 的「任务管理」页面，点击「创建任务」，填写：

任务名称：AI资讯自动翻译发布
目标：搜集中文互联网的 AI/科技/数码资讯，翻译成英文后发布

规划者（planner）被 cron 唤醒后，会：

1. 接收任务，拆解成多个模块（搜集 → 翻译 → 审核 → 发布）
2. 为每个模块创建子任务（sub-task）
3. 定义每个子任务的验收标准

执行者（executor）被唤醒后，会：

1. 从队列认领第一个待处理的子任务
2. 执行工作（联网搜索资讯、翻译内容）
3. 提交交付物到审查队列

审查者（reviewer）被唤醒后，会：

1. 获取待审查的交付物
2. 根据验收标准评分
3. 通过则标记子任务完成；驳回则打回执行者返工

巡查者（patrol）持续监控系统：

• 如果某个子任务超过阈值没有进展，自动标记为 blocked
• 发现审查驳回率异常升高，发送告警通知
• 发现执行者陷入死循环，通知管理员介入

你可以随时在 WebUI 的「活动流」页面，看到所有 Agent 的实时工作动态。

---

Step 9：配置通知渠道

OpenMOSS 支持在关键事件发生时自动通知你。在 config.yaml 中配置通知渠道：

notification:
  enabled: true
  channels:
    - "飞书群ID"    # 需要把 Agent 拉进飞书群并艾特一次获取 chat_id
    - "user:ou_xxx" # 飞书用户 open_id
  events:
    - task_completed   # 子任务完成
    - review_rejected   # 审查驳回（返工）
    - all_done          # 所有子任务完成
    - patrol_alert      # 巡查发现异常

Agent 会从 GET /config/notification 接口读取通知配置，然后用自己的能力（邮件、飞书等）发送通知。

---

常见问题排查

1. Agent 注册失败（registration_token 不匹配）

表现：Agent 注册时返回 403 或"invalid token"错误。

最常见原因是 registration_token 不一致。检查两件事：

1. OpenMOSS config.yaml 里的 agent.registration_token 值
2. Agent 注册请求里 Header 中的 X-Registration-Token 值

两者必须完全一致，包括空格和大驼峰。如果修改了 config.yaml，记得重启 OpenMOSS 服务。

---

2. cron 定时任务没有唤醒 Agent

表现：Agent 没有自动开始工作，控制台也没有错误日志。

排查顺序：

1. 确认 OpenClaw 端的 cron 配置正确——cron 表达式是否合法，任务描述是否清晰
2. 确认 OpenClaw 实例在运行——Agent 对应的 OpenClaw 进程是否存活
3. 检查 Agent 的 API Key 是否有效——在 WebUI Agent 页面查看状态是否为 active

可以用 WebUI 的「Agent」页面直接查看某个 Agent 的最后活跃时间，判断它有没有被定时唤醒。

---

3. 子任务被反复驳回，陷入死循环

表现：executor 提交的交付物一直被 reviewer 驳回，同一个子任务反复重做。

这通常说明 executor 对验收标准的理解有偏差，或者验收标准本身定义不清。

解决思路：

1. 在 WebUI 查看驳回记录，看 reviewer 给出的理由是什么
2. 调整 planner 在创建子任务时写下的验收标准，让它更具体可量化
3. 如果是 executor 能力不足，可以给它换一个更强大的模型（更新 OpenClaw Agent 的 API Key）

---

4. patrol 巡查无响应

表现：系统有阻塞任务，但 patrol 没有标记，也没有发送告警。

检查：

1. patrol Agent 对应的 OpenClaw 实例是否在运行
2. patrol 的 cron 间隔是否太稀疏（设置 */10 比 */60 敏感得多）
3. config.yaml 中 notification 是否开启，channels 是否配置正确
4. patrol Agent 是否具备发送通知的 Skill（飞书/邮件等）

---

5. API Key 过期或权限不足

表现：Agent 工作一段时间后突然停止，日志里出现 401 或 403 错误。

Agent 的 API Key（om_xxx 开头的）是 OpenMOSS 的内部凭证，不等于 LLM 的 API Key。如果日志里有 LLM 的认证错误，说明 Agent 的 LLM API Key 有问题（比如额度用完、权限被吊销）。

解决方案：更新 OpenClaw Agent 配置里对应的 LLM API Key，然后重启该 Agent 实例。

---

6. 多个 executor 同时认领同一个任务

表现：两个 executor 都开始做同一个子任务，造成重复劳动。

OpenMOSS 的任务队列有原子性保护，理论上不会出现两个 Agent 同时认领同一个子任务。如果出现这种情况，可能是：

1. 两个 executor 的 cron 间隔设置过短，在极短时间窗口内同时醒来
2. 任务状态更新有延迟，executor 读到了 stale 数据

解决方法：适当拉大 executor 的 cron 间隔（比如从 */5 改为 */15），给每次处理足够的时间窗口完成状态更新。

---

扩展阅读 / 进阶方向

1. 自定义 Agent 角色提示词

prompts/ 目录下有各角色的提示词模板。你可以在此基础上修改，打造符合自己业务需求的 Agent 人格：

# 编辑规划者提示词
vim prompts/agents/planner-agent-prompt.md

# 编辑执行者提示词
vim prompts/agents/executor-agent-prompt.md

修改提示词后，Agent 下次唤醒时会自动读取最新版本。

2. 接入 WordPress Skill，实现内容自动发布

skills/wordpress-skill/ 提供了 WordPress 发布能力。配合 executor 使用，可以让 Agent 把翻译好的文章自动发布到 WordPress 站点，无需人工操作。

需要配置 WordPress 站点的 URL 和 API Key：

# 查看 WordPress Skill 配置说明
cat skills/wordpress-skill/SKILL.md

3. 积分与绩效系统调优

OpenMOSS 内置了 Agent 积分机制，审查者的评分会直接影响 executor 的绩效排行。你可以在 WebUI 的「积分排行」页面查看各 Agent 的产出质量。

如果想让积分系统更严格或更宽松，修改 reviewer 的 prompt 里关于评分标准的描述即可。

4. 接入 Grok Search Skill，实现联网搜索

skills/grok-search-runtime/ 提供了 Grok 联网搜索能力。Executor 有了这个 Skill，可以实时抓取互联网资讯，然后翻译整理发布——这是 1M Reviews 这个真实案例的核心工作流。

5. 迁移到 PostgreSQL / MySQL

目前 OpenMOSS 默认使用 SQLite，适合中小规模团队。如果需要更高并发支持，可以切换到 PostgreSQL 或 MySQL：

# config.yaml
database:
  type: postgresql  # 或 mysql
  path: ""           # 留空，使用下面的连接字符串
  connection_string: "postgresql://user:pass@localhost:5432/openmoss"

6. Docker 一键部署

项目提供了 Dockerfile 和 docker-compose.yml，可以一键部署整个环境：

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

这会把 OpenMOSS、数据库和前端全部打包运行，适合快速验证或迁移到服务器。

7. 构建自己的内容生产流水线

参考 1M Reviews 的实际案例，完整流水线是：

1. planner 拆解任务：搜集 → 翻译 → 审核 → 发布
2. executor（搜集） 通过 Grok Search Skill 抓取资讯
3. executor（翻译） 调用翻译 API 改写内容
4. reviewer 审核内容质量和格式
5. executor（发布） 调用 WordPress Skill 发布到网站
6. patrol 监控系统运行状态，发现异常立即告警

整个流程完全自主运转，你只需要在开始时设定目标，最后验收结果。