OpenClaw 支持通过 models.providers 接入任意 OpenAI 兼容端点。这篇整理一下完整的配置流程，包括自定义 Provider 声明、多模型分层路由、以及调试过程中踩的几个坑。

---

背景

OpenClaw 内置支持 Anthropic、OpenAI、Google 等十几个 Provider，日常使用基本够用。但如果你有自建的 vLLM 服务、跑了 LiteLLM 做统一代理、或者想通过第三方网关把多家模型聚合到一个端点下，就需要用到 models.providers 的自定义配置。本文以 TikHub AI（ai.tikhub.io）的端点为例演示配置过程，其他兼容端点的配置方式一致。

原理很简单：只要目标端点实现了 OpenAI Chat Completions 或 Anthropic Messages 协议，就能作为自定义 Provider 接入。下面用 ai.tikhub.io 的端点做演示。

---

配置自定义 Provider

编辑 ~/.openclaw/openclaw.json，在 models.providers 中添加：

{
  "models": {
    "mode": "merge",
    "providers": {
      "tikhub": {
        "baseUrl": "https://ai.tikhub.io/v1",
        "apiKey": "${TIKHUB_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gemini-2.5-pro",
            "name": "Gemini 2.5 Pro",
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "gemini-2.5-flash",
            "name": "Gemini 2.5 Flash",
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "claude-sonnet-4-20250514",
            "name": "Claude Sonnet 4",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

几个关键字段说明：

• mode: "merge"：和内置 Provider 合并，而不是覆盖。漏了这个字段会导致内置模型全部消失
• api: "openai-completions"：声明端点协议类型。如果目标端点走 Anthropic 协议，改成 "anthropic-messages"
• models 数组：显式声明可用模型。contextWindow 和 maxTokens 是可选的，但建议填上——OpenClaw 会根据这些值决定上下文截断策略

设好环境变量后验证：

export TIKHUB_API_KEY=your-key
openclaw models list

如果输出里能看到 tikhub/gemini-2.5-pro 等模型，说明配置生效。

---

分层路由：primary / fallback / economy

OpenClaw 的模型分层机制是比较实用的设计。它允许你为不同复杂度的任务指定不同模型，Agent 会根据任务类型自动选择：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "tikhub/claude-sonnet-4-20250514",
        "fallback": "tikhub/gemini-2.5-pro",
        "economy": "tikhub/gemini-2.5-flash"
      }
    }
  }
}

各层的作用：

层级	触发场景	适合模型
primary	复杂推理、代码生成	Claude Sonnet / Opus
fallback	primary 不可用时的降级	Gemini 2.5 Pro
economy	heartbeat、简单消息回复、状态检查	Gemini 2.5 Flash

这里值得注意的是：OpenClaw 作为 24/7 Agent，大量 token 消耗来自 heartbeat 和日常消息处理这类轻量任务。如果不分层，这些任务也会走 primary 模型，纯粹是浪费。把 economy 层单独配出来之后，整体 token 分布会明显更合理。

---

调试与验证

配置过程中比较容易出问题的几个地方：

1. 先用 curl 确认端点本身没问题

在配置 OpenClaw 之前，先单独测试端点连通性：

curl https://ai.tikhub.io/v1/chat/completions \
  -H "Authorization: Bearer $TIKHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"ping"}]}'

如果 curl 都不通，那问题在端点或者 Key，不用去查 OpenClaw 的配置。

2. JSON 语法检查

openclaw.json 的语法错误是最常见的问题（漏逗号、多逗号、引号不匹配）。可以直接让 OpenClaw 帮你查：

帮我检查一下 openclaw.json 的配置有没有语法错误

3. 模型引用格式

自定义 Provider 下的模型引用格式是 provider名/模型id，比如 tikhub/gemini-2.5-flash。在 agent 配置里不能只写 gemini-2.5-flash，OpenClaw 会把它解析到内置的 Google Provider 上去。

---

其他注意事项

contextWindow 声明的影响：如果不显式声明 contextWindow，OpenClaw 会用默认值（通常偏保守）。这意味着 Claude Sonnet 的 200K 上下文不会被充分利用——Agent 在构造 prompt 时会过早截断历史消息。建议对每个模型都显式设置这个值。

Streaming 行为差异：对于非原生 OpenAI 端点，OpenClaw 会自动开启一些兼容参数（比如 compat.supportToolResultContent）。大部分情况下这个自动处理是 OK 的，但如果遇到 streaming 输出卡住或者 tool calling 返回格式异常，可以检查一下 provider 的 compat 配置项。

多 Provider 的 fallback 策略：如果你同时配了内置 Provider 和自定义 Provider，建议 primary 和 fallback 用不同来源——这样一个 Provider 出问题时还有退路。比如 primary 走自定义端点的 Claude Sonnet，fallback 走内置 Google 的 Gemini 2.5 Pro。

---

以上是完整的配置流程。OpenClaw 的 models.providers 机制扩展性不错，基本上只要是 OpenAI 或 Anthropic 兼容协议的端点都能接进来。分层路由配好之后，token 消耗的分布会合理很多。以上是个人折腾过程中的一些经验总结，欢迎大佬们评论区交流指点。