在 Claude Code 里配置 Kimi：环境变量、模型档位与排错
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
把 Claude Code 接到 Kimi 上，本质就是一件事：用环境变量把它的模型请求转发到 Kimi 的 Anthropic 兼容端点。难点不在这一步，而在三个容易踩空的地方——第一，~/.claude/settings.json 里 env 字段的旧配置会覆盖你在终端 export 的同名变量，不先清理就会出现「明明改了却不生效」；第二，Claude Code 内部会按任务档位选不同模型（主对话、后台摘要、子 Agent 各走各的变量），只配 ANTHROPIC_MODEL 一个会让其余场景静默失败；第三，验证配置有没有生效要看 /status，不能看 /model 菜单——那是内置的固定别名列表，压根不会显示 Kimi 模型。本文按 Kimi 官方文档《在 Claude Code 中使用 Kimi》的原文顺序，把安装、清理、配置、验证、排错串成一条能照着做的路径。
先别急着配，先把旧配置清干净
这一步官方文档放在安装小节的收起区块里，很多人直接跳过，然后卡在「改了没反应」上一两个小时。
官方的原话是：如果你之前通过第三方工具或手动改过 ~/.claude/settings.json，其 env 字段中残留的旧配置会覆盖终端里 export 的同名环境变量，导致新配置不生效，或者模型请求被静默改写。注意「静默」两个字——它不报错，只是悄悄把你的请求发到别的地方去。
官方给了一段 Node 脚本来清理，脚本只删 env 里这几类键，不动 settings.json 中权限、主题等其他配置：ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL、ANTHROPIC_SMALL_FAST_MODEL、CLAUDE_CODE_SUBAGENT_MODEL，以及 opus / sonnet / haiku / fable 四档的 ANTHROPIC_DEFAULT_*_MODEL 与对应的 *_MODEL_NAME，还有 ENABLE_TOOL_SEARCH、CLAUDE_CODE_AUTO_COMPACT_WINDOW、CLAUDE_CODE_EFFORT_LEVEL。这份键名清单本身就很有信息量：它等于告诉你，Claude Code 会读取的与端点、密钥、模型有关的变量一共就这些，排查时挨个看一遍不会漏。
除了 settings.json，还有一处更隐蔽：官方提醒要检查 ~/.zshrc、~/.bashrc 这类 shell 配置文件里有没有残留的 ANTHROPIC_* export，Windows 用户则要去看用户环境变量。这些地方留了旧值，同样会干扰新配置。
安装与拿 Key
已经装过 Claude Code 的可以跳过。官方给的安装命令是用 npm 全局安装 @anthropic-ai/claude-code，并且在命令里带上了国内 npm 镜像的 registry 参数，这一点对国内网络环境挺实在。
没有 Node.js 的话，官方在收起区块里也给了路径：macOS 和 Linux 用 fnm 装并设为默认版本，Windows 用 winget 安装 OpenJS.NodeJS，然后把 PowerShell 的执行策略设成当前用户范围的 RemoteSigned，关掉终端重开。装完 Node 之后官方还要求执行一次初始化：跑一小段 Node 脚本，往用户目录下的 .claude.json 里写入 hasCompletedOnboarding: true（文件已存在就合并进去）。这一步的作用是跳过首次启动的引导流程，省得引导过程和你的自定义端点打架。
API Key 在 Kimi 开放平台创建，官方特别注明选 default 默认项目，然后用它替换文档里的 YOUR_MOONSHOT_API_KEY 占位符。密钥怎么存、怎么轮换，可以顺带看看API Key 的安全管理做法，尤其是下面方式二会把明文密钥写进文件的场景。
两种配置方式，任选其一，不要混用
官方把话说得很死：两种方式任选其一，不要混用。
方式一是终端环境变量，立即生效，但只对当前终端会话有效，重开终端就没了。macOS 和 Linux 下用 export 依次设置，最后直接敲 claude 启动：
export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
export ANTHROPIC_AUTH_TOKEN="你的 Kimi API Key"
export ANTHROPIC_MODEL="kimi-k3[1m]"
# 还有几个档位变量与两个 CLAUDE_CODE_* 变量，见下一节
claude
Windows 用户在 PowerShell 里用 env: 作用域设置同名变量即可，官方文档给了完整写法；如果嫌每次重开终端都要重设麻烦，直接走方式二更省心。
方式二是写进 ~/.claude/settings.json 的 env 字段，长期生效。官方在这一节又强调了一遍三件事：settings.json 的 env 会覆盖终端里 export 的同名变量（所以才不许混用）；该文件包含明文 API Key，请勿提交到 git 仓库；保存后需要重启 Claude Code 才生效。
第三条最容易被忽略。改完 JSON 不重启，看到的还是旧进程里的旧值，然后就开始怀疑人生。
为什么要配一整排模型变量
只配 ANTHROPIC_MODEL 是新手最典型的做法，也是最典型的坑。官方文档的解释是：Claude Code 内部会按场景使用不同档位的模型（主对话、后台摘要、子 Agent 等），只配置部分变量会让对应场景静默失败。
官方那张「配置项说明」表把每个变量不配或配错的后果写得很直白，值得逐条记住：
ANTHROPIC_BASE_URL：把模型请求转发到 Kimi 的 Anthropic 兼容端点。不配，请求会发往 Anthropic 官方端点，鉴权失败。ANTHROPIC_AUTH_TOKEN：用 Kimi API Key 鉴权。不配，返回 401。ANTHROPIC_MODEL：主对话使用的模型。不配，会用 Claude 的默认模型名，Kimi 端点识别不了，报模型不存在。ANTHROPIC_DEFAULT_OPUS_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL/ANTHROPIC_DEFAULT_HAIKU_MODEL/ANTHROPIC_DEFAULT_FABLE_MODEL：Claude Code 按任务档位挑模型时用的名字。不配，对应档位的任务会失败——官方举的例子是 haiku 档的后台标题生成和摘要。CLAUDE_CODE_SUBAGENT_MODEL：子 Agent 使用的模型。不配，子任务请求失败或者效果明显变差。
看懂这张表你就明白，为什么有人配完之后主对话好好的，一开子 Agent 或者一让它生成会话标题就报错——不是端点的问题，是那几个档位变量没跟上。切换模型的时候，官方也提醒要把配置里所有模型变量的值一并换成新模型名，漏一个就留一个雷。
两个最容易漏配的 CLAUDE_CODE 变量
除了模型名，官方还要求配两个变量，它们不属于「转发」范畴，但直接影响体验。
CLAUDE_CODE_AUTO_COMPACT_WINDOW 控制触发自动压缩上下文的窗口大小。官方的要求是：这个值需要与所选模型的上下文窗口保持一致。设置过小会过早压缩、白白丢掉上下文；设置过大则会直接报上下文超限错误。文档为每个可选模型都给出了对应取值——比如默认推荐的 kimi-k3 对应 1M 上下文，配置里写的就是这个 token 数（具体数值以官方文档当前版本为准）。换模型的时候这个值也要跟着换，它和模型名是绑定的一对。
CLAUDE_CODE_EFFORT_LEVEL 控制 Claude Code 的推理强度。官方推荐设为 max 以获得最充分的推理，并说明较低的值可能在复杂任务上降低质量。这个变量属于「配了也看不出立刻变化，但复杂任务上会体现出来」的类型，别因为看不出效果就删掉。
验证：只认 /status，别看 /model
这一节的信息量很高，而且反直觉。
官方的验证方法是在 Claude Code 里输入 /status，确认两件事：Base URL 显示为 Kimi 的 Anthropic 兼容端点地址，Model 显示为你配置的 Kimi 模型名。然后随便发一条消息（官方举例就是发个 hi），能正常收到回复，就说明端到端跑通了。
反直觉的地方在这里：官方明确写了，Claude Code 的 /model 菜单是内置的固定别名列表，不会显示 Kimi 模型，也无需在其中切换。也就是说，你打开 /model 看到的还是那几个熟悉的名字，这完全正常，不代表配置失败。配置是否生效，以 /status 显示为准。
我见过不少人卡在这一步：/status 明明是对的，却因为 /model 里没看到 Kimi 而反复重配，越配越乱。记住判据只有一个就行了。
思考开关：不同模型的行为不一样
官方给了三个模型在 Claude Code 中的思考行为差异，这直接决定你要不要动 Thinking 开关：
kimi-k3（文档默认推荐）：默认开启思考，开箱即用，无需额外配置。kimi-k2.7-code：始终开启思考，请求必须显式开启思考。官方要求在 Claude Code 里按Tab保持 Thinking on 再使用，未开启时请求会被拒绝，报错原文是invalid thinking: only type=enabled is allowed for this model。kimi-k2.6：思考可选，可以关掉思考使用，官方说它适合对延迟敏感的简单任务。
官方还提到 K2.7 Code 有一个高速版模型 kimi-k2.7-code-highspeed，同样要求显式开启思考，速度差异与价格都在官方的 K2.7 Code 模型价格页上，这里不复述。
这个差异会以一种意想不到的方式咬人：官方在常见问题里说，用 kimi-k2.7-code 时 WebSearch 会报 400 invalid thinking: only type=enabled is allowed for this model，原因就是该模型强制思考开启而 WebSearch 请求没有显式开。解法是先按 Tab 开 Thinking on；仍然不行就切到 kimi-k2.6（思考可选，不受该限制）；kimi-k3 没有这个限制。官方特意补了一句：此问题与本地配置和 cc-switch 无关——省得你去错误的方向查。
报错对照表
把官方常见问题小节整理成一张排查顺序，出问题的时候从上往下走：
返回 401 鉴权错误：先确认 ANTHROPIC_AUTH_TOKEN 是有效的 Kimi API Key；如果你以前配过 ANTHROPIC_API_KEY，官方要求把它删掉——两个变量同时存在会冲突。这条和站内那篇Claude Code 401 鉴权报错可以对照着看，通用侧的排查思路是一致的。
提示模型不存在（model not found）：检查各个模型变量的值有没有拼错，官方提醒注意不要携带多余的空格或引号。模型名里带方括号的写法本身就容易在复制粘贴时出问题。
后台任务或子 Agent 报错：官方判断通常是 ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_FABLE_MODEL 或 CLAUDE_CODE_SUBAGENT_MODEL 没配，对应场景请求了 Kimi 端点识别不了的模型名，对照配置项说明补齐即可。
修改配置后不生效：回到第一节——查 ~/.claude/settings.json 的 env 里有没有残留旧配置（它会覆盖终端环境变量），跑一遍官方的清理脚本；另外记住终端 export 只对当前会话有效，重开终端要重设；写进 ~/.zshrc 或用 settings.json 方式的，确认改完重启过 Claude Code。
API Key 与端点不匹配：官方要求确认 ANTHROPIC_BASE_URL 与你创建 API Key 的平台是同一个，别在 A 平台建 Key 却指向 B 平台的端点。
之前用 /login 登录过 Claude 账号：官方说 ANTHROPIC_AUTH_TOKEN 设置后会优先于已保存的登录态生效，一般不用管；想确认当前生效的凭据来源，还是用 /status；确实要清掉已保存的登录，可以执行 /logout。
WebFetch 报 temporarily unavailable 或抓不到结果：官方说当前端点暂不支持 WebFetch 抓取，与你的配置无关，等平台支持后恢复。临时替代方案官方也给了：把网页内容直接粘贴给模型，或者用 MCP 类的抓取工具替代。这条值得单独记一下，因为它是「配置没错但功能确实不能用」的情况，再怎么改变量也没用。
关于 cc-switch 这类第三方工具
官方对社区工具的态度写得比较克制：cc-switch 等工具可以在多套供应商配置之间切换，但它们并非 Kimi 官方维护，预设配置可能与官方推荐值存在差异。用完之后要对照官方的配置项说明逐一核对各变量取值，并用 /status 确认实际生效的 Base URL 与模型。
翻译成人话：这类工具帮你省了打字，但没帮你省核对。它写进去的那份 settings.json 恰恰就是第一节里说的、会覆盖终端变量的那份文件——它出错的时候，症状和「旧配置残留」一模一样。
最后
真正会让你耗掉一下午的，从来不是那几行 export，而是「配了但不生效」。按官方文档的逻辑，这件事的排查顺序是固定的：先清 settings.json 的 env 和 shell 配置里的历史残留，再选一种方式配齐全部模型档位变量和两个 CLAUDE_CODE_* 变量，最后只用 /status 验证。三步走完还不对，再去看报错对照表。
另外提醒一句成本侧：Claude Code 是个高频调用工具，子 Agent 和后台摘要都在悄悄产生请求，切换供应商之后计费口径也跟着变了。接入完成后建议顺手把用量看板配起来，可以参考API 成本监控的通用做法；如果你是从别家端点切过来的，换厂商迁移清单里那几项对照检查也适用于这次切换。