Skip to content
🚀 快速起步第 15 / 16 节

更多国产模型与自定义中转端点 ​

国产模型专页到这里进入收尾:DeepSeek、Qwen、GLM、Kimi、MiniMax、豆包、混元、千帆都有官方插件,前几课已经接完。这一课解决剩下三件事——还有官方插件的 StepFun、小米 MiMo、美团 LongCat;没有官方 provider 的星火、百川等模型怎么办;以及 OpenClaw 中转的万能解法:custom-api-key 自定义端点,加上 OpenRouter、LiteLLM、ClawRouter 三条聚合路由。全程约 10 分钟,本教程基于 v2026.10.9。

学完你能做什么 ​

  • 装上 StepFun、小米 MiMo、美团 LongCat 三家官方插件,跑通各自的默认模型
  • 分清哪些国产模型没有官方 provider(星火、百川、零一 Yi、商汤),不再浪费时间找插件
  • 用 custom-api-key 流程把任意 OpenAI 兼容中转端点接进 OpenClaw——onboarding 与配置文件两种写法
  • 接入 OpenRouter / LiteLLM / ClawRouter 三种聚合路由,一把 Key 用多家模型
  • 会调中转端点的兼容开关:reasoning_effort 报 400、内网端点被拒、厂商私有字段透传

🎒 开始前的准备 ​

  • 完成了 连接模型总览:provider 体系与模型切换:「装插件 → 配凭据 → 选模型」三步和 provider/model 引用规则心里有数
  • OpenClaw 已安装、Gateway 在运行:openclaw gateway status 有输出
  • 手里有要接入的凭据:厂商 API Key,或中转站给你的 baseUrl + API Key
  • 走服务器 / 守护进程部署的话,知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做 ​

第 1 步:选路线——官方插件、自定义端点还是聚合路由 ​

为什么:OpenClaw 接模型有三条路,选错会白忙活——先花 30 秒 对号入座。

你的情况走哪条路本课去哪一步
用 StepFun / 小米 MiMo / 美团 LongCat官方插件(外部,需安装)第 2 步
用星火、百川、零一 Yi、商汤——厂商提供了 OpenAI 兼容 API自定义端点 custom-api-key第 3 步
手里是中转站(给了 baseUrl + Key 的 OpenAI 兼容代理)自定义端点 custom-api-key第 3 步
想一把 Key 用多家模型 / 团队统一网关聚合路由第 4 步

先交代一个负结果(官方仓库 2026-11-03 全量核对):讯飞星火、百川、零一万物 Yi、商汤 SenseChat 在 OpenClaw 里没有官方 provider 插件——extensions/ 与 docs/providers/ 里都找不到对应目录。商汤的 SenseAudio 倒是内置插件,但那是语音转写服务,不是 SenseChat 大模型。所以别去找「星火插件」——这三家只能走第 3 步的自定义端点,或第 4 步的聚合路由。

第 2 步:接入 StepFun、小米 MiMo、美团 LongCat(官方插件三连) ​

为什么:这三家是国产模型官方插件的最后三席(火山国际版 BytePlus 在豆包那课讲过),装法与 DeepSeek 完全同一个套路——装插件、配 Key、选模型。

先看速览表(信息全部来自官方 provider 文档):

厂商插件包(外部,需安装)provider id环境变量默认模型
阶跃星辰 StepFun@openclaw/stepfun-providerstepfun、stepfun-planSTEPFUN_API_KEYstepfun/step-3.5-flash
小米 MiMo@openclaw/xiaomi-providerxiaomi、xiaomi-token-planXIAOMI_API_KEY、XIAOMI_TOKEN_PLAN_API_KEYxiaomi/mimo-v2.6-pro
美团 LongCat@openclaw/longcat-providerlongcatLONGCAT_API_KEYlongcat/LongCat-2.0

StepFun:先分清中国 Key 和国际 Key ​

StepFun 的 Key 分区域,官方文档明确要求:中国 Key 配 .com 端点,国际 Key 配 .ai 端点,别混用。

bash
openclaw plugins install @openclaw/stepfun-provider
openclaw onboard --auth-choice stepfun-standard-api-key-cn    # 中国 Key → api.stepfun.com
openclaw onboard --auth-choice stepfun-standard-api-key-intl  # 国际 Key → api.stepfun.ai

你应该看到:onboarding 提示粘贴 STEPFUN_API_KEY,验证通过后默认模型变为 stepfun/step-3.5-flash。

标准端点模型目录:

模型引用上下文最大输出备注
stepfun/step-3.5-flash262,14465,536默认模型
stepfun/step-3.7-flash262,144262,144多模态,支持图像输入

另有 Step Plan 端点(独立 provider,引用前缀 stepfun-plan/...,auth-choice 是 stepfun-plan-api-key-cn|intl),模型如 stepfun-plan/step-3.5-flash-2603。Step 3.7 支持 low / medium / high 三档 effort,没有非推理模式,/think off 会映射到 low。

小米 MiMo:按量付费与 Token Plan 两个 provider ​

bash
openclaw plugins install @openclaw/xiaomi-provider
openclaw onboard --auth-choice xiaomi-api-key          # 按量付费,sk-... Key
openclaw onboard --auth-choice xiaomi-token-plan-sgp   # Token Plan,tp-... Key(区域可选 cn / sgp / ams)

按量付费 Key 在小米 MiMo 控制台创建:platform.xiaomimimo.com/#/console/api-keys;Token Plan 则从订阅页复制区域端点和配套的 tp-... Key。

模型一览:mimo-v2.6-pro(默认)、mimo-v2.6-flash、mimo-v2.6-pro-ultraspeed(官方目录标注 20x 输出速度)、mimo-v2.5、mimo-v2.5-pro——上下文都是 1,048,576 token。/think 全等级支持(off 到 max,默认 high)。这个插件还带 TTS(mimo-v2.5-tts),想给 Claw 配语音可以看图片与语音那课。

美团 LongCat:一个模型,专注推理 ​

bash
openclaw plugins install @openclaw/longcat-provider
openclaw onboard --auth-choice longcat-api-key

Key 在 LongCat API 平台创建:longcat.chat/platform/api_keys。

模型只有一个:longcat/LongCat-2.0——1,048,576 上下文 / 131,072 最大输出,纯文本输入,官方定位是「为 coding 与 agentic 工作负载构建的推理模型」。价格(官方文档口径,每百万 token):输入 $0.75(未缓存)/ $0.015(缓存命中),输出 $2.95。

💡 LongCat 开源权重想本地跑?

不要用 longcat/LongCat-2.0 这个引用去连本地部署——它指向的是托管 API。本地跑开源权重走 vLLM / SGLang,见下一课 本地模型:Ollama、vLLM 与 ds4。

  • 装了哪一家,openclaw models list --provider stepfun(或 xiaomi / longcat)就能列出它的模型目录

第 3 步:配置 OpenClaw 中转端点——custom-api-key 通用流程 ​

为什么:星火、百川、零一、商汤没有官方插件;市面上的「中转站」「API 代理」也各是各的私有部署。但只要对方给你一个 OpenAI 兼容的 baseUrl + API Key,OpenClaw 就能用 custom-api-key 流程接入——这是本课要讲的核心方法。

方式 A(推荐):onboarding 一条命令 ​

非交互全参数版(参数取自官方文档示例,$CUSTOM_API_KEY 需在环境里已设置):

bash
openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --custom-compatibility openai

五个参数各管一件事:

参数作用注意
--custom-base-url中转站地址OpenAI 兼容端点通常要带 /v1,见踩坑提醒
--custom-model-id模型 ID可以省略:省略时从端点的 /models 自动发现(5 秒超时),保存发现的全部模型、第一个当默认;发现失败就重跑并显式指定
--custom-api-keyAPI Key省略时读环境变量 CUSTOM_API_KEY
--custom-compatibility协议形态openai(默认,chat completions)/ openai-responses(只有 /v1/responses 的端点)/ anthropic;anthropic 必须给 --custom-model-id
--custom-image-input / --custom-text-input输入类型常见视觉模型 ID(GPT-4o/4.1/5.x、Claude 3/4、Gemini、Qwen-VL、LLaVA、Pixtral 等)自动标图像输入;不在名单里的视觉模型用前者强制标注

你应该看到:命令跑完无报错;openclaw models status 里多出一个自定义 provider,默认模型指向你给的 ID。

不想背参数?交互式跑 openclaw onboard,选 Custom setup 走全部引导选项,填的是同样的东西。

⚠️ Gateway 跑成守护进程?Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时,看不到你终端里 export 的环境变量。把 Key 写进 ~/.openclaw/.env,或经配置里的 env.shellEnv 提供给那个进程。

方式 B:手动改配置文件 ​

喜欢一切尽在掌握,或者要在多台机器批量铺配置——models.providers 手写。无鉴权端点的官方示例(原样):

json5
{
  agents: {
    defaults: { model: { primary: "my-studio/qwen3.8" } },
  },
  models: {
    providers: {
      "my-studio": {
        baseUrl: "https://studio.example.ts.net/v1",
        api: "openai-completions",
        auth: "none",
        models: [{ id: "qwen3.8", name: "Qwen3.8" }],
      },
    },
  },
}

带 Key、带完整模型元数据的写法(官方示例原样节选):

json5
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

模型字段可以省,省略时的默认值:reasoning: false、input: ["text"]、cost 全 0、contextWindow 不设时按 200000 兜底。官方建议:按你代理 / 模型的真实上限显式写全。

无鉴权端点:auth: "none" ​

内网自建、tailnet / VPN 上的推理服务常常不设 Key。OpenClaw 支持,但有两条硬规则:

  • 显式声明 auth: "none"(onboarding 对应 --custom-no-auth,不能与 --custom-api-key 同用)——自动无鉴权检测只覆盖 loopback 和 RFC1918 地址,tailnet / VPN 这种「私网但非 RFC1918」必须显式声明
  • auth: "none" 只对 openai-completions 适配器生效;Responses、Azure OpenAI、Anthropic 兼容端点即使无鉴权也要放一个占位 Key

中转端点的兼容开关(compat) ​

OpenClaw 对「baseUrl 不是 api.openai.com 的 openai-completions 端点」自动做一层保守裁剪,防止中转站被 OpenAI 专属字段打爆。自动规则与手动开关对照:

现象 / 需求开关
中转站不认 developer 角色自动:非原生端点强制 compat.supportsDeveloperRole: false(显式写 true 也会被覆盖)
报 400:不认识 reasoning_effort该模型设 compat.supportsReasoningEffort: false(reasoning: true 的自定义模型开 thinking 时默认会发这个字段)
thinking 会话要求回放 reasoning_content设 compat.requiresReasoningContentOnAssistantMessages: true(回放字段名 reasoning / reasoning_text / reasoning_content 默认保留原样)
要透传厂商私有字段agents.defaults.models["provider/model"].params.extra_body(或 extraBody),合并进请求体
LAN / tailnet 端点被拒models.providers.<id>.request.allowPrivateNetwork: true(loopback 默认放行)
慢端点老超时models.providers.<id>.timeoutSeconds
Anthropic 兼容中转不认 beta 头自动:抑制隐式 beta headers(如 claude-code-20250219);确需 beta 特性时在 models.providers.<id>.headers["anthropic-beta"] 显式声明
  • openclaw models status 能看到自定义 provider 的凭据来源;端点地址用 openclaw config get models.providers.<id>.baseUrl 查看

第 4 步:聚合路由三选一——OpenRouter、LiteLLM、ClawRouter ​

为什么:不想每家模型都注册一遍?聚合路由给你一把 Key、多家模型。三个插件全部内置在 OpenClaw 里(included in OpenClaw),不用先装。

路由是什么认证默认地址 / 模型
OpenRouter商业聚合服务,一把 Key 调多家模型OAuth 或 API Key默认模型 openrouter/auto
LiteLLM开源自建 LLM 网关(100+ provider)代理自己的 Key默认代理 http://localhost:4000
ClawRouterOpenClaw 官方托管的多上游路由管理员签发的 policy-scoped Keyhttps://clawrouter.openclaw.ai

OpenRouter:一把 Key 用国产 + 海外模型 ​

内置 starter 目录里就有国产模型:openrouter/moonshotai/kimi-k2.6、openrouter/moonshotai/kimi-k2.5;其他引用形如 openrouter/<provider>/<model>,动态解析 OpenRouter 官方目录。经 OpenRouter 调 DeepSeek V4 时,OpenClaw 会自动补 reasoning_content 回放,thinking 会话不断链。

bash
# 方式一:API Key(在 openrouter.ai/keys 创建)
openclaw onboard --auth-choice openrouter-api-key

# 方式二:聊天里直接 OAuth(私聊发送,浏览器登录授权)
/login openrouter

你应该看到:验证通过后默认模型为 openrouter/auto。想锁定具体模型:openclaw models set openrouter/moonshotai/kimi-k2.6。

LiteLLM:自建统一网关,成本记账 ​

LiteLLM 是开源 LLM 网关,统一 API 接 100+ provider,带成本追踪、日志、限额虚拟 Key 和后端故障转移。OpenClaw 接它的 OpenAI 兼容 /v1:

bash
openclaw onboard --auth-choice litellm-api-key
# 提示代理地址时回车用默认 http://localhost:4000,或填你的代理 URL

远程代理的非交互版(官方文档原样):

bash
openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice litellm-api-key \
  --litellm-api-key "$LITELLM_API_KEY" --custom-base-url "https://litellm.example/v1"

onboarding 会调代理的 /v1/models 发现模型,第一个当默认;发现失败会提示你手动填 ID。LAN 里的 LiteLLM 代理记得加 request.allowPrivateNetwork: true。要给不同人发限额 Key,用 LiteLLM 的 POST /key/generate(max_budget / budget_duration)。

ClawRouter:官方托管,凭据不出家门 ​

ClawRouter 是 OpenClaw 官方的托管多上游路由:上游各家的凭据与转发都留在 ClawRouter 侧,你的 OpenClaw 机器上不用装任何上游 provider 插件。插件内置且默认启用,你只需要一把管理员签发的 Key(签发时显示一次,存好)。

bash
export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter
openclaw models list --all --provider clawrouter

(clawrouter 本就默认启用;只有配置里设了 plugins.allow 时才需要先把它加进允许列表。)

模型引用保留上游命名空间,三段式:clawrouter/openai/gpt-5.5、clawrouter/anthropic/claude-sonnet-4-6、clawrouter/google/gemini-3.5-flash——照目录返回的原样用,openclaw models set clawrouter/<provider>/<model>。目录按 Key 的权限作用域经 /v1/catalog 发现(缓存 1 小时),配额走 /v1/usage。

第 5 步:验证中转链路 ​

为什么:配置落盘不等于链路能通。目录、凭据、端到端对话各查一层,哪一层断了都知道去哪儿修——这一步对官方插件和自定义中转端点通用。

bash
# 1. 看目录:新接入的 provider 和模型有没有进来
openclaw models list

# 2. 看凭据:默认模型、fallback,以及各 provider 的凭据来源
openclaw models status

# 3. 发一条测试消息,确认端到端连通
openclaw agent --agent <agent-id> --model <provider/model> --message "用一句话介绍你自己"

第 3 条命令从终端跑一轮完整的 agent turn(经 Gateway 转发)。注意 openclaw agent 至少要带一个会话选择器:--agent、--to、--session-key 或 --session-id,最常用 --agent <id>;--model 接受 provider/model 引用,只对这一轮生效,不改会话默认值。

你应该看到:

  • models list:目录里出现你刚接入的 provider 与模型——自定义端点显示 onboarding 保存的模型 ID(自动发现会把 /models 返回的全部模型都存进来)
  • models status:默认模型指向你选的模型,自定义 provider 的凭据来源正常显示;没有「Unavailable auth profiles」字样(有的话,条目会附上原因与恢复动作,照着做即可)。想核对端点地址:openclaw config get models.providers.<id>.baseUrl
  • agent:模型回你一句话,命令退出码 0——错误、超时、取消都退出 1。中转链路端到端打通

测试通过后,把顺手的模型设为日常默认:

bash
openclaw models set <provider/model>
  • 测试消息有回复、openclaw agent 退出码 0——中转链路端到端打通

检查点 ✅ ​

  • 用哪家装哪家:openclaw models list --provider stepfun(或 xiaomi / longcat)能列出模型目录
  • 记住负结果:星火、百川、零一 Yi、商汤 SenseChat 没有官方 provider——直接走 custom-api-key 自定义端点或聚合路由,不再花时间找插件
  • 自定义端点已接入:openclaw models status 能看到该 provider 的凭据来源,openclaw config get models.providers.<id>.baseUrl 能查到端点地址
  • openclaw agent 测试消息有回复、退出码 0——OpenClaw 中转链路端到端打通
  • 遇到兼容问题知道去哪查:第 3 步的 compat 开关表(reasoning_effort 报 400、内网端点被拒、厂商私有字段透传)

踩坑提醒 ​

❌ baseUrl 少了 /v1,请求全 404 ​

OpenAI 兼容端点的 baseUrl 一般要写到 .../v1:模型发现请求的是 <baseUrl>/models(官方文档举例 /v1/models),对话请求同样拼在 baseUrl 后面(如 /v1/chat/completions)。官方示例里的 baseUrl 全部以 /v1 结尾。拿到中转站地址先看一眼结尾,不确定就把它文档里的「Base URL」原样抄进来。

❌ 模型自动发现失败,或默认模型不是想要的 ​

省略 --custom-model-id 时,onboarding 会请求 <baseUrl>/models 自动发现(5 秒超时),保存发现的全部模型、第一个当默认。端点不可用、返回无效数据或列表为空都会失败——重跑并显式指定 --custom-model-id。发现的第一个模型不合适?不用重配,openclaw models set <provider/model> 换默认即可。

❌ StepFun 中国 Key 配了国际端点(或反过来) ​

StepFun 的 Key 分区域:中国 Key 配 .com 端点,国际 Key 配 .ai 端点,官方文档明确要求别混用。auth-choice 选 stepfun-standard-api-key-cn 还是 -intl 时就决定了端点——认证失败先检查是不是选错了区域。

❌ Anthropic 兼容端点没给 --custom-model-id ​

--custom-compatibility anthropic 的设置必须带 --custom-model-id——Anthropic 兼容端点没有模型自动发现这一步,省略会直接失败。

❌ auth: "none" 不生效 ​

两条硬规则:① 自动无鉴权检测只覆盖 loopback 和 RFC1918 地址,tailnet / VPN 上的端点必须显式声明 auth: "none"(onboarding 对应 --custom-no-auth,不能与 --custom-api-key 同用);② auth: "none" 只对 openai-completions 适配器生效——Responses、Azure OpenAI、Anthropic 兼容端点即使无鉴权也要放一个占位 Key。

❌ Gateway 跑成守护进程后,export 的 Key「不生效」 ​

Gateway 作为 launchd / systemd 服务运行时,看不到你终端里 export 的环境变量。把 Key 写进 ~/.openclaw/.env,或经配置里的 env.shellEnv 提供给那个进程(第 3 步方式 A 的警告框讲过,属高发坑,这里再提醒一次)。

❌ 中转站不认 reasoning_effort,一开 thinking 就 400 ​

reasoning: true 的自定义模型开 thinking 时默认会发 reasoning_effort 字段,部分中转站不认。给该模型设 compat.supportsReasoningEffort: false。其他兼容问题(developer 角色被拒、私有字段透传、内网端点被拒)见第 3 步的 compat 开关表。

❌ 中转站余额不足 / 计费没配好 ​

链路配置全对也可能倒在计费上:中转站余额不足、绑定的模型未开通,请求都会失败。想用 OpenClaw 自带的活体检查:openclaw models status --probe 对已配置的凭据发真实请求(可能消耗 token、触发限流),计费类失败归入 billing 状态桶;注意它要求独占状态目录,先 openclaw gateway stop 停掉 Gateway 再跑。日常排查先去中转站后台核对余额与模型开通状态,更直接。

下一步 ​

国产模型专页到此收官:官方插件(DeepSeek、Qwen、GLM、Kimi、MiniMax、豆包、混元、千帆、StepFun、MiMo、LongCat)、自定义端点、聚合路由三条路你都走通了。OpenClaw 中转的万能解法记住一句话:有官方插件装插件,没有官方 provider 就 custom-api-key,想一把 Key 用多家走聚合路由。接下来:

相关教程 ​

搞懂AI关于我们怎么写隐私说明

独立的第三方教程,与文中提到的任何产品及其公司没有隶属或合作关系;产品名称和商标归各自所有者。价格和政策以官方页面为准。