在 OpenCode 里配 Kimi K3：内置认证、选模型与推理强度
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
OpenCode 接 Kimi 和 Claude Code 那套不一样：它不需要你去改配置文件、也不需要手工填 base_url，Kimi 官方文档给的是「通过内置认证接入」——运行 opencode auth login，在 Provider 列表里直接选 Moonshot AI (China)，粘贴中国区开放平台的 API Key 就完事。真正会卡住人的是这三件事：第一，Kimi K3 需要账户有可用余额，而新用户认证赠送的代金券不能用于 Kimi K3，光有券配完也跑不起来；第二，同一个模型在不同工具里的写法不一样，官方明确说直接调用 API 和在 Codex 中用 kimi-k3、在 Claude Code 中用兼容别名 kimi-k3[1m]，而 OpenCode 走的是弹窗里选，你根本不用手打模型名，反而容易在排查时把这层差异忘掉；第三，配完之后还有一步 /variants，K3 的推理强度默认就是 max，不主动降档就一直按最深的档位跑。下面按官方那篇《在 OpenCode 中使用 Kimi 模型》的顺序走一遍，并把官方问题排查页里跟第三方 Agent 相关的部分接上。
动手之前，先把三个前提确认掉
官方文档在「准备工作」一节列了三件事，安装 OpenCode、创建 API Key、检查账户设置。前两件按各自官方指引做就行，第三件才是真正会让你白折腾半小时的地方。
原文的说法是：确认账户有可用余额，并检查调用限额、项目预算和组织设置。展开成人话是三条独立的闸门。
余额那条最硬。 官方写得很直白：Kimi K3 需要账户有可用余额，新用户认证赠送的代金券不能用于 Kimi K3。也就是说，你注册认证后拿到的那张券，在别的支持它的模型上能花，到了 K3 这里不作数，得实打实充值才解锁。这个设计和很多人的直觉相反——不少人以为「有券就是有余额」，结果在 OpenCode 里选完模型，一发请求就撞上余额相关的报错。
限额那条跟你的账户等级绑定。 官方在充值与限速页里说明，调用限额随用户等级变化，而等级是按账户的累计充值金额调整的；同时还有一句容易被忽略的补充：代金券不计入累计充值总额。所以券既不能开 K3，也不会帮你把速率档位往上抬。具体的档位数值以官方定价与限速页面为准，本文不搬。
组织设置那条只影响一部分人，但影响起来是全量断流。 如果你所在的组织启用了 IP 白名单，得先把当前网络的出口 IPv4 地址加进去。官方对这个功能的定义是组织级安全配置：配置并保存后，仅白名单内的 IP 可以访问当前组织下的 API；白名单为空时不限制来源。要注意的细节有两个——一是它只接受公网 IPv4 地址或规范的 IPv4 CIDR 网段，内网地址、回环地址、链路本地地址、组播与保留地址、以及运营商级 NAT 共享地址都通不过校验，暂不支持 IPv6；二是保存时是整体覆盖原有配置，不是追加，所以每次编辑前得先确认列表里还留着所有仍需要保留的网段。你在自己电脑上跑 OpenCode，填的应该是你实际访问 Kimi API 时用的那个出口公网 IP，而不是 ipconfig 里看到的那个内网地址。
第一步：opencode auth login 选 Moonshot AI (China)
运行 opencode auth login，会出现一个 Add credential 的交互界面，在 Select provider 里搜索并选择 Moonshot AI (China)，然后粘贴中国区 Kimi 开放平台的 API Key，回车确认。官方给的示意里，输入 Moon 就能过滤出候选项，选中之后进入填 Key 的一步，填完显示 Done。
这一步官方文档配了一句加粗提醒，原文是：「不要把 API Key 写入配置文件、截图或 Git 仓库。中国区、国际站使用不同的 API Key，请勿混用。」
后半句值得单独说。Kimi 的问题排查页把区域隔离讲得更清楚：中国站与国际站的账户、余额和 Key 相互隔离，Key 所属区域必须与你调用的端点一致。Provider 列表里那个括号里的 (China) 不是装饰，它决定了 OpenCode 往哪个端点发请求。拿国际站的 Key 配到中国区 Provider 上，或者反过来，症状就是官方排查页里那条「401、404 或 permission denied」。
顺带一提，Kimi 官方也明确说 Kimi API 开放平台、Kimi Code 和 Kimi 会员是相互独立的产品，付费方式、余额权益和 API Key 均不通用；把其他产品的 Key 填到开放平台端点上，同样会出现 401 或 404。所以「我明明是 Kimi 的付费用户」这句话在这里不成立，你得确认手上这把 Key 是从开放平台控制台创建出来的。
第二步：/models 里选 Kimi K3
认证配好后，直接运行 opencode 启动，在输入框里执行 /models 命令，在弹出的 Select model 窗口里搜索并选择 Kimi K3。
这里的关键差异是：OpenCode 走内置认证，模型是从列表里挑的，你不用手写模型名，也不用配 base_url。这和其他几个编程 Agent 的接法都不一样，而这个差异在排查阶段特别容易反噬。官方排查页里专门有一条讲模型名与接入方式要匹配：直接调用 API 和在 Codex 中使用 kimi-k3，在 Claude Code 中使用兼容别名 kimi-k3[1m]，并要求以对应接入教程为准。换句话说，你在别的工具里记下的那个模型写法，不能直接套到这里来对照；反过来，你在 OpenCode 里看到的显示名，也不等于 API 层的模型 ID。想对比其他工具的接法，可以看在 Claude Code 里配置 Kimi和在 OpenClaw 里用 Kimi 模型。
模型选择这一步还有个前置判断可以做：官方排查页提到，用同一个 Key 调用 GET /v1/models，确认目标模型是否在返回列表里。如果 OpenCode 的 Select model 弹窗里干脆搜不到 Kimi K3，用这条去验一下，就能把「工具没同步」和「账户没权限」两种可能分开。
至于上下文，官方在 OpenCode 那篇里的表述是使用具备 1M token 上下文的 kimi-k3 模型；账户与付费页里也写明 K3 的计费不按上下文长度分段，所有用量均按量付费，输入区分缓存命中与未命中、与输出分别计费。具体单价以官方定价页为准，这里只说结构：长上下文不会把你推到一个更贵的价格档去，但它会实打实地把每次请求的输入 token 数顶上去。
第三步：/variants 调推理强度
在输入框执行 /variants 命令，在 Select variant 弹窗里选 max。官方这句写得很值得注意：kimi-k3 的推理强度默认 max，也支持切换至 low / high。
对应到 API 层，这个档位就是请求顶层的 reasoning_effort 字段。官方在推理强度文档里给的说明是：Kimi K3 始终进行推理，该字段为 string 类型、非必填，支持 "low" / "high" / "max" 三档，默认 "max"。排查页里还补了一条很多人会问的：K3 的思维链目前关不了，始终开启思考模式；嫌思考过程太长，只能把 reasoning_effort 降到 low。
官方给的取舍原则是：任务越复杂，建议选择越高的档位；简单任务使用较低档位可以降低延迟和 Token 消耗。这句话反过来读就是成本提示——max 是默认值，你什么都不动，就是一直按最深档位在跑。在 OpenCode 这种会自动多轮往返的编程 Agent 里，这个默认值的累积影响比在单次对话里大得多。
另外，如果你之前是从 K2.x 迁过来的，官方明确要求移除 K2.x 的 thinking 配置，改用顶层 reasoning_effort。这条对直连 API 的人更要紧，OpenCode 内置认证的场景下参数由工具组装，但你要是同时维护着自己的脚本，别把两套写法混着放。
三步都做完了，看状态栏对不对
官方给的验收标准很具体：完成后，底部状态栏应依次显示 Kimi K3、Moonshot AI (China) 和 max。
这三格其实正好对应上面三步——模型、Provider、推理强度档位。排查时先看这一行，比翻日志快。 少了哪一格，就回头补哪一步：模型那格空着说明 /models 没选上，Provider 那格不是 (China) 说明认证时选错了区域，档位那格不对说明 /variants 没生效。
官方还提示，文中内容基于 OpenCode 1.18.3 版本，其界面、配置项和支持能力可能随版本变化。所以你看到的界面文案跟这里对不上不必慌，认准「provider 选中国区、模型选 K3、档位按需调」这三件事本身。
配完仍然报错：官方给的拆分法
Kimi 官方排查页里有一条专门讲第三方 Agent 或 IDE 配置后仍报错的，把 OpenCode 和 Claude Code、Codex 并列点了名。它给的思路是先把链路拆成 Kimi API 与第三方工具两层：
用相同的 Key、端点和模型直接调用 Kimi API。直连失败，说明问题在余额、鉴权、模型权限或请求参数这一层，先解决这些；直连成功但 OpenCode 里仍失败，就去看工具自己的日志，重点检查协议转换、流式响应、超时设置和自动重试。官方同时点明，第三方工具不由 Kimi 开放平台维护，直连正常而工具失败时需要同时联系对应工具的支持渠道。
报 401、404 或 permission denied 时，官方给的是一个有顺序的检查表：Key 是否来自你正在调用的产品（开放平台 Key 与 Kimi Code Key 不通用）→ Key 所属区域是否与端点一致 → 账户是否有可用余额、代金券是否支持目标模型 → 用同一个 Key 调 GET /v1/models 看目标模型在不在列表里 → 模型名是否与接入方式匹配 → 清理旧的环境变量、代理和本地路由中的旧配置，确认实际生效的 Key 与端点。最后那条对从别的工具切过来的人尤其重要，机器上残留的旧变量会让你以为在用 A，实际发到了 B。
报 429 则要先看响应里的 error.type，官方分了三种：engine_overloaded_error 是服务节点负载较高，按响应中的 Retry-After 提示等待、降低并发并用指数退避重试，这类由服务端容量导致，充值或提升 Tier 不能直接消除；rate_limit_reached_error 是触发了组织级并发、RPM、TPM 或 TPD 限速，需要降低调用频率或提升用户等级；exceeded_current_quota_error 是余额不足、欠费或代金券失效，先用查询余额接口确认 available_balance 再充值。官方还补了两句实用的：OpenAI SDK 等客户端默认会自动重试，一次操作可能放大为多次请求并占用限速额度；因 429 错误中断的请求不会扣费。通用的 429 处置策略见API 429 通用处理。
成本这一头别撒手
官方在账户与付费页里对编程工具场景有一段单独提醒：用大模型生成代码时，模型的随机性和复杂性可能需要多次尝试，编程工具会自动进行多轮重试和调用，这会导致 token 用量快速增长。给出的做法有两条——在开放平台项目设置里配置项目日消费预算，达到上限后系统会自动拒绝该项目下所有 API 请求（官方注明由于计费延迟，限制生效会有短暂延迟）；以及开启账户余额提醒，余额低于预设值时通过短信通知。组织侧还可以单独给项目配 TPM 限速值，注意项目 TPM 不得超过组织 TPM，设置超过也按组织 TPM 执行。
还有一个反直觉的情况，官方也写了：Agent 没有显示结果，账户却产生了费用。原因是客户端不显示结果不代表 API 请求失败——编程工具等待时间过短、代理断开或本地超时时，客户端可能停止展示，但服务端请求仍可能已完成并产生调用记录。核对顺序是：HTTP 状态码与 request_id → 响应中的 usage 字段 → 客户端是否自动重试、启动子 Agent 或循环调用工具 → 控制台的用量看板与计费明细 → 客户端日志里的超时和连接错误。
好消息是缓存不用你操心。官方明确说 Context Caching 不需要手动配置，Kimi API 会对重复的初始上下文自动尝试缓存，无需手动创建 cache ID、设置 TTL 或添加额外请求参数；保持 system prompt、工具定义和长文档等初始前缀稳定有助于命中，修改前缀内容可能降低命中率。这条对编程 Agent 特别有意义——频繁改动 system prompt 或工具定义，等于在给自己制造缓存未命中。
最容易栽的坑
按发生频率排，我建议这么记：券不能开 K3（得充值）、区域不能混（中国站和国际站的 Key、余额、账户彼此隔离）、默认档位是最深那档（不动 /variants 就一直是 max）、旧配置会阴魂不散（换工具前先清环境变量和本地路由）。
还有一条不算坑但值得提前做：先在开放平台把项目日消费预算设上，再去 OpenCode 里跑第一个任务。编程 Agent 的重试和子调用是自动的，等你发现用量不对再去设，那笔已经花掉了。想把成本盯得更细，可以配合API 成本监控那套做法。