---
name: "acp-backend-triage"
description: "ACP 后端排查：/acp doctor、ACP 会话起不来、dispatch_failed 时体检插件与配置、直连 stdio 探活 harness 命令。"
---

# ACP 后端排查（acp backend triage）

用于回答「/acp doctor 怎么样」「ACP 会话起不来」这类问题：先确认 acpx 后端插件与 `acp` 配置，再**绕过 OpenClaw 直接探活 harness 命令**，最后判断故障在 harness 还是在 OpenClaw 接线一侧。

**只读诊断**：不改配置、不重装插件。任何插件/配置改动都交 `openclaw` 工具（或 `/acp install` 给出的步骤），不要手工 `npm install`、不要改状态目录。

## 事实基础（本机 2026-09-16 实测，OpenClaw 2026.9.4）
- 后端插件体检：`openclaw plugins inspect acpx` 显示 `Status: enabled`、`Trust: reason=trusted-official`、`Version: 2026.9.4`；`plugins.allow` 必须含 `acpx`（`openclaw config get plugins.allow`）。`openclaw plugins doctor` 给出插件加载层结论。
- `acpx` 是**内嵌运行时**插件，没有独立的 acpx 二进制可配：`@openclaw/acpx/node_modules/` 下**不存在** `.bin/acpx`，照搬「用 `${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx`」会报「没有那个文件或目录」。确需 acpx CLI 时，它在 npm 工程根（`~/.openclaw/npm/projects/<acpx 工程>/node_modules/.bin/acpx`）。
- 配置区：`openclaw config get acp`（`backend`/`enabled`/`dispatch.enabled`/`defaultAgent`/`allowedAgents`）与 `openclaw config get plugins.entries.acpx`（`permissionMode`/`timeoutSeconds`/`cwd`/`agents.<id>.command|args`）。
- harness 命令直接取自 `plugins.entries.acpx.config.agents.<id>`。本机 `dsh`：`command=/home/yangxuan/.nvm/versions/node/v26.8.2/bin/dsh`、`args=["--profile","acp"]`。
- 非登录 shell 里 harness CLI 可能不在 PATH：先把 `/home/yangxuan/.nvm/versions/node/v26.8.2/bin` 前置，或直接用配置里的绝对路径。

## 步骤

1. **体检插件与配置**：`openclaw plugins doctor`、`openclaw plugins inspect acpx`、`openclaw config get plugins.allow`、`openclaw config get acp`、`openclaw config get plugins.entries.acpx`。逐项确认：插件 enabled、`acpx` 在 allow 列表、`acp.enabled=true`、`dispatch.enabled=true`、`allowedAgents` 含目标 id。
2. **确认 harness 命令可执行**：取配置里的 `command` + `args`，跑 `--version` 与 `<command> <args> --help`。自述为「ACP stdio 服务」即过本步。
3. **直连 stdio 探活（关键一步，不经 OpenClaw）**：
   ```bash
   printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}' \
     | timeout 40 <command> <args> 2>/tmp/acp-probe.err
   # 本机示例：... | timeout 40 dsh --profile acp
   ```
   通过判据：stdout 出现一行 JSON-RPC `result`（含 `agentInfo`）、退出码 0、`/tmp/acp-probe.err` 为空。本机实测返回 `agentInfo.name=deepseek-harness-acp`。
   - 通过 → harness 健康，故障在 OpenClaw 接线/派发一侧，转第 4 步。
   - 不通过 → 报 stderr 原文，属「harness 命令起不来」（未安装/未登录/首次适配器下载失败）。
4. **端到端派发检查**：`sessions_spawn(runtime="acp", agentId="<id>", mode="run", task="Reply with exactly: OK")`；只有 `status:"accepted"` 算通。
   - 若返回 `errorCode:"dispatch_failed"` 且 `error` 为 `Unknown agent id "<id>"`、并带 `childSessionKey: agent:<id>:acp:<uuid>`：本机在探活已通过的前提下复现过两次。含义是 Gateway 会话层不认这个 id（`openclaw agents list` 中无该 id，而 `acp.defaultAgent`/`allowedAgents` 单独列了它）。**本次未定位到具体判定点，也未验证任何修法**——遇到该签名就如实报告「harness 健康、派发失败、原因未定」，把「注册为 agent / 改用标准别名」作为选项交操作员决定，不要擅自改配置。
5. **报告**：只交三类证据——插件与配置结论、探活原始输出、端到端结果；未验证的推断一律标注「未验证」。

## 注意事项
- `/acp doctor`、`/acp status`、`/acp install` 是聊天里的斜杠命令；纯工具上下文（cron/子会话）里不可用，此时按上面 1–4 步手工体检。
- 探活会短时启动 harness 进程；stdin 关闭后它自行退出。
- 运行时不健康细节（quarantine/fallback）用 `openclaw health` 看，不要靠翻状态目录里的 sqlite。

## 参考
- `docs/tools/acp-agents/quickstart.md`、`docs/tools/acp-agents/troubleshooting.md`、`docs/tools/acp-agents-setup.md`（相对 `<openclaw 包>/docs`）
- 技能 `acp-router`（workspace，操作员维护）：ACP 路由与 harness 别名表；其「plugin-local `.bin/acpx`」步骤在本机不适用（见「事实基础」）。