Codex CLI 国内怎么用？API Key 中转配置教程（2026）

云雾API · 教程 · 更新于 2026-09-29

先给直接答案：Codex CLI 国内能用吗？ 能用，卡住大家的通常不是工具本身，而是账号和网络：默认要用 ChatGPT 账号或 OpenAI API Key 登录，安装脚本和登录流程也要访问境外域名。Codex CLI 本身支持自定义模型提供方（model provider），在 ~/.codex/config.toml 里写好 base_url、env_key、wire_api 三个字段，再把 API Key 放进环境变量，就能改走一个国内网络可用、兼容 OpenAI 接口的中转服务，不需要 ChatGPT 登录。要注意一点：Codex 现在只支持 Responses API，中转服务和你选的模型都必须支持这个接口，只兼容 Chat Completions 的站点接不上。

Key Takeaways（30 秒速读）

安装：npm install -g @openai/codex 或 brew install --cask codex；Windows 现在有原生安装方式，WSL2 是可选路线，WSL1 已不再支持。

接第三方中转不用 codex login：在 ~/.codex/config.toml 里定义 [model_providers.xxx]，用 env_key 指定存放 Key 的环境变量名。

wire_api 只能填 "responses"，旧教程里的 "chat" 已被移除，写了会直接报错。

base_url 要带 /v1（例如 https://v2.cloudmist.cloud/v1），Codex 会自己在后面拼 /responses。

模型只能选中转方标注支持 Responses 接口的，例如 gpt-5-codex、gpt-5.3-codex、gpt-6-sol；别把 Chat 专用模型填进去。

一、Codex CLI 是什么？国内使用卡在哪
二、Codex CLI 安装：npm、Homebrew 与 Windows/WSL
三、ChatGPT 登录与 API Key：接中转该选哪种
四、Codex CLI 配置：config.toml 接入中转 API
五、Codex CLI API Key 环境变量：Mac/Linux/Windows 写法
六、Codex 中转可用哪些模型：只选支持 Responses 的
七、验证是否接通，并用 profile 切换多套配置
八、常见报错排查：401、模型不存在、400/404、流式中断
九、用第三方中转前要知道的局限与风险
FAQ 常见问题
结论

一、Codex CLI 是什么？国内使用卡在哪

Codex CLI 是 OpenAI 开源的命令行编程智能体（仓库 openai/codex，Apache-2.0 协议），在你自己的电脑上运行：读代码、改文件、跑测试和命令，还能用 codex exec 放进脚本或 CI 里。和网页版 Codex 不同，CLI 的执行都在本地，模型推理则通过网络请求完成。

国内开发者用它，常见的卡点有三个：

账号与付费：按 OpenAI 的认证文档，Codex 默认有两种登录方式，一种是 ChatGPT 订阅账号，另一种是 OpenAI Platform 的 API Key（按标准 API 价格计费）。中国大陆不在 OpenAI API 支持的国家和地区列表里，开通账号、绑外币卡都不方便。
网络：安装脚本托管在 chatgpt.com，ChatGPT 登录要在浏览器里完成 OAuth 回调，这些境外域名在国内访问经常不稳定。
接口协议：不少人从旧教程抄来一段 wire_api = "chat" 的配置，结果一启动就报错。原因是 Codex 已经不再支持 Chat Completions，这一点第四节细讲。

好在 Codex 支持自定义模型提供方：base_url 换成任意兼容 OpenAI Responses 接口的服务，再配一个对应的 API Key，就可以绕开 ChatGPT 登录。下面以本站（云雾API）为例演示；换成别的兼容服务，步骤完全一样。

二、Codex CLI 安装：npm、Homebrew 与 Windows/WSL

按 Codex CLI 文档和仓库 README，目前有四种安装方式，任选一种即可。

方式 1：npm（国内最推荐）

npm install -g @openai/codex

npm 包要求 Node.js 16 或更高版本。各平台的二进制文件也以 npm 包的形式发布，所以默认源下载慢的话，可以临时换国内镜像。本文撰写时查询过，npmmirror 上已经同步了 @openai/codex 和各平台二进制包：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

升级也是同一条命令。

方式 2：Homebrew（macOS）

brew install --cask codex
# 升级
brew upgrade --cask codex

Codex 在 Homebrew 上是以 cask 形式发布的，仓库 README 给的写法就是 brew install --cask codex。

方式 3：OpenAI 提供的安装脚本（macOS / Linux）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

README 里说明，脚本默认从 releases.openai.com 下载，失败时会回退到 GitHub Releases。国内网络访问这几个域名不一定顺畅，所以更推荐用 npm。

方式 4：Windows 原生与 WSL

Windows 现在有原生安装方式，并且带原生沙箱：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

在 Windows 上用 npm install -g @openai/codex 也可以，npm 包里包含 win32 平台的二进制。至于要不要用 WSL，WSL 文档的说法是：需要 Linux 原生工具链、仓库本来就放在 WSL2 里，或者两种原生沙箱模式都跑不起来时，再选 WSL2。另外，WSL1 从 Codex 0.115 起不再支持，用 WSL 就必须是 WSL2。如果走 WSL，建议把代码放在 Linux 家目录（如 ~/code）下，不要放在 /mnt/c，文档的说法是这样读写更快，符号链接和权限问题也更少。

装完用下面的命令确认版本：

codex --version

三、ChatGPT 登录与 API Key：接中转该选哪种

先把 Codex 的几种认证方式理清楚，后面配置就不会乱：

方式	怎么做	计费	适合谁
ChatGPT 登录	运行 `codex login`，在浏览器里完成登录；无浏览器环境用 `codex login --device-auth`	用 ChatGPT 套餐（Plus / Pro / Business 等）包含的额度	已有 ChatGPT 付费订阅的用户
OpenAI API Key	`codex login --with-api-key`，从标准输入读入 Key（完整命令见表下）	走 OpenAI Platform 账户，按标准 API 价格计费	有 OpenAI Platform 账户的开发者
自定义提供方 + `env_key`	在 config.toml 里定义提供方，Key 放在环境变量里	由你接入的服务商计费	接第三方中转、本地模型

认证文档给出的 API Key 登录写法如下：

printenv OPENAI_API_KEY | codex login --with-api-key

前两种登录方式的凭据会缓存在 ~/.codex/auth.json 或系统凭据库里，可以用 codex login status 查看当前是哪种方式，用 codex logout 清除。

接第三方中转，用第三种。 Codex 源码里对这个开关的说明是：自定义提供方的 requires_openai_auth 默认为 false，这时会跳过登录界面，直接从 env_key 指定的环境变量里读取 API Key。所以接中转不需要运行 codex login。

这里有两个坑一定要避开：

不要给第三方提供方设 requires_openai_auth = true。 按认证文档，打开它之后 Codex 会用你的 OpenAI 登录凭据（ChatGPT 或 OpenAI API Key）去请求这个提供方，同时忽略 env_key。对第三方来说，这等于把你的 OpenAI 凭据交给对方。
不要用 openai_base_url 把内置的 openai 提供方直接指到第三方。 按源码逻辑，内置提供方会带上你已登录的 OpenAI 凭据发请求。如果你之前用 ChatGPT 账号或 OpenAI API Key 登录过，改了地址以后，这份凭据可能随请求发到新地址。单独定义一个提供方，两套配置互不干扰，更干净。

四、Codex CLI 配置：config.toml 接入中转 API

配置文件位置：macOS / Linux 是 ~/.codex/config.toml，Windows 原生对应用户目录下的 .codex\config.toml，没有就新建。设置了环境变量 CODEX_HOME 的话，以它指向的目录为准。

第 1 步：准备 API Key。 在本站注册并登录，到控制台「令牌」页创建一个 sk- 开头的令牌。注册和使用都在新系统 v2.cloudmist.cloud，注册后控制台显示为「云岚API」，这是本站的新系统，不用担心走错站。新手流程可以参考站内的《新手上手教程》。

第 2 步：写入 config.toml。 下面这份可以直接复制：

# ~/.codex/config.toml
# 注意:顶层键(model、model_provider)必须写在所有 [表] 之前
model = "gpt-5-codex"
model_provider = "cloudmist"

[model_providers.cloudmist]
name = "cloudmist"
base_url = "https://v2.cloudmist.cloud/v1"
env_key = "CLOUDMIST_API_KEY"
wire_api = "responses"

逐个字段解释（字段含义以 Codex 配置参考和进阶配置文档为准）：

model：默认使用的模型名，必须是中转方真实提供、并且支持 Responses 接口的模型，见第六节。
model_provider：要启用的提供方 ID，对应下面 [model_providers.cloudmist] 里的 cloudmist。ID 可以随便起，但 openai、ollama、lmstudio 是内置保留 ID，不能用。
name：显示名称，随意填。
base_url：接口根地址。Codex 请求时会在它后面拼上 /responses，所以这里要写到 /v1 为止，最终请求地址就是 https://v2.cloudmist.cloud/v1/responses。base_url 带不带 /v1 的通用规则，可以看站内《base_url 配置说明》。
env_key：存放 Key 的环境变量名，不是 Key 本身。不要把 sk- 明文写在这里。
wire_api：接口协议。配置参考里写明 responses 是唯一支持的取值，省略时也默认用它。写成 "chat" 会直接报错，报错原文见第八节。

可选：网络不稳时调这几个参数。 下面三项都写在 [model_providers.cloudmist] 表里，括号里是官方文档给出的默认值：

# 以下三行加在 [model_providers.cloudmist] 表内
request_max_retries = 4          # HTTP 请求失败重试次数(默认 4)
stream_max_retries = 5           # 流式中断后重连次数(默认 5)
stream_idle_timeout_ms = 300000  # 流式响应空闲超时,毫秒(默认 300000)

推理强度也可以在顶层设置，比如 model_reasoning_effort = "medium"，具体能选哪些档位取决于模型本身。

两个容易踩的坑：

TOML 的表作用域。 写在 [model_providers.cloudmist] 下面的键都归这个表管。如果把 model = ... 写到了表的下面，它就不再是顶层配置，Codex 读不到你指定的默认模型。
不要写在项目里的 .codex/config.toml。 配置参考明确说明，项目级配置文件里的 model_provider、model_providers、openai_base_url 会被忽略，这类键只能放在用户级的 ~/.codex/config.toml 里。

临时想换模型或提供方，也可以不改文件，直接在命令行覆盖：

codex -m gpt-5.3-codex
codex -c model_provider=cloudmist -m gpt-5-codex

五、Codex CLI API Key 环境变量：Mac/Linux/Windows 写法

env_key 写的是 CLOUDMIST_API_KEY，下面就把令牌放进同名环境变量里。各系统写法如下：

系统	当前终端临时生效	永久生效
macOS（zsh）	`export CLOUDMIST_API_KEY="sk-..."`	追加到 `~/.zshrc`
Linux / WSL（bash）	`export CLOUDMIST_API_KEY="sk-..."`	追加到 `~/.bashrc`
Windows PowerShell	`$env:CLOUDMIST_API_KEY = "sk-..."`	`setx CLOUDMIST_API_KEY "sk-..."`，然后重开终端

macOS：

echo 'export CLOUDMIST_API_KEY="sk-你的令牌"' >> ~/.zshrc
source ~/.zshrc
echo $CLOUDMIST_API_KEY   # 能打印出令牌说明已生效

Linux / WSL：

echo 'export CLOUDMIST_API_KEY="sk-你的令牌"' >> ~/.bashrc
source ~/.bashrc

WSL 是独立的 Linux 环境，要在 WSL 里面设置。Windows 侧设置的环境变量默认不会带进 WSL。

Windows PowerShell：

# 永久写入当前用户环境变量(新开的终端才生效)
setx CLOUDMIST_API_KEY "sk-你的令牌"

# 只对当前窗口生效
$env:CLOUDMIST_API_KEY = "sk-你的令牌"

如果启动 Codex 时看到下面这行，说明启动 Codex 的那个终端里读不到这个变量：

Missing environment variable: `CLOUDMIST_API_KEY`.

最常见的原因是用 setx 写入之后没有重开终端，或者 IDE 内置终端在你改完变量之前就已经打开了。关掉重开一次即可。

安全方面，配置参考里有一个 experimental_bearer_token 字段，可以把 Key 直接写进配置文件，但文档明确不推荐这样做，应该优先用 env_key。另外，.zshrc、auth.json 这类文件都不要提交到 Git。

六、Codex 中转可用哪些模型：只选支持 Responses 的

Codex 已经移除了 Chat Completions 支持。维护者在 GitHub 讨论 #7782 里宣布了弃用计划，完全移除定在 2026 年 2 月初；现在的配置参考和源码里，wire_api 都只接受 responses。所以在 Codex 里能用哪个模型，取决于中转方有没有为它开放 Responses 接口。

本站新系统的「模型广场」页面会列出每个模型的可用端点类型，也可以按端点类型筛选。下表列出其中标注支持 Responses 接口、适合写代码的一部分，数据是 2026-09-29 查询所得。模型名和参考价也可以看站内的模型价格总表，实际能用哪些以控制台为准。拿不准某个模型能不能用时，用第七节的 curl 按 Responses 格式请求一次就能确认。

模型名（config.toml 里直接填）	说明
`gpt-6-sol`	OpenAI 的 Codex 模型文档推荐用于复杂编码和 Agent 工作流
`gpt-6-luna`	OpenAI 的 Codex 模型文档推荐用于目标明确、可重复的任务
`gpt-6-astra`	OpenAI 称其为能力最强的型号，适合最难的端到端任务
`gpt-5-codex`	针对 Codex 编程场景优化的 GPT-5 版本；本站只开放 Responses 接口
`gpt-5.1-codex` / `gpt-5.2-codex` / `gpt-5.3-codex`	codex 系列的后续版本
`gpt-5.5` / `gpt-5.4` / `gpt-5.4-mini`	通用 GPT 模型，同样支持 Responses
`o3` / `o4-mini`	推理模型

选型时有三点值得了解：

ChatGPT 登录和 API 调用的退役时间不一样。 OpenAI 的模型文档写明，gpt-5.4、gpt-5.4-mini 已在 2026-08-31 从 ChatGPT 登录版 Codex 下线，gpt-5.5 将在 2026-10-14 下线，同时注明 OpenAI API 和用自有 API Key 的 Codex 不受 GPT-5.4 退役影响；gpt-5.3-codex 在 ChatGPT 登录版 Codex 里也已标为弃用。通过第三方中转时，模型还能不能用以中转方的清单为准，所以旧模型名随时可能下架。
Claude、Gemini 这类模型走不了 Codex。 在本站，它们开放的是 OpenAI 兼容的 Chat Completions 接口和各自的原生接口，没有 Responses 接口。想在终端里用 Claude 写代码，请用 Claude Code，配置方法见《Claude Code 国内接入教程》。
不确定时先查价格页。 模型名要一字不差地复制，大小写、点号和横杠都不能错。单个模型的介绍页可以参考gpt-5.5 模型页和o3 模型页。

七、验证是否接通，并用 profile 切换多套配置

先绕开 Codex，用 curl 直接测一下 Responses 接口：

curl https://v2.cloudmist.cloud/v1/responses \
  -H "Authorization: Bearer $CLOUDMIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5-codex","input":"ping"}'

能返回带 output 字段的 JSON，就说明 Key、地址、模型名都没问题。如果这一步就报错，按第八节排查，先不用动 Codex 的配置。Windows 用户建议在 WSL 或 Git Bash 里跑这条命令，PowerShell 的续行符和引号规则跟 bash 不一样。

再在 Codex 里验证：

# 先 cd 到你的项目目录再运行
codex exec "用一句话说明这个目录是什么项目"

codex exec 是非交互模式，跑完就退出，很适合做连通性测试。它默认要求在 Git 仓库里运行，如果当前目录不是 Git 仓库，加上 --skip-git-repo-check 参数。进入交互界面（直接运行 codex）后，输入 /status 可以看到当前会话的模型、审批策略和 token 用量，输入 /model 可以切换模型。

新版本还有一个 codex doctor 子命令，用来诊断本地的安装、配置和认证状态，配置不生效时可以先跑一下。

多套配置切换（profile）： 如果你既有 ChatGPT 订阅，又想按需切到中转，可以用 profile。注意新旧写法的区别：进阶配置文档写明，从 Codex 0.134.0 起，--profile 不再读取 config.toml 里的 [profiles.名字] 表，顶层的 profile = "名字" 也不再支持；现在的做法是每个 profile 单独一个文件。

# ~/.codex/config.toml —— 主配置:保持默认(ChatGPT 登录),只定义提供方
[model_providers.cloudmist]
name = "cloudmist"
base_url = "https://v2.cloudmist.cloud/v1"
env_key = "CLOUDMIST_API_KEY"
wire_api = "responses"

# ~/.codex/cloudmist.config.toml —— profile 文件:用顶层键,不要再套 [profiles.xxx]
model = "gpt-5-codex"
model_provider = "cloudmist"

codex                        # 默认配置
codex --profile cloudmist    # 切到中转
codex exec -p cloudmist "review 当前改动"

在主配置里只「定义」提供方，并不会启用它。只有 profile 里的 model_provider 才决定这一次用哪个，所以两套配置可以长期并存。

八、常见报错排查：401、模型不存在、400/404、流式中断

排查顺序建议固定成：先跑第七节的 curl，再看 Codex。curl 能通，问题就在 Codex 配置；curl 也不通，问题在 Key、地址或模型名。更通用的报错手册见站内《常见报错排查》。

1. 401 / 无效令牌

先确认启动 Codex 的终端里 echo $CLOUDMIST_API_KEY 能打印出完整的 sk- 令牌，注意有没有多复制空格或换行。
确认令牌是在新系统 v2.cloudmist.cloud 签发的。老系统的令牌和新系统不通用，拿老令牌请求新地址，同样会报无效令牌。
到控制台「令牌」页确认这个令牌没有被禁用或删除，额度上限也没有用完。
新系统对连续使用无效令牌的请求会临时限流：返回 429，提示等一段时间再试。遇到这种情况，先把 Key 改对，等一会儿再测，不要反复重试。

2. 模型不存在 / 无可用渠道

模型名拼错最常见，直接从价格页复制。
模型本身不支持 Responses 接口。比如你想用的某个模型只开放了 Chat 接口，在 Codex 里就调不通，换第六节表里的模型。
令牌分组不包含这个模型。新系统的令牌带有「令牌分组」，不同分组能调用的模型不同，比如 gpt-5-codex 只在部分分组下可用。可以在「模型广场」查看模型的可用分组，再确认令牌的分组包含它；不包含就换一个分组新建令牌。

3. 400 / 404：多半是协议或地址不对

如果 config.toml 里还留着旧写法 wire_api = "chat"，Codex 启动时会直接报这段错（源码原文）：

`wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.
More info: https://github.com/openai/codex/discussions/7782

改成 wire_api = "responses" 或整行删掉即可。base_url 拼错是另一类常见问题，报错不一定是 404：

多写了路径，比如写成 .../v1/responses 或 .../v1/chat/completions，Codex 再拼一次 /responses，本站会返回 404，错误信息里带 Invalid URL；
少了 /v1，请求会打到 https://v2.cloudmist.cloud/responses。这个地址在本站返回的是网页而不是接口数据，Codex 那边看到的可能是解析失败或流式中断，而不是 404；
域名写成了别的站。

400 的可能原因有两个：选的模型或通道不支持 Codex 请求里的某些参数，或者模型本身不支持 Responses 接口。可以先换成表里的 codex 系列模型交叉验证。

4. 流式中断 / 超时

Codex 的流式输出断开时，报错以 stream disconnected before completion: 开头。它会按 stream_max_retries（默认 5 次）自动重连，全部失败才会报出来。遇到这种情况可以这样处理：

在提供方配置里适当调大 stream_max_retries 和 stream_idle_timeout_ms（第四节有写法）；
本机开了全局代理的话，把 v2.cloudmist.cloud 设成直连再试，少一层转发，也少一个不稳定因素；
长任务、推理强度高的请求本来就慢，可以先把 model_reasoning_effort 调低，看是不是超时导致的。

如果看到 exceeded retry limit, last status: ...，说明重试次数已经用完，后面跟的状态码就是最后一次失败的原因。另外从源码看，HTTP 请求层面的自动重试覆盖 5xx 和网络错误，默认不包括 429。碰到 429 就等一会儿，或者到控制台看看令牌额度。

九、用第三方中转前要知道的局限与风险

接第三方中转之前，下面几点要心里有数：

数据会经过中转方的服务器。 你发给模型的代码、文件内容都要先到中转服务，再转给上游。涉及商业机密或密钥的仓库，要先评估能不能接受，存放密钥的文件最好不要放在 Codex 的工作目录里。
部分功能依赖 ChatGPT 登录。 认证文档写明 Codex cloud 必须用 ChatGPT 登录，用 API Key 时一些依赖 ChatGPT 工作区或云服务的功能会受限。接第三方提供方时，Codex cloud 这类依赖 ChatGPT 账号的功能同样用不了。
模型清单会变。 上游模型会升级、改名、下线，中转方的清单也会跟着调整。长期用的脚本里不要写死一个旧模型名，定期对照价格页检查一下。
Agent 模式很耗 token。 Codex 会反复读文件、跑命令、带着上下文多轮推理，一次任务的 token 消耗远高于普通对话。建议在「令牌」页给 Codex 专用令牌设额度上限，按量计费的原理可以看《token 计费说明》。
合规自查。 请确认你的使用方式符合所在地法规和上游服务条款。第三方中转服务与 OpenAI 没有隶属关系。

FAQ 常见问题

Q1：Codex CLI 国内能直接用吗？
工具本身可以用 npm 安装。默认的 ChatGPT 登录和 OpenAI API Key 对国内用户门槛较高，更常见的做法是在 ~/.codex/config.toml 里自定义提供方，接入国内网络可用、支持 Responses 接口的服务，这样不需要 ChatGPT 登录。

Q2：Codex CLI 一定要有 ChatGPT 账号吗？
不一定。使用自定义提供方且 requires_openai_auth 保持默认 false 时，Codex 会跳过登录界面，直接从 env_key 指定的环境变量读取 API Key。

Q3：wire_api 填 chat 还是 responses？
只能填 responses，省略也默认是它。Codex 已移除 Chat Completions 支持（维护者公告的移除时间是 2026 年 2 月初），写 chat 会在启动时直接报错。

Q4：Codex 能接 Claude、Gemini、DeepSeek 吗？
取决于中转方有没有为这些模型开放 Responses 接口。在本站，Claude、Gemini 开放的是 Chat Completions 和各自的原生接口，没有 Responses 接口，不适用于 Codex。能在 Codex 里用的主要是 GPT 系列和 o 系列，比如 gpt-5-codex、gpt-6-sol、o3。写代码想用 Claude，请用 Claude Code。

Q5：config.toml 可以放在项目目录里吗？
普通配置可以放在项目的 .codex/config.toml 里（项目被标记为受信任后才会加载），但 model_provider、model_providers 这类提供方配置在项目级文件里会被忽略，必须写在用户目录的 ~/.codex/config.toml。

Q6：照旧教程写了 [profiles.xxx]，为什么不生效？
从 Codex 0.134.0 起，profile 改成了独立文件 ~/.codex/名字.config.toml，文件里直接写顶层键，再用 codex --profile 名字 启用。旧的 [profiles.xxx] 表不再被读取。

Q7：用中转跑 Codex 怎么计费？
按实际 token 用量扣费，不同模型单价不同。本站支持人民币充值，价格以充值页实时显示为准。Codex 单次任务的消耗可能比较大，建议先用小任务看看控制台日志里的实际扣费。

结论

Codex CLI 在国内用，关键在三件事：用 npm 装、别走 ChatGPT 登录、在 config.toml 里自定义一个支持 Responses 接口的提供方。配置本身只有几行：model_provider 指向你定义的提供方，base_url 写到 /v1，env_key 填环境变量名，wire_api 固定写 responses，模型选中转方标注支持 Responses 的那些。出了问题先用 curl 测接口，再查 Codex 配置，大部分报错都能很快定位。

如果你想按上面的配置直接接入，可以在本站注册后到「令牌」页创建 Key（控制台显示为「云岚API」），一个 Key 可调用 200+ 模型，其中支持 Responses 接口的 GPT 与 codex 系列可用于 Codex。支持人民币充值，价格以充值页实时显示为准：👉 注册并创建 API Key。