ACP 链条级联故障：一个 bug 我们追了三层深

上周我们的 ACP 流水线瘫了整整一天。表面上看，就是 agents 不回消息。往深挖，是三个 bug 叠在一起，每一个都把下一个藏得更深。这篇是完整的 postmortem。

这条链路的结构

先交代一下我们 ACP 链条的结构：

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

这条链顺的时候，丝滑无比。一旦出问题，错误从最底层冒上来，你根本不知道到底是哪一层的锅。

最先发现的是 acpx 起不来，抛一个看不懂的 parse 错误。翻日志挖到根上：config.json 里少了 mcpServers。文档里说它不是必填字段，实际上基本没文档——但 acpx 0.3.1 启动时会无条件读它，值是空就直接崩。

补上字段，acpx 起来了。Agents 还是不回话。

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

没有报错。没有日志。就是一片安静。这是最恶心的 bug 类型——你连请求有没有到对面都没法确认。

我们是拿两个版本的源码一行一行 diff 才找到的。版本对齐之后，请求通了——但链路还是断的。

第三层才是真正的根因。

claude-agent-acp 启动时要读 ANTHROPIC_API_KEY 环境变量。而我们的 Gateway 在转发前会把所有 ANTHROPIC_ 前缀的变量剥掉——那是早前定的一个安全策略，防止密钥泄漏到子进程。

问题在于：claude-agent-acp 作为本地二进制运行时，它需要那个 key 来初始化自己，不是要把它转交给外部 API。Gateway 的过滤器一刀切太粗，把不该拦的也拦了。

三层问题，三个修法：

第一层：config.json 模板里把所有字段——必填和选填——全填上，配注释。不再依赖记忆，也不再依赖残缺的文档。

第二层：版本显式锁定。acpx-wrapper 现在硬编码 acpx 和 claude-agent-acp 的配对版本。任何一方要升级，两个必须在测试环境验证过才能上生产。

第三层：claude-agent-acp 固定走本地二进制 /opt/homebrew/bin/claude-agent-acp 0.24.2。完全绕开 Gateway 的进程注入，环境变量剥离自然就不生效了。Gateway 的过滤规则要细化，那是另一个排期的事。

难的不是修，是定位。

三个 bug 叠在一起，每修掉一个你以为完事了，然后发现底下还有一个。整个事故最耗时间的就是这一点：你不知道还剩几层。

事后我们给 ACP 链条加了逐跳健康检查。每一跳单独 ping。哪一跳挂了，一眼就知道是哪一跳。不用再从顶上往下追。这一个改动，比三个 bug 的修复加起来都值。

链条越长，调试越难。解法不是把链条缩短——有时候短不了——而是让每一层都能被独立观测。

acpx-wrapper 现在是我们的标准方案：不只是一个绕行层，更是一个诊断层。