OpenClaw03_使用Agent指南

坐吃山猪

2241人浏览 · 2026-02-25 21:41:30

坐吃山猪 · 2026-02-25 21:41:30 发布

OpenClaw03_使用Agent指南

文章目录

OpenClaw03_使用Agent指南

一、基础概念

1.1 什么是 OpenClaw 多 Agent 系统？

OpenClaw 支持在单个 Gateway 进程内运行多个完全隔离的 Agent。每个 Agent 拥有独立的：

组件	说明
Workspace	独立的工作目录，包含 `SOUL.md`、`AGENTS.md` 等配置文件
Agent Directory	认证配置和 Agent 专属状态存储
Session Store	独立的对话历史和会话状态
Auth Profiles	独立的 API 密钥、OAuth 令牌等凭证
Skills	可配置独立的技能列表和工具权限
Model Selection	可为不同 Agent 配置不同的 LLM 模型

1.2 核心架构组件

二、单 Agent vs 多 Agent

2.1 单 Agent 模式（默认）

适用场景：个人助手、开发伴侣、小型团队部署

特点：

一个 Agent 处理所有渠道的请求
配置简单，调试直接
跨渠道上下文一致

配置示例：

// config.jsonc
{
  "agents": {
    "list": [
      {
        "id": "default",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace"
      }
    ]
  }
}

2.2 何时需要多 Agent？

场景	原因
不同安全上下文	部分对话需要访问敏感系统，其他应保持沙箱隔离
专业领域分离	研究 Agent（具备网页浏览）与编码 Agent（具备仓库访问）分离
渠道特定行为	Slack 上的专业助手 vs Discord 上的休闲伴侣
资源管理	编排 Agent 使用 Claude Opus，工作 Agent 使用轻量级模型
多用户隔离	家庭成员共享一个 WhatsApp 号码，但各自拥有独立 Agent

2.3 多 Agent 的核心优势

隔离性：Agent 间不会意外共享或覆盖文件
安全性：凭证严格按 Agent 隔离，防止泄露
灵活性：可为不同 Agent 配置不同模型和工具策略
可扩展性：从单 Agent 平滑扩展到多 Agent 架构

三、持久化 Agent 配置

3.1 使用向导创建 Agent

# 添加工作 Agent
openclaw agents add work

# 添加编码 Agent
openclaw agents add coding

# 添加告警 Agent
openclaw agents add alerts

# 查看所有 Agent 及其绑定
openclaw agents list --bindings

3.2 手动配置示例

// config.jsonc
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace"
      },
      {
        "id": "coding",
        "name": "Coding Agent",
        "workspace": "~/.openclaw/workspace-coding",
        "model": { 
          "primary": "anthropic/claude-sonnet-4-5" 
        }
      },
      {
        "id": "alerts",
        "name": "Alerts",
        "workspace": "~/.openclaw/workspace-alerts",
        "model": { 
          "primary": "openai/gpt-5.2-mini" 
        }
      }
    ]
  }
}

3.3 配置关键字段说明

字段	必填	说明
`id`	是	Agent 唯一标识符
`name`	否	显示名称
`workspace`	是	工作目录路径
`default`	否	是否为默认 Agent（只能有一个）
`model.primary`	否	主模型选择
`model.fallback`	否	备用模型

注意：修改配置后需重启 Gateway 生效。

四、消息路由与绑定

4.1 绑定（Bindings）机制

Bindings 决定入站消息如何路由到特定 Agent。匹配规则按优先级从上到下执行。

4.2 场景一：WhatsApp 单号码多用户

需求：一个 WhatsApp 号码，不同家庭成员的 DM 路由到各自 Agent。

{
  "agents": {
    "list": [
      { "id": "alex", "workspace": "~/.openclaw/workspace-alex" },
      { "id": "mia", "workspace": "~/.openclaw/workspace-mia" }
    ]
  },
  "bindings": [
    {
      "agentId": "alex",
      "match": { 
        "channel": "whatsapp", 
        "peer": { "kind": "direct", "id": "+15551230001" } 
      }
    },
    {
      "agentId": "mia",
      "match": { 
        "channel": "whatsapp", 
        "peer": { "kind": "direct", "id": "+15551230002" } 
      }
    }
  ],
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551230001", "+15551230002"]
    }
  }
}

重要提示：

DM 访问控制是全局的（按 WhatsApp 账号），不是按 Agent 的
必须使用 allowlist 防止号码被公开滥用

4.3 场景二：Telegram 多 Bot 多 Agent

需求：一个 Bot 用于聊天，另一个 Bot 仅用于告警。

{
  "channels": {
    "telegram": {
      "accounts": {
        "default": { 
          "botToken": "123456:ABC...", 
          "dmPolicy": "pairing" 
        },
        "alerts": { 
          "botToken": "987654:XYZ...", 
          "dmPolicy": "allowlist", 
          "allowFrom": ["tg:123456789"] 
        }
      }
    }
  },
  "bindings": [
    { 
      "agentId": "main", 
      "match": { "channel": "telegram", "accountId": "default" } 
    },
    { 
      "agentId": "alerts", 
      "match": { "channel": "telegram", "accountId": "alerts" } 
    }
  ]
}

4.4 匹配规则优先级

Peer + Channel + Account：最具体的匹配
Channel + Account：按账号匹配
Channel：按渠道匹配
Default Agent：兜底路由

调试技巧：每次修改路由后运行 openclaw agents list --bindings 验证。

五、子 Agent 与编排模式

5.1 持久化 Agent vs 子 Agent

类型	生命周期	用途
持久化 Agent	长期运行	对应渠道、Bot 账号或家庭成员
子 Agent	任务完成后自动归档	并行处理特定任务

5.2 子 Agent 配置

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,        // 最大嵌套深度
        "maxChildrenPerAgent": 5,  // 每个 Agent 最多子 Agent 数
        "maxConcurrent": 8,        // 全局并发限制
        "model": "anthropic/claude-sonnet-4-5",  // 子 Agent 默认模型
        "thinking": "low"          // 思考强度
      }
    }
  }
}

5.3 编排器模式（Orchestrator Pattern）

架构：主 Agent（编排器）→ 分解任务 → 生成多个子 Agent（工作者）→ 汇总结果

适用场景：

复杂任务需要并行处理
需要不同专业领域的协作
需要负载均衡和成本控制

示例流程：

用户请求："分析这份财报并生成摘要"
    ↓
Orchestrator Agent (Claude Opus)
    ↓
├── Sub-agent 1: 提取财务数据 (GPT-4-mini)
├── Sub-agent 2: 分析市场趋势 (Claude Sonnet)
└── Sub-agent 3: 撰写执行摘要 (Claude Sonnet)
    ↓
Orchestrator 汇总并输出最终报告

5.4 嵌套限制说明

重要：子 Agent 默认不能无限嵌套。

默认限制：子 Agent 无法创建子 Agent
配置后：可支持最大深度为 2（即 Orchestrator → Worker）
不建议：深度超过 2 通常增加复杂性而不提升效果

六、典型应用场景

6.1 场景一：家庭共享助手

配置：一个 WhatsApp 号码，多个家庭成员各自拥有独立 Agent。

{
  "agents": {
    "list": [
      { "id": "dad", "workspace": "~/.openclaw/workspace-dad" },
      { "id": "mom", "workspace": "~/.openclaw/workspace-mom" },
      { "id": "kid", "workspace": "~/.openclaw/workspace-kid" }
    ]
  },
  "bindings": [
    { "agentId": "dad", "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+1111" } } },
    { "agentId": "mom", "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+2222" } } },
    { "agentId": "kid", "match": { "channel": "whatsapp", "peer": { "kind": "direct", "id": "+3333" } } }
  ]
}

6.2 场景二：开发团队工作流

配置：不同 Agent 处理不同职责。

Agent	职责	模型	技能
Orchestrator	任务分解与协调	Claude Opus	编排技能
Coder	代码生成与审查	Claude Sonnet	GitHub、代码工具
DevOps	部署与监控	GPT-4	K8s、CI/CD 工具
Docs	文档撰写	Claude Haiku	文档工具

6.3 场景三：成本优化架构

策略：主 Agent 使用高端模型，子 Agent 使用经济模型。

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "anthropic/claude-sonnet-4-5",
        "thinking": "low"
      }
    },
    "list": [
      {
        "id": "main",
        "model": { "primary": "anthropic/claude-opus-4-6" }
      }
    ]
  }
}

本地模型混合：

主 Agent：云端大模型（Claude/GPT）
子 Agent：本地 Ollama 模型（节省成本）

七、常见问题与故障排查

Q1: 两个 Agent 意外共享了文件/记忆？

原因：Workspace 路径配置重复或 Session Store 未隔离。

解决：

# 检查 Agent 列表
openclaw agents list --bindings

# 验证各 Agent 的 workspace 路径是否唯一
cat ~/.openclaw/config.jsonc | grep workspace

Q2: 消息路由到了错误的 Agent？

排查步骤：

运行 openclaw agents list --bindings 检查绑定顺序
确认 match 规则的具体性（越具体的规则应越靠前）
检查 default Agent 设置

Q3: 子 Agent 无法创建子 Agent？

原因：默认禁止嵌套，或已达到 maxSpawnDepth 限制。

解决：

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2  // 允许一层嵌套
      }
    }
  }
}

Q4: 多 Agent 配置后 Gateway 无法启动？

检查清单：

JSONC 格式正确（允许注释，但语法必须正确）
所有 workspace 路径存在且可写
没有重复的 agentId
只有一个 Agent 设置了 "default": true

Q5: 如何为不同 Agent 设置不同的工具权限？

方案：使用 per-agent 的 toolPolicy 或 deny 列表。

{
  "agents": {
    "list": [
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "skills": {
          "deny": ["shell", "file-system-write"]  // 限制危险工具
        }
      },
      {
        "id": "trusted",
        "workspace": "~/.openclaw/workspace-trusted",
        "skills": {
          "allow": ["shell", "code-execution"]  // 允许完整工具
        }
      }
    ]
  }
}

Q6: 子 Agent 没有继承主 Agent 的上下文？

解释：这是设计行为。子 Agent 获得的是精简上下文。

解决：

将关键指令放入 AGENTS.md（子 Agent 会读取）
在子 Agent 任务提示中显式包含必要上下文
使用 Orchestrator 模式，让主 Agent 负责分解和汇总

八、最佳实践与性能优化

8.1 配置最佳实践

从单 Agent 开始：先稳定运行单 Agent，再考虑扩展
明确隔离需求：添加 Agent 前能解释清楚为什么需要隔离
保守设置并发：maxConcurrent 初始设为 8，根据资源调整
使用向导创建：避免手动配置路径错误
版本控制配置：将 config.jsonc 纳入 Git 管理

8.2 成本控制策略

策略	实现方式
模型分层	主 Agent 用 Opus，子 Agent 用 Sonnet/Haiku
本地混合	子 Agent 使用 Ollama 本地模型
并发限制	设置 `maxConcurrent` 防止资源耗尽
深度限制	`maxSpawnDepth: 2` 避免无限递归

8.3 安全建议

公共 facing Agent：严格限制工具权限（deny shell、file-write）
凭证隔离：不同 Agent 使用不同的 API Key
Allowlist 策略：WhatsApp/Telegram 必须配置 allowlist
定期审计：运行 openclaw doctor 检查配置健康度

8.4 调试命令速查

# 查看 Agent 状态和绑定
openclaw agents list --bindings

# 检查系统健康
openclaw doctor

# 查看实时日志
openclaw logs --follow

# 测试特定渠道
openclaw channels test telegram

# 重置特定 Agent 会话
openclaw sessions reset --agent coding