2026年7月，月之暗面推出了Kimi K3，一款拥有1M tokens超长上下文窗口的推理大模型，完全兼容OpenAI API格式，还支持reasoning_effort参数（low/high/max三档，默认max）来控制推理深度。另一边，OpenAI的Codex编程智能体允许通过~/.codex/config.toml接入任意兼容OpenAI API的第三方模型。这意味着，把Kimi K3接入Codex只需要几行配置，完成后CLI终端和macOS桌面应用共享同一份配置，两端都能通过模型选择器切换到Kimi K3。这篇文章从API Key获取到全局配置，再到CLI动态切换（/model命令）和桌面端UI切换，以及Profile隔离多模型方案，完整覆盖两种接入路径，让开发者在5分钟内完成配置并开始使用。

---

为什么把 Kimi K3 接入 Codex？

Codex默认绑定OpenAI的编码模型，但对国内开发者来说，有两个常见痛点：访问延迟和费用。Kimi K3作为完全兼容OpenAI API格式的国产推理模型，天然可以作为Codex的底层模型替换方案。

Kimi K3的几个关键参数值得关注：

• 上下文窗口 1M tokens：远超Codex默认模型，处理大型代码仓库时不易截断
• reasoning_effort 三档可调：低延迟场景用low，深度推理用max，适配不同编码任务
• 国内直接访问：api.moonshot.cn无需额外网络配置
• OpenAI SDK 完全兼容：无需修改任何调用代码，直接替换base_url即可

Codex支持通过model_providers配置块定义自定义API提供方，之后无论是CLI还是桌面端，都会读取同一份配置。

---

第一步：获取 Kimi API Key

访问Kimi API开放平台，登录后进入API Keys页面创建一个新的Key。

创建完成后，将Key设置为环境变量。建议写入shell配置文件以持久生效：

# 写入 ~/.zshrc 或 ~/.bashrc
export MOONSHOT_API_KEY="你的 Kimi API Key"

# 立即生效
source ~/.zshrc

验证环境变量是否已生效：

echo $MOONSHOT_API_KEY

注意：请勿将API Key直接硬编码到配置文件中，始终通过环境变量传入。

---

第二步：配置 Codex 自定义 Provider

Codex的用户配置文件位于~/.codex/config.toml。如果该文件不存在，首次运行codex时会自动创建。

打开配置文件，添加以下内容：

# 默认使用 Kimi K3
model = "kimi-k3"
model_provider = "kimi"

# 配置 Kimi 为自定义 Provider
[model_providers.kimi]
name = "Kimi K3 (Moonshot AI)"
base_url = "https://api.moonshot.cn/v1"
env_key = "MOONSHOT_API_KEY"

保存后即可生效，无需重启任何服务。

备选方案：直接覆盖内置 OpenAI Provider

如果不需要多模型切换，只想把所有请求重定向到Kimi，可以用更简洁的openai_base_url方案：

model = "kimi-k3"
openai_base_url = "https://api.moonshot.cn/v1"

然后将Kimi API Key赋值给OPENAI_API_KEY：

export OPENAI_API_KEY="你的 Kimi API Key"

这种方式配置最少，但会覆盖内置OpenAI Provider，不便于同时维护多个Provider。推荐第一种model_providers方案，灵活性更高。

---

第三步：CLI 启动与动态切换

配置完成后，在终端启动Codex即可直接使用Kimi K3：

codex

在会话内动态切换模型——无需退出，在TUI输入框内输入/model并回车，会弹出模型选择器，选择kimi-k3即可切换：

/model

切换后可用/status确认当前模型：

/status

单次运行覆盖模型——如果只想针对某次任务临时使用Kimi K3，不修改全局配置：

codex --model kimi-k3 --config model_provider='"kimi"'

---

第四步：桌面端接入

桌面端有两种方式，视你使用的客户端选其一。

方式一：config.toml 共享配置（Codex macOS App）

Codex桌面应用和CLI共用同一份~/.codex/config.toml，完成第二步的配置后，桌面端无需任何额外操作。打开App后点击顶部或左下角的模型名称，弹出模型选择器，已配置的kimi-k3会出现在列表中，点击切换即可。

如果列表中没有看到kimi-k3，检查以下三点：

1. 配置文件语法错误：在终端运行codex --strict-config确认配置无误
2. 环境变量未加载：确认MOONSHOT_API_KEY已写入~/.zshrc，重新打开终端后再用codex app命令启动桌面App
3. App缓存未刷新：完全退出后重新启动

方式二：cc switch 供应商面板（零配置）

如果你使用的桌面端AI编程工具支持cc switch供应商管理功能，接入Kimi K3可以完全不碰配置文件，全程GUI操作。

打开供应商管理面板（通常在设置 → 模型 → 添加新供应商），可以看到预置了大量国内外AI服务商，其中包括Kimi和Kimi For Coding两个选项：

• Kimi：接入Kimi K3通用推理模型，适合需要深度推理的代码分析、架构设计类任务
• Kimi For Coding：接入Kimi K2.7 Code系列高速模型，适合高频代码补全和快速生成

操作步骤：

1. 在供应商列表中找到Kimi或Kimi For Coding，点击选中
2. 在弹出的配置框中填入你的Kimi API Key（MOONSHOT_API_KEY）
3. 点击右下角+ 添加，供应商即刻生效
4. 返回聊天界面，点击模型切换按钮，从列表中选择刚添加的Kimi模型即可

如果列表里没有预置Kimi，也可以点击左上角自定义配置手动填写：

• API Base URL：https://api.moonshot.cn/v1
• 模型名称：kimi-k3
• API Key：你的Moonshot API Key

进阶：Profile 隔离多模型

如果你同时使用OpenAI原生模型和Kimi K3，推荐使用Profile方案——不修改全局配置，单独维护一个Kimi配置层：

创建~/.codex/kimi.config.toml：

# ~/.codex/kimi.config.toml
model = "kimi-k3"
model_provider = "kimi"
model_context_window = 1048576

启动时加载Kimi Profile：

codex --profile kimi

不加--profile时，Codex恢复默认配置（OpenAI原生模型）。Profile支持随时切换，适合需要同时维护多个模型的场景。

---

Kimi K3 专属参数说明

在Codex中使用Kimi K3时，有几个参数需要注意。

reasoning_effort 推理力度

Kimi K3通过请求顶层的reasoning_effort参数控制推理深度，接受"low" / "high" / "max"三档，默认"max"。Codex的model_reasoning_effort配置枚举是minimal | low | medium | high | xhigh，两者有交集但不完全一致。

建议如下：

• 不设置model_reasoning_effort：Kimi K3默认使用"max"推理力度，适合大多数编码任务。
• 只在需要降低延迟时设置"high"或"low"，这两个值Codex和Kimi K3都接受：

# 需要加速时使用（日常编码、简单补全）
model_reasoning_effort = "high"

# 极速轻量场景
model_reasoning_effort = "low"

注意：Codex的minimal、medium、xhigh这三档值不被Kimi K3识别，传入会导致API报错。使用Kimi K3时仅填写"low"或"high"，或直接留空以使用Kimi K3默认的"max"推理档位。

temperature 固定不可修改

Kimi K3的temperature固定为1.0，传入其他值会报错。Codex本身不强制设置temperature，但如果你的项目配置或AGENTS.md里有temperature相关指令，需要确认不会传递给Kimi K3。

上下文窗口

Kimi K3支持1M tokens上下文，远超默认值。Codex不会自动感知第三方Provider的上下文大小，建议在Profile中手动声明以避免过早截断：

model_context_window = 1048576

代码高速模型的替换

如果你的任务是纯代码生成（不需要深度推理），可以用kimi-k2.7-code-highspeed替代K3，输出速度更快：

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

---

常见问题

配置后Codex报API认证错误怎么办？
最常见的原因是环境变量未被桌面App读取到。在终端中先运行echo $MOONSHOT_API_KEY确认Key存在，然后从同一个终端窗口启动Codex（codex或codex app）。如果是桌面App双击打开，它可能从系统环境继承变量，而非shell配置文件。解决方案：在~/.zshrc中设置变量后，重启终端，再用codex app命令打开桌面App。

同一台机器上如何快速在Kimi K3和OpenAI原生模型之间切换？
两种方式：一是使用Profile（codex --profile kimi vs codex），二是在TUI会话内用/model斜杠命令临时切换。Profile方式持久化到下次启动，/model仅影响当前会话。

Kimi K3接入Codex后，PR审查和issue处理功能还能正常工作吗？
Codex的工程功能（PR生成、issue处理、代码重构）依赖模型的工具调用（Function Calling）能力。Kimi K3支持tool_choice = "auto" / "none" / "required"，兼容Codex的工具调用格式，主要工程功能可以正常使用。但需注意：Kimi K3的reasoning_content字段在多轮对话中需要原样回传，如果工具链对响应结构有严格解析，偶尔可能出现兼容性问题。