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。

本页目录
  1. 开始之前
  2. 四步操作
  3. 它到底改了什么
  4. 回滚:怎么退回原来的模型
  5. 常见问题

开始之前

四步操作

  1. 添加 Kimi 供应商

    magpie provider add moonshot 你的key

    Kimi 在 Magpie 里是内置预设,供应商 id 叫 moonshot,只需要提供 key;接口地址和支持的协议,预设里已经记好。添加之后验证一下:

    magpie providers               # 已添加的供应商、key、可用模型、谁在用
    magpie provider test moonshot  # 每种 API 各发一次小请求,并报告延迟
    key 必须在 Magpie 里添加。Magpie 不会读取 shell 里 export 的 ANTHROPIC_API_KEY、OPENAI_API_KEY 等环境变量——这是刻意的设计。
  2. 确认有哪些 Kimi 模型

    magpie provider models moonshot   # 重新向厂商拉取模型列表
    magpie models                     # 所有 Agent 能选到的模型目录

    Magpie 没有把模型列表写死:有了 key 之后它会问厂商现在提供哪些模型,新模型发布后刷新一下就能选。下面用官网示例里的 kimi-k3,实际以你这里列出的名字为准。

  3. 把 Claude Code 指向 Kimi

    magpie claude moonshot/kimi-k3

    模型统一写成 供应商/模型。Magpie 只改写 Claude Code 配置里需要改的那几个字段,其余内容原样保留,详见下面的「它到底改了什么」。

  4. 确认并开始用

    magpie ls   # 每个 Agent 以及它当前用的模型

    看到 Claude Code 用的是 Kimi K3 之后,新开一个 Claude Code 会话,它就跑在 Kimi 上了——官方的说法是「下一个会话使用它」。

它到底改了什么

这几步涉及的文件主要是两个:

文件内容
~/.config/magpie/providers.jsonMagpie 自己的状态:你添加的供应商、key、每个供应商暴露哪些模型。第 1 步写入这里。
~/.claude/settings.jsonClaude 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 只改你切换的那个字段,注释、键顺序和缩进都原样保留,写入是原子操作,写到一半崩溃也不会留下半截文件。心里没底的话,切换前备份一份,命令见上文「它到底改了什么」。

下一步

查看全部中文教程 →

usemagpie.co 是 Magpie 的非官方第三方中文指南,与项目作者 yetone 没有隶属关系。Magpie 是 MIT 协议的开源项目,官网是 usemagpie.ai,官方安装包发布在 GitHub Releases。本文的命令取自官网的命令行示例和本站的配置指南,模型名与价格类信息核对于 2026-10-27,之后版本可能变化——请以 magpie provider models 的输出和各厂商官网为准。