核心用法
AgentRelay 是一种专为多智能体系统设计的可靠通信协议，用于解决 sessions_send 在传输超过 30 字符消息时的超时问题。其核心机制是将任意大小的数据写入共享 JSON 文件，然后通过极短的 CSV 格式消息（含文件指针）在代理间传递引用，而非直接传输数据本身。
协议定义了两种消息类型：
- REQ（请求）：发起任务，包含
TYPE,ID,PTR,,格式，指向包含完整任务内容的共享文件 - CMP（完成确认）：任务完成后返回，格式为
CMP,event_id,,,SECRET，携带从文件中读取的 6 位验证码以证明已实际读取文件
使用流程分为四步：接收方解析 CSV 消息 → 读取共享文件获取任务详情 → 执行任务 → 更新结果文件并发送 CMP 确认。
显著优点
1. 突破消息大小限制：通过文件指针间接传输，理论上可承载任意大小的 payload，彻底规避 sessions_send 的 30 字符瓶颈
2. 可靠性验证：Secret Code 机制确保接收方必须实际读取文件才能获取验证码，防止"假接收"或消息丢失
3. 轻量级协议：CSV 格式简洁，易于解析；AgentRelay: 前缀明确标识协议消息，便于 LLM 自动触发处理
4. 安全增强：支持 burn_on_read 阅后即焚模式，敏感数据读取后自动删除；24 小时 TTL 自动清理过期文件
5. 完备工具链：提供 receive、update、cmp、verify 等完整命令集，以及 smoke_test.py 和 pytest 回归测试
潜在缺点与局限性
1. 文件系统依赖：依赖共享文件系统的可访问性和一致性，分布式部署时需确保存储路径对所有代理可达
2. 时序复杂性：相比直接消息传递，增加了"写文件-发指针-读文件-更新文件-发确认"的多步流程，调试和故障排查更复杂
3. 无内置加密：文档未提及传输加密或文件加密机制，敏感场景需额外保障
4. 状态管理开销：需要维护 registry.json 事务日志，长期运行可能产生存储碎片，需定期运行 cleanup_relay.py
5. LLM 理解门槛：虽然设计了触发前缀，但多步命令流程对 LLM 的指令遵循能力要求较高
适合人群
- 构建多智能体协作系统的开发者，需要代理间传输复杂结构化数据（如分析报告、生成内容、任务配置）
- 受限于
sessions_send消息大小限制，需要可靠大负载传输方案的场景 - 对通信可靠性有要求，需要确认接收方实际消费数据的场景
- 使用 OpenClaw 或类似框架的智能体平台用户
常规风险
- 路径遍历风险：若
PTR字段未严格校验，可能存在目录遍历漏洞（../等），需确保文件操作限制在指定存储目录 - 竞态条件：多代理同时读写同一事件文件时可能产生冲突，协议未明确说明并发控制机制
- Secret 泄露：6 位验证码在 CMP 消息中明文传输，若通信通道被截获可被重放攻击，建议在可信通道使用或缩短验证窗口
- 存储耗尽：未及时清理的过期文件可能占满磁盘，需确保
cleanup_relay.py定时运行或监控存储容量