OpenClaw 接入 Models Hub:一键配置与 providers 手动接入

用 Models Hub CLI 一键配置 OpenClaw,或手动编辑 openclaw.json 的 models.providers 接入自定义模型网关,附验证步骤与常见报错排查。

OpenClaw 是一个开源、自托管的个人 AI 助手平台,把消息应用连接到跑在你自己机器上的 AI 代理。把它的默认模型换成 Models Hub 后,Gateway 处理的所有对话都会用 Models Hub 的额度调用你指定的模型。本文只讲接入,不讲 OpenClaw 本身的安装与渠道配置,详见 OpenClaw 官方文档。

三样东西

接入只需要:Models Hub 的 API Key、接入地址 https://modelsok.com/v1(注意要带 /v1)、一个或多个模型名。

准备

已安装并跑通 OpenClaw:curl -fsSL https://openclaw.ai/install.sh | bash 装好后运行 openclaw onboard --install-daemon 完成引导,openclaw gateway status 能看到 Gateway 正常、openclaw dashboard 能打开 Control UI 即可,渠道(Telegram/Discord 等)先不用配。
一个 Models Hub API Key。在控制台的令牌页创建,令牌所在分组要能访问你打算用的模型。

用途	模型名	定价	实时状态
日常对话首选	`claude-sonnet-4-6`	查看价格	可用率与延迟
复杂任务与长上下文	`gpt-5.5`	查看价格	可用率与延迟
便宜快速,适合常驻小任务	`gpt-5.4-mini`	查看价格	可用率与延迟

方式一:一键配置(推荐)

Models Hub CLI 会把 API Key、接入地址和默认模型写入 ~/.openclaw/openclaw.json 与 ~/.openclaw/.env。

curl -fsSL https://modelsok.com/cli/install.sh | sh

装好后运行 models,在交互菜单选择 OpenClaw;或免交互执行 models configure --target openclaw --api-key <你的_API_KEY>。完整用法见 CLI 一键配置。

方式二:手动配置 providers

OpenClaw 通过 models.providers 接入自定义或兼容 OpenAI 接口的模型网关。先导出密钥,再编辑 ~/.openclaw/openclaw.json:

export MODELSOK_API_KEY="你的 Models Hub API Key"

{
  models: {
    mode: "merge",
    providers: {
      modelsok: {
        baseUrl: "https://modelsok.com/v1",
        apiKey: "${MODELSOK_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "gpt-5.5", name: "GPT-5.5" },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "modelsok/claude-sonnet-4-6",
        fallbacks: ["modelsok/gpt-5.5"],
      },
    },
  },
}

配置项	说明
`models.mode`	设为 `merge`,在保留 OpenClaw 内置 provider 的同时追加 `modelsok`
`models.providers.modelsok.baseUrl`	Models Hub 接入地址,必须带 `/v1`
`models.providers.modelsok.apiKey`	推荐通过 `${MODELSOK_API_KEY}` 注入,不要明文写密钥
`models.providers.modelsok.api`	Models Hub 是 OpenAI 兼容网关,固定填 `openai-completions`
`models.providers.modelsok.models`	这里的 `id` 必须与 Models Hub 的模型名完全一致
`agents.defaults.model.primary`	默认主模型,格式是 `modelsok/<模型名>`

验证

配置完成后重开 openclaw dashboard,发起一次对话,能正常回复且默认模型显示为 modelsok/... 即接通。也可以运行 openclaw models list 确认 modelsok/ 前缀的模型已出现在列表里。再打开 Models Hub 控制台的用量日志,几秒内会出现一条对应模型名的请求。

常见报错

现象	原因	处理
`baseUrl` 报连接失败	地址没带 `/v1`,这是最常见的接入错误	确认写的是 `https://modelsok.com/v1`
默认模型没有变成 `modelsok/...`	`agents.defaults.model.primary` 没改,或改错了字段层级	对照上面的 JSON 结构重新检查
`401` / 鉴权失败	Key 写错、多了空格,或令牌已被禁用	到令牌页重新复制
模型不存在	`models.providers.modelsok.models` 里的 `id` 与 Models Hub 模型名不一致	对照定价页核对
Gateway 以服务方式常驻运行时报读不到密钥	服务进程读不到当前终端 `export` 的环境变量	确认服务进程的环境变量里也有 `MODELSOK_API_KEY`,或换成一键配置写入的 `.env`

想前台排障,可用 openclaw gateway --port 18789 观察日志。更多排查见故障排查。

常见问题

计费方式? 按请求实际消耗的输入与输出 token 计费,价格在各模型的定价页,用量日志里能看到每一条请求的明细。

和直接用官方模型账号有什么区别? 请求格式一致,只是把 provider 换成了 Models Hub;一个 Key 能同时接入多家厂商的模型,不需要分别注册。

怎么切换模型? 修改 agents.defaults.model.primary 后重启 Gateway,或在 agents.defaults.models 里给模型起别名,对话中直接引用。

OpenClaw 接入 Models Hub:一键配置与 providers 手动接入

准备

推荐模型

方式一:一键配置(推荐)

方式二:手动配置 providers

验证

常见报错

常见问题

相关

本页目录