yangxuan/openclaw-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
376fde448bd2805995459d6b0b22b1e2c021c2b5
openclaw-config/agents/main/agent/workshop-skills/acp-backend-triage/SKILL.md
T
yangxuan 43cd42a563 feat(acp): 接入 DSH 作为 ACP harness，打通 微信→OpenClaw→DSH 派发链路 
- openclaw.json
  - plugins.allow 放行 acpx（限制性白名单，缺了后端不会加载）
  - 新增 acp 策略段：enabled/dispatch、backend=acpx、defaultAgent=dsh、
    allowedAgents=[dsh]、stream.deliveryMode=live
  - 新增 plugins.entries.acpx.config：permissionMode=approve-all、
    timeoutSeconds=900、cwd、agents.dsh = dsh --profile acp（绝对路径）
  - 新增 OpenClaw agent dsh（runtime.type=acp → harness dsh），否则
    sessions_spawn 会报 dispatch_failed: Unknown agent id "dsh"
- workspace-dsh/：该 agent 的身份文件（AGENTS/SOUL/IDENTITY/USER/BOOTSTRAP.md）。
  其中的空 .git 由 `openclaw agents add` 的标准 provisioning 生成（非任何 agent 自建），
  会让父仓库把它当 gitlink，已移除后纳入版本控制
- docs/bk02-dsh-openclaw-ACP集成.md：部署/配置/验证证据/排错/回滚全文
- docs/dsh-acp-smoke.mjs：ACP 独立冒烟（initialize→session/new→prompt→close）
- docs/dsh-lang-check.mjs：全局中文指令验证（英文提问看是否回中文）
- skills/delegate-to-dsh：让「交给 dsh」稳定走 ACP 派发；缺此技能时模型会
  静默 fallback 到内嵌 subagent（已复现「假成功」并写入判据）
- agents/main/agent/workshop-skills/acp-backend-triage：ACP 后端排查技能
- plugin-skills/acp-router：acpx 插件自带技能（symlink，与既有渠道一致）
- .gitignore：workspace-dsh 沿用 workspace/ 白名单（只版本化顶层 *.md）；
  新增忽略 acpx/ 插件运行产物

验证：ACP 三条途径均通过（独立冒烟、显式 sessions_spawn、自然语言「转给 dsh」），
DSH 侧会话留痕与产物落地见 docs 文档 §5 与 §7。
2026-09-16 17:40:53 +08:00

4.7 KiB
Raw Blame History

name, description
name description
acp-backend-triage 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）： 
    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」步骤在本机不适用（见「事实基础」）。
Reference in New Issue View Git Blame Copy Permalink