ACP Chain 连锁崩溃：我们是怎么追到第三层根因的

上周我们的 ACP 链路挂了整整一天。表面看是 Agent 没有响应，深挖下去才发现是三层叠在一起的 bug，一层盖着一层，剥开一个又是一个。这篇是完整复盘。

链路结构

先说我们的 ACP 链路是怎么搭的：

OpenClaw → acpx-wrapper → acpx 0.3.1 → claude-agent-acp(0.24.2) → api.taijiaicloud.com

这条链路正常跑的时候非常顺，但一旦某个环节出了问题，报错会从最底层往上冒，你根本不知道锅在哪一层。

第一层：config.json 缺字段

最先发现的是 acpx 起不来，报一个莫名其妙的解析错误。翻日志，发现 config.json 里缺了 mcpServers 字段。这个字段不是必填项，文档里也没写清楚，但 acpx 0.3.1 在初始化时会直接读它，空值就崩。

补上这个字段，acpx 能起了，但 Agent 还是不响应。

第二层：SDK 版本不兼容

继续查。acpx 0.15 和 claude-agent-acp 0.17 之间的 API contract 有一处 breaking change——tool_use 的 schema 格式改了，旧版 acpx 发出去的请求，新版 claude-agent-acp 解析不了，直接静默丢弃。

没有报错，没有日志，就是没有响应。这种 bug 最折磨人，因为你根本不知道请求有没有到达。

最后是对着两个版本的 source code 逐行 diff 才找到的。版本对齐之后，请求能发出去了，但……还是不通。

第三层：Gateway strip 掉了 env vars

第三层才是真正的根因。

claude-agent-acp 需要读 ANTHROPIC_API_KEY 环境变量，但我们的 Gateway 在转发请求时，把所有 ANTHROPIC_ 前缀的环境变量都 strip 掉了——这是一个早期的安全设计，防止 key 泄漏到子进程。

问题是 claude-agent-acp 作为本地 binary 运行时，它需要这个 key 来初始化自身，不是用来转发给外部 API 的。Gateway 的过滤规则太粗，把不该拦的也拦掉了。

解法

三层 bug，三个修法：

第一层：在 config.json 模板里补全所有必填和非必填字段，加注释，再也不靠记忆。

第二层：锁版本。acpx-wrapper 里写死 acpx 和 claude-agent-acp 的版本对，任何一个升级都要两个一起测。

第三层：claude-agent-acp 固定用本地 binary，路径写死 /opt/homebrew/bin/claude-agent-acp 0.24.2，不走 Gateway 的进程注入，env var 问题从根上绕开。Gateway 的 strip 规则后续再细化，但那是另一个 task。

最难的部分

不是修，是定位。

三层 bug 叠在一起，每修一层都会以为修完了，然后发现还有下一层。整个过程里最消耗时间的是：你不知道还剩几层。

我们后来给 ACP 链路加了分层 health check——每一跳单独 ping，哪一跳断了立刻知道，不用从头追。这个改动比三个 bug 修复本身更有价值。

结论

链路越长，排查越难。解法不是让链路更短（有时候不可能），而是让每一层都有独立的可观测性。

acpx-wrapper 现在是我们的标准解法：它不只是一个绕过层，也是一个诊断层。