ACP 协议设计哲学 —— 为什么 OpenClaw 选择自研 Agent Client Protocol

关键词：ACP｜Agent Client Protocol｜JSON-RPC 扩展｜TypeBox｜流式通信｜多端同步

在构建一个支持 WhatsApp、Telegram、Web、iOS、Android 和 CLI 的 AI 智能体系统时，通信协议的选择直接决定了系统的扩展性、一致性与开发效率。

OpenClaw 没有采用现成的 gRPC、GraphQL 或 REST，而是基于 JSON-RPC 2.0 扩展出一套专为 AI Agent 场景定制的轻量级协议——ACP（Agent Client Protocol）。这并非“重复造轮子”，而是一次面向领域特性的精准设计。

本文将揭示：为什么通用协议不够用？ACP 解决了哪些 AI 原生问题？以及它是如何保障类型安全与多端一致性的。

一、通用协议为何“水土不服”？

1. REST / HTTP —— 请求-响应模型的局限

• ❌ 不支持服务端主动推送（如工具调用进度、思考过程）
• ❌ 难以表达流式输出（Streaming），需依赖 SSE 或长轮询
• ❌ 无内置幂等性或会话上下文概念

对 AI 而言，“发送消息”只是开始，后续可能有多轮 tool_call → observation → text.delta 事件流。

2. gRPC —— 强大但过重

• ✅ 支持双向流、强类型、高效序列化
• ❌ 依赖 Protobuf，前端（JS/TS）集成复杂
• ❌ 调试困难：二进制格式无法直接阅读
• ❌ 跨平台成本高：iOS/Android 需生成客户端 stub

OpenClaw 需要的是“人类可读 + 机器可靠”的平衡。

3. GraphQL —— 查询语言 ≠ 控制协议

• ✅ 灵活查询
• ❌ 本质仍是请求-响应，不擅长表达异步事件
• ❌ 缺乏对命令式操作（如 exec, abort）的自然建模

二、ACP 的设计原则：为 AI Agent 量身定制

OpenClaw 团队提出 ACP 的四大设计原则：

image

💡 ACP = JSON-RPC 2.0 + WebSocket + AI 原生语义扩展

三、ACP 核心机制详解

1. 基础结构：兼容 JSON-RPC 2.0

所有请求遵循标准格式：

{
  "jsonrpc": "2.0",
  "method": "chat.send",
  "params": { /* ... */ },
  "id": "req_abc123"
}

• method：RPC 方法名（如 agent.run, config.get）
• params：参数对象
• id：用于匹配响应（支持幂等性）

2. 服务端事件推送（非请求-响应）

当智能体执行过程中产生新状态，网关主动推送事件：

{
  "event": "assistant.text.delta",
  "payload": {
    "runId": "run_xyz789",
    "delta": "正在重启服务器..."
  }
}

常见事件类型：

• assistant.text.delta：AI 生成文本片段
• tool.call.request：AI 请求调用工具（如 bash_exec）
• tool.call.result：工具执行结果返回
• agent.lifecycle：start / end / error

🔄 这使得 Web UI 可实时渲染“打字机效果”或“工具调用卡片”。

3. 幂等性与任务追踪

• 每个 chat.send 可携带 idempotencyKey
• 网关缓存结果，防止网络重试导致重复执行
• 所有事件携带 runId，客户端可关联完整执行链

4. 错误模型标准化

ACP 定义统一错误码：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Model context overflow",
    "data": { "model": "claude-3-5-sonnet" }
  },
  "id": "req_abc123"
}

常见错误码：

• -32001：上下文溢出（触发自动压缩）
• -32002：需要用户审批（弹出确认框）
• -32003：账号限流（触发换号逻辑）

四、TypeBox：实现端到端类型安全

OpenClaw 使用 TypeBox 定义所有 ACP 方法的参数与响应结构。

示例：chat.send 参数 Schema

// src/acp/schemas/chat.ts

优势：

1. 运行时校验：网关收到请求后自动验证参数合法性
2. 编译时类型：ui/ 和 apps/ios/ 可导入该 Schema，获得 TypeScript 类型提示
3. 文档自动生成：结合 Swagger 可输出 API 文档

🔒 从源头杜绝“字段不存在”或“类型错误”类 bug。

五、ACP 如何支撑多端一致性？

由于所有客户端（Web/iOS/Android/CLI）都实现同一套 ACP 协议，它们天然具备功能对齐：

image

🧩 协议即契约——只要遵守 ACP，任何新客户端都能立即获得全部能力。

六、ACP vs 其他 AI 协议（对比视野）

image

✅ ACP 的独特价值在于：它连接了“渠道 ↔ 模型 ↔ 工具”全链路。

结语：协议是系统的“宪法”

在 OpenClaw 中，ACP 不仅是通信格式，更是系统架构的约束与保障。它强制解耦了渠道、协议、智能体三层，使得：

• 渠道开发者无需懂 LLM
• 智能体开发者无需关心 WhatsApp 协议
• 客户端开发者只需实现一套协议

这种“协议优先”（Protocol-First）的设计哲学，正是 OpenClaw 能够快速扩展到多端、多渠道、多模型的核心秘密。

在下一篇文章中，我们将聚焦 OpenClaw 的启动与配置体系，解析 openclaw.mjs、config.yaml 与环境变量如何协同工作。

✅ 下一篇预告： 第 4 篇：启动与配置体系 —— openclaw.mjs、config.yaml 与环境变量管理

如需，我可立即为您生成 第 4 篇全文，或提供本文的 Markdown 源码、TypeBox 示例代码 等。是否继续？