第一层：命令能不能执行#

比如：

• opencode 在不在 PATH
• 手动敲命令有没有版本输出

第二层：OpenClaw 能不能把它当作 ACP runtime 调度起来#

这又是另一件事。

sessions_spawn(runtime="acp", agentId="opencode") 走的不是普通 shell 命令调用，而是：

• ACP runtime backend
• agent/harness 映射
• Gateway / runtime 配置
• 后端插件加载

如果这一层没配，哪怕 opencode 本体再正常，OpenClaw 也还是会报：

1
ACP runtime backend is not configured

这也是这次问题的核心。

1. openclaw.json 里完全没有 acp 顶层配置#

也就是说，当时配置里根本没有类似这些东西：

1
{
2
  "acp": {
3
    "enabled": true,
4
    "backend": "acpx",
5
    "defaultAgent": "opencode"
6
  }
7
}

如果这层没写，OpenClaw 就根本不知道：

• ACP 是否启用
• 默认 backend 是谁
• 默认 agent 应该映射到哪个 harness

2. acpx 插件虽然存在，但它是 disabled#

我又去看了插件状态：

1
openclaw plugins list

结果里能看到一项很关键的条目：

• ACPX Runtime | acpx | disabled

也就是说：

• OpenClaw 这版其实自带 ACPX Runtime 插件
• 但它当时并没有启用

这一步基本就把问题锁死了。

因为文档里已经说得很明白：

ACP runtime backend is not configured 通常意味着 backend plugin missing or disabled

换句话说，真正的根因是：

• opencode 命令本身没问题
• 但 OpenClaw 的 ACP backend 这层根本没接好

1. ACP 需要顶层 acp 配置#

文档示例里有一段非常关键的 baseline 配置，大意就是：

1
{
2
  acp: {
3
    enabled: true,
4
    dispatch: { enabled: true },
5
    backend: "acpx",
6
    defaultAgent: "codex",
7
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"]
8
  }
9
}

这说明：

• acp.enabled=true 是必须的
• backend 应该明确指向 acpx
• agent allowlist 也要覆盖到要使用的 harness

2. opencode 确实是 acpx 支持的 harness alias#

文档里还专门列了当前 acpx 内建支持的 harness alias：

• pi
• claude
• codex
• opencode
• gemini
• kimi

这一步很关键，因为它说明：

我不是在硬把一个不支持的命令往 ACP 里塞。

opencode 在这版文档语义里，确实是 ACPX backend 应该支持的 agent id。

3. acpx 插件本来就是官方推荐 backend#

文档里关于 plugin setup 也写得很直接：

• acpx 是 ACP backend plugin
• 要安装并启用
• 启用后 OpenClaw 才能把外部 harness 当作 ACP runtime 用

到了这里，问题基本已经从“猜测”变成“按图施工”。

第一层：补顶层 acp 配置#

我在 openclaw.json 里加上了类似这样的配置：

1
"acp": {
2
  "enabled": true,
3
  "dispatch": {
4
    "enabled": true
5
  },
6
  "backend": "acpx",
7
  "defaultAgent": "opencode",
8
  "allowedAgents": [
9
    "pi",
10
    "claude",
11
    "codex",
12
    "opencode",
13
    "gemini",
14
    "kimi"
15
  ],
16
  "maxConcurrentSessions": 8,
17
  "stream": {
18
    "coalesceIdleMs": 300,
19
    "maxChunkChars": 1200
20
  },
21
  "runtime": {
22
    "ttlMinutes": 120
23
  }
24
}

这层的作用就是：

• 打开 ACP 总开关
• 指定 backend 为 acpx
• 把 opencode 设成默认 agent
• 明确 allowlist，避免被策略层挡掉

第二层：启用 acpx 插件#

然后在插件配置里把 acpx 打开：

1
"plugins": {
2
  "allow": [
3
    "telegram",
4
    "openclaw-weixin",
5
    "acpx"
6
  ],
7
  "entries": {
8
    "acpx": {
9
      "enabled": true,
10
      "config": {
11
        "permissionMode": "approve-all",
12
        "nonInteractivePermissions": "deny"
13
      }
14
    }
15
  }
16
}

这里我还顺手加了非交互权限策略。

因为 ACP session 是没有 TTY 的，如果后端 runtime 遇到权限提示，又没有明确策略，就很容易卡在“等待交互确认但根本没人能确认”的尴尬状态。

1. 命令存在，不等于 runtime 就已经接好了#

这是最容易让人误判的地方。

• opencode 在 PATH 里
• opencode --version 能跑

只能说明：

命令本体可用

但这和：

OpenClaw 能不能把它当作 ACP runtime 调度

是两回事。

2. 看到 ACP runtime backend is not configured，优先去查 plugin 和 ACP 顶层配置#

这类报错不要继续死盯 opencode 本身。

更应该先查：

• acp.enabled
• acp.backend
• acp.allowedAgents
• plugins.entries.acpx.enabled
• openclaw plugins list

尤其是最后这个命令，信息量很大。

3. disabled 和 loaded 差别非常大#

在 OpenClaw 里，配置写上去不等于运行态已经生效。

如果插件状态还是：

• disabled

那就别急着测功能。先把它变成：

• loaded

再说后面的事情。

4. Gateway 环境路径问题，很多时候比业务配置本身更烦#

这次真正让我多绕了几圈的，反而不是 ACP 配置逻辑，而是：

• gateway token 的环境路径
• CLI 自带的校验
• 服务重启时到底吃到了什么环境

这种问题很像“系统胶水层”的典型故障：

• 业务逻辑没错
• 但 glue code / runtime environment 不对
• 最后还是跑不起来