Kimi K3 是月之暗面（Moonshot AI）于 2026 年推出的新一代推理大模型，拥有 1M tokens 超长上下文窗口，完全兼容 OpenAI API 格式，支持 reasoning_effort 参数（low / high / max 三档，默认 max）控制推理深度；Codex 是 OpenAI 推出的 AI 编程智能体，支持通过 ~/.codex/config.toml 接入任意 OpenAI 兼容的第三方模型——这意味着把 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 开放平台（platform.kimi.com），登录后进入 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 字段在多轮对话中需要原样回传，如果工具链对响应结构有严格解析，偶尔可能出现兼容性问题。

延伸阅读

如果你还需要把其他 AI 模型接入 Cursor、VS Code 等编程工具，七牛云 AI 编程工具配置大全 汇总了主流模型在各类 IDE 的集成配置方案，供参考。