Skill: roger0808/acpx-bridge-troubleshooting-guide (version 1.0.0)

--- name: [REDACTED_SECRET] description: "解决 acpx 桥接超时问题和 OpenClaw 飞书多账户配置。当遇到 acpx 连接 Gateway 超时、initialize 卡住、WebSocket 1005 错误、gateway.token 缺失、acpx 配置错误、飞书多机器人配置、ACP 协议解析失败、bindings 路由不生效等问题时使用。包括创建 token 文件、修复 acpx 配置、更新 acpx 版本、正确配置飞书多账户（使用 accounts 结构而非新建 channel）、使用 openclaw config set 命令而非 jq 直接修改 JSON 等关键步骤。" metadata: { "openclaw": { "emoji": "🦞" } } --- # acpx 桥接超时排查与飞书多账户配置指南 本技能帮助解决 acpx 桥接超时问题并正确配置 OpenClaw 飞书多账户，避免常见配置陷阱和协议兼容性问题。 ## 何时使用此技能 - 当 acpx 连接 Gateway 时卡在 `initialize` 阶段或超时时 - 当需要配置多个飞书机器人连接到不同 AI 后端（如 Claude Code）时 - 当遇到 WebSocket 1005 错误、ACP 协议解析失败、Gateway 断开连接时 - 当需要修改 OpenClaw 配置但不确定正确命令方式时（避免直接用 jq 修改 JSON） ## 步骤 ### 1. 检查并创建 Gateway Token 文件 **操作：** ```bash # 检查文件是否存在 ls -la ~/.openclaw/gateway.token # 如果不存在，从 openclaw.json 找到 token 并创建 echo "你的_gateway_token" > ~/.openclaw/gateway.token ``` **原因：** gateway.token 文件缺失是 acpx 超时的常见根本原因，Gateway 需要此文件进行身份验证。 ### 2. 修复 acpx 配置文件 **操作：** ```bash # 编辑 ~/.acpx/config.json { "defaultAgent": "openclaw", "agents": { "openclaw": { "command": "openclaw", "args": ["acp", "client"] } } } ``` **原因：** acpx 配置中的脚本路径必须指向实际存在的命令，`openclaw acp client` 是官方推荐的 ACP 入口，不需要 `--url` 和 `--token-file` 参数（会自动从 OpenClaw 配置读取）。 ### 3. 更新 acpx 到最新版本 **操作：** ```bash npm install -g acpx@latest acpx --version # 确认版本 ``` **原因：** acpx 处于 alpha 阶段，更新频繁。新版本可能包含 ACP 协议错误处理的修复（如 0.4.0 修复了 -32601/-32602 错误处理）。 ### 4. 配置飞书多账户（正确方式） **操作：** ```bash # 使用 openclaw config set 命令，不要用 jq 直接修改 JSON openclaw config set 'channels.feishu.accounts.claude' '{"appId":"cli_xxx","appSecret":"xxx","domain":"feishu","connectionMode":"websocket"}' # 验证配置 openclaw config validate # 重启 Gateway openclaw gateway restart ``` **原因：** 飞书多账户应使用 `channels.feishu.accounts` 结构，而不是创建新的 channel（如 feishu-claude）。使用官方命令可避免 JSON 格式错误。 ### 5. 验证配置和连接 **操作：** ```bash # 检查配置有效性 openclaw doctor # 测试 ACP 连接 openclaw acp client # 检查 Gateway 状态 openclaw gateway status ``` **原因：** 配置修改后必须验证有效性并重启 Gateway 才能生效。 ## 陷阱与解决方案 ❌ **直接用 jq 修改 openclaw.json** → JSON 格式可能出错（缩进、换行问题），导致配置无效 → ✅ **使用 `openclaw config set` 命令** ❌ **创建新 channel（如 feishu-claude）来添加第二个飞书机器人** → bindings 无法正确路由，配置结构错误 → ✅ **在 `channels.feishu.accounts` 下添加第二个账户** ❌ **acpx 配置中添加 `--url` 和 `--token-file` 参数** → `openclaw acp client` 会自动从配置读取，额外参数可能导致冲突 → ✅ **只配置 command 和 args，不添加 URL 和 token 参数** ❌ **在 bindings 中手动添加 `accountId: "default"`** → 没有 accountId 的 binding 自动匹配 default account，手动添加可能导致匹配失败 → ✅ **让 default account 自动匹配，只给非 default 账户指定 accountId** ❌ **忽略 acpx 版本更新** → 旧版本可能存在 ACP 协议兼容性问题（如 0.3.0 的协议错误处理 bug） → ✅ **定期更新到最新版本，查看 release notes** ❌ **配置修改后不重启 Gateway** → 配置不会生效，问题难以排查 → ✅ **每次配置修改后执行 `openclaw gateway restart`** ## 关键代码和配置 ### gateway.token 创建 ```bash echo [REDACTED_SECRET] > ~/.openclaw/gateway.token ``` ### acpx 配置文件 (~/.acpx/config.json) ```json { "defaultAgent": "openclaw", "timeout": 900, "agents": { "openclaw": { "command": "openclaw", "args": ["acp", "client"] }, "claude": { "command": "claude" } } } ``` ### 飞书多账户配置结构（参考） ```json5 { channels: { feishu: { enabled: true, accounts: { default: { appId: "cli_a90d44041b38dcd4", appSecret: "[REDACTED]" }, claude: { appId: "cli_a944379913b85ccb", appSecret: "[REDACTED]" } } } }, bindings: [ { agentId: "main", match: { channel: "feishu", accountId: "default" } }, { type: "acp", agentId: "claude", match: { channel: "feishu", accountId: "claude" }, acp: { agent: "claude", backend: "acpx", mode: "persistent" } } ] } ``` ### 配置命令示例 ```bash # 添加第二个飞书账户 openclaw config set 'channels.feishu.accounts.claude' '{"appId":"cli_a944379913b85ccb","appSecret":"[REDACTED]"}' # 验证配置 openclaw config validate # 重启 Gateway openclaw gateway restart ``` ## 环境和前提条件 - **acpx 版本**: 0.4.0+（推荐最新） - **OpenClaw Gateway**: 正常运行，端口 18789 - **Node.js**: npm 可全局安装 acpx - **配置文件路径**: - `~/.openclaw/gateway.token` - `~/.openclaw/openclaw.json` - `~/.acpx/config.json` - **权限**: 需要读写上述配置文件的权限 - **已知限制**: 飞书多账户绑定路由功能尚未完全支持（issue #51467），bindings 无法区分同一用户的不同机器人 ## 伴随文件 - `scripts/gateway-token-check.sh` — 检查 gateway.token 是否存在并验证格式 - `references/feishu-multi-account-config.md` — 飞书多账户配置详细文档和示例 - `references/acp-protocol-troubleshooting.md` — ACP 协议常见问题和调试方法 ## 任务记录 **任务标题**: 解决 acpx 超时问题 **关键发现**: - Gateway 的 ACP 后端将日志行和 JSON-RPC 消息混在同一个 WebSocket 流中发送，导致 acpx 解析失败 - bindings 只能匹配 `channel` 和 `peer`，无法区分同一用户的不同机器人（等待官方实现 `account` 字段绑定） - 使用 `openclaw config set` 命令比直接用 jq 修改 JSON 更安全可靠 **最终状态**: - gateway.token 创建 ✅ - acpx 配置修复 ✅ - acpx 版本更新 0.3.0 → 0.4.0 ✅ - ACP 连接测试 ⚠️ 部分成功（能连接但执行时 Gateway 断开 1005 错误） - 飞书多账户配置 ❌ 不支持（bindings 无法区分 accountId） - Gateway 运行状态 ✅ 正常（PID 105020, 端口 18789） **建议方案**: 暂时放弃 acpx 桥接，继续使用 echo agent + qwen3.5-plus，飞书新机器人需等待官方实现多账户绑定路由功能。 ## Companion files - `scripts/fix_acpx_bridge.sh` — automation script - `scripts/add_feishu_account.sh` — automation script - `scripts/diagnose_acpx.sh` — automation script - `references/acpx-配置参考.md` — reference documentation - `references/openclaw-飞书多账户配置.md` — reference documentation - `references/acp-协议故障排查.md` — reference documentation

path: evals/evals.json
content: {
  "skill_name": "acpx-bridge-troubleshooting-guide",
  "evals": [
    {
      "id": 1,
      "prompt": "acpx 连接 Gateway 一直卡在 initialize 阶段，日志里刷 WebSocket 1005 错误。我看了下 ~/.openclaw 目录，好像没有 gateway.token 文件。这会是根本原因吗？具体该怎么创建和配置？",
      "expectations": [
        "确认 gateway.token 文件缺失是 acpx 超时的常见根本原因",
        "提供创建 token 文件的具体 bash 命令（如 echo \"token\" > ~/.openclaw/gateway.token）",
        "建议检查 ~/.acpx/config.json 配置是否正确指向 openclaw acp client"
      ],
      "trigger_confidence": "high"
    },
    {
      "id": 2,
      "prompt": "我想配置多个飞书机器人连接到不同 AI 后端。是不是应该在 channels 里新建一个 feishu-claude 的 channel？另外修改 openclaw.json 时直接用 jq 命令方便点吧？",
      "expectations": [
        "纠正多账户配置误区，说明应使用 channels.feishu.accounts 结构而非新建 channel",
        "警告不要直接用 jq 修改 JSON（易导致格式错误），推荐使用 openclaw config set 命令",
        "提供配置第二个飞书账户的命令示例（openclaw config set 'channels.feishu.accounts.claude' ...）"
      ],
      "trigger_confidence": "high"
    },
    {
      "id": 3,
      "prompt": "acpx 老报 ACP 协议解析失败，版本是 0.3.0。 ~/.acpx/config.json 里我需要给 openclaw agent 加上 --url 和 --token-file 参数吗？感觉配置一直没生效。",
      "expectations": [
        "建议更新 acpx 到最新版本 (npm install -g acpx@latest) 以修复协议错误",
        "指出 ~/.acpx/config.json 中不需要添加 --url 和 --token-file 参数（会自动读取）",
        "提醒配置修改后必须执行 openclaw gateway restart 才能生效"
      ],
      "trigger_confidence": "high"
    },
    {
      "id": 4,
      "prompt": "刚改完配置，openclaw gateway restart 了但还是连不上。之前用 jq 改的 openclaw.json，现在 bindings 路由完全不生效，acpx 也超时。求排查步骤。",
      "expectations": [
        "指出 jq 修改可能导致 JSON 格式错误，建议用 openclaw config validate 验证配置",
        "检查 bindings 路由配置，说明 default account 自动匹配规则（无需手动添加 accountId）",
        "引导排查 gateway.token 是否存在及 acpx 版本是否过旧"
      ],
      "trigger_confidence": "medium"
    }
  ]
}

path: references/acp-协议故障排查.md
content: # ACP 协议故障排查参考

## 常见错误代码

### WebSocket 错误

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 1005 | 连接断开（无状态码） | 检查 Gateway 日志，重启 Gateway |
| 1006 | 异常关闭 | 检查网络配置和防火墙 |

### JSON-RPC 错误

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| -32601 | 方法未找到 | 检查 ACP 命令是否正确 |
| -32602 | 无效参数 | 检查参数格式 |

## 排查步骤

### 1. 检查 Gateway 状态
```bash
openclaw gateway status
openclaw gateway logs
```

### 2. 测试 ACP 连接
```bash
# 直接测试（绕过 acpx）
openclaw acp client

# 通过 acpx 测试
acpx openclaw exec 'status'
```

### 3. 检查日志输出

**问题**: Gateway 的 ACP 后端将日志行和 JSON-RPC 消息混在同一个 WebSocket 流中发送

**影响**: acpx 期望纯 JSON，导致解析失败超时

**解决方案**:
- 方案 A: 暂时放弃 acpx 桥接，继续用 echo agent
- 方案 B: 修改 Gateway 源码，日志输出到 stderr
- 方案 C: acpx 配置中添加日志过滤

### 4. 验证配置
```bash
openclaw doctor
openclaw config validate
```

## 已知问题

### acpx 0.3.0 问题
- ACP 协议错误处理不完善
- 日志解析可能失败

### acpx 0.4.0 修复
- 修复 -32601/-32602 错误处理
- 修复中断会话处理

## 推荐方案

### 方案优先级

1. **首选**: 直接使用 `openclaw acp client`（官方推荐）
2. **次选**: 修复 acpx 配置后使用
3. **备选**: 通过 `sessions_spawn(runtime="acp")` 内部调用

### 架构选择

| 需求 | 推荐方案 |
|------|----------|
| 飞书 → OpenClaw 主 agent | openclaw acp |
| 飞书 → Claude Code | ACP 后端绑定 |
| 多 agent 路由 | acpx（谨慎使用） |

## 环境检查清单

- [ ] ~/.openclaw/gateway.token 文件存在
- [ ] ~/.acpx/config.json 配置正确
- [ ] acpx 版本为最新 (0.4.0+)
- [ ] Gateway 服务正在运行
- [ ] 端口 18789 可访问
- [ ] 配置修改后已重启 Gateway


path: references/acpx-配置参考.md
content: # acpx 配置参考文档

## 官方文档
- **acpx 文档**: https://docs.openclaw.ai/cli/acp
- **GitHub**: https://github.com/openclaw/openclaw

## 配置文件位置
```
~/.acpx/config.json
```

## 正确配置示例
```json
{
  "defaultAgent": "openclaw",
  "timeout": 900,
  "agents": {
    "openclaw": {
      "command": "openclaw",
      "args": ["acp", "client"]
    },
    "claude": {
      "command": "claude"
    }
  }
}
```

## 常见配置错误

### ❌ 错误：添加 --url 和 --token-file 参数
```json
// 不要这样配置
{
  "args": ["acp", "client", "--url", "ws://127.0.0.1:18789", "--token-file", "..."]
}
```
**原因**: `openclaw acp client` 会自动从 OpenClaw 配置读取 URL 和 token，额外参数会导致冲突。

### ✅ 正确：只配置 command 和 args
```json
{
  "args": ["acp", "client"]
}
```

## 版本信息

| 版本 | 发布日期 | 关键修复 |
|------|----------|----------|
| 0.3.0 | 2026-03-12 | 基础版本 |
| 0.4.0 | 2026-03-29 | 修复 -32601/-32602 ACP 协议错误处理 |

## 更新命令
```bash
npm install -g acpx@latest
acpx --version
```

## ACP 与 acpx 的区别

| 特性 | openclaw acp | acpx |
|------|--------------|------|
| 类型 | OpenClaw 内置命令 | 独立 npm 包 |
| 推荐度 | ⭐⭐⭐⭐⭐ (官方推荐) | ⭐⭐ (第三方工具) |
| 配置复杂度 | 低 | 中 |
| 适用场景 | 直接 ACP 桥接 | 多 agent 路由 |

## 测试命令
```bash
# 测试 ACP 连接
openclaw acp client

# 测试 acpx 连接
acpx openclaw exec 'status'

# 检查 Gateway 状态
openclaw gateway status
```


path: references/openclaw-飞书多账户配置.md
content: # OpenClaw 飞书多账户配置参考

## 配置结构

### ✅ 正确：使用 accounts 结构
```json5
{
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "default": {
          "appId": "cli_a90d44041b38dcd4",
          "appSecret": "[REDACTED]"
        },
        "claude": {
          "appId": "cli_a944379913b85ccb",
          "appSecret": "[REDACTED]"
        }
      }
    }
  }
}
```

### ❌ 错误：创建新 channel
```json5
// 不要这样配置
{
  "channels": {
    "feishu": { ... },
    "feishu-claude": { ... }  // 错误！
  }
}
```
**原因**: bindings 无法正确路由，配置结构错误。

## 配置命令

### 添加第二个飞书账户
```bash
openclaw config set 'channels.feishu.accounts.claude' '{"appId":"cli_xxx","appSecret":"xxx","domain":"feishu","connectionMode":"websocket"}'
```

### 验证配置
```bash
openclaw config validate
openclaw doctor
```

### 重启 Gateway
```bash
openclaw gateway restart
```

## Bindings 配置

### 默认账户绑定
```json
{
  "agentId": "main",
  "match": { "channel": "feishu", "accountId": "default" }
}
```

### ACP 后端绑定
```json
{
  "type": "acp",
  "agentId": "claude",
  "match": { "channel": "feishu", "accountId": "claude" },
  "acp": {
    "agent": "claude",
    "backend": "acpx",
    "mode": "persistent"
  }
}
```

## 重要规则

1. **不要手动添加 accountId: "default"** - 没有 accountId 的 binding 自动匹配 default account
2. **使用 openclaw config set 命令** - 避免直接用 jq 修改 JSON 导致格式错误
3. **配置修改后必须重启 Gateway** - 否则配置不会生效

## Gateway Token

### 文件位置
```
~/.openclaw/gateway.token
```

### 创建方法
```bash
echo "你的_gateway_token" > ~/.openclaw/gateway.token
```

### 从 openclaw.json 获取 token
```bash
# 从 openclaw.json 中找到 gateway.token 字段
```

## 常见问题排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| acpx 超时 | gateway.token 缺失 | 创建 token 文件 |
| WebSocket 1005 错误 | ACP 协议兼容性 | 更新 acpx 到最新版本 |
| bindings 不生效 | 配置结构错误 | 使用 accounts 而非新 channel |
| 配置不生效 | Gateway 未重启 | 执行 gateway restart |


path: scripts/add_feishu_account.sh
content: #!/bin/bash
# add_feishu_account.sh - 添加飞书多账户配置
# 使用 openclaw config set 命令而非直接修改 JSON

set -e

if [ $# -lt 3 ]; then
    echo "用法：$0 <account_name> <app_id> <app_secret>"
    echo "示例：$0 claude cli_a944379913b85ccb your_app_secret"
    exit 1
fi

ACCOUNT_NAME=$1
APP_ID=$2
APP_SECRET=$3

echo "🦞 添加飞书账户：$ACCOUNT_NAME"

# 使用 openclaw config set 命令添加账户
openclaw config set "channels.feishu.accounts.$ACCOUNT_NAME" "{\"appId\":\"$APP_ID\",\"appSecret\":\"$APP_SECRET\",\"domain\":\"feishu\",\"connectionMode\":\"websocket\"}"

echo "✅ 账户配置已添加"

# 验证配置
echo "🔍 验证配置..."
openclaw config validate

# 重启 Gateway
echo "🔄 重启 Gateway..."
openclaw gateway restart

echo ""
echo "✅ 完成！新飞书账户 $ACCOUNT_NAME 已配置并生效"


path: scripts/diagnose_acpx.sh
content: #!/bin/bash
# diagnose_acpx.sh - 诊断 acpx 桥接问题
# 检查配置、连接和 Gateway 状态

set -e

echo "🦞 acpx 桥接诊断工具"
echo "===================="
echo ""

# 1. 检查 gateway.token 文件
echo "1️⃣ 检查 gateway.token 文件:"
if [ -f ~/.openclaw/gateway.token ]; then
    echo "   ✅ ~/.openclaw/gateway.token 存在"
    echo "   Token: $(cat ~/.openclaw/gateway.token | head -c 10)..."
else
    echo "   ❌ ~/.openclaw/gateway.token 缺失"
    echo "   修复：echo \"<token>\" > ~/.openclaw/gateway.token"
fi
echo ""

# 2. 检查 acpx 配置
echo "2️⃣ 检查 acpx 配置:"
if [ -f ~/.acpx/config.json ]; then
    echo "   ✅ ~/.acpx/config.json 存在"
    echo "   配置内容:"
    cat ~/.acpx/config.json | sed 's/^/   /'
else
    echo "   ❌ ~/.acpx/config.json 缺失"
fi
echo ""

# 3. 检查 acpx 版本
echo "3️⃣ 检查 acpx 版本:"
acpx --version 2>/dev/null || echo "   ❌ acpx 未安装"
echo ""

# 4. 检查 Gateway 状态
echo "4️⃣ 检查 Gateway 状态:"
openclaw gateway status 2>/dev/null || echo "   ⚠️ 无法获取 Gateway 状态"
echo ""

# 5. 验证 OpenClaw 配置
echo "5️⃣ 验证 OpenClaw 配置:"
openclaw config validate 2>/dev/null || echo "   ⚠️ 配置验证失败"
echo ""

# 6. 运行 doctor
echo "6️⃣ 运行 openclaw doctor:"
openclaw doctor 2>/dev/null || echo "   ⚠️ doctor 检查失败"
echo ""

echo "🦞 诊断完成！"


path: scripts/fix_acpx_bridge.sh
content: #!/bin/bash
# fix_acpx_bridge.sh - 修复 acpx 桥接超时问题
# 创建 gateway.token 文件并修复 acpx 配置

set -e

echo "🦞 开始修复 acpx 桥接问题..."

# 1. 创建 ~/.openclaw 目录（如果不存在）
mkdir -p ~/.openclaw

# 2. 从 openclaw.json 提取 token 并创建 gateway.token 文件
if [ -f ~/.openclaw/openclaw.json ]; then
    [REDACTED_SECRET] -o '"token"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.openclaw/openclaw.json | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
    if [ -n "$TOKEN" ]; then
        echo "$TOKEN" > ~/.openclaw/gateway.token
        echo "✅ gateway.token 已创建"
    else
        echo "⚠️ 未在 openclaw.json 中找到 token，请手动创建 ~/.openclaw/gateway.token"
    fi
else
    echo "⚠️ ~/.openclaw/openclaw.json 不存在，请手动创建 ~/.openclaw/gateway.token"
fi

# 3. 修复 acpx 配置文件
mkdir -p ~/.acpx
cat > ~/.acpx/config.json << 'EOF'
{
  "defaultAgent": "openclaw",
  "timeout": 900,
  "agents": {
    "openclaw": {
      "command": "openclaw",
      "args": ["acp", "client"]
    }
  }
}
EOF
echo "✅ acpx 配置已修复 (~/.acpx/config.json)"

# 4. 更新 acpx 到最新版本
echo "📦 更新 acpx 到最新版本..."
npm install -g acpx@latest 2>/dev/null || echo "⚠️ npm 更新失败，请手动执行：npm install -g acpx@latest"

# 5. 验证安装
echo ""
echo "🔍 验证安装:"
acpx --version 2>/dev/null || echo "⚠️ acpx 未安装或版本检查失败"

echo ""
echo "✅ 修复完成！请执行以下命令重启 Gateway:"
echo "   openclaw gateway restart"


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