将外部模型连接到 Codex 是一个复杂的过程。本指南以 Kimi API 为实例，带你完成 macOS 和 Windows 上的 Codex API 完整配置。
什么是 Codex？
Codex 是 OpenAI 推出的编程 agent，用于处理仓库和终端相关工作。它可以：
编写代码： 创建函数、测试、脚本以及具体功能。
理解陌生代码库： 搜索文件、追踪调用链并解释各组件。
审查代码： 发现潜在缺陷、风险假设、缺失的测试以及安全隐患。
调试并修复问题： 复现错误、提出修改方案并运行检查。
自动化常规工作： 在你的批准下更新文件并执行既定的工作流程。
安装并登录 Codex
第一部分：安装 Codex CLI
在 macOS 上打开终端，或在 Windows 上打开 PowerShell。
根据你的操作系统运行相应命令：
macOS：
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"等待安装完成，然后关闭并重新打开终端或 PowerShell。
运行：
codex选择“使用 ChatGPT 登录”，完成浏览器登录流程，然后返回终端或 PowerShell。
第二部分：安装 Codex 桌面应用
访问 Codex 桌面应用官方页面。
下载适用于 macOS 或 Windows 的 ChatGPT 桌面应用。
安装并打开该应用，然后用你的 ChatGPT 账号登录。
创建任务或打开一个项目，并选择 Codex 作为工作模式。
输入
Say hello in one sentence.并发送消息。
内置 AI 模型与外部 LLM API 的对比
安装 Codex 后，你可以使用其内置 AI 模型，也可以连接兼容的外部 LLM API。选择哪种方式取决于你希望投入多少配置成本、需要多大的灵活性，以及是否愿意管理独立账户。
使用 Codex 内置模型
内置模型提供最简单的体验。你可以直接选择一个可用模型开始编码，无需运行其他服务或配置独立的 API key。
优势：
设置快捷，无需额外配置步骤。
与 Codex 工具和功能直接集成
需要管理的服务和凭据更少
局限：
只能从账户可用的模型中选择
如果想使用其他供应商的模型，灵活性较低
需要 GPT 订阅，使用成本相对较高。
使用外部 LLM API
外部 API 可以让你选择更多模型，并使用已有的其他供应商账户。不过，某些模型在 Codex 使用之前需要额外配置，或需要本地兼容工具。
优势：
可访问其他供应商的模型
针对不同编码任务有更高的灵活性
可独立控制外部 API 账户和使用情况
无需 GPT 订阅，适合对成本敏感的场景。
局限：
需要 API key 和额外配置
可能需要保持运行的本地路由器
计费、兼容性、隐私和故障排查均取决于外部供应商
如果想要最快完成设置，可先从内置模型开始。如果你已有外部 API 账户，或想要更多模型选择，可继续阅读下面的操作说明。它以 Kimi API 为实际示例，介绍如何将外部模型连接到 Codex。
如何将外部 LLM API 连接到 Codex：以 Kimi 为例
macOS 设置
步骤 1：打开终端 A，验证 Node.js 和 npm
操作位置： 按下 Command+Space，输入 Terminal，然后按 Enter。将这个首次打开的窗口视为终端 A。
运行：
node --version
npm --version预期结果： 每条命令都会输出一个版本号。例如 Node.js 的 v22.x.x 和 npm 的 10.x.x 仅为示例，并非最低版本要求。
如果提示命令未找到： 打开浏览器，访问 https://nodejs.org/en/download，下载 LTS 版本的 macOS .pkg 安装包，在 Finder 中打开下载目录，双击安装包，并按默认选项完成安装。使用 Command+Q 关闭终端，重新打开终端 A，再次运行两条版本查询命令。在两条命令都返回版本号之前，请不要继续下一步。
步骤 2：创建 Kimi API key
打开 Kimi API 开放平台。 在控制台中创建一个 API key，然后将其保存到密码管理器或密钥管理工具中。如果控制台只在创建时完整显示一次密钥，请在离开该页面前先复制保存。
步骤 3：在终端 A 中设置 MOONSHOT_API_KEY
操作位置： 回到终端 A。
运行：
export MOONSHOT_API_KEY="YOUR_KIMI_API_KEY"只需将 YOUR_KIMI_API_KEY 替换为真实的 Kimi 密钥。请保留引号以及变量名 MOONSHOT_API_KEY 不变。
预期结果： export 命令不会输出任何内容。请通过以下方式确认变量已设置，但不显示其具体值：
test -n "$MOONSHOT_API_KEY" && echo "Kimi key is set"终端应输出 Kimi key is set。
步骤 4：直接在终端 A 中测试 Kimi
操作位置： 继续使用已设置 MOONSHOT_API_KEY 的终端 A。
运行：
curl --silent --show-error https://api.moonshot.ai/v1/chat/completions \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","messages":[{"role":"user","content":"Say hello in one sentence."}],"stream":false}'预期结果： 出现一个 JSON 响应，其中 choices[0].message.content 字段包含生成的文本。
第 5 步：打开终端 B，并在终端 A 中启动路由器
位置： 保持终端 A 处于活动状态，按 Command+N 打开第二个窗口，将新窗口命名为终端 B。运行路由器命令前请返回终端 A。
在终端 A 中运行：
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey "$MOONSHOT_API_KEY"不要替换基础 URL 或模型。$MOONSHOT_API_KEY 必须保持为变量引用，而不是再粘贴一次密钥的副本。
可能出现的首次运行提示： npx 可能会显示“Need to install ... Ok to proceed? (y)”。请先查看包名及其链接的第三方来源，只有在你接受该包的情况下才输入 y 并按 Enter。此处未声明经过测试的具体包版本。
预期结果： 进程保持运行，并报告正在监听 127.0.0.1:8787。保持终端 A 处于打开状态。
如果失败： 如果 npm 无法下载该包，请确认网络连接正常，然后重新运行 node --version 和 npm --version。如果端口 8787 已被占用，请停止使用该端口的其他本地进程，或回到其对应终端按 Ctrl+C，然后重新运行路由器命令。
第 6 步：在终端 B 中测试 localhost
位置： 点击终端 B。
运行：
curl --no-buffer --show-error http://127.0.0.1:8787/v1/responses \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","input":"Say hello in one sentence.","stream":true}'预期结果： 终端 B 会输出类似 Responses 的流式事件，或包含一句问候语的输出内容。具体事件序列可能因路由器版本而有所不同。
如果看到 Connection refused： 查看终端 A。如果路由器已停止，请重新运行第 5 步的命令并保持其运行。如果终端 A 显示上游返回 401，请在其中重新设置 MOONSHOT_API_KEY 并重启路由器。
第 7 步：创建并编辑 macOS 的 Codex 配置文件
位置： 继续使用终端 B。
运行：
mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/config.toml" ]; then cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"; fi
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"这些命令会在必要时创建用户级配置文件，备份已有文件，并在 TextEdit 中打开 ~/.codex/config.toml。
如果文件为空
粘贴以下完整配置：
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000如果文件已包含设置
不要用完整配置覆盖现有文件。请保留无关设置，并逐项更新所需的行。
找到以
model =开头的行，将整行替换为：
model = "kimi-k2.7-code"找到以
model_provider =开头的行，将整行替换为：
model_provider = "kimi-proxy"找到以
model_context_window =开头的行，将整行替换为：
model_context_window = 256000找到以
model_supports_reasoning_summaries =开头的行，将整行替换为：
model_supports_reasoning_summaries = false如果这四项设置中的任何一项尚不存在，请在文件顶部附近添加缺失的那一行。
找到并删除任何以以下内容开头的整行：
model_catalog_json =同时找到并删除任何以以下内容开头的整行：
service_tier =添加下方的配置段：
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000不要移除其他提供方的配置段，例如 [model_providers.openai]。
保留其他与此无关的现有设置，包括 notify、审批、沙箱、项目及界面偏好设置。不要复制他人的 notify 行，因为它可能包含特定于某台计算机的绝对路径。
按 Command+S 保存文件，然后关闭 TextEdit。
第 8 步：重启 Codex 并运行完整的 macOS 测试
位置： 让路由器继续在终端 A 中运行。在终端 B 中，先按 Ctrl+C 关闭已有的 Codex 会话，然后准备一个可随时删除的临时文件夹。
在终端 B 中运行：
mkdir -p "$HOME/codex-kimi-test"
cd "$HOME/codex-kimi-test"
codex测试： 输入 hello. 并按 Enter。收到一句话的回复即可确认基本请求路径正常。
Windows 设置
使用两个独立的 PowerShell 窗口。PowerShell A 用于存储当前会话的 Kimi 密钥并运行路由器。PowerShell B 用于测试 localhost、编辑配置并启动 Codex。持久化的用户变量可供以后打开的窗口使用；当前会话的赋值则可让密钥在 PowerShell A 中立即生效。
步骤 1：打开 PowerShell A 并验证 Node.js 和 npm
位置： 按 Windows 键，输入 PowerShell，打开 Windows PowerShell。将此窗口称为 PowerShell A。
运行：
node --version
npm --version预期结果： 两条命令都会输出版本号。v22.x.x 和 10.x.x 等值仅为示例，并非最低版本要求。
如果命令无法识别： 打开浏览器访问 https://nodejs.org/en/download。下载 LTS 版 Windows .msi 安装包，在文件资源管理器中打开下载文件夹，双击安装程序，接受默认选项，并确保安装程序保留将 Node.js 添加到 PATH 的选项。关闭所有 PowerShell 窗口，重新打开 PowerShell A，再重新运行这两条命令。
步骤 2：创建 Kimi API key
打开 Kimi 开放平台。 在控制台中创建一个 API key，然后将其保存到密码管理器或密钥管理工具中。如果控制台只会完整显示一次密钥，请在离开该页面前先复制好。
步骤 3：在 PowerShell A 中设置持久变量和当前会话变量
位置： 回到 PowerShell A。
运行：
[Environment]::SetEnvironmentVariable("MOONSHOT_API_KEY", "YOUR_KIMI_API_KEY", "User")
$env:MOONSHOT_API_KEY = "YOUR_KIMI_API_KEY"在两行中都只替换 YOUR_KIMI_API_KEY，使用同一个 Kimi 密钥。保持 MOONSHOT_API_KEY、User、引号和标点不变。第一行会将该值保存供以后的进程使用。第二行会让它立即在 PowerShell A 中生效。
预期结果： 两条命令都不会有输出。可以在不打印密钥的情况下验证其是否存在：
$null -ne $env:MOONSHOT_API_KEYPowerShell 应输出 True。
如果输出 False： 使用直角引号重新运行当前会话赋值命令。如果因策略限制导致无法写入用户环境变量，可在本教程中继续使用当前会话的值，并向管理员咨询用户环境变量应如何存储。撤销任何已在日志或共享文本中暴露过的密钥。
步骤 4：直接从 PowerShell A 测试 Kimi
API 参考文档可能会显示 POST URL，但切勿只在 PowerShell 中单独输入 POST https://...。请按照此处所示使用 Invoke-RestMethod -Method Post。
位置： 留在已设置 $env:MOONSHOT_API_KEY 的 PowerShell A 中。
运行：
$headers = @{ Authorization = "Bearer $env:MOONSHOT_API_KEY" }
$body = @{ model = "kimi-k2.7-code"; messages = @(@{ role = "user"; content = "Say hello in one sentence." }); stream = $false } | ConvertTo-Json -Depth 5
$response = Invoke-RestMethod -Method Post -Uri "https://api.moonshot.ai/v1/chat/completions" -Headers $headers -ContentType "application/json" -Body $body
$response.choices[0].message.content不要替换端点、模型或变量名。PowerShell 会从 $env:MOONSHOT_API_KEY 读取密钥。
预期结果： 最后一行会输出来自 choices[0].message.content 的一句问候语。
如果收到 401： 确认该密钥来自全局的 .ai 控制台，如有必要请撤销并重新创建密钥，重新运行步骤 3 中的两条赋值命令，然后重试。如果模型被拒绝，请确认模型 ID 是否精确为 kimi-k2.7-code，并在 Kimi 控制台中检查模型访问权限。
步骤 5：打开 PowerShell B，并在 PowerShell A 中启动路由器
位置： 再次按 Windows 键，输入 PowerShell，打开第二个 Windows PowerShell 窗口，将其称为 PowerShell B。运行路由器命令时请回到 PowerShell A。
在 PowerShell A 中运行：
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey $env:MOONSHOT_API_KEY保持 $env:MOONSHOT_API_KEY 不变；不要将密钥直接粘贴到命令中。
首次运行时可能出现的提示： npx 可能会显示 Need to install ... Ok to proceed? (y)。请查看该软件包及其第三方来源。只有在你接受的情况下，才输入 y 并按 Enter。此处不对任何具体已测试的软件包版本作出保证。
预期结果： 该进程会保持运行，并显示正在监听 127.0.0.1:8787。请保持 PowerShell A 处于打开状态。
如果失败： 在 PowerShell A 中运行 node --version 和 npm --version。如果任一命令失败，请重复步骤 1。如果端口 8787 已被占用，请在对应窗口中按 Ctrl+C 停止另一个路由器，然后重新运行该命令。
步骤 6：从 PowerShell B 测试本地地址
位置： 点击 PowerShell B。不要停止 PowerShell A 中的路由器。
运行：
$localBody = @{ model = "kimi-k2.7-code"; input = "Say hello in one sentence."; stream = $false } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8787/v1/responses" -ContentType "application/json" -Body $localBody不要替换本地地址 URL，它指向的是 PowerShell A 中的路由器。
预期结果： PowerShell 会返回一个类似 Responses 的对象，或包含该问候语的输出内容。具体字段可能因路由器版本不同而有所差异。
如果连接被拒绝： 查看 PowerShell A，若路由器已退出，请重新运行步骤 5 中的命令。如果 PowerShell A 显示上游认证错误，请按 Ctrl+C，重新设置 $env:MOONSHOT_API_KEY，然后重启路由器。在默认的 @codeproxy/cli 快速上手流程中，不要添加本地授权头。
步骤 7：创建并编辑 Windows 版 Codex 配置文件
位置： 继续使用 PowerShell B。提供商配置应放在 $HOME\.codex\config.toml，而不是项目文件夹中。
运行：
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
$configPath = "$HOME\.codex\config.toml"
if (Test-Path $configPath) { Copy-Item $configPath "$configPath.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')" }
if (-not (Test-Path $configPath)) { New-Item -ItemType File -Path $configPath | Out-Null }
notepad "$HOME\.codex\config.toml"这些命令会创建用户目录，备份已有配置，若文件不存在则创建它，并用记事本打开该文件。
在记事本中： 粘贴以下完整的默认配置；如果文件中已存在冲突的重复模型或提供商键，请将其删除：
model_provider = "kimi-proxy"
model = "kimi-k2.7-code"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000不要替换 kimi-proxy、localhost URL 或 responses。按 Ctrl+S 保存并关闭记事本。
确认文件名： 运行：
Get-Item "$HOME\.codex\config.toml" | Select-Object FullName, Name, Length预期结果： Name 恰好为 config.toml，而不是 config.toml.txt，且 Length 大于零。
如果记事本添加了 .txt： 在记事本中选择 文件 → 另存为，将 保存类型 设置为 所有文件，输入 config.toml，并将其保存到 $HOME\.codex 中。重新运行 Get-Item。如果 Codex 忽略了该 provider，请确认你编辑的是用户级路径，并删除重复的 TOML 键。
第 8 步：重启 Codex 并运行完整的 Windows 测试
位置： 保持 PowerShell A 及其路由器继续运行。完全关闭所有 Codex 应用或会话。关闭 PowerShell B，通过按下 Windows 键并输入 PowerShell 重新打开它，选择 Windows PowerShell，然后创建一个临时文件夹。
在重新打开的 PowerShell B 中运行：
New-Item -ItemType Directory -Force -Path "$HOME\codex-kimi-test" | Out-Null
Set-Location "$HOME\codex-kimi-test"
codex测试： 输入 hello. 并按 Enter。一句话的回复即可确认基本请求路径正常。
在 Codex 桌面应用中使用 Kimi
继续之前，请先完成 macOS 或 Windows 设置中本地路由器和 config.toml 的第 1–7 步。你不需要先完成 CLI 测试，但在桌面应用中使用 Kimi 时路由器必须保持运行。
第 1 步：保持本地路由器运行
保持 Terminal A 或 PowerShell A 窗口打开，让 @codeproxy/cli 持续运行在：
http://127.0.0.1:8787第 2 步：确认 provider 配置
打开用户级 Codex 配置文件。
在 macOS 上，运行：
open -e "$HOME/.codex/config.toml"在 Windows 上，运行：
notepad "$HOME\.codex\config.toml"确认该文件包含以下顶层设置：
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000第 3 步：完全重启桌面应用
在 macOS 上，按 Command+Q 完全退出桌面应用。仅关闭窗口是不够的。
在 Windows 上，关闭所有桌面应用窗口，并确认该应用在系统托盘中也已不再运行。
重新打开桌面应用并打开一个项目文件夹。
第 4 步：保持选中 Custom 模型
桌面端模型选择器可能会显示 Custom，而不是 Kimi K2.7 Code。这是正常现象。
在 config.toml 中定义的自定义 provider 并不总是以名称形式显示在桌面模型列表中。如果你想使用 Kimi provider，请不要选择 GPT-5.6 Sol 等 OpenAI 模型。请保持选中 Custom。
你也可能会看到以下警告：
Model metadata for `kimi-k2.7-code` not found.
Defaulting to fallback metadata.这只是一条警告，并不意味着连接失败。以下设置已经提供了正常使用所需的重要模型信息：
model_context_window = 256000
model_supports_reasoning_summaries = false第 5 步：验证桌面端的请求路径
在桌面应用中发送以下提示词：
在桌面应用响应时，观察 Terminal A 或 PowerShell A。如果 Terminal A 窗口收到了新请求，并且桌面应用返回了回答，说明桌面应用正在使用本地 Kimi 路由。
排查常见集成错误
zsh: command not found: POST
POST URL 是 API 文档中的记法，并非命令。在 macOS 上，请复制完整的 curl 示例。在 Windows 上，请复制完整的 Invoke-RestMethod -Method Post 示例。
端口 8787 连接被拒绝
回到 Terminal A 或 PowerShell A。如果没有路由器进程在运行，请设置当前会话的 Kimi 变量，并重新运行文档中给出的 npx @codeproxy/cli ... 命令。保持该窗口打开，然后在窗口 B 中重复 localhost 测试。
返回 401 响应
查看路由器窗口以确定失败发生在哪一环节。上游 Kimi 返回 401 通常意味着 MOONSHOT_API_KEY 无效、已被吊销，或来自错误的地区账户。请在全局 .ai 控制台中吊销该密钥，创建一个新密钥，重置当前会话变量，并重启路由器。默认路由器路径没有入站 bearer 校验。如果使用其他适配器时出现本地 401，可能是其可选的 CODEX_KIMI_PROXY_KEY 缺失或无效。
不支持的参数或工具错误
路由器可能转发了 Kimi 不接受的字段。采样相关字段应保持未设置；如果确实发出，则必须使用可接受的固定值。请确认 tool_choice 为 auto 或 none，并确认适配器保留了 reasoning_content。如果多步骤测试仍然失败，请停止使用该路由器版本，改用或更新到明确支持 Kimi 的版本。
Codex 忽略了 provider
直接打开用户配置文件：在 macOS 上运行 open -e "$HOME/.codex/config.toml"，在 Windows 上运行 notepad "$HOME\.codex\config.toml"。确认其中只有一个顶层的 model_provider = "kimi-proxy"、一个 provider 表、本地主机的 base URL，以及 wire_api = "responses"。保存后完全退出 Codex，再重新启动。不要只在项目级的 .codex/config.toml 中设置 provider。
npx 无法启动路由
在路由窗口 A 中运行 node --version 和 npm --version。如果任一命令失败，请从 nodejs.org/download 安装 Node.js LTS 版本，关闭并重新打开终端后再试一次。如果 npx 请求下载软件包的权限，请在输入 y 之前先检查该软件包及其来源。
使用 Kimi API 的优势
在 Cursor 的 API 工作流中使用 Kimi 可以提升编码、调试和开发任务的效率。它出色的能力有助于生成准确的回答、处理复杂的指令，并加快问题的解决速度。以下是在 Cursor 工作流中使用 Kimi 以提升生产力和效率的几个主要优势。
长上下文代码理解
Kimi 能够一次性处理大量代码和信息，更有效地识别不同文件和项目模块之间的关联。这样一来，处理大型或复杂的代码库就变得容易得多。
更好的文档与仓库分析
使用 Kimi 可以快速梳理项目文档、技术说明和仓库内容，不必逐一翻阅文件就能找到关键信息。开发者可以在更短的时间内更清晰地了解整个项目。
具有成本优势的 AI 开发
Kimi 为处理许多开发任务提供了一个实用且经济的选择。团队无需完全依赖成本更高的模型，也能获得强大的 AI 支持，从而在提升整体生产力的同时更好地控制开支。
更快的知识检索
在大型代码库、数据集和项目文件中都能快速定位所需信息，减少为了寻找答案或参考资料而花费的时间，让更多精力可以投入到编码、测试和项目改进中。
更完善的工作流自动化
借助 Kimi，重复性的开发任务变得更容易管理和完成。它可以协助代码生成、内容审查以及日常项目工作，让日常工作流保持有序、高效，长期效率也更高。
Codex 如何改善开发工作流
配置好的 Codex CLI API 工作流将仓库检查、编辑、命令执行和审查整合在同一上下文中。Codex 可以搭建文件框架、解释不熟悉的模块、复现问题、提出测试方案，并运行经过批准的检查。外部 provider 支持增加了模型选择的空间，但并不能免除审查责任。
每项任务都应从一个明确的小目标开始。在编辑之前先让 Codex 进行检查，审查其提出的更改，只批准你能理解的命令，运行仓库中的测试，并检查最终的差异。在通过审查和验证之前，应将生成的代码视为不可信的贡献。
结语
可靠的 Codex API 使用方式来自于按顺序测试每一层：先验证 Codex 身份、再直接调用 Kimi、启动并测试本地主机、保存用户级 provider 配置、运行一次只读提示词，最后完成一次涉及文件和工具的任务。真实的 Kimi 密钥应留在路由中保存，不要将密钥放入共享文件，使用结束后记得停止路由。