Xikapi 接入文档

配置总览 ​

OpenClaw 的配置核心是 Gateway、模型、Agent、Skill 和通讯渠道。建议先用向导生成基础配置，再用 openclaw config 做小范围修改，最后用状态命令验证。

配置文件位置 ​

OpenClaw 默认读取 JSON5 配置文件：

text
~/.openclaw/openclaw.json

查看当前 CLI 使用的配置文件：

bash
openclaw config file

如果你需要指定另一份配置文件，可以设置 OPENCLAW_CONFIG_PATH：

bash
export OPENCLAW_CONFIG_PATH="/path/to/openclaw.json"

Windows PowerShell：

powershell
$env:OPENCLAW_CONFIG_PATH="C:\path\openclaw.json"

注意：如果 Gateway 是 daemon / service，当前终端里的临时环境变量不一定会被服务读取。排查时要确认 CLI 配置路径和 service 配置路径一致。

四种修改方式 ​

方式适合场景说明
openclaw onboard首次安装、重新初始化完整 onboarding 流程，会引导模型、Gateway、daemon 等基础项
openclaw configure交互式调整配置适合不熟悉配置字段的新手
openclaw config ...单项修改、脚本化修改适合设置模型、Channel、Skill、SecretRef 等明确字段
直接编辑配置文件批量调整、复制示例适合熟悉 OpenClaw schema 的用户

常用命令：

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

修改前先预演：

bash
openclaw config set agents.defaults.model.primary xikapi/YOUR_MODEL_ID --dry-run

如果要写入 SecretRef，优先使用 builder 参数，减少手写 JSON 出错：

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

推荐配置顺序 ​

  1. 完成 安装指南。
  2. 进入配置向导，生成基础 openclaw.json。
  3. 配置 Xikapi 模型，并设置默认模型。
  4. 配置默认 Agent，例如工作目录、默认模型、权限范围。
  5. 按人群安装少量 Skill。
  6. 连接飞书、Telegram 或 QQ 等通讯渠道。
  7. 补齐 密钥与安全配置。
  8. 运行 doctor、模型探测和 Channel 探测。

最小配置结构 ​

下面是一个围绕 Xikapi 的简化示例：

js
{
  env: {
    XIKAPI_API_KEY: "YOUR_XIKAPI_API_KEY"
  },
  agents: {
    defaults: {
      model: {
        primary: "xikapi/YOUR_MODEL_ID"
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      xikapi: {
        baseUrl: "https://xikapi.com/v1",
        apiKey: "${XIKAPI_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "YOUR_MODEL_ID", name: "My Xikapi model" }
        ]
      }
    }
  }
}

生产环境不建议把真实 API Key 写进公开配置文件。密钥保存方式见 密钥与安全配置。

默认 Agent ​

最常用的是设置默认模型：

bash
openclaw config set agents.defaults.model.primary xikapi/YOUR_MODEL_ID

如果你有不同使用场景，可以继续配置多个 Agent，例如工作 Agent、个人 Agent、客服 Agent。多 Agent 配置要配合通讯渠道绑定规则一起设计，避免所有渠道都落到同一个高权限 Agent。

Skill 和 Channel ​

Skill 建议按实际人群逐步启用：

通讯渠道名称要使用 OpenClaw 的实际 channel key：

渠道配置名
Telegramtelegram
飞书 / Larkfeishu
QQ Botqqbot

不要把 telegram 写成 telegrm、tg，也不要把 qqbot 写成 qq。

热重载和重启 ​

OpenClaw Gateway 会监听 ~/.openclaw/openclaw.json，大多数配置可以热更新：

配置类型是否通常可热更新
channels.*可以
agents / models / routing可以
skills / tools / messages可以
gateway.port / bind / auth / TLS / HTTP需要重启或由 hybrid 模式处理
plugins / 基础设施类配置通常需要重启

修改后推荐按这个顺序验证：

bash
openclaw config validate
openclaw gateway status
openclaw models status --probe
openclaw channels status --probe

如果是 Gateway 服务端口、绑定地址、认证、TLS、插件等关键配置，直接重启更清晰：

bash
openclaw gateway restart

常见误区 ​

  • CLI 看到的是一份配置，daemon / service 实际读取的是另一份配置。
  • 临时 $env:... 或 export ... 只在当前终端生效，服务进程读不到。
  • 默认模型没有写 provider 前缀，例如应写 xikapi/YOUR_MODEL_ID。
  • 配置中使用了本地版本不支持的字段，没有先运行 openclaw config schema。
  • 把 Xikapi Key、Bot Token、App Secret 直接提交到公开仓库。

参考链接 ​