FAQ: 常见问题与解决方案

[HK6666]

常见问题与解决方案

安装相关

Q: 安装插件报错 config validation failed

Config validation failed: plugins.entries.openilink.config.hub_url: must have required property 'hub_url'

原因： 安装时需要已配置好 hub_url 和 app_token。

解决： 先在 ~/.openclaw/openclaw.json 的 plugins.entries 中添加配置，再安装插件：

{
  "plugins": {
    "entries": {
      "openilink": {
        "config": {
          "hub_url": "https://hub.openilink.com",
          "app_token": "你的token"
        }
      }
    }
  }
}

然后执行安装：

openclaw plugins install openclaw-channel-openilink

---

Q: openclaw status 报 unknown channel id: openilink

Invalid config: channels.openilink: unknown channel id: openilink

原因： OpenClaw 配置校验器在插件加载之前运行，此时还不认识 openilink 这个 channel。

影响： 纯警告，不影响收发消息。可以忽略。

---

连接相关

Q: 插件显示 configured 但不是 running

可能原因：

1. Hub URL 或 Token 不正确
2. Hub 不可达（网络问题）

排查步骤：

# 查看频道状态
openclaw channels status

# 查看日志
openclaw channels logs | grep openilink

确认日志中有 [openilink] Connected to Hub 和 [openilink] Init: bot=...。

---

Q: WebSocket 反复断开重连

可能原因：

1. 网络不稳定
2. Hub 重启或部署中
3. Token 已失效（Hub 上重新安装 App 会生成新 Token）

解决： 检查 Token 是否最新。到 Hub 后台查看 App Installation 详情页，确认 Token 一致。

---

Q: 收不到微信消息（Hub 日志无 event）

可能原因：

1. Hub 上的微信 Bot 不在线（需要扫码登录）
2. Token 已更换（Hub 重装 App 后会生成新 Token）
3. Hub 版本过旧，builtin App 事件分发有 bug（需要 v0.1.1+）

解决：

1. 登录 Hub 后台，确认 Bot 状态为在线
2. 确认 Token 与 Hub Installation 页面一致
3. Hub 升级到 v0.1.1 以上

---

Q: 收到消息但回复返回 409

[openilink] Send failed: 409

原因： Hub 的 Bot 还没有与该用户建立过会话上下文。

解决： 确保是用户先发消息给 Bot（而不是 Bot 主动发起），Hub 会自动建立会话上下文。

---

AI 模型相关

Q: 回复返回 400 错误

[openilink] Send failed: 400

可能原因：

1. 模型 ID 大小写不匹配（如 glm-5 vs GLM-5）
2. 模型 API 额度用完
3. 模型 API 不可达

排查： 直接测试模型 API：

curl -X POST "你的模型API地址/chat/completions" \
  -H "Authorization: Bearer 你的apikey" \
  -H "Content-Type: application/json" \
  -d '{"model":"模型名","messages":[{"role":"user","content":"hi"}],"max_tokens":50}'

---

Q: Dispatching to AI 之后没有响应

原因： 模型调用超时或无响应。

排查：

1. 通过 Telegram 等已有频道测试模型是否正常
2. 检查模型 API 额度
3. 确认 openclaw.json 中模型 ID 正确

---

多账户配置

Q: 如何同时接入多个微信号？

使用 accounts 字段，每个账户配不同的 app_token：

{
  "channels": {
    "openilink": {
      "enabled": true,
      "hub_url": "https://hub.openilink.com",
      "accounts": {
        "wechat1": {
          "app_token": "app_第一个微信号的token"
        },
        "wechat2": {
          "app_token": "app_第二个微信号的token"
        }
      }
    }
  }
}

• hub_url 放外层共享
• 每个账户名（wechat1、wechat2）可以随意命名
• 每个账户独立建立 WebSocket 连接
• 如果某个账户需要不同的 Hub，可以在账户内覆盖 hub_url

---

其他

Q: /s、/p、/gi 等斜杠命令不能用？

这些命令是 Hub 的 Command Service App 提供的，不是 OpenClaw 的功能。

需要在 Hub 后台单独安装：Bot 详情页 → 应用市场 → Command Service → 安装。

---

Q: 发送中文消息显示乱码

如果通过 API 手动发送消息出现乱码，请确保请求的 Content-Type 包含 charset：

Content-Type: application/json; charset=utf-8

或使用 Node.js 发送（自动 UTF-8）：

fetch('https://hub.openilink.com/bot/v1/message/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer 你的token'
  },
  body: JSON.stringify({ content: '你好' })
})

---

遇到其他问题？请提交 Issue。