WeClaw如何用ACP协议与Claude对话:stdio JSON-RPC实现原理详解

原创2026-10-11 01:12:112,250 阅读

WeClaw如何用ACP协议与Claude对话:stdio JSON-RPC实现原理详解

WeClaw 是一款开源的微信 AI Agent 桥接器,它通过 ACP 协议(Agent Client Protocol)让微信用户直接与 Claude、Codex、Gemini 等 AI Agent 对话。本文深入解析 WeClaw 基于 stdio JSON-RPC 2.0 的 ACP 通信实现原理,带你理解一条微信消息是如何变成一次完整的 AI 对话的。

一、WeClaw 架构:一张图看懂全局

WeClaw 的核心定位是微信与 AI Agent 之间的桥梁。整体架构如下图所示:

WeClaw微信AI Agent桥接器ACP架构图:WeClaw连接微信与Claude等AI对话

用户通过微信发消息 → 消息经 ClawBot 中继到 WeClaw → WeClaw 路由到对应的 AI Agent(如 Claude Code)→ 回复原路返回。

WeClaw 支持三种 Agent 接入模式:

模式 工作方式 支持的 Agent
ACP 长驻子进程,JSON-RPC over stdio,复用会话,速度最快 Claude、Codex、Kimi、Gemini、Cursor 等
CLI 每条消息启动新进程,支持 --resume 恢复会话 Claude(claude -p)、Codex(codex exec)
HTTP OpenAI 兼容的 Chat Completions API OpenClaw(HTTP 回退)

💡 当 ACP 和 CLI 同时可用时,WeClaw 自动优先选择 ACP 模式。

二、ACP 模式为什么更快?

传统 CLI 模式每条消息都要冷启动一个新进程:

微信消息 → 启动 claude 进程 → 加载环境 → 执行 → 输出 → 进程退出

而 ACP 模式启动一个长驻子进程,进程存活期间反复复用:

微信消息 → 写入 stdin(JSON-RPC 请求)→ 读取 stdout(JSON-RPC 响应)→ 回复

核心优势:

  • ⚡ 零冷启动:子进程只启动一次,后续消息直接在已有进程内执行
  • 🔄 会话复用:sessionID 维持对话上下文,无需每次传历史
  • 📡 流式输出:通过 session/update 通知实时接收文本片段

三、stdio JSON-RPC:通信核心机制

ACP 模式的通信完全基于 JSON-RPC 2.0 over stdio,即通过子进程的标准输入(stdin)和标准输出(stdout)传输 JSON 消息。核心实现位于 agent/acp_agent.go。

3.1 NDJSON 传输格式

每条 JSON-RPC 消息占一行(Newline-Delimited JSON),写入 stdin 时自动追加换行符:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true}}}}

WeClaw 用 bufio.Scanner 按行读取 stdout,缓冲区设为 4MB 以支持大消息。

3.2 三类 JSON-RPC 消息

类型 特征 典型方法
Request 有 id + method,等待响应 initialize、session/new、session/prompt
Response 有 id + result/error,无 method 对请求的回复
Notification 有 method,无 id,无需回复 session/update、initialized

3.3 并发架构:单读循环 + 请求/通知分派

WeClaw 的 ACP 通信采用单读循环 + 多通道的并发模型(见 acp_agent.go#L691-L752):

  • readLoop:独占一个 goroutine,持续扫描 stdout,解析每行 JSON
  • pending map:requestID → channel,将响应分派给对应的等待协程
  • notifyCh map:sessionID → channel,将 session/update 通知推给正在收集回复的协程
子进程 stdout ──→ readLoop ──┬── 有 id、无 method?→ pending[id] 通道(唤醒请求方)
                             └── 有 method?→ 按 sessionID 分发到通知通道

四、完整对话流程:从启动到回复

4.1 启动子进程与 initialize 握手

Start() 方法(acp_agent.go#L215-L310)完成以下步骤:

  1. 创建子进程:exec.CommandContext 启动 ACP Agent 二进制(如 claude-agent-acp),设置工作目录和环境变量
  2. 建立管道:获取 stdin/stdout 管道,启动 readLoop goroutine
  3. 握手:发送 initialize 请求,携带协议版本(protocolVersion: 1)和客户端能力(文件系统读写支持)
  4. 超时保护:握手有 30 秒超时,失败则终止子进程并返回错误

🔍 如果配置了 claude CLI 而非 claude-agent-acp,WeClaw 会检测并给出明确提示:"claude CLI 不支持 ACP 协议,请安装 claude-agent-acp 并设置 command 为 claude-agent-acp"。

4.2 会话管理:conversationID → sessionID

WeClaw 为每个微信对话维护一个 conversationID(微信会话 ID),通过 session/new 请求将其映射到 ACP 的 sessionID(见 acp_agent.go#L462-L489):

第一次发消息:
  conversationID="wx123" → 发送 session/new → 获得 sessionID="abc"
  缓存: {"wx123": "abc"}

后续消息:
  conversationID="wx123" → 查缓存 → 复用 sessionID="abc"

在微信中发送 /new 命令时,ResetSession 会删除缓存并创建新会话,实现"清除对话历史"。

4.3 发送消息:session/prompt 与流式通知

Chat() 方法(acp_agent.go#L362-L460)是核心对话入口,流程如下:

  1. 获取/创建会话:getOrCreateSession 确保 sessionID 存在
  2. 注册通知通道:为该 sessionID 创建一个带缓冲(256)的 channel
  3. 异步发送 prompt:在 goroutine 中调用 session/prompt 请求(阻塞直到 Agent 处理完毕)
  4. 并发收集流式片段:主循环同时监听通知通道,收集所有 agent_message_chunk
  5. 等待完成:prompt 请求返回后,清空残留通知,拼接所有文本片段作为最终回复
WeClaw ──stdin──→ session/prompt {sessionID, prompt:[{type:"text", text:"你好"}]}
                  (阻塞等待响应)

WeClaw ←-stdout- session/update {sessionId, update:{sessionUpdate:"agent_message_chunk", text:"你"}}
WeClaw ←-stdout- session/update {sessionId, update:{sessionUpdate:"agent_message_chunk", text:"好"}}
...
WeClaw ←-stdout- 响应 {id, result:{stopReason:"end_turn"}}
                  → 拼接 "你好" 作为完整回复

4.4 权限自动审批

AI Agent 在执行工具调用前会发送 session/request_permission 请求。WeClaw 的处理策略是自动允许(acp_agent.go#L911-L954):解析请求中的选项列表,找到 kind: "allow" 的选项,立即回传 outcome: "selected"。

这使得 Agent 可以在微信场景中无需人工交互地执行文件读写、命令运行等操作。

五、多协议适配:不只是 legacy ACP

WeClaw 内置了协议自动检测机制(acp_agent.go#L175-L187),根据命令名和参数判断使用哪种协议:

  • legacy_acp(默认):标准 ACP 协议,用于 claude-agent-acp、codex-acp、cursor agent、kimi acp 等
  • codex_app_server:Codex 原生 app-server 协议,仅当命令为 codex 且参数包含 app-server 时触发

两种协议的方法映射:

功能 legacy_acp codex_app_server
创建会话 session/new thread/start
发送消息 session/prompt turn/start
流式通知 session/update item/agentMessage/delta
完成信号 prompt 响应 turn/completed

六、如何配置 ACP Agent?

ACP 模式的配置位于 ~/.weclaw/config.json,结构定义见 config/config.go。以 Claude 为例:

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-xxx" },
      "model": "sonnet"
    }
  }
}

关键字段说明:

字段 作用
type 设为 "acp" 启用 ACP 模式
command ACP Agent 二进制路径
args 额外启动参数(如 Cursor 需 ["acp"])
env 注入子进程的环境变量(API Key 等)
model 指定模型名称
cwd Agent 工作目录(默认 ~/.weclaw/workspace)

WeClaw 还支持自动检测本机已安装的 Agent(config/detect.go),检测优先级为 ACP > CLI。例如检测到 claude-agent-acp 会自动配置为 ACP 模式,无需手动填写。

七、源码导读:关键文件速查

文件 职责
agent/acp_agent.go ACP 协议核心实现:子进程管理、JSON-RPC 通信、会话管理
agent/agent.go Agent 接口定义:Chat、ResetSession、Info、SetCwd
agent/cli_agent.go CLI 模式实现(对比参考)
config/config.go 配置加载/保存,AgentConfig 结构定义
config/detect.go Agent 自动检测与协议优先级

总结

WeClaw 的 ACP 模式通过 JSON-RPC 2.0 over stdio 实现了高效的微信-AI Agent 桥接:

  • 长驻进程 避免冷启动开销
  • NDJSON 行协议 简单可靠,无需额外网络开销
  • 单读循环 + 通道分派 的并发模型清晰易维护
  • 协议自动检测 兼容多种 Agent 生态

理解这套机制,不仅能帮你更好地配置 WeClaw,也为开发类似的 Agent 桥接工具提供了参考范式。

登录后查看全文
weclaw