Claude Code 接 Kimi 完整教程
用 Magpie 让 Claude Code 跑在 Kimi K3 上只要两条命令:先把 Kimi 的 key 交给 Magpie,再把 Claude Code 指向 moonshot/kimi-k3。这篇把每一步会改哪个文件、怎么确认生效、怎么退回原样都写清楚了。
命令取自 Magpie 官网的命令行示例;模型名等信息核对于 2026-10-27。
两条命令,加一条确认
magpie provider add moonshot 你的key # 添加 Kimi 供应商(id 是 moonshot)
magpie claude moonshot/kimi-k3 # 把 Claude Code 指向 Kimi K3
magpie ls # 确认 Claude Code 当前用的模型
切换后,下一个 Claude Code 会话开始使用 Kimi。
开始之前
- Magpie 已安装。终端里运行
magpie ls,能列出本机的 Agent 就说明装好了。还没装?先看安装教程(英文)。 - Claude Code 已安装。如果
magpie ls的列表里没有它,先启动一次 Claude Code,让它写出自己的配置文件,再重新运行magpie ls——Magpie 只显示已安装或已配置的 Agent。 - 一个 Kimi(Moonshot)API key。在月之暗面的开放平台创建,账户里要有可用额度。
四步操作
-
添加 Kimi 供应商
magpie provider add moonshot 你的keyKimi 在 Magpie 里是内置预设,供应商 id 叫
moonshot,只需要提供 key;接口地址和支持的协议,预设里已经记好。添加之后验证一下:magpie providers # 已添加的供应商、key、可用模型、谁在用 magpie provider test moonshot # 每种 API 各发一次小请求,并报告延迟key 必须在 Magpie 里添加。Magpie 不会读取 shell 里 export 的ANTHROPIC_API_KEY、OPENAI_API_KEY等环境变量——这是刻意的设计。 -
确认有哪些 Kimi 模型
magpie provider models moonshot # 重新向厂商拉取模型列表 magpie models # 所有 Agent 能选到的模型目录Magpie 没有把模型列表写死:有了 key 之后它会问厂商现在提供哪些模型,新模型发布后刷新一下就能选。下面用官网示例里的
kimi-k3,实际以你这里列出的名字为准。 -
把 Claude Code 指向 Kimi
magpie claude moonshot/kimi-k3模型统一写成
供应商/模型。Magpie 只改写 Claude Code 配置里需要改的那几个字段,其余内容原样保留,详见下面的「它到底改了什么」。 -
确认并开始用
magpie ls # 每个 Agent 以及它当前用的模型看到 Claude Code 用的是 Kimi K3 之后,新开一个 Claude Code 会话,它就跑在 Kimi 上了——官方的说法是「下一个会话使用它」。
它到底改了什么
这几步涉及的文件主要是两个:
| 文件 | 内容 |
|---|---|
~/.config/magpie/providers.json | Magpie 自己的状态:你添加的供应商、key、每个供应商暴露哪些模型。第 1 步写入这里。 |
~/.claude/settings.json | Claude Code 的配置。第 3 步只改 Magpie 文档列出的字段:provider、model,以及 opus / sonnet / haiku / fable 这几个模型别名。注释、键顺序和缩进原样保留,写入是原子操作。 |
Windows 上 Claude Code 的配置在用户目录下的 .claude\settings.json。
Claude Code 的配置里不会出现 Kimi 的 key,也不会出现 Kimi 的接口地址:它只保存要用的模型和本机网关地址 http://127.0.0.1:3425/v1,真正的 key 在 Magpie 手里,请求由网关转发。
关于「模型别名」
Claude Code 用 opus、sonnet、haiku 这几个别名来选不同档位的模型。Magpie 官网的说法是:Kimi、GLM 或 GPT 可以放在这三个别名后面。具体每个别名被写成了什么,以你机器上的文件为准——切换前后各对比一次最直观:
macOS / Linux
cp ~/.claude/settings.json ~/claude-settings.before.json # 切换前先备份
magpie claude moonshot/kimi-k3
diff ~/claude-settings.before.json ~/.claude/settings.json # 看 Magpie 实际改了哪几行
Windows(命令提示符)
copy %USERPROFILE%\.claude\settings.json %USERPROFILE%\claude-settings.before.json
magpie claude moonshot/kimi-k3
fc %USERPROFILE%\claude-settings.before.json %USERPROFILE%\.claude\settings.json
对比输出里如果出现 token 或 key,贴到论坛或群里之前先打码。
回滚:怎么退回原来的模型
切换只是改配置,随时能退回。三种办法,从省事到保险:
办法一:在应用里选回原生模型
在 Magpie 的菜单栏应用里,点 Claude Code 当前显示的模型,选回它原生的模型。官网的说法是:选回原生模型,Magpie 会把文件恢复成切换之前的样子。
办法二:先存一个 Profile,用命令一次性恢复
magpie save before-kimi # 切换之前执行:把所有 Agent 当前的设置存成一个方案
# …… 用了一阵之后想退回:
magpie use before-kimi # 一次性把所有 Agent 恢复成当时的样子
Profile 保存的是执行 save 那一刻所有 Agent 的设置,所以一定要在切换之前存;每次实验换一个名字,别把最初的快照覆盖掉。
办法三:手动恢复备份
按上一节的方法,切换前把 settings.json 备份一份;要退回时把备份拷回原位就行。
想彻底删掉 Kimi 这个供应商:先用上面任一办法退回,再执行 magpie provider rm moonshot。
常见问题
为什么命令里是 moonshot,而不是 kimi?
Kimi 由月之暗面(Moonshot)提供,Magpie 里这家供应商的 id 是 moonshot:添加 key 用 magpie provider add moonshot 你的key,模型写成 moonshot/kimi-k3。不确定某家供应商的 id 时,运行 magpie presets 查看所有预设。
切换之后 Claude Code 还是原来的模型怎么办?
先确认 magpie ls 里 Claude Code 对应的已经是 Kimi。官方说明切换后由「下一个会话」使用新配置,所以退出当前会话、新开一个再试。如果 magpie ls 里根本没有 Claude Code,说明 Magpie 还没发现它:先启动一次 Claude Code 让它写出配置文件,再重新打开 Magpie。
怎么判断是 key 有问题,还是接口有问题?
运行 magpie provider test moonshot。它对这家供应商支持的每种 API 各发一次小请求并报告延迟,能区分「key 不对」和「这家厂商没有你的 Agent 所说协议的接口」;后一种情况由 Magpie 的网关负责协议转换。
我已经在用 Claude 订阅,换成 Kimi 会影响订阅吗?
不会。Magpie 只改 Claude Code 配置里的模型相关字段,你的 Claude 登录不受影响;想用回原来的模型,按上文的办法选回原生模型即可。
会不会把我的 settings.json 改乱?
不会。Magpie 只改你切换的那个字段,注释、键顺序和缩进都原样保留,写入是原子操作,写到一半崩溃也不会留下半截文件。心里没底的话,切换前备份一份,命令见上文「它到底改了什么」。
下一步
magpie provider models 的输出和各厂商官网为准。