第14章协作架构设计与ACP协议安装配置

本章前置检查：

□ OpenClaw已成功部署并运行（完成第2章）
□ Hermes已成功部署并运行（完成第8章）
□ 理解两者协作的基本原理（第13章）
□ 拥有至少一个消息渠道（飞书/Telegram）用于测试

本章预估总时长：3.5小时

本章难点提示：

14.2节涉及ACP协议的底层细节，建议先搭建连接再回头理解，不要被序列化格式、心跳保活等概念卡住。
14.3节是实操核心，包括hermes claw migrate命令，第一次运行务必使用--dry-run预览。
14.4节的任务调度优先级在实际生产环境中价值很大，建议动手配置一个“模式对比”实验。
14.5节是为企业级部署准备的进阶内容，个人开发者可先跳过，但建议至少阅读“直连vs网关模式”部分。

🎯 本章教学目标：掌握OpenClaw与Hermes之间的ACP协议配置方法，能够独立搭建双Agent协作环境，熟练使用hermes claw migrate迁移已有资产，理解ask和delegate两种任务调度模式的区别，并能够根据场景选择合适的优先级队列策略。

14.1 两种协作模式

🎯 本节目标：理解OpenClaw与Hermes集成的两种架构模式，能够根据安全需求和网络环境做出合理选择。

预计时长：0.5小时

14.1.1 模式一：统一入口——通过ACP协议直接桥接

在此模式下，OpenClaw作为唯一的用户入口，负责接收所有消息渠道的请求。当任务需要深度处理时，OpenClaw通过ACP协议将任务直接委托给Hermes。

架构示意：

用户 → [飞书/Telegram/微信] → OpenClaw Gateway → ACP → Hermes Agent → 结果返回

适用场景：

需要统一用户会话管理
OpenClaw已经接入多个渠道，不想重复配置
希望保持单一入口便于审计和权限控制

优点：

用户无感知切换，体验统一
配置相对简单，只需打通OpenClaw → Hermes的单向ACP连接
可利用OpenClaw的bindings做精细化路由（哪些消息给Hermes）

缺点：

Hermes无法主动发起消息（除非通过OpenClaw反向调用）
多一层转发，增加少量延迟
如果OpenClaw宕机，Hermes也无法对外服务

14.1.2 模式二：独立部署并行运行——各司其职，共享资源

在此模式下，OpenClaw和Hermes各自独立对外提供服务：OpenClaw仍然负责多渠道交互，Hermes也可以开启自己的Gateway（如飞书Bot）直接接收用户消息。两者通过共享记忆和API调用协作，但不互相依赖存活。

架构示意：

用户 → [飞书] → OpenClaw Gateway ──┐
用户 ─→ [Telegram] → Hermes Gateway ─┴── 共享记忆/API调用

适用场景：

需要高可用（希望一个挂了另一个还能继续）
Hermes需要直接处理某些高频渠道（如Telegram），减少转发延迟
团队分工明确：不同渠道由不同Agent直接响应

优点：

无单点故障，容错性好
减少ACP通信开销，响应更快
可以独立扩展（如OpenClaw部署在公网，Hermes部署在内网）

缺点：

需要维护两套Gateway配置
用户可能在不同渠道体验到不同的Agent行为（如果不做记忆共享）
会话状态同步更复杂

龙马注：个人开发者强烈推荐模式一（统一入口）。大部分场景下你不需要Hermes直接面对用户，让OpenClaw负责所有“聊天界面”的事情，Hermes专心做“大脑”，架构最清晰。模式二适合已经有一定规模、需要横向扩展的团队。

🛠️ 实践任务（本节）：根据你的部署环境（公网服务器/内网机器/混合），选择一种模式，并写下选择理由。

💭 本节总结（不看书写3行）：

📊 用时记录：计划____min → 实际____min → 偏差原因：________

14.2 ACP协议深度解析

🎯 本节目标：理解ACP协议的消息格式、通信机制和可靠性设计，为配置排错打下基础。

预计时长：0.8小时

14.2.1 ACP消息格式与序列化

ACP（Agent Client Protocol）是基于JSON-RPC 2.0的扩展协议，增加了Agent特有的会话管理、工具代理和流式回调能力。

基础请求格式：

json

{
  "jsonrpc": "2.0",
  "method": "agent/delegate",
  "params": {
    "session_id": "feishu:oc_xxx:user_123",
    "task": "分析CSV文件销售趋势",
    "attachments": [{"url": "https://...", "type": "csv"}],
    "context": {"memory_hint": "prefer_weekly"},
    "callback_uri": "acp://openclaw:3000/callback"
  },
  "id": 1
}

近期二进制优化（v2026.3.22后）：ACP支持使用MessagePack序列化代替JSON，在大消息体（如文件附件）场景下可减少30%～50%传输大小。需在握手时协商Content-Type: application/msgpack。

序列化兼容性：OpenClaw和Hermes的ACP实现会自动降级——如果对方不支持MessagePack，则回退到JSON。

14.2.2 心跳保活与连接管理

为防止网络中间设备（NAT、防火墙）切断长连接，ACP要求两端定期互发Ping/Pong帧：

心跳间隔：默认30秒，可通过acp.heartbeat_interval调整。
超时检测：连续3次Ping无响应，判定连接断开，触发重连。
重连策略：指数退避（1s, 2s, 4s…），最大间隔60秒。

配置示例（OpenClaw端，openclaw.json） ：

json

{
  "acp": {
    "connections": [{
      "name": "hermes",
      "transport": "stdio",
      "heartbeat_interval": 30,
      "timeout": 10
    }]
  }
}

14.2.3 流式回调机制

对于耗时任务（如回测、大文件分析），ACP支持Hermes在执行过程中主动推送中间状态。

实现方式：

OpenClaw在发起请求时提供callback_uri参数（通常是acp://openclaw:port/callback）。
Hermes在任务执行中可以多次调用该callback URI，推送进度消息或中间结果。
OpenClaw收到后可以将进度实时转发到用户消息渠道（如飞书）。

进度消息格式：

json

{
  "jsonrpc": "2.0",
  "method": "progress/update",
  "params": {
    "request_id": 1,
    "stage": "downloading_file",
    "percent": 30,
    "message": "正在下载CSV文件..."
  }
}

沈飞注：量化回测场景下，流式回调极大改善了用户体验。用户不用再焦虑地等待10分钟，而是每隔1分钟收到一条“回测进行中…”的提示。我们会在实盘环境中强制要求所有耗时超过30秒的ACP请求都必须实现progress回调。

✏️ 即时自测：ACP协议支持哪两种序列化格式？

✏️ 自测答案：JSON（默认）和MessagePack（需协商）。

🛠️ 实践任务（本节）：抓取一次OpenClaw与Hermes之间的ACP通信包（可使用Wireshark或tcpdump），查看实际传输的JSON结构。

💭 本节总结（不看书写3行）：

📊 用时记录：计划____min → 实际____min → 偏差原因：________

14.3 安装部署完整步骤

🎯 本节目标：按照步骤配置OpenClaw与Hermes之间的ACP连接，并验证通信正常。

预计时长：1.2小时

14.3.1 前置条件检查

OpenClaw和Hermes都已正常启动（hermes gateway status / openclaw gateway status）
两者能互相访问（如果使用TCP transport，确保防火墙开放端口）
至少有一个消息渠道（如飞书）可以用于测试

14.3.2 方式一：stdio通信（推荐、最简配置）

stdio方式适用于OpenClaw和Hermes运行在同一台机器上，通过子进程管道通信，无需网络配置。

步骤1：确认Hermes的ACP模式已启用

在Hermes端，不需要额外启动服务。Hermes的ACP Client模式默认启用，只需确保hermes命令在PATH中。

步骤2：配置OpenClaw的ACP连接

编辑~/.openclaw/openclaw.json，添加acp配置段：

json

{
  "acp": {
    "connections": [
      {
        "name": "hermes-local",
        "transport": "stdio",
        "command": "hermes",
        "args": ["acp", "serve"],
        "env": {
          "HERMES_CONFIG_PATH": "/home/user/.hermes/config.yaml"
        }
      }
    ]
  }
}

参数说明：

transport: "stdio"：通过子进程标准输入/输出通信
command：启动Hermes ACP服务进程的命令
args：传递给hermes的子命令（acp serve）
env：可选，用于指定Hermes配置文件路径

步骤3：重启OpenClaw Gateway

bash

openclaw gateway restart

查看日志确认ACP连接建立：

bash

openclaw logs --follow | grep -i acp

应看到类似输出：

[INFO] ACP connection 'hermes-local' established
[INFO] Hermes reported tools: [web_search, file_read, code_execute, ...]

步骤4：测试通信

通过OpenClaw发送一条消息，强制委托给Hermes：

bash

openclaw message send --agent default --message "请使用Hermes帮我计算 1234 * 5678"

（如果OpenClaw默认不会自动委托，可以通过Agent配置或手动调用ACP工具测试）

14.3.3 方式二：TCP通信（跨机器部署）

当OpenClaw和Hermes不在同一台机器时，使用TCP transport。

步骤1：在Hermes端启动ACP服务器

bash

hermes acp serve --listen tcp://0.0.0.0:50051

也可以后台运行：

bash

tmux new -d -s hermes-acp 'hermes acp serve --listen tcp://0.0.0.0:50051'

步骤2：配置OpenClaw连接

json

{
  "acp": {
    "connections": [
      {
        "name": "hermes-remote",
        "transport": "tcp",
        "address": "192.168.1.100:50051",
        "tls": false
      }
    ]
  }
}

步骤3：防火墙配置

确保Hermes服务器的50051端口可以从OpenClaw所在机器访问。

14.3.4 技能一键迁移：`hermes claw migrate`

如果你已经为OpenClaw积累了大量Skill（位于~/.openclaw/workspace/skills/），可以使用hermes claw migrate将它们转换为Hermes兼容格式并复制到~/.hermes/skills/。

重要：迁移不会删除OpenClaw中的原始Skill，而是复制一份并做格式转换。

步骤1：预览迁移（不实际执行）

bash

hermes claw migrate --source ~/.openclaw/workspace/skills --dry-run

输出会显示将迁移哪些Skill、哪些可能不兼容。

步骤2：执行迁移

bash

hermes claw migrate --source ~/.openclaw/workspace/skills

默认会将转换后的Skill安装到~/.hermes/skills/。

步骤3：验证迁移结果

bash

hermes skills list

应能看到从OpenClaw迁移过来的技能（通常名称保持不变）。

龙马注：hermes claw migrate是混合部署的第一步。迁移后，你可以在Hermes中利用自动技能改进机制来优化这些Skill，然后通过ACP反向共享给OpenClaw。这种“生态反哺”是双Agent协作的高级形态。

14.3.5 验证协作功能

创建一个简单的测试：让OpenClaw自动将数学计算任务委托给Hermes。

方法1：在OpenClaw的AGENTS.md中增加一条规则：

markdown

## 委托规则
- 如果用户消息包含“计算”、“分析”、“研究”等关键词，使用`acp_delegate`工具将任务发送给Hermes。

方法2：直接通过OpenClaw CLI测试ACP工具：

bash

openclaw acp call --connection hermes-local --method agent/delegate --params '{"task":"计算100+200"}'

应能看到Hermes执行并返回结果。

✏️ 即时自测：hermes claw migrate命令的--dry-run参数作用是什么？

✏️ 自测答案：预览迁移效果，不实际复制/转换文件，用于检查兼容性。

🛠️ 实践任务（本节）：完成stdio方式ACP连接配置，并通过一次简单任务验证通信成功。

💭 本节总结（不看书写3行）：

📊 用时记录：计划____min → 实际____min → 偏差原因：________

14.4 协作任务调度

🎯 本节目标：掌握ask、delegate两种任务调度模式的区别，学会设置任务优先级队列。

预计时长：0.5小时

14.4.1 直接提问（ask）：同步等待结果

ask模式是同步阻塞调用：OpenClaw向Hermes发送请求，等待完整结果返回后再继续。

适用场景：

任务执行时间较短（< 10秒）
用户期望立即得到答案
简单计算、信息查询

API使用示例：

bash

openclaw acp call --method agent/ask --params '{"task":"什么是ACP协议？"}' --wait

优缺点：

✅ 简单、直观
❌ 阻塞主会话，不能处理长时间任务

14.4.2 结构化委托（delegate）：异步回调

delegate模式是异步非阻塞：OpenClaw提交任务后立即返回一个task_id，Hermes执行完毕后通过回调通知OpenClaw。

适用场景：

任务执行时间长（> 10秒）
用户不需要实时等待，可以稍后推送结果
批量任务

流程：

OpenClaw调用agent/delegate，提供callback_uri
Hermes返回task_id
OpenClaw可以继续处理其他消息
Hermes执行完成后，向callback_uri发送结果

API使用示例：

bash

openclaw acp call --method agent/delegate --params '{"task":"回测策略三年数据","callback_uri":"acp://openclaw:3000/callback"}'

14.4.3 优先级队列管理

当多个任务同时涌入时，需要设定优先级以保证关键任务优先执行。

在OpenClaw侧配置优先级映射：

yaml

# openclaw.yaml
acp:
  priority_rules:
    - pattern: "风控|止损|警报"
      priority: 10
    - pattern: "交易|下单"
      priority: 9
    - pattern: "回测|分析"
      priority: 5
    - pattern: ".*"
      priority: 0

在Hermes侧接收优先级：

Hermes的ACP服务支持priority字段，会将其映射到内部队列。默认队列处理顺序：

高优先级（>7）立即调度
普通优先级（4-7）进入队列，按FIFO
低优先级（<4）仅在系统空闲时执行

沈飞注：在量化实盘中，我们将“风控告警”优先级设为最高（10），确保即使系统繁忙，告警也能立即处理。交易信号次之（9），回测任务优先级最低（3）。这样可以在收盘后批量跑回测，不会干扰盘中关键任务。

✏️ 即时自测：delegate模式和ask模式的核心区别是什么？

✏️ 自测答案：ask同步等待结果，阻塞；delegate异步提交，立即返回，结果通过回调推送。

🛠️ 实践任务（本节）：

分别使用ask和delegate模式执行一个耗时较长的任务，对比体验差异。
配置一个优先级规则，测试高优先级任务能否抢占队列。

💭 本节总结（不看书写3行）：

📊 用时记录：计划____min → 实际____min → 偏差原因：________

14.5 ACPC底层通信优化与企业版适配指南

🎯 本节目标：了解ACP通信底层的性能优化选项，以及企业级部署时需要考虑的安全和扩展问题。

预计时长：0.5小时

本节内容主要面向企业生产环境，个人开发者可先跳过。

14.5.1 直连模式 vs 网关中转模式

模式	描述	适用场景
直连模式	OpenClaw与Hermes直接建立TCP连接	同一内网、低延迟要求
网关中转模式	通过一个中间代理（如Nginx、Envoy）转发ACP流量	跨VPC、需要TLS终止、负载均衡

直连模式配置：已在14.3.3节介绍。

网关中转模式配置示例（Nginx） ：

nginx

stream {
    upstream acp_backend {
        server 192.168.1.100:50051;
    }
    server {
        listen 50051;
        proxy_pass acp_backend;
    }
}

OpenClaw连接地址改为Nginx的地址即可。

14.5.2 防火墙与企业内网部署要点

端口要求：默认50051（可自定义），需在防火墙开放。
TLS加密：生产环境建议启用tls: true并提供证书（cert_file和key_file）。
代理穿透：某些企业网络要求出站流量走HTTP代理，ACP支持HTTP_PROXY环境变量，但建议使用stdio模式绕过代理限制。

14.5.3 ACP Client生态：ACP UI / WeChat ACP / VS Code ACP

除了OpenClaw和Hermes，社区还开发了多种ACP客户端，方便调试和管理：

工具	功能	项目地址
ACP UI	图形化ACP连接管理、消息监视	https://github.com/acp-ui/acp-ui
WeChat ACP	微信小程序接入ACP	https://github.com/acp-wechat/wechat-acp
VS Code ACP	在VSCode中直接调用ACP Agent	扩展市场搜索“ACP Agent”

这些工具可以作为OpenClaw的补充，用于快速测试ACP连接或开发新的Client。

龙马注：ACP UI是我排查连接问题时最常用的工具。它展示每个请求的耗时、序列化大小、是否触发重连等指标，比翻日志高效得多。

🛠️ 实践任务（本节）：（可选）尝试使用ACP UI连接到你搭建的ACP服务，观察消息监控面板。

💭 本节总结（不看书写3行）：

📊 用时记录：计划____min → 实际____min → 偏差原因：________

第14章参考资料与扩展阅读

ACP协议官方规范（OpenClaw Docs） https://docs.openclaw.ai/zh-CN/protocol/acp-spec
Hermes Agent ACP集成文档 https://hermes-agent.nousresearch.com/docs/features/acp
ACP二进制序列化性能报告（MessagePack vs JSON） https://openclaw.com/blog/acp-msgpack
hermes claw migrate完整指南 https://www.ai-indeed.com/encyclopedia/19598.html
企业级ACP部署最佳实践（Nginx + TLS） https://www.volcengine.com/docs/87732/2277059
ACP UI 使用教程 https://github.com/acp-ui/acp-ui/blob/main/README.md

第14章综合实践

任务：完成以下所有检查项，并记录输出。

选择并配置一种ACP连接方式（stdio或TCP），验证openclaw acp call能成功调用Hermes。
执行一次hermes claw migrate --dry-run，预览可迁移的Skill。
创建一个简单的委托任务（例如“计算数学表达式”），通过OpenClaw触发，观察Hermes执行结果。
（可选）配置优先级规则，提交两个不同优先级的任务，验证队列顺序。
（可选）使用ACP UI连接，查看至少一次请求的详细信息。

完成后，保存配置文件和ACP测试日志，命名为chapter14_acp_setup.txt。

龙马的评审：

14.3节的hermes claw migrate在实际使用中要注意：某些OpenClaw Skill可能依赖特定的环境变量或脚本路径，迁移后需要手动调整SKILL.md。建议你在迁移后，先hermes skills list确认技能加载，然后选一个最简单的Skill测试运行。如果遇到“command not found”之类的错误，检查SKILL.md中的scripts/路径是否需要修改。

关于14.5节的ACP UI，我补充一句：初次配置AC连接时，最好先用acp-ui的模拟客户端模式（不连真实Agent）熟悉界面，然后再连你的测试环境。ACP UI的“消息历史”功能对于复现偶发问题非常有帮助，建议养成记录会话ID的习惯。

沈飞的评审：

在实盘环境中，我推荐使用直连模式 + TLS，并将OpenClaw和Hermes部署在同一内网的不同机器上。这样既能隔离风险（若OpenClaw被攻击，Hermes仍在内网安全），又保证了通信延迟最低。

对于优先级队列，我们每周会复盘一次任务统计，根据实际延迟动态调整优先级数值。例如，我们发现“因子回测”任务经常被高优先级告警阻塞，于是将回测的优先级从3提升到5，并增加了晚间专有的批处理窗口。建议读者也建立类似的定期优化机制。

最后，hermes claw migrate是资产复用的利器，但迁移后的Skill建议先在Hermes的experimental模式下试运行一周，确认无误后再正式启用。我们在迁移首批50个Skill时，有3个因为依赖了OpenClaw特有的全局变量而出错，如果直接在生产环境使用会出问题。

下一章预告：第15章协作模式实战 —— 你将亲手配置规划者-执行者模式、定时监控与巡检、深度研究与内容处理、代码开发与审查，以及新增的“零代码联动与技能一键迁移实践”章节。这些模式可以直接应用到你的日常工作中。

文章版权归作者所有，未经允许请勿转载。

THE END