在 OpenClaw 里用 Kimi 模型：K3 配置与排错
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
在 OpenClaw 里接 Kimi，官方文档给的是一条「插件 → 向导 → 默认模型」的主路径：先用 openclaw plugins install @openclaw/moonshot-provider 装官方 Moonshot Provider 并重启 Gateway，再跑 openclaw onboard --auth-choice moonshot-api-key-cn 走完认证向导，最后把默认模型设成 moonshot/kimi-k3。官方常见问题里列出的三个坑分别是 401 / Invalid Authentication、找不到 Moonshot 认证选项、K3 不在模型列表；前两个的答复各只有两三句，第三个官方给了两级兜底——先 openclaw models list --provider moonshot 看一眼、不行就升级插件重启 Gateway、再不行就在 ~/.openclaw/openclaw.json 里手工补一条 K3 模型条目。文档还专门强调了这条手写条目里的 compat 三个字段不能删。另外文档明确写了：kimi-k2.5 已停止向新注册用户开放，旧版向导截图里的 Moonshot AI (Kimi K2.5) 预设属于历史配置，不要留着当默认模型。
先搞清楚 OpenClaw 是个什么东西
按官方文档的描述，OpenClaw（前身为 Clawdbot 和 Moltbot）是一个开源的自托管 AI 智能体平台，让你在本地运行 AI 助手。它集成了 WhatsApp、Telegram、Discord、Slack 和 Signal 这些消息应用，把大语言模型接到实际工作流程里。文档同时点出了它的三个特点：支持多个 LLM 提供商、技能可扩展、你完全掌控自己的数据和 API 密钥。
这句「完全掌控自己的数据和 API Key」对配置方式有直接影响——密钥是落在你本机的，不经过第三方托管。所以官方文档紧接着给了一条安全提醒：API Key 只在本机向导或终端中输入，不要写入文档、截图、仓库或聊天记录。这条别当客套话，自托管场景下配置文件就在你自己的目录里，最容易出事的恰恰是顺手把配置片段贴进 issue 或者群聊。密钥保管的通用做法可以另看API Key 安全管理。
另外要注意文档给这套步骤划的适用范围：以下步骤基于 OpenClaw 2026.7.1 和官方 Moonshot Provider，使用 Kimi K3 完成 Chat Completion 配置。也就是说这是一份有版本锚点的教程，你手上版本差太远时，命令名和向导措辞都可能对不上，以官方文档当前版本为准。
动手之前的四项准备
官方把准备工作单列了一节，而且说得很克制——安装、源码和账号相关操作请按照对应的官方入口完成，这篇文档只展开 Kimi 在 OpenClaw 中的配置。具体是四件事：
- 按 OpenClaw 官方入口完成安装或更新；
- 需要看仓库、版本和变更说明的，去官方仓库；
- 在中国区 Kimi 开放平台创建并妥善保存 API Key；
- 确认账户状态满足调用条件。
第四项听着像走过场，其实是官方在准备一节里单独交代的硬条件，配置本身全写对了也可能栽在它上面。文档写得很直白：Kimi K3 需要账户有可用余额；调用限额随用户等级变化。而 Kimi 的等级规则在充值与限速页里说明，是基于账户的累计充值金额做速率限制的，页面还额外注明代金券不计入累计充值总额——也就是说代金券不会把你的等级和限速档位抬上去。还有更要紧的一条写在账户与支付页里：官方明确回答了「新用户赠送的代金券可以体验 Kimi K3 吗」这个问题，答案是不可以，国内注册并完成认证的用户获赠的新用户代金券不可用于体验 Kimi K3，需要充值后解锁使用。本文从头到尾配的就是 K3，所以别指望靠新用户代金券把这条链路跑通，配置全对了也可能卡在这一步。速率限制这类概念本身怎么读，可以看RPM 与 TPM 到底限的是什么。
还有一项条件是组织维度的：如果组织启用了 IP 白名单，请先按照组织最佳实践添加当前网络的出口 IPv4 地址。官方对白名单的说明是，配置并保存后仅白名单内的 IP 可以访问当前组织下的 API，不在白名单内的 IP 发起 API 请求时无法访问当前组织资源；白名单为空时不限制调用来源。对 OpenClaw 这种自托管场景，请求是从你本机或你自己那台服务器发出去的，出口 IP 跟你团队线上服务往往不是同一个，所以「线上服务好好的，本地 OpenClaw 死活连不通」这种情况有一个很现实的解释就在这里。文档也提醒了保存白名单时是整体覆盖原有配置，别为了加一个本机 IP 把线上那批覆盖没了。
装官方 Provider，然后重启 Gateway
准备工作齐了，正式配置从两条命令开始：
openclaw plugins install @openclaw/moonshot-provider
openclaw gateway restart
这里的关键信息是插件包名 @openclaw/moonshot-provider，它是官方 Moonshot Provider。注意第二条 gateway restart 不是可选步骤：文档在正文和常见问题两处都把「装插件」和「重启 Gateway」写成一组，两处的命令写法一字不差。至于 Gateway 为什么必须重启一次、它内部是怎么加载新 Provider 的，官方文档里没有给出对应说明，这里也就不替它编解释了——照做就是。后面你会看到，「找不到 Moonshot 认证选项」这个问题的官方答复，原样就是这两条命令。
跑 onboard 向导：这四步分别选什么
装完插件运行配置向导：
openclaw onboard --auth-choice moonshot-api-key-cn
--auth-choice 后面这个 moonshot-api-key-cn 是中国区的认证选项标识，别写错。向导里依次要选四项，官方给的对应关系是：
- 第 1 步 Model auth provider：选 Moonshot；
- 第 2 步 Model AI auth method：选 Kimi API key (.cn)；
- 第 3 步 Enter Moonshot API Key (.cn)：输入中国区 API Key；
- 第 4 步 Default model：完成向导后设置为
moonshot/kimi-k3。
第 4 步的措辞值得留意——文档写的是「完成向导后设置为」，也就是说这一步不一定能在向导里当场选到 K3。文档紧跟着就给了替代命令：
openclaw models list --provider moonshot
openclaw models set moonshot/kimi-k3
先列出该 Provider 下的模型确认 K3 在不在，再显式把默认模型设过去。这两条命令后面排查时还会再用到，值得记住。
K3 不在列表里：官方给的两级兜底
如果稳定版 Provider 目录仍然没有 K3，官方的第一级处理是升级插件并重启 Gateway，再列一次：
openclaw plugins update @openclaw/moonshot-provider
openclaw gateway restart
openclaw models list --provider moonshot
第二级才是手工改配置。文档说，如果升级后仍没有 K3，可以在 ~/.openclaw/openclaw.json 的 models.providers.moonshot.models 中补充 K3 条目，并且特别交代了保留已有模型。官方给出的片段是这样的：
{
"models": {
"mode": "merge",
"providers": {
"moonshot": {
"baseUrl": "https://api.moonshot.cn/v1",
"api": "openai-completions",
"models": [{
"id": "kimi-k3",
"name": "Kimi K3",
"reasoning": true,
"input": ["text", "image", "video"],
"contextWindow": 1048576,
"maxTokens": 8192,
"thinkingLevelMap": {
"off": null, "minimal": "max", "low": "max", "medium": "max",
"high": "max", "xhigh": "max", "max": "max"
},
"compat": {
"maxTokensField": "max_tokens",
"supportsUsageInStreaming": false,
"requiresStringContent": true,
"supportsReasoningEffort": true,
"supportedReasoningEfforts": ["minimal", "low", "medium", "high", "xhigh", "max"]
}
}]
}
}
}
}
几个字段值得逐个说清楚，因为它们解释了很多「为什么要这么写」：
"mode": "merge" 是合并模式，配合文档那句「保留已有模型」看就明白了——你是在往现有 Provider 配置上叠加一条，而不是整段替换掉。baseUrl 指向中国区端点，api 声明为 openai-completions，也就是走 OpenAI 风格的 Chat Completion 形态，这跟本文开头「使用 Kimi K3 完成 Chat Completion 配置」的定位是一致的。
reasoning: true 和 input: ["text", "image", "video"] 是这条模型条目声明的属性。注意这是配置文件里给 OpenClaw 看的模型描述，写在这里表示按此条目参与调度。
contextWindow 和 maxTokens 这两项，文档专门解释过一句，很值得抄下来理解：contextWindow 保持 1M；maxTokens 使用 8192 作为 OpenClaw 单次回复上限，避免把 1M 输入窗口误当成单次输出上限。这是配置里最容易望文生义的地方——输入窗口和单次输出上限根本不是一回事，把大窗口当成「一口气能吐这么多」是个典型误解。这两个数值以官方文档当前版本为准。
thinkingLevelMap 把 OpenClaw 侧的各档思考等级映射到具体取值，除了 off 是 null，其余各档全都映射到 max。为什么全映射成同一个值？文档给了明确原因：K3 的服务端思考参数固定为 max。也就是说这不是偷懒写法，而是如实反映服务端行为——你在 OpenClaw 里挑哪一档，落到服务端都是同一档。
compat 里那三个字段，文档说不能删
compat 块看上去像是可以精简掉的可选项，官方却在正文里专门点名了三个字段：maxTokensField: "max_tokens"、supportsUsageInStreaming: false 和 requiresStringContent: true 是 K3 兼容性配置，不能删除。原因文档也写了一句：K3 对 max_completion_tokens、流式 usage 和纯文本数组 content 的兼容性不同。
把这句话拆开看，三个字段各自对应一件事。maxTokensField 指定输出上限用哪个字段名传，这里显式声明为 max_tokens，而不是另一个同类字段 max_completion_tokens。supportsUsageInStreaming: false 声明流式响应里不按支持 usage 的方式处理。requiresStringContent: true 声明 content 需要按字符串形态给，而不是纯文本数组那种结构。
这三条本质上都是「兼容层要按哪种写法发请求」的开关。删掉之后 OpenClaw 会按它自己的默认写法发，请求形态就和 K3 的预期对不上了——具体会报什么错，官方文档里没有给出对应说明，所以别删就是了。同一个 compat 块里还有 supportsReasoningEffort 和 supportedReasoningEfforts 两项，后者列出了这条条目声明支持的推理强度档位取值，跟上面 thinkingLevelMap 的键是对应的。
想让图片和视频也走 K3，得再加一段
上面那段配置只解决了聊天主模型。文档另外给了一段：如果需要让图片和视频输入也走 K3，请在同一个配置中加入 agents.defaults.imageModel 设为 moonshot/kimi-k3，同时在 tools.media.image 和 tools.media.video 各挂一条 type: "provider"、provider: "moonshot"、model: "kimi-k3" 的条目，capabilities 分别写 ["image"] 和 ["video"]。
这套结构透露的信息是：OpenClaw 里的「默认对话模型」和「媒体工具用哪个模型」是分开配置的两处，改了前者不会自动带上后者。所以如果你配完之后发现文字对话已经走 K3、丢图片进去却不是预期行为，先去看这一段有没有加。
三个官方列出的常见问题
401 / Invalid Authentication。 官方给了三条排查方向：确认使用的是 Kimi 开放平台 API Key，而不是 Kimi Code Key；中国区使用 moonshot-api-key-cn，国际站使用国际版认证选项；如果环境变量中已有旧的 Key，重新运行向导并重新输入中国区 Key。第一条是最阴的——两种 Key 长得都像 Key，拿错了报的却是认证失败，很容易往网络问题上想。第三条则说明环境变量里的残留 Key 会参与进来，换 Key 时别只改配置文件。这类鉴权失败的通用排查思路可以对照API 401 与 403 怎么排查。
找不到 Moonshot 认证选项。 官方答复就是确认官方插件已安装并重启 Gateway，也就是前面那两条 plugins install 加 gateway restart，官方对这个问题给出的答复里没有第三种处置。换句话说，向导里没有 Moonshot 这个选项，官方要你查的方向就是插件装没装上、Gateway 重启没重启，而不是去怀疑 API Key 或者网络。
K3 不在模型列表。 官方处置是升级 OpenClaw 和 Moonshot Provider；仍缺失时补充手写的 K3 条目，然后重新执行 openclaw models set moonshot/kimi-k3。注意最后这次 models set 不能省——补了条目不等于默认模型就切过去了。
配完之后先确认一件事
安装完成后，打开安装向导或 Gateway 输出的 Control UI 地址进入聊天界面，底部模型应显示 kimi-k3 · moonshot。这个显示串是最省事的自检点：Provider 和模型 ID 都在里面，看到它就说明 Provider 挂上了、默认模型也切对了；看到的还是别的，回去补 openclaw models set moonshot/kimi-k3。
最后重复一遍这篇文档里最容易栽的坑：旧版向导截图中的 Moonshot AI (Kimi K2.5) 和 moonshot/kimi-k2.5 是历史预设，官方明确说不再使用，请以文字步骤为准，不要保留旧的默认模型。如果你是照着网上老教程配的，很可能默认模型还停在 k2.5 上，而 kimi-k2.5 已停止向新注册用户开放。Kimi 官方文档的「生态集成」下面还并列着 Claude Code 那一篇，在 Claude Code 里配 Kimi 走的是环境变量方式，跟本文这套「插件 + onboard 向导」的入口完全不同，两边的命令别混着用。更多 Kimi API 问题排查方法，官方指向的是问题排查页面。