Agent 通信方式完整指南
# Agent 通信方式完整指南
> **文档用途**：指导 Agent 之间如何选择合适的通信方式
> **适用对象**：所有 Agent（曹小兔、小智、采儿、老旺、大壮、小笔等）
> **最后更新**：2026-03-19
—
## 一、三种通信方式概览
| 方式 | 工具/机制 | 响应速度 | 适用场景 | 持久化 |
|——|———-|———|———|——–|
| **Message** | `sessions_send` | 即时 | 实时对话、紧急通知 | ❌ 不持久 |
| **Cron** | `openclaw cron` | 延迟（分钟级）| 定时任务、异步处理 | ✅ 持久 |
| **Tasks.md** | 文件读写 | 被动（下次心跳）| 任务分配、状态跟踪 | ✅ 持久 |
—
## 二、Message 工具使用说明
### 2.1 使用场景
– ✅ **实时对话**：需要立即得到回复
– ✅ **紧急通知**：重要信息需要对方立即知晓
– ✅ **协作讨论**：多 Agent 共同讨论问题
– ✅ **即时确认**：需要对方立即确认某事
### 2.2 优缺点
| 优点 | 缺点 |
|——|——|
| 即时响应，实时交互 | 不持久化，消息丢失风险 |
| 适合复杂讨论 | 需要对方在线才能收到 |
| 支持多轮对话 | 不适合需要记录的任务 |
### 2.3 使用方法
“`javascript
// 发送消息给其他 Agent
sessions_send(
sessionKey: “agent:目标Agent名称”,
message: “消息内容”
)
“`
### 2.4 可用 Agent 列表
| Agent ID | 名称 | 职责 |
|———-|——|——|
| `agent:caier-team` | 采儿 | 数据组长 |
| `agent:laowang-team` | 老旺 | 理财经理 |
| `agent:doctor` | 曹医生 | 家庭医生 |
| `agent:dazhuang` | 大壮 | 健身教练 |
| `agent:xiaozhi` | 小智 | 技术支持 |
| `agent:main` | 曹小兔 | 管家 |
### 2.5 示例
“`javascript
// 通知采儿数据已准备好
sessions_send(
sessionKey: “agent:caier-team”,
message: “数据已准备好，请查收”
)
// 向小智请求技术支持
sessions_send(
sessionKey: “agent:xiaozhi”,
message: “需要帮忙写一个MySQL查询脚本，需求是…”
)
“`
### 2.6 故障排查
| 问题 | 原因 | 解决方案 |
|——|——|———|
| 消息发送失败 | 目标格式错误 | 使用 `agent:xxx` 格式 |
| 消息发送失败 | action参数错误 | 使用 `action=”send”` |
| 消息发送失败 | message为空 | 确保message有内容 |
| 对方未收到 | Agent不在线 | 改用Cron或Tasks.md |
—
## 三、Cron 任务使用说明
### 3.1 使用场景
– ✅ **定时任务**：固定时间执行的任务
– ✅ **异步处理**：不需要立即响应的任务
– ✅ **延迟执行**：需要在将来某个时间点执行
– ✅ **周期性任务**：每日/每周重复执行的任务
### 3.2 优缺点
| 优点 | 缺点 |
|——|——|
| 持久化存储，不会丢失 | 响应有延迟（分钟级） |
| 可定时/周期性执行 | 不适合需要即时响应的场景 |
| 可指定执行 Agent 和模型 | 需要配置，相对复杂 |
### 3.3 使用方法
“`bash
# 创建一次性任务
openclaw cron create –agent 目标Agent –prompt “任务描述” –run-at “2026-03-19 15:00”
# 创建周期性任务
openclaw cron create –agent 目标Agent –prompt “任务描述” –schedule “0 9 * * *”
# 查看所有定时任务
openclaw cron list
# 删除任务
openclaw cron delete –id 任务ID
“`
### 3.4 示例
“`bash
# 让小智在15:00执行数据库备份脚本
openclaw cron create \
–agent xiaozhi \
–prompt “执行MySQL数据库备份脚本” \
–run-at “2026-03-19 15:00”
# 让采儿每天早上9点检查数据更新
openclaw cron create \
–agent caier-team \
–prompt “检查昨日数据更新情况，生成报告” \
–schedule “0 9 * * *”
“`
### 3.5 故障排查
| 问题 | 原因 | 解决方案 |
|——|——|———|
| 任务未执行 | 时间格式错误 | 使用标准时间格式 |
| 任务未执行 | Agent不存在 | 检查Agent名称拼写 |
| 任务执行失败 | 权限不足 | 检查Agent权限配置 |
—
## 四、Tasks.md 使用说明
### 4.1 使用场景
– ✅ **任务分配**：给Agent分配具体任务
– ✅ **状态跟踪**：跟踪任务执行状态
– ✅ **工作记录**：记录工作历史和成果
– ✅ **被动触发**：Agent心跳时自动检查
### 4.2 优缺点
| 优点 | 缺点 |
|——|——|
| 持久化，任务不会丢失 | 响应延迟（依赖心跳频率） |
| 状态可视化，便于跟踪 | 不适合紧急任务 |
| 支持优先级管理 | 需要Agent主动检查 |
### 4.3 使用方法
在目标Agent的 `tasks.md` 文件中添加任务记录：
“`markdown
| ID | 任务描述 | 优先级 | 状态 | 创建时间 | 创建者 | 完成时间 | 积分 | 执行动作 | 输出位置 | 通知方式 |
|—-|———|——–|——|———|——–|———-|———-|———-|———-|———-|
| T001 | 任务描述 | P1 | ⏳ 待执行 | 2026-03-19 | 曹小兔 | – | 1 | 具体动作 | 输出路径 | 完成后通知 |
“`
### 4.4 状态定义
| 状态 | 说明 |
|——|——|
| ⏳ 待执行 | 新任务，等待执行 |
| 🔄 执行中 | 正在执行 |
| ✅ 已完成 | 任务完成，待验证 |
| ✅✓ 已验证 | 任务完成且验证通过 |
| ❌ 已取消 | 任务取消 |
| ⚠️ 阻塞 | 需要协调资源 |
### 4.5 示例
“`markdown
| T010 | Agent通信方式指南文档 | P1 | ⏳ 待执行 | 2026-03-19 | 曹小兔 | – | 1 | 编写完整指南 | `docs/agent-communication-guide.md` | 完成后通知曹小兔 |
“`
### 4.6 故障排查
| 问题 | 原因 | 解决方案 |
|——|——|———|
| 任务未被处理 | Agent未检查 | 等待心跳或手动触发 |
| 状态未更新 | 格式错误 | 检查表格格式 |
| 任务丢失 | 文件冲突 | 确保正确写入文件 |
—
## 五、三种方式对比
| 维度 | Message | Cron | Tasks.md |
|——|———|——|———-|
| **响应速度** | ⚡ 即时 | ⏱️ 分钟级 | 🐢 心跳触发 |
| **持久化** | ❌ 否 | ✅ 是 | ✅ 是 |
| **复杂度** | 简单 | 中等 | 简单 |
| **适用场景** | 实时对话 | 定时/异步 | 任务分配 |
| **可靠性** | 中等 | 高 | 高 |
| **可追溯性** | 低 | 中 | 高 |
—
## 六、决策流程图
“`
需要与其他Agent通信？
│
▼
是否需要即时响应？
│
├── 是 → 使用 Message
│ └── 发送失败？→ 改用 Cron
│
└── 否 → 是否需要定时执行？
│
├── 是 → 使用 Cron
│
└── 否 → 使用 Tasks.md
└── Agent心跳时自动处理
“`
### 快速决策表
| 场景 | 推荐方式 | 备选方式 |
|——|———|———|
| “请立即帮我…” | Message | Cron |
| “请在明天9点…” | Cron | – |
| “请记录这个任务…” | Tasks.md | – |
| “紧急！系统故障！” | Message | Cron |
| “每天检查一次…” | Cron | – |
| “有空的时候…” | Tasks.md | Cron |
—
## 七、最佳实践
### 7.1 组合使用
– **Message + Tasks.md**：先用Message通知，同时在Tasks.md记录任务
– **Cron + Tasks.md**：Cron任务执行后更新Tasks.md状态
– **Message + Cron**：Message通知后，用Cron设置提醒
### 7.2 避免的问题
| ❌ 错误做法 | ✅ 正确做法 |
|————|————|
| 用Message发送重要任务 | 用Tasks.md记录，Message通知 |
| 用Cron处理需要即时响应的任务 | 用Message直接沟通 |
| 反复Message询问任务进度 | 查看Tasks.md状态 |
| 任务完成后不更新状态 | 及时更新Tasks.md状态 |
### 7.3 执行优先原则
> **看到任务立即执行，不需要确认**
1. 看到任务 → **立即执行**
2. 需要帮助 → **安排任务给其他Agent**（不发消息询问）
3. 尝试无果 → **才寻求帮助**
—
## 八、总结
| 方式 | 一句话描述 | 使用时机 |
|——|———–|———|
| **Message** | 即时聊天工具 | 需要立即回复时 |
| **Cron** | 定时任务调度 | 需要定时/异步执行时 |
| **Tasks.md** | 任务看板 | 需要分配和跟踪任务时 |
—
_文档编写：小笔 ✍️_
_最后更新：2026-03-19_
