Skip to main content

​
前置条件

1

kapon 账号与 API Key

登录 kapon 控制台，创建可用于模型调用的 API Key（格式如 sk-xxxx）。kapon API 基础地址为 https://models.kapon.cloud。
2

OpenClaw 已安装并启动

确保 OpenClaw CLI 已安装且 Gateway 可正常运行。参见 安装与启动。

​
协议背景

不同品牌模型的接口协议并不相同，kapon 同时支持以下三类协议。你可以按需配置一个或多个 provider。
协议典型接口适用模型
OpenAI（GPT 协议）POST /v1/chat/completions 或 POST /v1/responsesGPT 系列及 OpenAI 兼容模型
Anthropic（Claude 协议）POST /v1/messagesClaude 系列
Google（Gemini 协议）POST .../models/{model}:generateContentGemini 系列

​
配置 kapon 模型提供方

编辑 OpenClaw 配置文件 ~/.openclaw/openclaw.json。
以下示例使用 JSON5 写法（允许注释与尾逗号）；若你环境严格要求 JSON，请去掉注释与尾逗号。示例中的模型 ID 需替换为你在 kapon 控制台中实际启用的模型 ID。

​
GPT（OpenAI 协议）

用于对接 GPT 系列以及任何走 OpenAI 协议的模型。 
{
  agents: {
    defaults: {
      model: { primary: "kapon-openai/gpt-5.4" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "kapon-openai": {
        baseUrl: "https://models.kapon.cloud",
        apiKey: "${KAPON_API_KEY}",
        api: "openai-completions",
        // 如 kapon 要求额外请求头，可在此追加
        // headers: { "X-Kapon-Project": "xxx" },
        models: [
          { id: "gpt-5.4", name: "GPT 5.4 (via kapon, OpenAI protocol)" },
        ],
      },
    },
  },
}

​
Claude（Anthropic 协议）

用于对接 Claude 系列（Anthropic 原生 messages 协议，推荐 claude-opus-4-6）。 
{
  agents: {
    defaults: {
      model: { primary: "kapon-anthropic/claude-opus-4-6" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "kapon-anthropic": {
        baseUrl: "https://models.kapon.cloud",
        apiKey: "${KAPON_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-opus-4-6", name: "Claude Opus 4.6 (via kapon, Anthropic protocol)" },
        ],
      },
    },
  },
}

​
Gemini（Google 协议）

Gemini 走 Google 原生协议，接口与鉴权方式不同于 OpenAI / Anthropic。 
{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3-pro-preview" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      google: {
        baseUrl: "https://models.kapon.cloud",
        apiKey: "${KAPON_API_KEY}",
      },
    },
  },
}
配置说明：
字段说明
agents.defaults.model.primaryOpenClaw 默认模型，格式为 provider/model
models.providers.*.baseUrl对应协议的 kapon 入口地址
models.providers.*.apiKeykapon 平台的 API Key
models.providers.*.api请求协议类型：openai-completions（GPT）或 anthropic-messages（Claude），Gemini 无需指定
models.providers.*.models[].idkapon 控制台中的实际模型 ID，需完全一致（含前缀、大小写）
models.providers.*.models[].name在 OpenClaw 中展示的模型名称
若只需一种协议，仅配置对应的 provider 即可。多协议可同时配置，在 agents.defaults.model.primary 中指定默认使用的模型。

​
使用环境变量（推荐）

为避免在配置文件中写死密钥，推荐使用系统环境变量： 
export KAPON_API_KEY="YOUR_KAPON_API_KEY"
配置中使用 ${KAPON_API_KEY} 占位符即可引用。确保启动 OpenClaw 的进程环境中已设置该变量。

​
重启 Gateway

修改配置后需重启 Gateway 使其生效。 直接启动： 
openclaw gateway --port 18789 --verbose
守护进程模式（systemd）： 
systemctl --user restart openclaw-gateway.service
重启后建议执行健康检查： 
openclaw doctor

​
验证集成

​
curl 验证协议连通性

分别验证已配置的协议是否打通。 GPT（OpenAI 协议）： 
curl -X POST "https://models.kapon.cloud/v1/chat/completions" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{ "role": "user", "content": "你好，请用一句话介绍你自己。" }],
    "temperature": 0.7
  }'
Claude（Anthropic 协议）： 
curl -X POST "https://models.kapon.cloud/v1/messages" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
  }'
Gemini（Google 协议）： 
curl -X POST "https://models.kapon.cloud/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "你好" }] }]
  }'

​
终端验证

openclaw agent --message "请说明你当前是通过 kapon 聚合平台调用模型的。"
若配置正确：
  • 终端会返回模型生成的文本
  • kapon 控制台的「调用日志 / 监控」中可看到对应调用记录

​
Web UI 验证

  1. 打开 OpenClaw Web UI
  2. 在「Models / 模型配置」中确认可看到已配置的 kapon 模型条目
  3. 在 WebChat / Playground 中选择模型，发送测试消息，确认返回正常

​
常见问题排查

  • 检查 kapon API Key 是否正确、未过期、权限充足
  • 使用上方的 curl 命令单独测试 kapon 接口
  • 示例验证：
curl -X POST "https://models.kapon.cloud/v1/messages" \
  -H "Authorization: Bearer YOUR_KAPON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
  }'
  • 确认模型 ID 与 kapon 控制台中的完全一致（包括前缀、大小写）
  • 在 kapon 控制台查看当前可用模型列表
  • 确认 OpenClaw 读取的是当前 ~/.openclaw/openclaw.json
  • 确认 agents.defaults.model.primary 与对应 provider 的 models[].id 一致
  • 如使用环境变量，确保启动 OpenClaw 的同一进程环境中已设置相关变量
  • 检查网络连通性：curl -I https://models.kapon.cloud
  • 确认各 baseUrl 地址正确
  • 如有代理，确保 OpenClaw 进程也使用了相同的代理配置