OpenClaw 入门到精通

主题

多 Agent 搭建指南：从单打独斗到团队协作 ​

为什么需要多 Agent？ ​

想象一下：你的主 AI agent 既要处理投资分析、又要写推文、还要监控业务机会、搞社群运营……很快就会变成一个"什么都会，但什么都不精"的全才。

多 agent 架构的核心价值：

  1. 专业化分工 - 每个 agent 专注一个领域，有自己的记忆、技能和判断
  2. 并行执行 - 不同 agent 可以同时执行任务，互不干扰
  3. 隔离失败 - 一个 agent 崩了不影响其他人
  4. 清晰的责任边界 - 谁做什么一目了然

一个 5 Agent 团队示例：

Agent角色职责
Atlas主 Agent / Chief of Staff协调一切
Elliott投资分析IBKR 同步，组合策略
Ogilvy内容策略X/公开内容，推文起草
Scout商业情报机会挖掘
Cyrus社群运营课程搭建

最小可行配置 ​

打开你的 ~/.openclaw/openclaw.json，在 agents.list 数组里添加新 agent：

json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "sonnet",
        "fallbacks": ["gemini-3-flash"]
      },
      "workspace": "/path/to/your/workspace",
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["cyrus", "elliott"]
        }
      },
      {
        "id": "cyrus",
        "name": "Cyrus",
        "workspace": "/path/to/workspace/agents/cyrus",
        "agentDir": "/path/to/.openclaw/agents/cyrus/agent",
        "model": {
          "primary": "sonnet",
          "fallbacks": ["opus"]
        }
      }
    ]
  }
}

关键配置项：

字段说明
idagent 唯一标识，cron 和 spawn 时用这个
workspace用户工作目录，放 SOUL.md、MEMORY.md、代码等你能看到的文件
agentDir系统状态目录（~/.openclaw/agents/<id>/agent），放 sessions、auth 等内部数据。不设会自动生成，但显式设置更清晰
model.primary默认模型（可以不同 agent 用不同模型省钱）
model.fallbacks主模型不可用时的备选
subagents.allowAgents主 agent 允许 spawn 哪些 agent（不设则只能 spawn 自己）

通过 Telegram/Discord 绑定不同 Agent ​

每个 agent 可以有自己的 bot，通过 bindings + channels 配置：

json
{
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "telegram", "accountId": "atlas" }
    },
    {
      "agentId": "cyrus",
      "match": { "channel": "telegram", "accountId": "cyrus-bot" }
    },
    {
      "agentId": "elliott",
      "match": { "channel": "discord", "accountId": "elliott-dc" }
    }
  ],
  "channels": {
    "telegram": {
      "accounts": {
        "atlas": {
          "name": "Atlas",
          "botToken": "123456:ABC...",
          "dmPolicy": "pairing"
        },
        "cyrus-bot": {
          "name": "Cyrus",
          "botToken": "789012:DEF...",
          "dmPolicy": "allowlist",
          "allowFrom": ["你的telegram数字ID"]
        }
      }
    },
    "discord": {
      "accounts": {
        "elliott-dc": {
          "name": "Elliott",
          "token": "MTIzNDU2...",
          "groupPolicy": "allowlist",
          "guilds": {
            "你的服务器ID": {
              "channels": {
                "频道ID": { "requireMention": false }
              }
            }
          }
        }
      }
    }
  }
}

效果：和不同 bot 说话 → 不同 agent 处理，每个 bot 在自己的 workspace 工作。

给 Agent 分配独立身份 ​

每个 agent 的 workspace 里需要这些核心文件：

SOUL.md — 我是谁 ​

markdown
# Cyrus

## Role
Community ops & course builder. 社群运营和课程搭建专员。

## Tone
友好、教学向、耐心。适合面向社群成员的内容。

## Boundaries
- 只负责社群内容和课程材料
- 不处理投资分析（Elliott 的活）
- 不写公开推文（Ogilvy 的活）

AGENTS.md — 我怎么工作 ​

工作流程、输出规范、内存规则。

NOW.md — 当前状态 ​

任务列表、进度跟踪（可覆写）。

MEMORY.md — 长期记忆 ​

跨 session 的知识积累。

WARNING

Sub-agent（通过 sessions_spawn 派发的）只会注入 AGENTS.md + TOOLS.md，不会加载 SOUL.md、USER.md、IDENTITY.md。所以关键指令要写在 AGENTS.md 里。

sessions_spawn：主 Agent 派发任务 ​

这是多 agent 协作的核心工具。主 agent 用 sessions_spawn 把任务交给其他 agent：

python
sessions_spawn(
  agentId: "cyrus",
  task: "写一篇 AI agent 入门教程，保存到 /abs/path/community/wiki/",
  model: "sonnet"           # 可选，覆盖默认模型
  runTimeoutSeconds: 300    # 可选，超时自动终止
)

Sub-agent 特性：

  • 在独立 session 里执行（agent:cyrus:subagent:<uuid>）
  • 完成后自动 announce 结果给主 agent
  • 默认继承调用者的模型，也可以单独指定更便宜的模型
  • 有自己的 token 用量（不占主 agent 的 context）
  • 默认 60 分钟后自动 archive

省钱技巧

设 agents.defaults.subagents.model 让所有 sub-agent 默认用便宜模型：

json
{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "gemini-3-flash"
      }
    }
  }
}

用 agents_list 可以查看当前允许 spawn 的 agent 列表。

Cron 任务：指定 agentId 定时执行 ​

通过 OpenClaw 的 cron 系统，让特定 agent 定时执行任务：

json
{
  "name": "cyrus-daily-content",
  "agentId": "cyrus",
  "schedule": { "kind": "cron", "expr": "0 10 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "model": "anthropic/claude-sonnet-4-5",
    "message": "写今天的社群内容，保存到 /abs/path/community/daily/YYYY-MM-DD.md"
  }
}

关键点：

字段说明
agentId指定哪个 agent 执行（不设则默认 main）
sessionTarget: "isolated"独立会话，不影响交互式 session
payload.model可以覆盖 agent 默认模型（贵的任务用好模型，便宜的用 Flash）
Cron session没有交互上下文，payload 里要写清楚所有输入输出路径

嵌套 Sub-Agent（Orchestrator 模式） ​

默认 sub-agent 不能再 spawn sub-agent。如果你需要"主 agent → 编排者 → 多个 worker"的模式，可以开启嵌套：

json
{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,
        "maxChildrenPerAgent": 5,
        "maxConcurrent": 8
      }
    }
  }
}

结果逐级向上汇报：Worker → 编排者 → 主 Agent → 用户。

实战案例：5 Agent 团队 ​

模型策略

不是所有 agent 都需要最贵的模型。数据同步/扫描用 Flash 或 MiniMax，内容创作用 Sonnet，复杂决策用 Opus。

常见坑与解决方案 ​

坑 1：Edit 在 Isolated Session 容易失败 ​

Cron 和 sub-agent 的 isolated session 用 Edit（精确匹配替换）时，文件可能被其他 session 改过导致匹配失败。

解决：

  • NOW.md（状态板）→ 用 Write 覆写
  • memory/*.md（日志）→ 用 printf >> 追加
  • 在 cron payload 里明确写 "更新 NOW.md 用 Write，禁止用 Edit"

坑 2：Cross-Context 消息限制 ​

Sub-agent 在 Telegram context 里执行时，无法直接发 Discord 消息（反之亦然）。

解决： 用一次性 cron（schedule.kind: "at"）在 isolated session 里发送，绕过 context 限制。

坑 3：Workspace 路径隔离 ​

Sub-agent 的 cwd 是自己的 workspace，访问主 workspace 或其他 agent 的文件需要绝对路径。

解决： 在 AGENTS.md 里写清楚绝对路径。相对路径只用于自己 workspace 内的文件。

坑 4：Sub-agent 不加载 SOUL.md ​

sessions_spawn 的 sub-agent 只注入 AGENTS.md + TOOLS.md，不加载 SOUL.md、USER.md 等。

解决： 把关键行为指令写在 AGENTS.md 里，或者在 spawn 的 task 参数里写清楚。

快速上手 Checklist ​

  • [ ] 在 openclaw.json 的 agents.list 里添加新 agent
  • [ ] 设置 subagents.allowAgents 允许主 agent spawn 新 agent
  • [ ] 创建 agent workspace 目录 + 4 个核心文件
  • [ ] （可选）注册独立 Telegram/Discord bot，配置 bindings
  • [ ] 写第一个 cron 任务或用 sessions_spawn 测试
  • [ ] 观察执行结果，调整 payload 和路径
  • [ ] 迭代!

最后的建议 ​

TIP

  • 从小开始： 不要一次搞 5 个 agent。先加一个专门处理某个明确任务的，跑稳了再扩展
  • 文件是记忆： Agent 不记得上次 session 的事，只记得写进文件的东西。勤写 memory
  • 边界清晰： 每个 agent 只做自己的事。专业化分工是效率的源泉
  • 模型分级： 不是每个任务都需要最贵的模型。合理分配 = 省钱 + 高效

参考：OpenClaw Sub-Agents 官方文档

基于 MIT 许可发布 | OpenClaw 入门到精通 | 内容自动更新

雪安的小龙虾 · 2026