Xikapi 接入文档

密钥与安全配置 ​

OpenClaw 配置里会出现 Xikapi API Key、Telegram Bot Token、飞书 App Secret、QQ AppSecret、Gateway Token 等敏感信息。不要把这些内容写进公开仓库、截图、群聊或可公开下载的配置包。

哪些内容算密钥 ​

类型常见字段建议
Xikapi Keymodels.providers.*.apiKey使用环境变量或 SecretRef
Telegram Bot Tokenchannels.telegram.botToken使用 openclaw channels add 或 SecretRef
飞书 App Secretchannels.feishu.accounts.*.appSecret使用 SecretRef 或受保护配置文件
QQ AppSecretchannels.qqbot.clientSecret / channels.qqbot.accounts.*.clientSecret / clientSecretFile使用 SecretRef 或 clientSecretFile
Gateway Tokengateway.auth.token绑定非本机地址时必须配置
Webhook Tokencron.webhookToken、各渠道 webhook secret不要复用 Gateway Token

SecretRef 是什么 ​

SecretRef 允许 OpenClaw 在启动或重载时从外部来源读取密钥，而不是把明文直接写进 openclaw.json。

OpenClaw 使用统一对象形态：

js
{ source: "env" | "file" | "exec", provider: "default", id: "..." }

三种来源：

来源适合场景说明
env本机个人使用、简单部署从环境变量读取
file服务器或固定机器从本地受保护文件读取
exec企业密钥管理器执行指定命令读取，例如 Vault、1Password、sops

Xikapi Key 示例 ​

最简单的方式是环境变量：

bash
export XIKAPI_API_KEY="YOUR_XIKAPI_API_KEY"

Windows PowerShell：

powershell
$env:XIKAPI_API_KEY="YOUR_XIKAPI_API_KEY"

配置中可以用环境变量替换：

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

也可以使用 SecretRef：

js
{
  secrets: {
    providers: {
      default: { source: "env" }
    }
  },
  models: {
    providers: {
      xikapi: {
        baseUrl: "https://xikapi.com/v1",
        apiKey: { source: "env", provider: "default", id: "XIKAPI_API_KEY" },
        api: "openai-completions",
        models: [{ id: "YOUR_MODEL_ID", name: "My Xikapi model" }]
      }
    }
  }
}

如果用 CLI 写入 SecretRef，建议先 --dry-run：

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

确认无误后去掉 --dry-run 再写入。

Telegram Token 示例 ​

Telegram 的 SecretRef 支持 channels.telegram.botToken 和 channels.telegram.accounts.*.botToken。

js
{
  secrets: {
    providers: {
      default: { source: "env" }
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: { source: "env", provider: "default", id: "TELEGRAM_BOT_TOKEN" }
    }
  }
}

如果你刚开始使用，优先用向导写入配置：

bash
openclaw channels add --channel telegram --token "your BotFather token"

之后再按需要迁移到 SecretRef。

飞书 App Secret 示例 ​

飞书的 SecretRef 支持 channels.feishu.appSecret、channels.feishu.accounts.*.appSecret、encryptKey、verificationToken 等敏感字段。

js
{
  secrets: {
    providers: {
      default: { source: "env" }
    }
  },
  channels: {
    feishu: {
      enabled: true,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: { source: "env", provider: "default", id: "FEISHU_APP_SECRET" },
          name: "Xikapi Assistant"
        }
      }
    }
  }
}

appId 通常不是密钥，但仍不建议随意公开完整配置。appSecret 必须按密钥处理。

QQ AppSecret 示例 ​

QQ Bot 的 SecretRef 支持 channels.qqbot.clientSecret 和 channels.qqbot.accounts.*.clientSecret。如果使用环境变量：

js
{
  secrets: {
    providers: {
      default: { source: "env" }
    }
  },
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" }
    }
  }
}

也可以继续使用文件方式：

js
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "~/.openclaw/secrets/qqbot-secret.txt"
    }
  }
}

qqbot-secret.txt 中只放 AppSecret，不要把 AppID:AppSecret 整串都放进去。AppID 仍需要写在配置文件或持久环境变量中。

如果你使用多 QQ Bot 账号，可以在本地执行 openclaw config schema，按当前版本支持的 channels.qqbot.accounts.*.clientSecret 结构配置。

daemon 和 service 的环境变量问题 ​

PowerShell 的 $env:KEY="..." 和 macOS / Linux 的 export KEY="..." 只对当前终端会话可靠。OpenClaw 如果以 daemon / service 方式运行，通常不会读取你刚在终端里设置的临时环境变量。

更稳定的方式：

  • 使用 openclaw channels add、openclaw configure 或 openclaw config set 写入配置。
  • 使用系统级持久环境变量。
  • 使用 SecretRef 的 file 或 exec provider。
  • 把共享密钥放在权限受控的 ~/.openclaw/secrets.json 或单独密钥文件里。

file provider 示例 ​

密钥文件：

js
{
  "providers": {
    "xikapi": {
      "apiKey": "YOUR_XIKAPI_API_KEY"
    },
    "telegram": {
      "botToken": "123456:abc"
    }
  }
}

OpenClaw 配置：

js
{
  secrets: {
    providers: {
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json"
      }
    },
    defaults: {
      file: "filemain"
    }
  },
  models: {
    providers: {
      xikapi: {
        apiKey: { source: "file", provider: "filemain", id: "/providers/xikapi/apiKey" }
      }
    }
  },
  channels: {
    telegram: {
      botToken: { source: "file", provider: "filemain", id: "/providers/telegram/botToken" }
    }
  }
}

file provider 的 id 是 JSON Pointer，必须以 / 开头。

exec provider 示例 ​

如果你用企业密钥管理器，可以让 OpenClaw 执行一个固定命令读取密钥：

js
{
  secrets: {
    providers: {
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true
      }
    }
  },
  channels: {
    feishu: {
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: { source: "exec", provider: "vault", id: "channels/feishu/appSecret" }
        }
      }
    }
  }
}

exec 会运行本地命令。只使用可信命令，并确认命令路径、权限和输出格式。

权限边界 ​

  • Gateway 如果绑定到非本机地址，例如 0.0.0.0 或公网地址，必须配置认证。
  • Webhook token、Channel webhook secret、Gateway token 不要互相复用。
  • Skill 安装前先查看说明和权限：
bash
openclaw skills info <skill-slug>
  • 插件和 Skill 都可能执行外部代码，只安装可信来源。
  • 配置文件和密钥文件不要放进公开 Git 仓库。

安全检查清单 ​

bash
openclaw config file
openclaw config validate
openclaw doctor --deep
openclaw secrets audit --check
openclaw models status --probe
openclaw channels status --probe

遇到 SecretRef 解析失败时，先确认：

  • source 是否是 env、file 或 exec
  • provider 是否已经在 secrets.providers 中定义
  • id 是否符合对应来源要求
  • daemon / service 是否能读取到该环境变量或文件
  • 对应字段是否在本地版本的 SecretRef 支持面内

参考链接 ​