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 的四大设计原则：

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

import { Type } from '@sinclair/typebox'

export const ChatSendParams = Type.Object({
  sessionKey: Type.String(),
  message: Type.Optional(Type.String()),
  attachments: Type.Array(AttachmentSchema),
  timeoutMs: Type.Optional(Type.Number({ minimum: 1000, maximum: 300000 })),
  idempotencyKey: Type.Optional(Type.String())
})