很多人第一次在 OpenClaw 里接 Claude Code、Codex 这类外部代码 agent 时，默认都会先走一条“看起来最自然”的路：直接使用 ACP runtime，把 agent 开在线程里，像聊天一样持续协作。

这条路当然很优雅，但现实是——它并不总是最容易落地。

尤其是在某些聊天 surface 或特定运行环境下，ACP thread/session 可能因为 binding 限制、线程支持不完整、上下文管理差异等原因，表现得不够稳定。这个时候，如果还一味死磕“原生 thread 模式”，往往会把大量时间花在排障上，而不是把 agent 真正接通。

所以我越来越倾向于一个更务实的判断：

先把 agent 调通，比先把形式做漂亮更重要。

这也是为什么，direct acpx 这条路值得单独写一篇。

direct acpx 是什么？

可以把它理解成一种“电话转接”模式。

正常情况下，你可能希望 OpenClaw 直接托管一个 ACP thread/session，让 Claude Code 或 Codex 像平台原生角色一样挂在线程里持续对话。

而 direct acpx 的思路是：

用户 → OpenClaw 主会话 → acpx → 外部代码 agent

也就是说：

  • 用户还是正常在聊天里给 OpenClaw 下指令
  • OpenClaw 不走 ACP thread/session
  • 而是在后台通过 acpx CLI 调用 Claude Code 或 Codex
  • 再把结果返回给用户

社区里有时也会把这条路叫作：

  • telephone-game
  • direct acpx

名字听上去不那么“官方”，但它有一个非常现实的优点：

简单、直接、容易验证。

为什么这条路值得优先考虑？

因为很多时候，你遇到的真正问题不是“Claude Code 能不能用”，而是：

  • 当前聊天 surface 对 ACP thread 的支持是否完整
  • runtime thread 是否能正确绑定
  • 会话生命周期是否可控
  • provider 授权与平台侧状态是否叠加出问题

当这些问题缠在一起时，排障会变得非常痛苦。

而 direct acpx 的好处是，它把链路拆得非常清楚：

  1. acpx 在不在
  2. 目标 agent CLI 在不在
  3. provider 是否已登录
  4. provider 当前是否有额度
  5. 当前 workspace 能不能被正确读取

这意味着你可以一层一层验证，而不是一上来就被 thread/session 生命周期困住。

对于刚开始接入外部代码 agent 的人来说，这条路通常更容易成功。

什么时候适合用 direct acpx？

如果你遇到下面这些情况，建议优先考虑：

  • 当前平台对 ACP thread/session 支持不完整
  • sessions_spawn(runtime="acp") 起不来
  • 你想先快速验证 Claude Code / Codex 是否接通
  • 你更重视“先跑起来”，而不是“先做成原生线程体验”
  • 你想统一接入多个代码 agent，减少额外心智负担

反过来说，如果你的环境里 ACP thread/session 已经非常稳定，而且你也明确依赖 OpenClaw 原生的会话生命周期管理，那当然可以继续优先用 runtime path。

direct acpx 不是为了替代所有场景，而是为了在“不稳定”或“刚起步”的阶段，提供一条更容易落地的路。

开始之前，需要准备什么？

1. 安装 @openclaw/acpx 扩展

如果还没安装，可以先执行：

openclaw plugins install @openclaw/acpx

它的作用，是给 OpenClaw 提供与 acpx 协作的能力，并维护兼容版本关系。

2. 准备 acpx

这里有一个很重要的建议：

优先使用 plugin-local 的 acpx，而不是默认依赖全局 PATH。

原因很简单：

  • 更容易与扩展版本保持一致
  • 更适合长期维护
  • 更容易排障
  • 不容易被全局 npm 升级意外打坏

如果扩展目录下没有对应 binary，可以进入目录后按 pinned version 安装：

npm install --omit=dev --no-save acpx@<pinnedVersion>

然后验证：

./node_modules/.bin/acpx --version

3. 安装目标 agent CLI

根据你要接入的 agent，准备相应 CLI：

  • Claude Code CLI
  • Codex CLI
  • 或其他 acpx 支持的 agent

这里的关键不是“装了某个包就一定能用”，而是后面要能确认：

  • CLI 确实存在
  • 当前用户可见
  • 登录态可用

4. 完成 provider 登录 / 授权

这是新手最容易忽略的一步。

很多人看到 acpx 已经安装成功，就会以为整条链路应该能跑通。但实际上，如果 Claude / Codex 自己还没有登录成功，或者虽然登录了但当前额度不足，那么最后一样会失败。

常见信号非常明确：

  • Authentication required

    • 通常说明 CLI 和 acpx 可能都没问题，但 provider 登录态还没接好

  • You've hit your limit ...

    • 通常说明链路已经成功打到 provider，当前只是额度或限流问题

看懂这两种错误，排障就会快很多。

一个非常容易踩的配置坑

如果你在 OpenClaw 配置里写权限，最容易犯的错误是把 key 写错位置。

错误写法：

{
  "acp.permissionMode": "approve-all"
}

正确写法应该是：

{
  "extensions": {
    "acpx": {
      "permissionMode": "approve-all"
    }
  }
}

也就是：

extensions.acpx.permissionMode = "approve-all"

不是：

acp.permissionMode = "approve-all"

这个细节很小，但如果写错了，后面很多现象会变得很迷惑。

推荐的命令参数

无论你最终调用的是 Claude Code 还是 Codex，我都建议尽量显式带上下面这些参数：

--cwd <workspace>
--approve-all
--format quiet
--timeout <seconds>

它们各自解决的是非常具体的问题：

  • --cwd <workspace>：告诉 agent 当前工作目录，避免脱离项目上下文
  • --approve-all：避免交互式审批打断流程
  • --format quiet：输出更干净，便于直接转发
  • --timeout <seconds>：避免命令卡住太久

这些参数看起来琐碎，但实际使用时，能帮你省掉很多莫名其妙的排障时间。

最小验证：先别急着做复杂任务

接外部 agent 时，我很建议先做两轮最小验证。

第一步：验证 agent 是否能回一句固定话

以 Codex 为例：

$ACPX_CMD \
  --cwd <workspace> \
  --approve-all \
  --format quiet \
  --timeout 90 \
  codex exec "Reply with exactly: CODEX_OK"

Claude 也是同样的思路：

$ACPX_CMD \
  --cwd <workspace> \
  --approve-all \
  --format quiet \
  --timeout 90 \
  claude exec "Reply with exactly: CLAUDE_OK"

如果这一步都没通，就先不要往下走。

第二步：验证它能不能真的读你的 workspace

比如：

$ACPX_CMD \
  --cwd <workspace> \
  --approve-all \
  --format quiet \
  --timeout 120 \
  codex exec "List the filenames under <target-dir> and summarize them in bullet points."

这一步的价值在于：

  • 不是只验证 provider 返回一句话
  • 而是真正验证 agent 是否能在你指定的 workspace 里工作

很多时候，真正的问题不在“能不能回复”，而在“能不能正确读到文件”。

两种常用工作模式

模式一：one-shot

如果你只是：

  • 查一个文件
  • 做一次总结
  • 跑一个小任务
  • 快速判断是否接通

那最简单的方式就是 one-shot：

acpx <agent> exec "..."

例如：

acpx codex exec "Summarize this file"

这类场景下，one-shot 足够，而且最省心。

模式二：persistent session

如果你要做的是：

  • 多轮连续协作
  • 持续写代码 / 改代码
  • 连续追问同一个问题
  • 保留 agent 上下文

那就更适合 session 模式。

创建 session：

acpx codex sessions new --name my-codex-session

后续持续对话：

acpx codex -s my-codex-session --cwd <workspace> --format quiet "Read the project and tell me the top 3 risks."

继续追问：

acpx codex -s my-codex-session --cwd <workspace> --format quiet "Now give me mitigation ideas."

结束后关闭：

acpx codex sessions close my-codex-session

Claude 的用法完全相同，只需要把 codex 换成 claude。

一个小建议：session 名称要统一

如果你后面会频繁使用 session，最好一开始就约定统一命名规则，比如：

oc-<agent>-<task>

例如：

oc-codex-refactor
oc-claude-docs
oc-codex-debug

这样后面查看 session、取消任务、清理上下文时都会轻松很多。

常见错误，应该怎么判断？

1. Authentication required

通常意味着：

  • CLI 可能已经装好了
  • acpx 路径也可能没问题
  • 但 provider 登录态还没真正接好

这种情况下，不要先去怀疑 acpx 本身，优先检查授权。

2. You've hit your limit ...

通常意味着：

  • 链路已经打到 provider
  • 当前问题是额度或限流
  • 不是安装问题

这时候继续折腾安装，通常是无效劳动。

3. 找不到 acpx

通常意味着：

  • plugin-local acpx 没装好
  • 命令路径写错
  • 当前 shell 环境不对

最直接的办法，就是先单独验证：

./node_modules/.bin/acpx --version

4. OpenClaw ACP runtime 起不来

这并不一定说明 Claude Code 或 Codex 本身有问题。

很多时候，只是当前平台对 ACP thread/session 支持不完整。

如果你已经明确碰到这类限制，与其一直卡在 runtime thread，不如直接切到 direct acpx。

对新手来说，最推荐的落地顺序

如果你第一次接这套链路，我建议按下面这个顺序来：

第一步：先验证链路

acpx codex exec "Reply with exactly: OK"

或：

acpx claude exec "Reply with exactly: OK"

第二步：再验证 workspace

acpx codex exec "Read <file> and summarize it"

第三步：最后再决定要不要上 session

如果只是偶尔用一下，one-shot 足够。

如果要连续协作，再切 persistent session。

这个顺序看起来保守，但实际最省时间。

这套方案的优点和局限

优点

  • 简单直接
  • 更容易排障
  • 可统一调用多个代码 agent
  • 不依赖 ACP thread binding

局限

  • 不是 OpenClaw 原生 ACP thread 会话
  • session 生命周期需要自己维护
  • provider 的登录态、额度问题仍需要单独处理

所以我对它的定位一直很明确：

它未必是“最优雅”的方案， 但在很多真实场景里，它是最容易成功的方案。

最后

如果你的目标是：

  • 尽快把 Claude Code / Codex 接通
  • 用一条更容易验证、更容易排障的路径先跑起来
  • 避免一开始就被 ACP thread/session 的兼容性问题困住

那么 direct acpx 非常值得优先尝试。

对很多人来说，真正重要的不是“这条路是否最原生”，而是：

它能不能在今天、在你的环境里，真的跑起来。

而 direct acpx 往往就是那条最先跑起来的路。