Skill: roger0808/acpx-connection-troubleshooting (version 1.0.0)

--- name: "acpx-bridge-troubleshooting" description: "用于排查 acpx 桥接连接失败、超时或初始化卡住的问题。当用户提到 acpx 无法连接、ACP 桥接超时、gateway.token 缺失、Claude Code 认证失败、initialize 阶段卡住、或尝试将微信/飞书渠道切换到 ACP 后端时触发。涵盖配置验证、令牌文件修复、模型端点检查及网络连通性测试。即使未明确说'acpx'，但描述'CLI 连不上网关'或'子代理调用失败'也应使用。" metadata: {{ "openclaw": {{ "emoji": "tool" }} }} --- # acpx 桥接连接问题排查与修复 本技能帮助诊断和修复 acpx 与 OpenClaw Gateway 或 Claude Code CLI 之间的连接问题，确保 ACP 桥接正常工作。 ## 何时使用此技能 - 当 `acpx` 命令执行超时或卡在 `initialize` 阶段时 - 当用户尝试将渠道（微信/飞书）路由切换到 ACP 后端但失败时 - 当遇到 `gateway.token` 缺失或认证错误时 - 当 Claude Code CLI 配置与预期模型（如百炼 vs Anthropic）不匹配时 - 当需要验证 ACP 网关连通性或入口脚本路径时 ## 步骤 ### 1. 确认渠道支持性 检查目标渠道（如 wecom、feishu）是否在 ACP 支持列表中。 - **操作**：查阅 ACP 文档或当前绑定配置。 - **原因**：企业微信 (wecom) 可能不在默认支持列表（目前主要支持 Discord/Telegram），强行绑定会导致路由失败。 ### 2. 验证 Claude Code CLI 配置 检查 `~/.claude/config.json` 中的 API 端点和模型配置。 - **操作**：查看配置是否指向正确的 API（Anthropic 或 阿里云百炼）。 - **原因**：acpx 调用的是本地 CLI 配置，若 API Key 失效或端点错误，会卡在认证阶段。 ```json // ~/.claude/config.json 示例 { "apiEndpoint": "https://coding.dashscope.aliyuncs.com/apps/anthropic", "apiKey": "sk-sp-[REDACTED]", "model": "qwen3.5-plus" } ``` ### 3. 检查 Gateway Token 文件 确认 `~/.openclaw/gateway.token` 是否存在且内容正确。 - **操作**：若文件缺失，从 `openclaw.json` 中提取 token 并创建文件。 - **原因**：acpx 连接 OpenClaw Gateway 需要此令牌进行 WebSocket 认证，缺失会导致连接立即超时。 ```bash # 修复命令（替换为实际 token） echo [REDACTED_SECRET] > ~/.openclaw/gateway.token ``` ### 4. 分析 acpx 日志 运行命令时添加 verbose 模式或观察输出日志。 - **操作**：关注 `[client] initialize` 状态。 - **原因**：若卡在 `initialize` 说明网络或认证失败；若卡在 `session/new` 说明服务响应问题。 ### 5. 测试替代方案 若 `acpx claude` 失败，尝试 `acpx openclaw` 或其他内置 agent。 - **操作**：`acpx openclaw exec 'status'`。 - **原因**：内置 agent 不依赖外部 CLI 配置，可隔离问题是出在桥接层还是模型层。 ## pitfalls and solutions ❌ **假设 wecom 渠道直接支持 ACP** → 为什么失败：ACP 可能未适配企业微信协议，导致路由无法建立。 ✅ **正确做法**：先确认渠道兼容性，或使用 `echo agent` 内部调用 acpx 作为替代方案。 ❌ **忽略 gateway.token 文件存在性** → 为什么失败：acpx 默认从该文件读取认证令牌，不存在则无法握手 Gateway。 ✅ **正确做法**：手动创建 `~/.openclaw/gateway.token` 并写入 `openclaw.json` 中的 token 值。 ❌ **混淆 Bailian 配置与 Anthropic 配置** → 为什么失败：Claude Code CLI 默认期望 Anthropic 端点，若配置为阿里云百炼需确保端点格式兼容。 ✅ **正确做法**：验证 `~/.claude/config.json` 中的 `apiEndpoint` 是否可访问，或改用 `acpx openclaw` 绕过 CLI 配置。 ❌ **遇到超时就放弃排查** → 为什么失败：超时可能是网络路由问题，也可能是入口脚本路径错误。 ✅ **正确做法**：检查 Gateway 日志是否有连接记录，确认 ACP 服务端口（默认 18789）是否开放。 ## 关键代码与配置 **ACP 绑定配置示例 (openclaw.json)** ```json { "type": "acp", "agentId": "claude", "match": { "channel": "feishu-claude" }, "acp": { "agent": "claude", "backend": "acpx", "mode": "persistent" } } ``` **飞书多机器人配置示例** ```json { "channels": { "feishu-claude": { "enabled": true, "appId": "新机器人的 App ID", "appSecret": "新机器人的 App Secret", "domain": "feishu", "connectionMode": "websocket", "webhookPath": "/feishu-claude/events" } } } ``` **Gateway 认证修复** ```bash # 确保目录存在 mkdir -p ~/.openclaw # 写入 token echo "YOUR_GATEWAY_TOKEN" > ~/.openclaw/gateway.token chmod 600 ~/.openclaw/gateway.token ``` ## 环境与前置条件 - **acpx 版本**: v0.3.0 或更高 - **OpenClaw Gateway**: 运行中，端口默认 18789 - **Claude Code CLI**: 已安装且可执行 - **配置文件**: - `~/.openclaw/openclaw.json` (Gateway 配置) - `~/.claude/config.json` (Claude Code 配置) - `~/.openclaw/gateway.token` (认证令牌) - **网络**: 需能访问 API 端点及 Gateway WebSocket 地址 ## companion files - `scripts/check_gateway.sh` — 检查 Gateway 端口及 token 文件状态的脚本 - `references/acp_channels.md` — ACP 支持的渠道列表及绑定示例 ## 任务记录 **任务标题**: 微信渠道切换 acpx 配置及桥接问题排查 **关键发现**: 1. `acpx claude` 卡在初始化，原因是 Claude Code CLI 配置的百炼 API 连通性问题。 2. `acpx openclaw` 超时，根本原因是 `~/.openclaw/gateway.token` 文件缺失。 3. 企业微信 (wecom) 渠道可能不在 ACP 默认支持列表中。 **最终建议**: 若桥接调试成本过高，建议保持现有 `echo agent` 配置，或通过 subagent 内部调用 Claude Code。 ## Companion files - `references/acp-bridge-config-reference.md` — reference documentation

path: evals/evals.json
content: {
  "skill_name": "acpx-connection-troubleshooting",
  "evals": [
    {
      "id": 1,
      "prompt": "我在配置飞书渠道切换到 ACP 后端，但是运行 `acpx claude` 的时候卡在 initialize 阶段不动了。日志里好像提到 gateway.token 缺失，文件路径是 ~/.openclaw/ 下的。",
      "expectations": [
        "验证 `~/.openclaw/gateway.token` 文件是否存在",
        "提供从 `openclaw.json` 提取 token 并创建文件的具体命令",
        "检查飞书渠道是否在 ACP 支持列表中"
      ],
      "trigger_confidence": "high"
    },
    {
      "id": 2,
      "prompt": "最近想把企业微信的消息路由到 Claude 处理，但是配置好后一直超时。错误信息显示 'CLI 连不上网关' 或者 '子代理调用失败'。我检查了 openclaw.json 配置好像没问题，是不是哪里漏了？",
      "expectations": [
        "识别为 acpx 桥接连接问题（即使用户未明确提及 acpx）",
        "指出企业微信 (wecom) 可能不在默认支持列表的风险",
        "建议检查 Gateway 端口 18789 连通性"
      ],
      "trigger_confidence": "medium"
    },
    {
      "id": 3,
      "prompt": "急！acpx 桥接一直超时，是不是 ~/.claude/config.json 里的 apiEndpoint 配错了？我用的是阿里云百炼的 key，但好像它默认要找 Anthropic？报错是认证失败。",
      "expectations": [
        "检查 `~/.claude/config.json` 中的 API 端点配置",
        "解释百炼配置与 Anthropic 配置的兼容性差异",
        "建议改用 `acpx openclaw` 绕过 CLI 配置或修正端点"
      ],
      "trigger_confidence": "high"
    },
    {
      "id": 4,
      "prompt": "尝试将飞书机器人绑定到 acpx 后端，启动后日志卡在 [client] initialize。之前用过 echo agent 是正常的。需要检查哪些配置文件？端口 18789 好像也没通。",
      "expectations": [
        "分析 `[client] initialize` 卡住的原因（网络或认证）",
        "指导检查 OpenClaw Gateway 服务状态及 18789 端口",
        "建议测试 `acpx openclaw exec 'status'` 隔离问题"
      ],
      "trigger_confidence": "high"
    }
  ]
}

path: references/acp-bridge-config-reference.md
content: # ACP 桥接配置隔离与渠道兼容性参考

本文档补充 acpx 桥接的系统架构细节、配置隔离说明及渠道兼容性实测数据，用于辅助排查连接问题前的架构确认。

## 1. 配置隔离说明
OpenClaw 系统中，主 Agent 与 acpx 桥接进程使用独立的配置文件，排查问题时需严格区分：

| 组件 | 配置文件路径 | 用途 | 常见误区 |
|------|--------------|------|----------|
| **OpenClaw 主 Agent** | `~/.openclaw/openclaw.json` | 控制主对话流、内置模型调用、路由绑定 | 误以为修改此处会影响 `acpx claude` 的模型行为 |
| **Claude Code CLI** | `~/.claude/config.json` | 控制 `acpx claude` 的模型后端、API Key 及端点 | 误以为主 Agent 能通则 CLI 也能通（Key 权限可能不同） |
| **Gateway 认证** | `~/.openclaw/gateway.token` | ACP 桥接握手令牌 (WebSocket 认证) | 文件缺失导致 `acpx openclaw` 直接超时，而非认证错误 |

**排查原则**：
- 若主 Agent 正常但 `acpx claude` 失败 → 重点检查 `~/.claude/config.json`。
- 若 `acpx openclaw` 失败 → 重点检查 `~/.openclaw/gateway.token`。

## 2. 渠道兼容性实测
基于 ACP v0.3.0+ 版本的兼容性测试状态：

| 渠道 | 支持状态 | 备注 |
|------|----------|------|
| **Feishu (飞书)** | ✅ 支持 | 支持多机器人配置，可通过不同 Webhook 隔离 Agent |
| **Discord** | ✅ 支持 | 原生支持，稳定性高 |
| **Telegram** | ✅ 支持 | 原生支持 |
| **Wecom (企业微信)** | ⚠️ 不确定 | 协议可能未完全适配，建议优先使用 Echo Agent 内部调用 |

**飞书多机器人策略**：
- **Bot A (主)**: 绑定默认 Agent (如 Qwen)，用于日常对话。
- **Bot B (副)**: 绑定 ACP/Claude Code，用于特定复杂任务。
- **配置要点**: 确保 `webhookPath` 不冲突 (例如 `/feishu` vs `/feishu-claude`)，且在 `bindings` 中通过 `channel` 字段精确匹配。

## 3. 阿里云百炼 (Bailian) 适配细节
当使用 Claude Code CLI 对接阿里云百炼时，需满足特定格式要求以兼容 CLI 的 Anthropic 协议封装：

- **API Endpoint**: 必须使用兼容 Anthropic 格式的代理端点。
  - ✅ 推荐：`https://coding.dashscope.aliyuncs.com/apps/anthropic`
  - ❌ 避免：直接使用百炼原生 SDK 端点（CLI 可能无法识别协议）
- **Model Name**: 需填写 CLI 认可的模型标识 (如 `qwen3.5-plus`)。
- **API Key**: 需确保 Key 有访问该特定端点的权限（有时与主配置 Key 权限范围不同）。

## 4. 常见故障特征对照

| 故障现象 | 可能原因 | 优先检查点 |
|----------|----------|------------|
| **卡在 initialize** | CLI 配置网络不通或 Key 无效 | `~/.claude/config.json` 连通性 |
| **acpx openclaw 超时** | Gateway 令牌缺失 | `~/.openclaw/gateway.token` 存在性 |
| **路由失败/无响应** | 渠道名称不匹配或协议不支持 | `openclaw.json` 中 `channel` 字段及渠道支持列表 |
| **InvalidApiKey** | Key 过期或权限不足 | 百炼控制台 Key 状态及端点白名单 |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)