更多国产模型与自定义中转端点
国产模型专页到这里进入收尾: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-provider | stepfun、stepfun-plan | STEPFUN_API_KEY | stepfun/step-3.5-flash |
| 小米 MiMo | @openclaw/xiaomi-provider | xiaomi、xiaomi-token-plan | XIAOMI_API_KEY、XIAOMI_TOKEN_PLAN_API_KEY | xiaomi/mimo-v2.6-pro |
| 美团 LongCat | @openclaw/longcat-provider | longcat | LONGCAT_API_KEY | longcat/LongCat-2.0 |
StepFun:先分清中国 Key 和国际 Key
StepFun 的 Key 分区域,官方文档明确要求:中国 Key 配 .com 端点,国际 Key 配 .ai 端点,别混用。
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-flash | 262,144 | 65,536 | 默认模型 |
stepfun/step-3.7-flash | 262,144 | 262,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
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:一个模型,专注推理
openclaw plugins install @openclaw/longcat-provider
openclaw onboard --auth-choice longcat-api-keyKey 在 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 需在环境里已设置):
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-key | API 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 手写。无鉴权端点的官方示例(原样):
{
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、带完整模型元数据的写法(官方示例原样节选):
{
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 |
| ClawRouter | OpenClaw 官方托管的多上游路由 | 管理员签发的 policy-scoped Key | https://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 会话不断链。
# 方式一: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:
openclaw onboard --auth-choice litellm-api-key
# 提示代理地址时回车用默认 http://localhost:4000,或填你的代理 URL远程代理的非交互版(官方文档原样):
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(签发时显示一次,存好)。
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 步:验证中转链路
为什么:配置落盘不等于链路能通。目录、凭据、端到端对话各查一层,哪一层断了都知道去哪儿修——这一步对官方插件和自定义中转端点通用。
# 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>.baseUrlagent:模型回你一句话,命令退出码 0——错误、超时、取消都退出 1。中转链路端到端打通
测试通过后,把顺手的模型设为日常默认:
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 用多家走聚合路由。接下来:
- 下一课 本地模型:Ollama、vLLM 与 ds4:完全不出网、不花 API 费的本地推理——LongCat 开源权重本地跑也在这课
- 其他模型专页从 连接模型总览:provider 体系与模型切换 的课程表进
- 模型都配好了?日常使用从 日常使用:和你的 Claw 高效相处 开始——Control UI、聊天命令、记忆系统都在那一章
相关教程
- 接入 DeepSeek:V4 系列模型配置实战——官方插件接入的标准套路,本课 StepFun / MiMo / LongCat 装法同源
- 连接模型总览:provider 体系与模型切换——「装插件 → 配凭据 → 选模型」三步与
provider/model引用规则 - 接入豆包/火山引擎:方舟端点与 Coding Plan——火山系官方插件,含国际版 BytePlus
- 接入腾讯混元与百度千帆:大厂 MaaS 实战——上一课:腾讯、百度两家 MaaS
- 图片与语音:给内容配图、把文章转语音——小米 MiMo 插件自带 TTS(
mimo-v2.5-tts),配语音看这课