WeClaw如何用ACP协议与Claude对话:stdio JSON-RPC实现原理详解
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 之间的桥梁。整体架构如下图所示:
用户通过微信发消息 → 消息经 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,解析每行 JSONpendingmap:requestID → channel,将响应分派给对应的等待协程notifyChmap:sessionID → channel,将session/update通知推给正在收集回复的协程
子进程 stdout ──→ readLoop ──┬── 有 id、无 method?→ pending[id] 通道(唤醒请求方)
└── 有 method?→ 按 sessionID 分发到通知通道
四、完整对话流程:从启动到回复
4.1 启动子进程与 initialize 握手
Start() 方法(acp_agent.go#L215-L310)完成以下步骤:
- 创建子进程:
exec.CommandContext启动 ACP Agent 二进制(如claude-agent-acp),设置工作目录和环境变量 - 建立管道:获取 stdin/stdout 管道,启动
readLoopgoroutine - 握手:发送
initialize请求,携带协议版本(protocolVersion: 1)和客户端能力(文件系统读写支持) - 超时保护:握手有 30 秒超时,失败则终止子进程并返回错误
🔍 如果配置了
claudeCLI 而非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)是核心对话入口,流程如下:
- 获取/创建会话:
getOrCreateSession确保 sessionID 存在 - 注册通知通道:为该 sessionID 创建一个带缓冲(256)的 channel
- 异步发送 prompt:在 goroutine 中调用
session/prompt请求(阻塞直到 Agent 处理完毕) - 并发收集流式片段:主循环同时监听通知通道,收集所有
agent_message_chunk - 等待完成: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 桥接工具提供了参考范式。
