Codex Kimi 配置教程

这一篇带你把 Codex 连接到 Kimi API。

Kimi 的配置路径比阿里云百炼简单一些：官方文档明确提供了 OpenAI 兼容接口，base_url 是固定的 https://api.moonshot.cn/v1。但 Kimi 的模型更新比较快，所以本篇重点会放在 确认当前模型名 和 不要使用已下线旧模型。

前置教程：Codex + 通义千问/Qwen 配置
如果你还没有理解“服务商文档参数、环境变量、配置草稿、只读验收”这条流程，建议先完成前置教程，再回到本篇。

依据来源：OpenAI Codex 官方手册中的 Custom model providers、config.toml、环境变量认证说明；Kimi API 官方文档中的 OpenAI 兼容说明、开始使用 Kimi API、模型列表。

本篇目标

跟着本篇做完后，你应该能做到：

从 Kimi 官方文档确认 OpenAI 兼容 Base URL。
从 Kimi 模型列表确认当前适合编程任务的模型名。
创建或准备 Kimi API Key。
把 API Key 放到 Windows 环境变量 MOONSHOT_API_KEY。
让 Codex 生成 Kimi 配置草稿。
确认后让 Codex 写入配置。
用最小对话和只读项目分析验收。
遇到模型下线、Key 无效、参数不兼容时知道怎么排查。

本篇不做什么

本篇不做这些事：

不把真实 API Key 写进教程。
不让你把真实 API Key 发给 Codex。
不讲 Kimi API 全部参数。
不测试 Kimi 的联网搜索、文件问答、Batch API 等高级能力。
不在模型配置未验收前让 Codex 修改业务代码。

本篇只解决一个目标：

让 Codex 可以通过 Kimi API 正常响应，并完成一次只读项目分析。

第 1 步：打开 Kimi API 官方文档

先打开 Kimi API 文档：

https://platform.kimi.com/docs/guide/start-using-kimi-api

再打开 OpenAI 迁移文档：

https://platform.kimi.com/docs/guide/migrating-from-openai-to-kimi

你要确认 4 件事：

要确认的信息	官方文档示例	你要记下什么
是否兼容 OpenAI API	Kimi API 兼容 OpenAI 接口规范	可以走 OpenAI 兼容方式
Base URL	`https://api.moonshot.cn/v1`	复制这个地址
API Key 示例	`MOONSHOT_API_KEY`	本篇使用这个环境变量名
示例模型	`kimi-k2.6`	还要去模型列表确认最新模型

第 2 步：确认当前模型名

打开 Kimi 模型列表：

https://platform.kimi.com/docs/models

本篇写作时，Kimi 官方模型列表里可以看到：

模型名	说明
`kimi-k2.7-code`	Kimi 当前更偏编程任务的模型，上下文 256k
`kimi-k2.7-code-highspeed`	Kimi K2.7 Code 高速版
`kimi-k2.6`	Kimi 智能模型，支持长上下文和 Agent 编程等场景
`kimi-k2.5`	较早的 K2.5 模型
`moonshot-v1-8k` / `32k` / `128k`	Moonshot V1 生成模型

本篇默认使用：

kimi-k2.7-code

原因：它在当前官方页面里被描述为 Kimi 更适合 Coding 的模型。

但你要记住：Kimi 模型更新快，配置前必须打开模型列表确认一次。

第 3 步：避开已下线模型

Kimi 官方模型列表里明确列出了已下线模型。

你可能在旧文章里看到：

kimi-latest
kimi-thinking-preview
kimi-k2-0905-preview
kimi-k2-turbo-preview

不要直接复制旧文章。

如果 Codex 配置里写了已下线模型，常见结果是：

模型不存在。
无权限。
请求失败。
某些参数报错。

你要养成习惯：

写入配置前，先看 Kimi 官方模型列表。

第 4 步：准备 Kimi API Key

进入 Kimi API 开放平台：

https://platform.kimi.com/

你要做：

登录账号。
进入用户中心或开发工作台。
找到 API Key 管理入口。
创建一个新的 API Key。
复制 API Key。
保存到安全位置。

不要把 API Key 放到这些地方：

不要发给 Codex。
不要写进 Markdown。
不要发到微信。
不要截图露出完整 Key。
不要提交到 Git。

第 5 步：设置 Windows 环境变量

本篇使用 Kimi 官方文档里的环境变量名：

MOONSHOT_API_KEY

方法 A：用 Windows 图形界面设置

适合新手。

操作步骤：

按 Win 键。
搜索 环境变量。
打开“编辑系统环境变量”。
点击“环境变量”。
在“用户变量”区域点击“新建”。
变量名填写：

MOONSHOT_API_KEY

变量值填写你的真实 Kimi API Key。
点击确定。
关闭所有设置窗口。
关闭当前 PowerShell。
重新打开一个新的 PowerShell。

方法 B：用 PowerShell 设置

适合熟悉 PowerShell 的用户。

打开 PowerShell，运行：

setx MOONSHOT_API_KEY "你的真实 Kimi API Key"

注意：

引号里替换成你的真实 Key。
执行后关闭当前 PowerShell。
重新打开 PowerShell 才能读到新变量。

第 6 步：验证环境变量能读取

重新打开 PowerShell 后运行：

$env:MOONSHOT_API_KEY

如果能看到一串 Key，说明环境变量能读到。

截图时一定要遮住输出。

如果没有输出，先不要继续配置 Codex。

按顺序检查：

变量名是不是 MOONSHOT_API_KEY。
设置后有没有重开 PowerShell。
API Key 有没有复制完整。
你是不是在另一个 Windows 用户里启动了 Codex。

第 7 步：让 Codex 生成配置草稿

打开 Codex。

先不要让它直接写文件。

把下面这段复制给 Codex：

我准备把 Codex 连接到 Kimi API 的 OpenAI 兼容接口。

我已经从 Kimi 官方文档确认：
- base_url：https://api.moonshot.cn/v1
- model：kimi-k2.7-code
- API Key 环境变量名：MOONSHOT_API_KEY

要求：
1. 先不要修改任何文件。
2. 不要让我把真实 API Key 发给你。
3. 请根据当前 Codex 官方配置方式，给出 config.toml 配置草稿。
4. provider_id 使用 moonshot。
5. 配置里只能写环境变量名，不能写真实 API Key。
6. 请解释每一行配置是什么意思。
7. 请特别说明是否需要 wire_api 字段；如果你不确定，请写“不确定”，不要编。
8. 请提醒我模型名必须以 Kimi 官方模型列表为准。

你希望 Codex 给出的草稿大概像这样：

model = "kimi-k2.7-code"
model_provider = "moonshot"

[model_providers.moonshot]
name = "Kimi / Moonshot"
base_url = "https://api.moonshot.cn/v1"
env_key = "MOONSHOT_API_KEY"

重点检查：

model 是你从官方模型列表确认的模型名。
model_provider 是 moonshot。
[model_providers.moonshot] 和 model_provider 对得上。
base_url 是 https://api.moonshot.cn/v1。
env_key 是 MOONSHOT_API_KEY，不是你的真实 Key。
没有乱加你看不懂的字段。

关于 wire_api 的说明

Kimi 官方文档说明它兼容 OpenAI 接口规范，并列出了 /v1/chat/completions 等兼容接口。

OpenAI Codex 官方手册说明自定义 provider 涉及 Base URL、wire API、认证和可选请求头；当前手册示例里的 wire_api 注释为 responses，并标注这是支持值。

所以本篇继续采用保守做法：

不要自己随便加 wire_api。
先让 Codex 根据当前版本解释是否需要。
最终用只读任务验收能不能跑通。

如果 Codex 要加 wire_api = "chat"，你要追问：

请说明你添加 wire_api = "chat" 的依据来自哪里。当前 Codex 官方手册是否支持这个值？如果没有明确依据，请不要添加。

第 8 步：让 Codex 写入配置

确认配置草稿没问题后，再发：

我确认 Kimi 配置草稿可以继续。

请把 moonshot provider 写入 Codex 用户级配置文件。

要求：
1. 修改前先告诉我目标配置文件路径。
2. 只修改 Codex 配置文件。
3. 不要写入真实 API Key。
4. 只写入 env_key = "MOONSHOT_API_KEY"。
5. 如果配置文件不存在，请先说明将创建哪个文件。
6. 修改后展示 diff。
7. 用中文解释每一处变化。
8. 不要修改业务项目文件。

Windows 上 Codex 用户级配置一般位于：

C:\Users\你的用户名\.codex\config.toml

也可以理解成：

~\.codex\config.toml

如果你设置过 CODEX_HOME，让 Codex 先解释实际路径。

第 9 步：重启 Codex

配置文件和环境变量改完后，建议重新启动。

操作顺序：

退出当前 Codex。
关闭当前 PowerShell。
重新打开 PowerShell。
进入练习项目目录。
重新启动 Codex。

这样可以确保新环境变量和新配置都被读取。

第 10 步：做最小对话验证

进入 Codex 后，先发：

请只用一句中文回复：Kimi 配置验证开始。

如果能正常回复，说明模型调用链路有机会是通的。

如果这里失败，不要继续项目操作，先看错误信息。

第 11 步：做只读项目验证

最小对话能回复后，再做项目只读验证。

复制这段给 Codex：

请只读分析当前项目，不要修改任何文件，不要创建文件，不要删除文件。

请按下面格式输出：

## 1. 响应状态
- 你是否能正常响应：
- 如果你能判断，本次使用的模型/provider 是什么：
- 如果不能判断，请写“不能判断”：

## 2. 当前项目
- 当前目录：
- 是否像项目根目录：
- 判断依据：

## 3. 只读检查
- 你查看了哪些文件或目录：
- 有没有运行只读命令：
- 有没有修改文件：

## 4. Kimi 配置提醒
- 当前模型名是否可能来自 Kimi 模型列表：
- 如果模型不存在，应该先查哪里：
- 如果参数不兼容，应该先查哪里：

## 5. 下一步建议
- 如果配置正常，下一篇应该做什么：
- 如果配置异常，先查哪 3 件事：

你希望看到：

Codex 能正常输出。
它能读到当前项目路径。
它没有修改文件。
它能提醒模型名和官方模型列表关系。
它能说明不确定的地方。

第 12 步：确认没有改业务文件

继续让 Codex 检查：

请检查当前 Git 状态，确认这次 Kimi 配置验证有没有修改业务项目文件。

要求：
1. 只运行只读检查。
2. 不要修改任何文件。
3. 如果工作区噪音较多，请列出变化文件，并说明这些变化是否和本次配置有关。

如果工作区干净，本篇验收更稳。

如果有变化，先截图，再让 Codex 解释 diff，先不要提交。

常见问题

问题 1：API Key 无效或 401

优先检查：

MOONSHOT_API_KEY 是否存在。
Key 是否复制完整。
Key 是否属于当前 Kimi API 开放平台账号。
账号是否有额度或调用权限。
是否设置后没有重开 PowerShell。

可以问 Codex：

Codex 提示 MOONSHOT_API_KEY 相关错误。
请只读检查当前环境是否能读取这个环境变量。
不要显示完整 Key，只告诉我是否存在，以及长度是否大于 0。

问题 2：模型不存在

优先检查：

kimi-k2.7-code 当前是否在 Kimi 模型列表里。
你的账号是否能调用这个模型。
是否复制了旧教程里的已下线模型名。
是否使用了 kimi-latest 这类已下线别名。

可以问 Codex：

Kimi 返回模型不存在或无权限。
请不要修改配置，先列出我应该去 Kimi 官方模型列表和控制台确认的 5 个位置。

问题 3：参数不兼容

Kimi 官方迁移文档说明，它尽力兼容 OpenAI API，但某些参数仍有差异。

常见差异包括：

temperature 取值范围不同。
某些模型对 temperature 有固定要求。
functions 已废弃，应使用 tools。
tool_choice=required 暂不支持。

如果 Codex 报参数错误，不要先改 Key。

先问：

Kimi 返回参数不兼容错误。
请根据错误信息判断是模型名问题、鉴权问题、Base URL 问题，还是请求参数问题。先解释，不要修改文件。

问题 4：能聊天，但代码任务效果不稳定

这不一定是配置错误。

可能原因：

当前模型不适合这个项目复杂度。
项目上下文太长。
提示词太模糊。
任务范围太大。
Codex 权限范围不够。

先用只读项目分析和单文件小改动验证，不要一上来重构。

本篇验收结果

做到这里，如果满足下面 8 条，就说明 Kimi 配置教程完成：

你从 Kimi 官方文档确认了 OpenAI 兼容接口。
你确认了 Base URL 是 https://api.moonshot.cn/v1。
你从 Kimi 模型列表确认了当前可用模型名。
你把 API Key 放进了 MOONSHOT_API_KEY 环境变量。
Codex 配置文件没有出现真实 API Key。
Codex 能正常回复一句中文验证消息。
Codex 能完成一次只读项目分析。
Git 状态确认没有意外业务文件变化。

下一篇学什么

下一篇看：第一次让 Codex 阅读项目。

如果你想继续补齐国内模型系列，下一篇服务商教程可以写：Codex + 硅基流动配置。

参考资料

OpenAI Codex 官方手册：https://developers.openai.com/codex/codex-manual.md
Kimi 开始使用 API：https://platform.kimi.com/docs/guide/start-using-kimi-api
Kimi 从 OpenAI 迁移到 Kimi API：https://platform.kimi.com/docs/guide/migrating-from-openai-to-kimi
Kimi 模型列表：https://platform.kimi.com/docs/models