Xikapi 接入文档

常见命令与报错处理 ​

这一页用于快速查找 OpenClaw 常用命令，以及安装、Gateway、模型、Skill、通讯渠道中常见问题的排查方法。

基础命令 ​

目标命令
查看版本openclaw --version
健康检查openclaw doctor
自动修复常见问题openclaw doctor --repair
深度检查openclaw doctor --deep
打开控制台openclaw dashboard
更新 OpenClawopenclaw update

建议遇到问题时先执行：

bash
openclaw doctor
openclaw status --deep

配置命令 ​

目标命令
查看当前配置文件openclaw config file
查看配置项openclaw config get <path>
设置配置项openclaw config set <path> <value>
删除配置项openclaw config unset <path>
输出配置 schemaopenclaw config schema
校验配置openclaw config validate
写入前预演openclaw config set <path> <value> --dry-run

常用示例：

bash
openclaw config file
openclaw config get agents.defaults.model.primary
openclaw config set agents.defaults.model.primary xikapi/YOUR_MODEL_ID --dry-run
openclaw config validate
openclaw config schema

如果要写入 SecretRef，建议优先使用 builder 参数，并先 --dry-run：

bash
openclaw config set models.providers.xikapi.apiKey \
  --ref-provider default \
  --ref-source env \
  --ref-id XIKAPI_API_KEY \
  --dry-run

Gateway 命令 ​

目标命令
启动 Gatewayopenclaw gateway
前台运行 Gatewayopenclaw gateway run
查看 Gateway 状态openclaw gateway status
检查 Gateway 健康openclaw gateway health
重启 Gatewayopenclaw gateway restart
查看日志openclaw logs --follow

如果只是临时开发测试，可以使用：

bash
openclaw gateway --allow-unconfigured

正式环境不要长期依赖 --allow-unconfigured，应修复配置文件中的 gateway.mode。

模型命令 ​

目标命令
查看模型状态openclaw models status
列出模型openclaw models list
列出全部模型openclaw models list --all
设置默认模型openclaw models set <provider/model>
扫描模型配置openclaw models scan
探测模型鉴权openclaw models status --probe

示例：

bash
openclaw models list
openclaw models status --probe
openclaw models set xikapi/YOUR_MODEL_ID

Skill 命令 ​

目标命令
搜索 Skillopenclaw skills search "calendar"
安装 Skillopenclaw skills install <slug>
安装到全局openclaw skills install <slug> --global
更新 Skillopenclaw skills update <slug>
更新全部 Skillopenclaw skills update --all
列出 Skillopenclaw skills list
查看 Skill 信息openclaw skills info <name>
检查 Skillopenclaw skills check

示例：

bash
openclaw skills search "gmail"
openclaw skills install <skill-slug>
openclaw skills list --verbose
openclaw skills check

插件命令 ​

目标命令
列出插件openclaw plugins list
只看已启用插件openclaw plugins list --enabled
安装插件openclaw plugins install <package>
查看插件详情openclaw plugins inspect <id>
启用插件openclaw plugins enable <id>
禁用插件openclaw plugins disable <id>
卸载插件openclaw plugins uninstall <id>
插件健康检查openclaw plugins doctor

安装插件等同于运行外部代码，建议只安装可信来源，并尽量使用固定版本。

通讯渠道命令 ​

目标命令
列出渠道openclaw channels list
查看渠道状态openclaw channels status
探测渠道状态openclaw channels status --probe
查看渠道能力openclaw channels capabilities
查看渠道日志openclaw channels logs --channel all
添加渠道账号openclaw channels add --channel <channel>
交互式添加渠道账号openclaw channels add
旧版交互式登录openclaw channels login --channel <channel>
移除渠道账号openclaw channels remove --channel <channel> --delete

Telegram 示例：

bash
openclaw channels add --channel telegram --token <bot-token>

飞书示例：

bash
openclaw channels add

在向导中选择 Feishu，并填入飞书应用的 App ID 和 App Secret。

QQ 示例：

bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"

配对命令 ​

当私聊策略是 pairing 时，陌生用户首次私聊需要管理员批准。

bash
openclaw pairing list
openclaw pairing list --channel telegram
openclaw pairing approve telegram <CODE>
openclaw pairing deny telegram <CODE>

日志命令 ​

目标命令
查看最近日志openclaw logs
持续跟随日志openclaw logs --follow
限制日志行数openclaw logs --limit 100
输出 JSON 日志openclaw logs --json
查看渠道日志openclaw channels logs --channel all

排查问题时建议先开一个终端跟随日志：

bash
openclaw logs --follow

然后在另一个终端或通讯软件里复现问题。

报错处理 ​

openclaw: command not found ​

常见原因：

  • npm 全局 bin 目录没有加入 PATH
  • 安装脚本没有执行完成
  • 当前终端没有重新加载环境变量

处理方法：

bash
npm prefix -g
openclaw --version

如果 openclaw --version 仍不可用，重新安装：

bash
npm install -g openclaw@latest

然后关闭并重新打开终端。

Node.js 版本过低 ​

常见表现：

text
Unsupported engine
SyntaxError
Cannot find module

处理方法：

bash
node --version

建议使用 Node 24，至少 Node 22.14+。升级后重新执行：

bash
npm install -g openclaw@latest
openclaw doctor

Gateway 无法启动 ​

先查看状态和日志：

bash
openclaw gateway status
openclaw logs --follow

常见原因：

  • gateway.mode 缺失
  • 端口被占用
  • 配置文件损坏
  • 权限不足
  • SecretRef 无法解析

处理方法：

bash
openclaw doctor --repair
openclaw config validate
openclaw gateway restart

如果只是本地临时测试：

bash
openclaw gateway --allow-unconfigured

端口被占用 ​

常见表现：

text
EADDRINUSE
address already in use

处理方法：

bash
openclaw gateway status
openclaw gateway restart

如果需要强制抢占指定端口：

bash
openclaw gateway --force

先确认端口上的旧进程确实是 OpenClaw 或可以被停止的测试进程。

模型不可用 ​

先执行：

bash
openclaw models status
openclaw models status --probe
openclaw models list

常见原因：

  • API Key 错误
  • baseUrl 写错
  • 模型名没有在 Xikapi 后台启用
  • 默认模型引用没有 provider 前缀
  • 当前令牌没有模型权限
  • 上游限流或余额不足

Xikapi 常见配置应类似：

text
baseUrl: https://xikapi.com/v1
model: xikapi/YOUR_MODEL_ID

401 / 403 鉴权失败 ​

处理顺序：

  1. 检查 API Key 是否复制完整。
  2. 检查 Key 是否来自正确平台或 Xikapi 令牌。
  3. 检查模型是否在该令牌分组中可用。
  4. 运行模型探测：
bash
openclaw models status --probe

如果使用环境变量，重新打开终端或重新启动 Gateway。daemon / service 读不到当前终端临时环境变量时，改用持久环境变量、SecretRef 或受保护的密钥文件，详见 密钥与安全配置。

429 限流 ​

常见原因：

  • 并发过高
  • 模型限速
  • 令牌额度不足
  • 短时间重试过多

处理方法：

  • 降低并发
  • 增加重试退避
  • 切换到低成本或高配额模型
  • 在 Xikapi 后台检查令牌额度和模型权限

Skill 安装失败 ​

先检查：

bash
openclaw skills search "<keyword>"
openclaw skills info <name>
openclaw skills check

常见原因：

  • Skill slug 写错
  • 网络无法访问 ClawHub
  • 当前工作区不可写
  • 已安装同名 Skill
  • Skill 依赖安装失败

处理方法：

bash
openclaw skills install <slug> --force
openclaw skills check

如果希望安装到全局：

bash
openclaw skills install <slug> --global

插件安装失败 ​

先执行：

bash
openclaw plugins list
openclaw plugins doctor

常见原因：

  • 插件来源不可信
  • 插件配置 schema 不通过
  • 本地配置处于 invalid 状态
  • 网络无法访问 ClawHub 或 npm

处理方法：

bash
openclaw doctor --repair
openclaw plugins install <package>

不要轻易使用危险强制安装选项，除非你已经确认插件来源和代码内容。

飞书不回复 ​

检查：

bash
openclaw channels status --probe
openclaw channels logs --channel feishu
openclaw logs --follow

常见原因：

  • 没有完成 openclaw channels add
  • 飞书应用没有发布或没有审批通过
  • 没有启用机器人能力
  • 事件订阅没有选择长连接，或没有订阅 im.message.receive_v1
  • 群 ID 没加入 allowlist
  • 群聊要求 @ 机器人
  • Gateway 没有重启
  • App ID / Secret 配置错误

处理方法：

bash
openclaw channels add
openclaw gateway restart

Telegram 不回复 ​

检查：

bash
openclaw channels status --probe
openclaw channels logs --channel telegram
openclaw pairing list --channel telegram

常见原因：

  • Bot token 错误
  • 私聊还没有配对批准
  • 群里没有 @ 机器人
  • BotFather Privacy Mode 限制了群消息
  • Gateway 没有启动

处理方法：

bash
openclaw pairing approve telegram <CODE>
openclaw gateway restart

QQ 不回复 ​

检查：

bash
openclaw channels status --probe
openclaw channels logs --channel qqbot
openclaw logs --follow

常见原因：

  • qqbot 通道名写错
  • AppID / AppSecret 错误
  • Bot 没有加入群
  • group openid 配置错误
  • 群聊要求 @ 机器人
  • 使用 --token-file 但没有单独配置 AppID

处理方法：

bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"
openclaw gateway restart

当前版本通常已经内置 QQ Bot。只有在 openclaw channels status --probe 明确提示缺少 QQ Bot 能力时，才需要检查或安装 @openclaw/qqbot 插件。

修改配置后不生效 ​

常见原因：

  • Gateway 没有重启
  • CLI 使用的配置路径和 service 使用的配置路径不同
  • 环境变量只在当前终端生效

处理方法：

bash
openclaw config file
openclaw config validate
openclaw gateway status
openclaw doctor --deep
openclaw gateway restart

查看状态输出中的 CLI 配置路径和 service 配置路径是否一致。

SecretRef 无法解析 ​

常见表现：

text
SecretRef assignment(s) could not be resolved
Environment variable "XIKAPI_API_KEY" is not set
unsupported SecretRef usage

处理顺序：

  1. 运行 openclaw config validate，确认配置结构没有错误。
  2. 运行 openclaw config schema，确认当前版本支持你写入的字段。
  3. 检查 source 是否为 env、file 或 exec。
  4. 检查 provider 是否已经在 secrets.providers 中定义。
  5. 如果使用 env，确认 daemon / service 也能读取该环境变量。
  6. 如果使用 file，确认 id 是以 / 开头的 JSON Pointer。
  7. 如果使用 exec，确认命令路径可信、可执行，并按需要在 dry-run 时加入 --allow-exec。

常见支持面包括 Xikapi 模型 Key、Telegram botToken、飞书 appSecret、QQ clientSecret、Gateway Token 和部分 Skill / Plugin API Key。具体字段以 openclaw config schema 和官方 SecretRef 支持面为准。

建议先用 dry-run 验证：

bash
openclaw config set models.providers.xikapi.apiKey \
  --ref-provider default \
  --ref-source env \
  --ref-id XIKAPI_API_KEY \
  --dry-run

更多示例见 密钥与安全配置。

排查顺序建议 ​

遇到问题时按这个顺序排查：

  1. openclaw --version
  2. openclaw doctor
  3. openclaw config file
  4. openclaw config validate
  5. openclaw gateway status
  6. openclaw logs --follow
  7. openclaw models status --probe
  8. openclaw channels status --probe
  9. 根据具体渠道查看 openclaw channels logs --channel <channel>

如果日志中出现真实上游 HTTP 状态码，优先根据 HTTP 状态码判断是鉴权、限流、模型权限还是服务端错误。

参考链接 ​