Codex 接入外部模型

Codex 接入外部模型

介绍如何通过 CC Switch 或 Codex 自定义 model provider 接入第三方在线模型,并讲解配置、认证、模型切换与故障排查。

Codex 接入外部模型#

Codex 中文站说明: 本页围绕“Codex 接入外部模型”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新,请以当前客户端为准。

Codex 本地客户端不只能够使用 OpenAI 官方模型。通过 CC Switch 或 Codex 的自定义 model provider,你可以把 Codex 接入第三方模型厂商、API 聚合平台或企业内部模型网关。

本文只介绍第三方在线模型,提供两种接入路线:

接入方式适合场景 / 是否需要协议转换
CC Switch第三方接口只支持 Chat Completions、Anthropic Messages,或者你希望通过图形界面快速切换多个 provider

是否需要协议转换: 由 CC Switch 根据上游协议自动处理
自定义 model provider第三方服务原生、完整地兼容 OpenAI Responses API

是否需要协议转换: 不需要

开始前必须理解一个关键限制:

Codex 自定义 provider 当前使用 OpenAI Responses APIwire_api 唯一支持的值是 responses。如果第三方服务只有 /v1/chat/completions,不能仅把地址写进 config.toml 直接使用,应该通过 CC Switch 或其他协议转换网关接入。

本文适用于运行在本机的 Codex CLI、Codex IDE 扩展以及读取同一套 config.toml 的桌面客户端。Codex 云端会话目前不能通过本文方式切换为自定义模型。

开始之前#

安装或更新 Codex CLI#

bash
npm install -g @openai/codex@latest
codex --version

首次安装后,至少运行一次:

bash
codex

这样可以初始化 Codex 的用户配置目录。

Codex 配置文件位置#

macOS 和 Linux:

text
~/.codex/config.toml

Windows:

text
%USERPROFILE%\.codex\config.toml

修改配置前建议备份。

macOS / Linux:

bash
mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
2>/dev/null || true

PowerShell:

powershell
$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

区分 provider、MCP 和模型网关#

这三个概念解决的问题不同:

  • model_provider:决定 Codex 把模型请求发送到哪里;
  • MCP:给 Codex 增加浏览器、GitHub、数据库等工具与上下文;
  • 模型网关:在 Codex 和模型服务之间完成协议转换、鉴权、路由、日志或限流。

因此,更换 Codex 的底层模型需要配置 provider,不是配置 MCP。

API Key 安全#

不要把真实 API Key 提交到 Git 仓库,也不要把完整密钥放进公开截图、日志或工单。

手动配置 provider 时,优先使用环境变量:

toml
[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch 会在本机保存 provider 配置,并在切换时修改 Codex 的本地配置。它是第三方开源工具,不是 OpenAI 官方产品。应只从 CC Switch 官方网站或官方 GitHub 仓库安装,并保护好本机配置、数据库和备份文件。

---

1. 使用 CC Switch 接入第三方模型#

对于大多数第三方模型,CC Switch 是更容易使用的接入方式。它可以管理 provider、API Key、模型列表和本地路由,并在上游协议不兼容时完成转换。

1.1 CC Switch 解决了什么问题#

新版 Codex 按 Responses API 发送请求,但不少第三方服务提供的是:

  • OpenAI Chat Completions;
  • Anthropic Messages;
  • 非 Codex 默认识别的模型 ID;
  • 厂商自定义的推理参数和流式事件格式。

CC Switch 的本地路由可以把调用链转换为:

text
Codex
│  Responses API
▼
CC Switch 本地路由
│  根据 provider 配置转换协议和模型名称
▼
第三方模型 API
│
▼
CC Switch 将响应、SSE、推理内容和工具调用转换回 Responses 格式
│
▼
Codex

对于原生支持 Responses API 的 provider,CC Switch 可以不做 Chat 协议转换;对于 Chat Completions 或 Anthropic Messages provider,则必须启用本地路由。

1.2 安装 CC Switch#

只从以下官方来源获取安装包:

macOS 推荐使用 Homebrew:

bash
brew install --cask cc-switch

更新:

bash
brew upgrade --cask cc-switch

Windows 可以从 Releases 下载 .msi 安装包或便携版压缩包。

Linux 可以从 Releases 下载 .deb.rpm 或 AppImage。不同版本的界面文字可能略有变化,建议始终使用最新稳定版本,并以应用内实际选项为准。

1.3 准备工作#

接入前准备以下内容:

  1. 已安装并运行过一次 Codex;
  2. 已安装并能够正常启动 CC Switch;
  3. 已获得目标模型服务的 API Key;
  4. 已从供应商文档确认 Base URL、模型 ID 和上游 API 协议;
  5. 如果需要保留 Codex 官方账号能力,先完成一次官方登录。

检查 Codex 登录状态:

bash
codex login status

需要登录时可以运行:

bash
codex login

也可以使用设备码登录:

bash
codex login --device-auth

1.4 可选:切换第三方 provider 时保留官方登录#

这一项主要适用于同时使用 Codex 桌面功能、官方插件或远程控制能力的用户。只使用 CLI 且不依赖官方登录能力时,可以跳过。

推荐顺序:

  1. 在 CC Switch 的 Codex 页面切换到 OpenAI Official
  2. 启动 Codex,并完成官方账号登录;
  3. 在 CC Switch 打开 Settings → General → Codex App Enhancements
  4. 开启 Keep official login when switching third-party providers
  5. 再添加或切换第三方 provider。

开启后,CC Switch 会尽量保持:

  • ~/.codex/auth.json:继续保存官方登录状态;
  • ~/.codex/config.toml:保存当前第三方 provider、模型、地址和认证配置。

auth.json 中包含敏感登录信息,不要复制给他人,也不要提交到版本控制系统。

1.5 添加第三方 provider#

打开 CC Switch,切换到顶部的 Codex 页面,然后点击右上角的添加按钮。

优先使用预设#

如果应用内已经有对应 provider 预设,优先选择预设,只填写 API Key 和必要参数。预设通常会自动配置:

  • Base URL;
  • 默认模型;
  • 上游协议;
  • 是否需要本地路由;
  • 模型映射;
  • 部分推理参数。

CC Switch 的预设列表会随着版本更新。文档中不应长期固定某个厂商的模型 ID,应以应用内列表和供应商官方文档为准。

使用自定义 provider#

预设中没有目标服务时,选择自定义配置,并填写:

字段说明
Provider Name自定义名称,仅用于识别
API Key第三方服务的密钥
Base URL供应商公布的 API 根地址
Model ID上游真实模型 ID,必须完全一致
Upstream Format上游实际使用的协议
Model MappingCodex 中显示和调用的模型列表

最关键的是正确选择 Upstream Format

上游格式何时使用是否需要本地路由
Responses (native)上游原生实现 Responses API通常不需要协议转换
Chat Completions (routing required)上游提供 /chat/completions需要
Anthropic Messages (routing required)上游使用 Anthropic Messages 协议需要

不要因为供应商宣传“兼容 OpenAI API”就默认选择 Responses。很多所谓 OpenAI 兼容接口只兼容 Chat Completions。

1.6 正确填写 Base URL#

默认情况下,CC Switch 会在 Base URL 后拼接对应的 API 路径。因此,通常只填写供应商文档给出的 API 根地址,不要自行重复添加 /chat/completions/responses

例如,供应商要求:

text
POST https://api.example.com/v1/chat/completions

通常填写:

text
https://api.example.com

或者按照预设要求填写:

text
https://api.example.com/v1

具体是否包含 /v1,取决于 CC Switch 预设和供应商文档。保存前应使用 CC Switch 的连接检测或请求日志确认最终请求地址。

只有当供应商要求非标准完整路径时,才使用 CC Switch 的 Full URL Mode,并填写完整 endpoint。

1.7 配置 Needs Local Routing 和模型映射#

当 provider 使用 Chat Completions、Anthropic Messages,或者模型名称不是 Codex 默认模型时,应启用 Needs Local Routing

选择 Chat 类型预设时,CC Switch 通常会自动开启该选项;自定义 provider 需要自行确认。

启用后会出现模型映射配置。常见字段包括:

字段说明
Model ID第三方 API 接收的真实模型名称
Display NameCodex /model 菜单中显示的名称
Context Window可选,模型真实上下文窗口

注意:

  • Model ID 必须与供应商文档完全一致;
  • 不要凭感觉填写上下文窗口;
  • 模型列表变化后需要重启 Codex;
  • CC Switch 会根据映射生成 Codex 使用的模型目录;
  • 如果中转平台修改了模型名称或域名,自动推理能力识别可能不准确,应在高级设置中检查。

1.8 开启本地路由并接管 Codex#

在 CC Switch 中打开:

text
Settings → Routing → Local Routing

完成以下操作:

  1. 开启本地路由总开关;
  2. Routing Enabled 中开启 Codex
  3. 确认目标 provider 的 Needs Local Routing 状态正确;
  4. 使用期间保持 CC Switch 正在运行。

本地路由默认地址通常是:

text
http://127.0.0.1:15721

接管生效后,Codex 的实时配置会指向 CC Switch 本地路由。CC Switch 再根据当前选中的 provider,把请求转发到真正的第三方 API。

如果上游是 Chat Completions,实际过程通常类似:

text
Codex POST /responses
→ CC Switch 转换为 POST /chat/completions
→ 第三方模型返回 JSON 或 SSE
→ CC Switch 转换回 Responses JSON 或 SSE
→ Codex 继续执行工具调用

1.9 切换 provider 并重启 Codex#

返回 CC Switch 的 Codex provider 列表,选中刚刚配置的 provider,然后点击启用。

切换后建议完全退出并重新启动 Codex,原因包括:

  • Codex 在启动时读取 config.toml
  • /model 菜单通常在启动时加载模型目录;
  • IDE 扩展或桌面客户端可能缓存旧 provider;
  • 已存在的会话可能仍保存旧模型信息。

CLI 用户可以重新运行:

bash
codex

1.10 验证是否接入成功#

进入 Codex 后运行:

text
/status

检查当前模型、provider、权限和上下文信息。

查看模型列表:

text
/model

检查配置层级:

text
/debug-config

同时检查:

  • CC Switch 当前选中的 Codex provider;
  • CC Switch 本地路由日志或统计;
  • 第三方平台的请求记录和余额变化;
  • ~/.codex/config.toml 是否暂时指向本地路由。

不要只发送“你好”来验证。至少完成一次智能体能力测试:

  1. 让 Codex 列出当前项目文件;
  2. 让 Codex 读取一个文件并总结内容;
  3. 让 Codex 修改一个小文件;
  4. 让 Codex 运行测试;
  5. 故意保留一个简单错误,观察它能否根据测试结果继续修复。

只有文本对话成功,不代表工具调用和多轮智能体工作流已经兼容。

1.11 切回 OpenAI 官方 provider#

在 CC Switch 中选择 OpenAI Official,然后重启 Codex。

检查登录状态:

bash
codex login status

如果官方登录状态异常,重新执行:

bash
codex login

如果你需要同时保留官方登录和第三方模型请求,检查 Keep official login when switching third-party providers 是否仍然开启。

1.12 CC Switch 的限制与注意事项#

CC Switch 简化了配置,但仍有以下限制:

  • 使用 Chat 或 Messages 协议时,CC Switch 必须持续运行;
  • 协议转换不能保证还原所有供应商特有能力;
  • 某些模型虽然能聊天,但工具调用质量不足;
  • Web Search、图片输入、WebSocket、响应存储等高级功能可能不兼容;
  • 供应商的限流、计费和数据保留政策仍然生效;
  • 中转平台可能再次修改请求或响应;
  • CC Switch、Codex 或供应商升级后,旧配置可能需要重新验证。

CC Switch 更适合本地桌面开发。服务器、CI 或无图形界面的长期自动化任务,优先使用原生 Responses API 或自建协议网关。

---

2. 手动接入第三方在线模型 API#

只有当第三方服务原生支持 Codex 所需的 Responses API 时,才建议直接配置自定义 provider。

如果供应商只提供 /chat/completions 或 Anthropic Messages,请使用第一部分的 CC Switch 流程,不要尝试配置 wire_api = "chat"

2.1 接口需要满足的条件#

一个可以直接接入 Codex 的 provider,至少应支持:

  • POST /responses
  • Responses JSON 结构;
  • Responses SSE 流式事件;
  • function/tool calling;
  • JSON Schema 工具参数;
  • 工具结果回传后的继续推理;
  • 多轮请求或 previous_response_id 等连续对话机制;
  • 足够的上下文窗口和稳定的长请求处理;
  • 清晰的认证、限流和错误响应。

仅支持普通文本生成并不足以稳定运行 Codex 智能体。

2.2 通用配置#

编辑用户级配置:

text
~/.codex/config.toml

添加:

toml
model_provider = "third_party"
model = "provider-model-id"

# 仅在模型明确支持时设置。
model_reasoning_effort = "high"

# 可选:没有官方模型目录时,填写供应商公布的真实值。
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

不要使用以下保留 provider ID:

text
openai
ollama
lmstudio

可以使用 third_partycompany_gateway 或其他自定义 ID。

2.3 配置字段说明#

字段作用
model_provider选择 [model_providers.] 中定义的 provider
model第三方服务接收的真实模型 ID
name显示名称
base_url第三方 Responses API 根地址
env_key保存 API Key 的环境变量名称
wire_api当前只能使用 responses,省略时默认也是 responses
request_max_retries普通 HTTP 请求失败后的重试次数
stream_max_retries流式连接中断后的重试次数
stream_idle_timeout_msSSE 多久没有事件后判定为空闲超时
model_context_window可选,模型的真实上下文窗口
model_reasoning_effort可选,模型支持的推理强度

base_url 是否包含 /v1 必须以供应商文档为准。Codex 会在它后面访问 Responses 路径,常见最终地址是:

text
https://provider.example.com/v1/responses

2.4 设置 API Key#

bash / zsh 当前会话:

bash
export THIRD_PARTY_API_KEY="你的 API Key"

fish:

fish
set -gx THIRD_PARTY_API_KEY "你的 API Key"

PowerShell 当前会话:

powershell
$env:THIRD_PARTY_API_KEY = "你的 API Key"

PowerShell 持久保存到当前用户:

powershell
[Environment]::SetEnvironmentVariable(
"THIRD_PARTY_API_KEY",
"你的 API Key",
[EnvironmentVariableTarget]::User
)

持久设置后,需要重新启动终端、IDE 或桌面客户端。

2.5 先测试 Responses endpoint#

在启动 Codex 前,先直接测试第三方接口:

bash
export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
-H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "provider-model-id",
"input": "Reply with exactly: PROVIDER_OK",
"stream": false
}'

至少检查:

  • endpoint 不是 404;
  • 返回的是 Responses 风格结构,不是只有 choices 的 Chat Completions 结构;
  • 模型 ID 正确;
  • 认证方式正确;
  • 错误响应包含可排查的信息。

随后还应单独测试:

  • stream: true
  • 工具调用;
  • 工具结果回传;
  • 多轮调用;
  • 长上下文;
  • 并发和限流。

2.6 验证 Codex 配置#

严格模式启动:

bash
codex --strict-config

--strict-config 会把不认识的配置项当作错误,适合发现旧教程中的废弃字段。

进入 Codex 后运行:

text
/status

需要检查配置来源时运行:

text
/debug-config

临时覆盖 provider 和模型,不修改默认配置:

bash
codex \
-c 'model_provider="third_party"' \
-m 'provider-model-id'

2.7 模型目录与 Unknown model#

Codex 的模型目录可以描述:

  • 上下文窗口;
  • 支持的推理等级;
  • 输入模态;
  • 工具调用能力;
  • 截断策略;
  • 客户端最低版本。

如果供应商提供 Codex 可用的模型目录文件,保存到本机后配置:

toml
model_catalog_json = "~/.codex/provider-models.json"

如果没有模型目录,可以在确认真实值后设置:

toml
model_context_window = 131072

不要复制另一模型的元数据来消除警告。错误的上下文窗口或工具能力声明,可能导致提前截断、超出限额或工具调用异常。

2.8 完整兼容性检查#

正式使用前,建议逐项验证:

  • /responses 非流式文本;
  • Responses SSE 流式输出;
  • 单个工具调用;
  • 多个并行或连续工具调用;
  • JSON Schema 参数;
  • 工具结果回传;
  • 长上下文与自动压缩;
  • reasoning 参数;
  • 图片或其他输入模态;
  • 速率限制和重试;
  • 代理是否缓冲 SSE;
  • 供应商是否修改或丢弃工具字段;
  • 数据保留、日志和隐私政策。

2.9 provider 配置应放在哪里#

model_providermodel_providers 和 provider 认证配置应放在用户级文件:

text
~/.codex/config.toml

不要把它们放进项目仓库的:

text
<project>/.codex/config.toml

Codex 会忽略项目级配置中可能重定向模型请求或认证信息的相关字段。这可以防止克隆不可信仓库后,请求被项目配置悄悄转发到其他服务器。

---

3. 使用配置档案管理多个第三方 provider#

如果使用 CC Switch,通常直接在图形界面切换 provider 即可,不必再配置 Codex 配置档案(Profile)。

配置档案更适合手动配置多个原生 Responses provider 的用户。可以把 provider 定义放在基础配置中,再用独立配置档案文件选择模型。

基础配置 ~/.codex/config.toml

toml
[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

创建:

text
~/.codex/fast.config.toml

内容:

toml
model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

再创建:

text
~/.codex/quality.config.toml

内容:

toml
model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

启动时选择:

bash
codex --profile fast
codex --profile quality

非交互模式:

bash
codex exec --profile quality "Review the current changes"

配置档案文件位于:

text
$CODEX_HOME/<profile-name>.config.toml

默认 CODEX_HOME~/.codex

较新的 Codex 版本使用独立配置档案文件,不再读取旧式的 [profiles.] 表。如果从旧配置迁移,应把每个配置档案拆分为单独的 .config.toml

---

4. 特殊认证 Header 与高级认证#

4.1 标准 Bearer Token#

大多数第三方服务可以直接使用:

toml
[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex 会从环境变量读取密钥,并使用 provider 要求的 Bearer 认证。

4.2 自定义 API Key Header#

某些平台要求:

text
x-api-key: <key>

可以使用 env_http_headers

toml
model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

右侧的 VENDOR_API_KEY 是环境变量名称,不是真实密钥。

bash
export VENDOR_API_KEY="你的 API Key"

4.3 固定 Header 和查询参数#

添加不敏感的固定 Header:

toml
http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

添加查询参数:

toml
query_params = { "api-version" = "2026-08-01" }

不要把真实密钥直接写进 http_headers

4.4 命令式动态认证#

企业环境中可能需要从系统密钥链、云凭证工具或内部命令获取短期 Token:

toml
[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

认证命令必须把 Token 输出到标准输出,并且不要输出额外日志。

以下认证方式不要混用:

  • [model_providers..auth]
  • env_key
  • experimental_bearer_token
  • requires_openai_auth

4.5 通过代理继续使用 OpenAI 认证#

只有当代理后面仍然访问 OpenAI 模型,并且希望 Codex 使用 OpenAI 官方认证时,才配置:

toml
requires_openai_auth = true

这不适用于普通第三方模型 API Key。开启后,Codex 会忽略该 provider 的 env_key

---

5. 常见错误与排查#

5.1 CC Switch 已切换,但 Codex 仍使用旧模型#

依次检查:

  1. CC Switch 中当前启用的是目标 Codex provider;
  2. 本地路由总开关是否开启;
  3. Routing Enabled 中是否开启 Codex;
  4. Chat 或 Messages provider 是否启用了 Needs Local Routing
  5. CC Switch 是否仍在运行;
  6. 是否完全重启了 Codex、IDE 或桌面客户端;
  7. /debug-config 是否显示了预期配置来源。

模型映射变更后,通常必须重启 Codex 才能刷新 /model 列表。

5.2 返回 404400 或找不到 /responses#

常见原因:

  • 把 Chat Completions provider 当成 Responses provider;
  • Base URL 多写或少写了一层 /v1
  • 重复拼接了 /chat/completions
  • 非标准地址没有开启 Full URL Mode;
  • CC Switch 本地路由没有接管 Codex;
  • 第三方网关没有实现完整 Responses API。

CC Switch 用户应检查 Upstream Format 和路由日志。手动 provider 用户应直接用 curl 测试 /responses

5.3 返回 401 Unauthorized403 Forbidden#

检查:

  • API Key 是否有效;
  • Key 是否属于正确区域、项目或套餐;
  • 余额和权限是否充足;
  • 服务要求 Bearer Token 还是 x-api-key
  • 环境变量名称是否与 env_key 完全一致;
  • CC Switch 中是否保存了正确密钥;
  • 代理是否删除了认证 Header。

检查环境变量时不要在共享日志中打印完整密钥。

bash / zsh:

bash
printenv THIRD_PARTY_API_KEY

PowerShell:

powershell
$env:THIRD_PARTY_API_KEY

5.4 第三方模型没有出现在 /model#

检查:

  • CC Switch 的 Model Mapping 是否包含真实模型 ID;
  • provider 是否已经保存并启用;
  • 是否重启了 Codex;
  • 手动配置是否提供了正确的 model_catalog_json
  • 模型目录 JSON 是否有效;
  • 模型 ID 是否已被供应商下线或重命名。

5.5 可以聊天,但不能读写文件或运行命令#

常见原因:

  • 模型本身不擅长工具调用;
  • 上游不支持 function calling;
  • 中转层丢失了 tool call ID;
  • SSE 分片没有被正确重组;
  • JSON Schema 被修改;
  • 工具结果没有正确回传到下一轮;
  • 模型上下文过短;
  • 模型目录错误声明了能力。

应使用真实项目测试“读取 → 修改 → 运行测试 → 根据失败继续修复”的完整循环。

5.6 流式响应频繁中断#

CC Switch 用户先查看本地路由日志和上游响应。常见原因包括:

  • 上游排队或推理时间过长;
  • 第三方网关没有及时发送 SSE;
  • CDN、反向代理或公司网络缓冲了流;
  • 上游发送了非标准事件;
  • CC Switch 或 provider 版本存在兼容问题。

手动 provider 可以适当增加:

toml
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

增加超时只能缓解网络或长推理问题,不能修复错误的协议实现。

5.7 wire_api = "chat" 无法启动#

这是旧教程中常见的配置。当前 Codex 只支持:

toml
wire_api = "responses"

如果上游只有 Chat Completions,改用 CC Switch,不要继续尝试 wire_api = "chat"

运行以下命令检查其他过时字段:

bash
codex --strict-config

5.8 修改项目内配置后 provider 没有变化#

以下配置必须放在用户级文件中:

text
~/.codex/config.toml

项目内 .codex/config.toml 不能覆盖会重定向请求或改变 provider 认证的字段,包括 model_providermodel_providers

5.9 终端可用,但 IDE 扩展提示缺少 API Key#

GUI 应用通常不会继承刚刚在某个终端中临时设置的环境变量。

可以:

  • 从已经设置变量的终端启动 IDE;
  • 将变量持久保存到系统用户环境;
  • 完全退出并重新打开 IDE;
  • 改用 CC Switch 管理本地 provider 配置。

5.10 切换后官方登录状态或官方功能异常#

检查:

  • 是否先切回 OpenAI Official
  • Keep official login when switching third-party providers 是否开启;
  • ~/.codex/auth.json 是否被旧配置覆盖;
  • codex login status 是否正常。

必要时重新执行:

bash
codex login

不要手动分享或编辑包含 Access Token 的 auth.json

5.11 Web Search、图片或其他高级功能不可用#

第三方 provider 能完成文本和工具调用,不代表支持 Codex 的全部能力。

自定义 provider 默认不会声明 standalone Web Search。只有 provider、模型和 endpoint 都真实兼容时,才应配置:

toml
supports_standalone_web_search = true

错误开启只会让 Codex发送上游无法处理的请求。图片输入、WebSocket、响应存储和其他高级能力也应分别验证。

---

6. 如何选择接入方式#

需求推荐方式
第三方只提供 Chat CompletionsCC Switch
第三方只提供 Anthropic MessagesCC Switch
经常在多个第三方模型之间切换CC Switch
希望用图形界面管理 API Key 和模型CC Switch
第三方原生支持完整 Responses API自定义 model provider
服务器、CI 或无图形界面环境原生 Responses provider 或自建网关
企业需要统一鉴权、审计和限流企业模型网关 + 自定义 provider
只完成普通聊天、不支持工具调用不适合作为完整的 Codex 智能体 provider

推荐按三个层级验收:

  1. 连接测试:可以稳定返回文本;
  2. 工具测试:可以读取文件、调用命令并正确回传结果;
  3. 任务测试:可以连续完成修改、测试和修复。

最后还要确认:

  • 第三方计费方式;
  • 速率限制;
  • 请求和代码是否被记录;
  • 数据保存地区;
  • 团队或企业合规要求;
  • 模型升级后是否需要重新测试。

使用第三方 API Key 时,费用由第三方服务或中转平台单独结算,不会自动使用或共享 ChatGPT Plus、Pro 或 Codex 订阅中的额度。

参考资料#

本站实践建议#

阅读“Codex 接入外部模型”时,建议先在非生产项目中走完一次完整流程,并记录实际界面、命令输出和验证结果。产品更新后,可据此快速判断哪些步骤需要调整。

Codex API 与国内使用#

在实践“Codex 接入外部模型”相关功能时,如需为 Codex 配置 OpenAI-compatible API,可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。