Codex 接入国产大模型实战:DeepSeek、Qwen、Kimi 配置与报错排查
新版 Codex 依赖 Responses API,手把手教你接入 DeepSeek、Qwen、Kimi,包含配置文件、模型切换、工具调用验证和高频报错解决方案。

不少开发者已经习惯使用 Codex 编写代码,但在实际项目中,OpenAI 官方模型并不一定是唯一选择。DeepSeek、Qwen、Kimi 等国产大模型也具备代码分析、项目理解、多文件修改和 Agent 工具调用能力。
问题在于,这些模型虽然有不少都兼容 OpenAI API,却不一定能够直接接入新版 Codex。有些用户修改了 API Key 和 Base URL,启动 Codex 后却遇到 404;有些用户已经成功返回文本,但模型无法正常执行终端命令或修改文件;还有一些用户明明配置了正确的模型名称,Codex 却提示找不到模型元数据。这些问题往往不是模型本身造成的,而是 API 协议、模型目录和客户端配置之间存在差异。
本文以 Codex CLI 为例,介绍如何接入 DeepSeek、Qwen 和 Kimi,重点解决 Responses API 兼容、配置文件修改、模型切换和常见错误排查问题。
一、为什么 Codex 不能直接接入所有 OpenAI 兼容模型?
首先需要理解 Codex 的工作方式。Codex 不只是一个调用大模型生成代码的聊天客户端,它还需要模型参与工具调用、文件修改、终端执行和多轮任务管理。
例如,开发者输入:
检查当前项目中的登录模块,修复密码校验逻辑,并运行相关测试。Codex 的实际执行过程可能包含:
- 读取项目目录。
- 分析相关源代码。
- 确定需要修改的文件。
- 生成代码修改指令。
- 调用工具执行文件修改。
- 运行测试命令。
- 分析测试结果。
- 根据错误继续修复。
模型与 Codex 之间需要持续交换结构化信息,而不只是传递普通文本。
1. Chat Completions 与 Responses API 有什么区别?
目前常见的 OpenAI 兼容接口主要有两种。
Chat Completions
传统聊天补全接口,主要使用 messages 数组传递对话内容。
典型请求地址:
/v1/chat/completionsResponses API
面向更复杂的模型交互和 Agent 工作流设计,支持统一组织输入、输出、工具调用和响应状态。
典型请求地址:
/v1/responses两者虽然都可以用于模型调用,但请求结构、事件格式和工具交互方式并不完全相同。
新版 Codex 使用 Responses API。根据 QwenCloud 官方接入文档,Codex 0.94.0 及之后版本只支持 Responses API。OpenAI 当前配置文档也明确将 responses 作为自定义 Provider 支持的通信协议。
这意味着,即使一个模型服务商支持 OpenAI Python SDK,也不能直接推断它能够接入新版 Codex。
2. Codex 自定义模型需要哪些配置?
Codex 主要通过以下几个配置项连接自定义模型:
表格
| 配置字段 | 作用 |
|---|---|
| model | 指定模型 ID |
| model_provider | 指定模型提供方 |
| base_url | 设置 API 服务地址 |
| env_key | 指定 API Key 所在的环境变量 |
| wire_api | 指定通信协议 |
| model_catalog_json | 指定模型元数据文件 |
| model_context_window | 设置客户端使用的上下文窗口 |
其中最关键的是 wire_api。新版 Codex 的自定义 Provider 应使用:
wire_api = "responses"不能因为某个接口支持 /chat/completions,就将 wire_api 设置成 chat 来绕过协议要求。
官方参考:OpenAI Codex 配置参考文档
二、接入前的准备:Codex 配置文件在哪里?
在正式配置国产模型之前,先确认 Codex 已经正常安装。可以通过以下命令检查:
codex --versionDeepSeek 官方当前提供的自动配置脚本 1.5.0 要求 Codex 0.164 或更新版本。建议先更新到当前可用的稳定版本,再进行后续操作。
1. 找到 config.toml
Codex 的用户级配置文件位置如下:
表格
| 操作系统 | 配置文件路径 |
|---|---|
| Windows | %USERPROFILE%.codex\config.toml |
| macOS | ~/.codex/config.toml |
| Linux | ~/.codex/config.toml |
如果第一次运行 Codex,系统通常会自动创建 .codex 目录;如果没有生成,可以手动创建。
Windows PowerShell:
New-Item -ItemType Directory -Force "$HOME\.codex"
New-Item -ItemType File -Force "$HOME\.codex\config.toml"macOS / Linux:
mkdir -p ~/.codex
touch ~/.codex/config.toml2. 修改配置之前先备份
如果已经使用 Codex 配置过 MCP、权限策略、沙箱或其他模型,不建议直接覆盖整个文件。
macOS / Linux:
cp ~/.codex/config.toml \
~/.codex/config.toml.backupWindows PowerShell:
Copy-Item "$HOME\.codex\config.toml" `
"$HOME\.codex\config.toml.backup"后续接入时,只需要修改模型提供商相关配置。
3. API Key 不要直接写进配置文件
建议使用环境变量管理密钥。例如:
export DEEPSEEK_API_KEY="your_api_key"Windows PowerShell:
$env:DEEPSEEK_API_KEY="your_api_key"这样,配置文件只需要引用环境变量名称,不需要保存真实密钥。需要注意,PowerShell 中的 $env: 设置只对当前终端会话生效;正式使用时,应根据自己的系统配置持久化环境变量。
三、Codex 接入 DeepSeek:官方脚本与手动配置
DeepSeek 是目前比较适合用来演示 Codex 接入流程的模型。DeepSeek 官方已经提供 Responses API 支持,并专门发布了 Codex 集成指南。
当前官方模型标识包括:
deepseek-flash
deepseek-v4-pro其中,deepseek-flash 已升级为 DeepSeek V4.1 Flash 1017,旧模型名称不应继续作为新项目的默认配置。
1. 使用官方自动配置脚本
这是 DeepSeek 官方提供的快捷接入方式。
macOS / Linux:
bash <(curl -fsSL \
https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)Windows PowerShell:
irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex运行脚本后,根据菜单选择:
- 选项 1:配置 DeepSeek Flash。
- 选项 2:配置 DeepSeek V4 Pro。
- 选项 9:恢复默认 Codex 配置并移除 DeepSeek 相关设置。
首次运行时,需要输入 DeepSeek API Key。
官方脚本会自动完成以下工作:
- 备份原有 Codex 配置。
- 生成 models.json 模型目录。
- 写入 DeepSeek Provider 配置。
- 配置模型推理等级和相关参数。
- 检查生成的配置文件。
这也是为什么 DeepSeek 的官方方案比简单替换 Base URL 更完整。它不仅告诉 Codex 应该向哪里发送请求,还会提供模型上下文、推理等级和工具调用相关元数据。
官方接入文档:DeepSeek Codex 集成文档
2. 手动配置 DeepSeek
如果希望自己管理配置,也可以手动添加 Provider。编辑:
~/.codex/config.toml添加:
model = "deepseek-flash"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"这里有几个容易写错的地方:
- model 必须使用官方实际开放的模型 ID。
- model_provider 必须与 Provider 配置块名称一致。
- base_url 只填写基础地址,不要把 /responses 拼进去。
- env_key 必须对应系统中真实存在的环境变量。
- wire_api 使用 responses。
Codex 会根据通信协议构造对应的请求地址。
3. 为什么还需要 models.json?
这是手动配置时容易遗漏的一步。config.toml 负责告诉 Codex 如何连接模型服务;models.json 则负责告诉客户端当前模型具备什么能力。
例如:
- 模型上下文窗口。
- 支持的输入模态。
- 默认推理等级。
- 可用推理等级。
- 工具调用格式。
- 是否支持并行工具调用。
DeepSeek 官方脚本会自动生成这个文件。对于需要自行维护模型目录的开发者,建议直接参考官方指南中的完整 JSON 示例,而不是只复制一个模型名称。
官方当前提供的 DeepSeek Flash 元数据包括:
- 上下文窗口:1,048,576 Tokens。
- 图片输入:支持。
- 默认推理等级:high。
- 支持等级:low、high、max。
- 最低客户端版本:0.164.0。
这些信息是 Codex 对模型能力的描述,不代表每一个模型都能自动获得相同功能。不同版本和服务端配置仍需分别核对。
四、Codex 接入 Qwen:Token Plan 与按量计费配置有什么区别?
QwenCloud 也提供了官方 Codex 接入指南。与 DeepSeek 不同,QwenCloud 的接入需要特别关注 API Key 类型和套餐类型。
目前官方文档提供两种主要方式:
- Token Plan。
- Pay-as-you-go 按量计费。
两种方式使用不同的密钥和服务地址,不能混合配置。
1. Token Plan 接入方式
首先进入 QwenCloud 控制台,购买对应套餐并获取 Token Plan API Key。Token Plan 个人版密钥通常以:
sk-sp-开头。普通按量计费 API Key 则通常以:
sk-ws-开头。两种 Key 不通用。
官方 Token Plan 的 OpenAI 兼容地址为:
https://token-plan.maas.qwencloudapi.com/compatible-mode/v1修改 Codex 配置:
model_provider = "Qwen_Token_Plan"
model = "auto"
[model_providers.Qwen_Token_Plan]
name = "Qwen Token Plan"
base_url = "https://token-plan.maas.qwencloudapi.com/compatible-mode/v1"
env_key = "QWEN_API_KEY"
wire_api = "responses"然后设置环境变量:
export QWEN_API_KEY="your_token_plan_key"这里使用 model = "auto",是 QwenCloud 官方 Token Plan Codex 快速配置提供的写法。如果套餐支持指定模型,也可以按照当前控制台和模型目录选择具体模型。
2. 按量计费接入方式
如果使用 QwenCloud 的按量计费服务,需要选择与账号区域对应的 API 地址。以新加坡区域为例:
model_provider = "QwenCloud"
model = "qwen3.8-max"
[model_providers.QwenCloud]
name = "QwenCloud"
base_url = "https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1"
env_key = "QWEN_API_KEY"
wire_api = "responses"以上模型 ID 和区域地址应以当前账户可用的官方模型目录为准。QwenCloud 不同区域的 API Key 具有区域属性,不能拿一个区域的密钥随意配置到另一个区域的 Endpoint。
3. Qwen 接入时最容易遇到的问题
有些用户使用模型切换工具时,会看到类似:
domestic models not supported或者:
Bad Request (400)这不一定意味着模型不支持 Codex。QwenCloud 官方文档特别解释,部分第三方配置管理工具会在切换模型时发送健康检查请求,而健康检查格式可能与 Codex 实际发送的请求不同。因此,工具的测试请求失败,不代表真实 Codex 调用也失败。
如果遇到这种情况,可以先直接修改用户级 config.toml,绕过管理工具的健康检查,再运行 Codex 验证。
五、Codex 接入 Kimi K3.1 Pro:需要额外配置模型目录
Kimi 的接入与前面两款模型略有不同。Kimi Code 官方已经提供 Codex 专门配置教程,支持通过 Responses API 直接连接。
当前 Kimi Code 模型 ID 包括:
k3.1-pro
k3.1-pro-highspeed其中:
- K3.1 Pro:适合复杂编程和长周期 Agent 任务。
- K3.1 Pro Highspeed:官方标注输出速度约为标准版本的 2~3 倍,但配额消耗约为两倍。
需要注意,Kimi K3.1 Pro 的上下文窗口取决于会员等级。
表格
| 会员等级 | K3.1 Pro 上下文窗口 |
|---|---|
| Plus / Moderato | 262,144 Tokens |
| Pro / Allegretto 及以上 | 1,048,576 Tokens |
不能因为模型本身支持 1M 上下文,就认为所有账户都能直接使用完整额度。
1. 获取 Kimi Code API Key
进入 Kimi Code 控制台创建 API Key。官方说明,会员最多可以创建 5 个 Key,每个 Key 在创建时显示一次,需要妥善保存。
Kimi Code 国内服务地址:
https://api.kimi.com/coding/v1海外服务地址:
https://api.kimi.ai/coding/v1如果使用 Kimi 开放平台而不是 Kimi Code 会员服务,则需要根据对应平台文档选择不同的 API 地址和计费方式。两者不能简单混为一谈。
2. 创建 Kimi 模型目录
Kimi 官方建议为 Codex 创建独立的 models.json 文件。路径:
~/.codex/models.jsonWindows:
C:\Users\<username>\.codex\models.json示例:
{
"models": [
{
"slug": "k3.1-pro",
"display_name": "Kimi K3.1 Pro",
"description": "Kimi K3.1 Pro",
"default_reasoning_level": "high",
"supported_reasoning_levels": [
{
"effort": "low",
"description": "Light reasoning"
},
{
"effort": "high",
"description": "Enhanced reasoning"
},
{
"effort": "max",
"description": "Deep reasoning"
}
],
"shell_type": "shell_command",
"apply_patch_tool_type": "freeform",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"base_instructions": "",
"supports_reasoning_summaries": true,
"default_reasoning_summary": "none",
"support_verbosity": false,
"truncation_policy": {
"mode": "bytes",
"limit": 10000
},
"context_window": 1048576,
"max_context_window": 1048576,
"effective_context_window_percent": 95,
"supports_parallel_tool_calls": true,
"experimental_supported_tools": [],
"input_modalities": [
"text",
"image"
]
}
]
}这里的 1M 上下文配置适用于拥有相应会员权益的账户。如果账户只有 256K 权限,应当相应调整模型元数据,不要让 Codex 使用超过实际服务权限的上下文配置。
3. 修改 config.toml
打开:
~/.codex/config.toml添加:
model = "k3.1-pro"
model_provider = "kimi"
model_catalog_json = "~/.codex/models.json"
[model_providers.kimi]
name = "Kimi"
base_url = "https://api.kimi.ai/coding/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"
[desktop]
enabled-reasoning-efforts = ["low", "high", "max"]国内服务可以将 Base URL 改为:
https://api.kimi.com/coding/v1然后设置 API Key:
macOS:
echo 'export KIMI_API_KEY="sk-kimi-your-key"' >> ~/.zshrc
source ~/.zshrcLinux:
echo 'export KIMI_API_KEY="sk-kimi-your-key"' >> ~/.bashrc
source ~/.bashrcWindows PowerShell:
setx KIMI_API_KEY "sk-kimi-your-key"Kimi 官方还特别提醒,K3.1 Pro 必须开启思考模式。如果关闭思考模式,请求会被拒绝。
配置完成后,重新启动 Codex,输入 /model,即可选择模型和推理等级。
六、DeepSeek、Qwen、Kimi 如何在 Codex 中切换?
如果每次更换模型都要手动修改整个配置文件,使用体验并不好。更合理的方式是将不同模型的配置分开管理。新版 Codex 支持使用独立 Profile 配置文件。
例如,可以在 .codex 目录中创建:
~/.codex/
├── config.toml
├── deepseek.config.toml
├── qwen.config.toml
└── kimi.config.toml每个 Profile 保存对应的模型配置。
例如,DeepSeek:
model = "deepseek-flash"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"Qwen:
model = "auto"
model_provider = "qwen"
[model_providers.qwen]
name = "Qwen Token Plan"
base_url = "https://token-plan.maas.qwencloudapi.com/compatible-mode/v1"
env_key = "QWEN_API_KEY"
wire_api = "responses"Kimi:
model = "k3.1-pro"
model_provider = "kimi"
model_catalog_json = "~/.codex/models.json"
[model_providers.kimi]
name = "Kimi"
base_url = "https://api.kimi.ai/coding/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"启动时选择对应配置:
codex --profile deepseekcodex --profile qwencodex --profile kimi注意:上述是独立配置文件的示例。实际使用时,需要将每个 Profile 文件保存到 Codex 当前 CODEX_HOME 对应目录,并确保对应环境变量已经设置。如果需要模型元数据,还要确保 models.json 路径有效。
这样就能在不反复覆盖主配置文件的情况下,切换不同国产模型。
七、接入成功后,如何判断模型真的能够使用 Codex 工具?
很多开发者看到模型能够正常回复 Hello,就认为接入已经完成。实际上,这只能说明基础请求能够返回。Codex 的核心能力还包括文件修改、终端执行和工具调用。因此,需要进行更完整的验证。
建议分成三个阶段。
第一阶段:验证基础连接
启动 Codex:
codex发送:
请用三句话介绍你当前使用的模型,并说明你能否分析当前工作目录中的代码。检查是否能够正常返回。
第二阶段:验证文件读取与修改
在一个测试项目中创建:
def calculate_total(price, quantity):
return price * quantity然后向 Codex 提出:
请检查这个函数是否存在输入校验问题。增加以下功能:1. price 不能为负数;2. quantity 必须为非负整数;3. 不符合条件时抛出 ValueError;4. 为函数编写 pytest 测试。先分析,再修改文件。观察 Codex 是否能够读取文件并执行实际修改。
第三阶段:验证终端和测试执行
继续要求:
运行刚才编写的 pytest 测试。如果出现失败,请分析错误原因,修改代码并重新执行测试。最后列出修改文件和测试结果。如果模型能够正常完成上述过程,说明基础文本调用、工具调用和文件操作链路已经基本打通。不过,还需要在真实项目中验证多文件修改、长上下文和持续任务执行能力。
八、Codex 接入国产模型常见的六种报错及解决办法
1. HTTP 404:接口地址不存在
常见原因:
- Base URL 填写错误。
- 模型服务只支持 Chat Completions。
- Codex 请求的 Responses API 未开放。
- 地址中重复添加 /v1/responses。
解决方式:先检查 Base URL 是否为官方文档中的基础地址,再确认服务端是否支持 Responses API。不要将完整的 /responses 路径直接填写到 Base URL 中。
2. HTTP 401:API Key 无效
检查:
- API Key 是否复制完整。
- 环境变量名称是否一致。
- 是否混用了 Token Plan 和普通 API Key。
- 当前账户是否有对应模型使用权限。
例如,Qwen Token Plan 的 Key 不能直接用于普通按量计费 Endpoint。
3. HTTP 400:请求格式不匹配
这类问题需要优先检查协议和请求字段,尤其是工具调用任务,不能只验证普通文本请求。如果客户端发送 Responses API 格式,而服务端只支持 Chat Completions,就可能出现请求结构不兼容。
4. Model metadata not found
这通常表示 Codex 没有找到当前模型对应的元数据。检查:
- model_catalog_json 是否正确。
- models.json 是否存在。
- 模型 slug 是否与 model 完全一致。
- JSON 文件是否存在语法错误。
- 上下文窗口是否配置合理。
部分情况下,基础 API 调用可能仍然正常,但客户端无法正确识别模型的推理等级或输入能力。
5. Codex 可以回答,但无法执行工具
优先检查:
- 模型是否支持 Responses API。
- 是否支持 Codex 所需的函数调用和工具调用格式。
- 模型目录中的 apply_patch_tool_type 是否符合服务端能力。
- Codex 的沙箱与权限配置是否阻止了执行。
不要通过关闭全部安全限制来解决工具调用问题。应先判断是模型协议不兼容,还是本地执行权限不足。
6. 桌面版找不到环境变量
这是 macOS 用户容易遇到的问题。从终端启动的 Codex 可以读取当前 Shell 环境变量,但从 Dock 或 Finder 启动的桌面应用不一定继承这些变量。
Kimi 官方提供的 macOS 处理方式是:
launchctl setenv KIMI_API_KEY "sk-kimi-your-key"执行后彻底退出桌面应用,再重新打开。其他模型也应根据各自的环境变量名称进行设置。
九、统一管理国产模型 API:什么时候需要 API 聚合接入?
如果只使用 DeepSeek,一个官方 API Key 通常就足够。但如果团队需要在 DeepSeek、Kimi、Qwen、GLM、Gemini 等模型之间切换,就需要维护多套密钥、服务地址和调用记录。当模型数量增加时,配置和管理工作也会变得复杂。
例如,一个开发团队可能需要:
- 使用 DeepSeek 处理常规代码任务。
- 使用 Kimi 分析大型代码仓库。
- 使用 Qwen 处理部分开发任务。
- 使用 Gemini 分析图片和界面截图。
这种情况下,可以考虑使用 KoalaAPI 这样的多模型 API 聚合服务,集中管理已经接入的模型和 API 凭证。
但有一个必须提前确认的条件:Codex 接入需要 Responses API,而不是仅仅兼容 OpenAI SDK。
因此,在选择统一接入服务时,应核对:
- 是否提供 Codex 可用的 Responses API Endpoint。
- 是否支持 SSE 流式事件。
- 是否支持函数调用和工具调用。
- 是否保留模型原生的推理参数。
- 是否正确返回模型使用量和错误信息。
- 是否有明确的模型 ID 和上下文限制。
如果服务只支持 Chat Completions,即使可以正常运行 OpenAI Python SDK,也不代表能够直接接入新版 Codex。
另外,API 聚合层负责模型接入和请求转发,不会自动提供本地终端、文件修改或沙箱执行能力。这些仍由 Codex 自身负责。
十、总结:Codex 接入国产模型,先看协议,再看模型能力
Codex 接入国产大模型并不复杂,真正需要注意的是接口协议与模型元数据。
DeepSeek 已经提供官方 Codex 配置脚本,可以直接完成模型注册和相关参数配置。QwenCloud 提供 Token Plan 和按量计费两种接入方式,需要注意密钥、区域和 Endpoint 的对应关系。Kimi K3.1 Pro 则需要额外维护模型目录,并根据会员等级设置合理的上下文窗口。
对于开发者而言,最重要的不是将所有模型配置到 Codex 中,而是建立一套可以稳定切换、方便测试和持续维护的接入方式。
如果只是简单代码补全,可以优先考虑响应速度和调用成本;如果需要分析大型代码仓库、多文件修改和长周期 Agent 执行,则需要重点测试上下文、工具调用和任务完成能力。
当 Codex 能够根据不同开发任务调用合适的国产模型,模型选择就不再局限于某一个厂商的默认配置,而是成为整个开发工作流中可以灵活管理的一部分。

