OpenClaw A2A 协议详解：Agent-to-Agent 通信全面指南

本文基于 OpenClaw 官方文档，详解 Agent-to-Agent（A2A）通信的核心概念、机制和配置方法。

一、什么是 A2A？

A2A（Agent-to-Agent）是指多个 AI Agent 之间相互通信、协作的协议和工作模式。在 OpenClaw 中，A2A 不是一套独立的外部协议，而是框架内置的多 Agent 路由 + 会话管理机制，让不同 Agent 可以：

• 互相发送消息
• 委托任务
• 共享上下文
• 形成主从（Orchestrator-Worker）协作模式

---

二、OpenClaw A2A 核心组件

2.1 三大通信原语

OpenClaw 提供三种 A2A 通信方式，适用不同场景：

原语	用途	典型场景
sessions_send	向另一个 Agent 发送消息	委托任务、跨 Agent 通信
sessions_spawn	启动一个子 Agent（sub-agent）运行	并行处理、后台任务
sessions_spawn(runtime:"acp")	启动外部编码 Agent（Codex/Claude Code）	深度编码任务

2.2 Sub-Agent 详解

Sub-Agent 是 OpenClaw 原生的 A2A 机制，主 Agent 可以生成子 Agent 在后台独立运行，结果完成后通知主 Agent。

会话隔离：

agent:<agentId>:subagent:<uuid>

核心特性：

• 每个 Sub-Agent 有独立上下文
• 通过 announce 机制将结果汇报给主 Agent
• 支持嵌套（Orchestrator 模式），深度可达 2 层

工具策略（默认）：

• Sub-Agent 默认获得除会话工具外的所有工具
• 会话工具（sessions_list/sessions_history/sessions_send/sessions_spawn）默认禁用
• 当 maxSpawnDepth >= 2 时，深度-1 的 Orchestrator 子 Agent 可获得 sessions_spawn 等管理工具

2.3 ACP Agent 详解

ACP（Agent Client Protocol）用于运行外部编码工具（Codex、Claude Code、Gemini CLI 等），相当于把这些外部 Agent 作为 OpenClaw 的子进程来调用。

会话隔离：

agent:<agentId>:acp:<uuid>

支持的 Harness： | Agent ID | 实际工具 | |----------|---------| | pi | Pi | | claude | Claude Code | | codex | OpenAI Codex | | opencode | OpenCode | | gemini | Gemini CLI | | kimi | Kimi |

---

三、多 Agent 架构

3.1 Agent 隔离模型

每个 Agent 是完全独立的"大脑"，拥有：

• 独立 Workspace — 文件系统隔离
• 独立 Auth Profiles — 凭据不共享
• 独立 Session Store — 对话历史独立
• 独立 Skills — 技能可共享可不共享

~/.openclaw/
├── agents/
│   ├── main/agent/        # 主 Agent
│   │   ├── auth-profiles.json
│   │   └── sessions/
│   ├── coding/agent/      # 编码 Agent
│   └── alerts/agent/      # 告警 Agent
└── workspace/
    ├── main/               # 主 Agent 工作区
    ├── coding/             # 编码 Agent 工作区
    └── ...

3.2 多 Agent 配置

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
    defaults: {
      model: "anthropic/claude-sonnet-4-6",
    },
  },

  bindings: [
    // WhatsApp → main agent
    { agentId: "main", match: { channel: "whatsapp" } },
    // Discord coding bot → coding agent
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
    // 特定 WhatsApp 群 → alerts agent
    {
      agentId: "alerts",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}

3.3 路由优先级（Most-Specific Wins）

消息路由到 Agent 的优先级：

1. peer 匹配（精确 DM/群/频道 ID）
2. parentPeer 匹配（线程继承）
3. guildId + roles（Discord 角色路由）
4. guildId（Discord 服务器级）
5. teamId（Slack 工作区级）
6. accountId 匹配
7. channel 级别匹配
8. 兜底 → agents.default 或列表第一个

---

四、跨 Agent 任务委托

4.1 sessions_send：发送消息到另一个 Agent

// 向 coding agent 发送任务
sessions_send({
  sessionKey: "agent:coding:subagent:<uuid>", // 或 agent:coding:main
  message: "帮我审查这段代码：\n\nconst x = 1;",
})

典型用途：

• 主 Agent 分析需求，委托编码 Agent 写代码
• 跨 Agent 知识查询
• 任务分发给专用 Agent

4.2 sessions_spawn：启动子 Agent

// 启动后台子 Agent 执行研究任务
sessions_spawn({
  task: "研究 RAG 架构的最新进展，给出摘要",
  label: "rag-research",
  agentId: "main",  // 可选，默认继承调用者
  model: "anthropic/claude-sonnet-4-6",
  runTimeoutSeconds: 300,
})

// 返回
// {
//   status: "accepted",
//   runId: "<uuid>",
//   childSessionKey: "agent:main:subagent:<uuid>"
// }

Announce 机制（子 Agent 完成后通知）：

子 Agent 完成
 └─ announce step 执行（内部）
 ├─ 若 reply == "ANNOUNCE_SKIP" → 不通知
 ├─ 否则 → 格式化结果 + runtime stats
 └─ 推送给 requester session

Announce 包含：

• 运行结果文本
• 状态（success/error/timeout/unknown）
• 运行时长和 Token 统计
• 子会话 sessionKey（供主 Agent 回查）

4.3 Orchestrator 模式（嵌套 Sub-Agent）

当配置 maxSpawnDepth: 2 时：

深度	会话 Key 格式	角色	可否生子？
0	agent:<id>:main	主 Agent	✅ 可生成 depth-1
1	agent:<id>:subagent:<uuid>	Orchestrator	✅ 可生成 depth-2（当 depth>=2）
2	agent:<id>:subagent:<uuid>:subagent:<uuid>	Worker	❌ 不可生子

结果汇报链：

Depth-2 Worker  →  汇报给 parent (depth-1 Orchestrator)
Depth-1 Orchestrator → 综合子结果 → 汇报给 main agent
Main Agent → 汇总 → 回复用户

---

五、ACP Agent（外部编码 Harness）

5.1 为什么用 ACP？

Sub-Agent 适合通用任务，但深度编码任务（需要完整 REPL、文件系统操作、多轮交互）交给专业的编码 Agent 效果更好。ACP 就是这个桥接层。

5.2 核心配置

{
  acp: {
    enabled: true,
    backend: "acpx",         // 使用 acpx 插件
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

5.3 启动 ACP Session

// 通过 sessions_spawn 启动
sessions_spawn({
  task: "帮我用 Vite 创建一个 React 项目",
  runtime: "acp",
  agentId: "codex",
  mode: "session",    // persistent session
  thread: true,        // 绑定到当前 channel thread
})

// 或者用 /acp 命令
// /acp spawn codex --mode persistent --thread auto

5.4 ACP 沙箱限制

⚠️ 重要： ACP Session 运行在宿主机上，不在 OpenClaw 沙箱内。

场景	结果
沙箱会话尝试生成 ACP	❌ 报错：Sandboxed sessions cannot spawn ACP sessions
sessions_spawn sandbox="require" + ACP	❌ 不支持
需要沙箱时	用 runtime="subagent" 代替

5.5 ACP 权限配置

# acpx 插件权限配置
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

permissionMode	行为
approve-all	所有文件写入和命令执行自动批准
approve-reads	只读自动批准，写入/执行需 TTY 交互
deny-all	所有权限提示都拒绝

---

六、线程绑定（Thread Binding）

6.1 什么是线程绑定？

线程绑定让 Agent 的对话持久化绑定到一个 channel thread，后续消息直接路由到同一个 Agent session。

支持 channels：

• Discord 线程/频道
• Telegram 论坛主题（Groups/Supergroups + DM Topics）

6.2 配置

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,      // 空闲 N 小时后自动解绑
      maxAgeHours: 0,     // 0=不限制
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
        spawnSubagentSessions: true,
      },
    },
  },
}

6.3 使用方式

# /acp spawn + 线程绑定
/acp spawn codex --mode persistent --thread auto

# /subagents spawn + 线程绑定
/subagents spawn main "研究这篇论文" --thread here

# /focus 绑定已有 session 到当前 thread
/focus <session-label|session-key|session-id>

# /unfocus 解绑
/unfocus

---

七、完整 A2A 协作流程示例

场景：主 Agent 协调多个子 Agent 完成复杂任务

用户：
"帮我调研市面上的 API 网关，给出选型建议"

           ┌──────────────────────────────────────┐
           │  Main Agent (depth-0)                │
           │  分析需求 → 拆解任务                   │
           └───────┬──────────────────────────────┘
                   │ sessions_spawn (depth-1)
         ┌─────────┼──────────────┐
         ▼         ▼              ▼
    ┌─────────┐ ┌─────────┐ ┌──────────┐
    │researcher│ │  coder  │ │ writer   │
    │ 子 Agent │ │ 子 Agent │ │ 子 Agent  │
    └────┬────┘ └────┬────┘ └────┬─────┘
         │           │            │
         ▼           ▼            ▼
    ┌─────────┐ ┌─────────┐ ┌──────────┐
    │ Kong    │ │ 搭建Demo │ │ 写报告   │
    │ Tyk     │ │         │ │          │
    └────┬────┘ └────┬────┘ └────┬─────┘
         │           │            │
         └───────────┼────────────┘
                     │ announce
                     ▼
           ┌──────────────────────┐
           │  Main Agent          │
           │  汇总 → 给出建议      │
           └──────────────────────┘
                     │
                     ▼
                用户收到回复

对应代码

// 1. 启动研究员子 Agent（搜索）
sessions_spawn({
  task: "调研 API 网关：Kong、Tyk、Apigee、AWS API Gateway。列出优缺点和定价模式。",
  label: "api-gateway-research",
  agentId: "main",
  model: "anthropic/claude-sonnet-4-6",
  runTimeoutSeconds: 600,
})

// 2. 启动开发者子 Agent（Demo）
sessions_spawn({
  task: "用 Kong 搭建一个简单的 API 网关示例，Git 提交。",
  label: "api-gateway-demo",
  agentId: "coding",
  runTimeoutSeconds: 900,
})

// 3. 启动 Writer 子 Agent（报告）
sessions_spawn({
  task: "基于研究员和开发者的输出，撰写 API 网关选型报告。",
  label: "api-gateway-report",
  agentId: "main",
  runTimeoutSeconds: 300,
})

// 每个子 Agent 完成后 announce → Main Agent 汇总

---

八、安全与权限

8.1 工具策略（Tool Policy）

每个 Agent 可独立配置工具访问权限：

{
  agents: {
    list: [
      {
        id: "family",
        sandbox: { mode: "all", scope: "agent" },
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "sessions_spawn"],
          deny: ["write", "edit", "exec", "browser"],
        },
      },
    ],
  },
}

8.2 Sub-Agent 工具覆盖

{
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        // allow: ["read", "exec"]
      },
    },
  },
}

8.3 A2A 通信限制

{
  // 全局关闭 A2A
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],  // 仅允许特定 agent 间通信
    },
  },
}

---

九、配置参考速查

9.1 agents.list 完整字段

interface AgentConfig {
  id: string;                    // 唯一标识
  name?: string;                 // 显示名
  workspace: string;              // 工作区路径
  agentDir?: string;             // 状态目录
  model?: ModelConfig;            // 默认模型
  default?: boolean;              // 是否默认 agent
  groupChat?: GroupChatConfig;    // 群聊配置
  sandbox?: SandboxConfig;         // 沙箱配置
  tools?: ToolPolicy;             // 工具策略
  subagents?: SubagentConfig;     // 子 Agent 配置
  runtime?: ACPConfig;            // ACP 默认配置
}

9.2 sessions_spawn 完整参数

interface SessionsSpawnOptions {
  task: string;                  // ✅ 必填：初始 prompt
  label?: string;                 // 可读标签
  agentId?: string;               // 目标 agent ID
  model?: string;                 // 模型覆盖
  thinking?: string;               // 思考层级覆盖
  runTimeoutSeconds?: number;      // 运行超时（秒）
  thread?: boolean;               // 是否绑定线程
  mode?: "run" | "session";       // 一次性 vs 持久会话
  cleanup?: "delete" | "keep";     // 完成后是否删除会话
  sandbox?: "inherit" | "require"; // 沙箱策略
  runtime?: "subagent" | "acp";   // 运行时类型
}

9.3 ACP 配置完整字段

interface ACPConfig {
  enabled: boolean;                              // 全局开关
  dispatch?: { enabled: boolean };               // 调度开关
  backend: string;                               // 后端类型（acpx）
  defaultAgent?: string;                        // 默认 harness
  allowedAgents?: string[];                      // 允许的 harness 列表
  maxConcurrentSessions?: number;               // 最大并发
  stream?: {
    coalesceIdleMs?: number;                    // 空闲合并
    maxChunkChars?: number;                     // 最大块大小
  };
  runtime?: {
    ttlMinutes?: number;                        // 会话 TTL
  };
}

---

十、故障排查

问题	原因	解决方案
ACP runtime backend is not configured	未安装 acpx 插件	openclaw plugins install acpx
ACP is disabled by policy	全局关闭	acp.enabled=true
ACP agent "<id>" is not allowed	Agent 未在 allowlist	检查 acp.allowedAgents
Unable to resolve session target	错误的 session key/id/label	用 /acp sessions 查看有效目标
Sandboxed sessions cannot spawn ACP	沙箱内无法运行 ACP	使用 runtime="subagent"
Sub-agent announce 丢失	Gateway 重启	Announce 是尽力而为，重启后会话丢失
Thread bindings unavailable	Channel 不支持	确认 channel adapter 支持 thread

---

十一、相关文档

• Multi-Agent Routing — 多 Agent 路由
• Sub-Agents — Sub-Agent 机制
• ACP Agents — ACP 外部编码 Agent
• Multi-Agent Sandbox & Tools — 沙箱与工具策略