OpenClaw Agent-to-Agent 通信完全指南

概述

之前研究让飞书群里的机器人对话，最终采用的就是这个 OpenClaw 内部的 agent-to-agent 通信的两种主要方式，有兴趣可以看看。

两种方式对比

方式一：sessions_send 工具

适用场景：需要与已存在的 session 进行持续对话，保持上下文

配置要求：

{  tools: {    agentToAgent: {      enabled: true,      allow: ["main", "social", "test"], // 允许发送消息的 agent 列表    },    sessions: {      visibility: "all", // 允许查看其他 sessions    },  },}

权限要求：

• 调用 agent 需要 group:sessions 权限
• 否则将收到 insufficient permissions 错误

使用示例：

await sessions_send({  sessionKey: "agent:test:feishu:direct:ou_xxx",  message: "你好，小芳！"})

特点：

• 需要目标 session 已存在
• 支持双向持续对话
• 受 agentToAgent.allow 白名单限制

方式二：openclaw agent CLI

适用场景：脚本、自动化任务、一次性消息

使用示例：

openclaw agent --agent test --message "你好，小芳！"

特点：

• 不需要预存 session
• 每次创建新 session
• 不受 agentToAgent.allow 限制
• 适合 cron 任务和脚本

配置步骤

1. 启用 Agent-to-Agent 通信

编辑 ~/.openclaw/openclaw.json：

{  tools: {    agentToAgent: {      enabled: true,      allow: ["main", "social", "test"],    },    sessions: {      visibility: "all",    },  },}

1. 重启 Gateway

openclaw gateway restart

1. 验证配置

# 查看 agents 列表openclaw agents list# 测试通信openclaw agent --agent test --message "测试消息"

常见问题

Q1: sessions_send 返回 "forbidden"

原因：发送方 agent 不在 agentToAgent.allow 列表中

解决：将发送方 agent ID 加入 allow 列表

Q2: sessions_send 返回 "timeout"

原因：消息已送达，但目标 agent 没有回复

解决：这是正常行为，表示消息已成功发送

Q3: 找不到目标 session

原因一：session key 错误或目标 session 不存在

解决：使用 sessions_list 查询正确的 session key

原因二：调用 agent 缺少 group:sessions 权限

解决：确保调用 agent 的权限组包含 sessions，最简单的确认方法是：问agent的 tools 列表是什么？看回答里有没有session的功能

最佳实践

1. 白名单管理
   ：将所有需要通信的 agent 加入 allow 列表
2. Session Key 获取
   ：使用 sessions_list 工具查询
3. 错误处理
   ：区分 forbidden（权限）和 timeout（无回复）
4. CLI vs Tool
   ：脚本用 CLI，对话用 sessions_send

参考

• OpenClaw 文档：openclaw-2026.3.13-1/docs/concepts/session-tool.md