国内如何使用Codex?Codex 的官方入口是 developers.openai.com/codex,核心命令就是终端里敲一个 codex。但国内用户的真正障碍不在安装——Codex CLI 本体是 Apache-2.0 许可的开源项目,npm 上直接可装——而在"模型从哪来":OpenAI 的支持地区名单不含中国大陆、中国香港和中国澳门,两条官方认证路径在国内都走不通,必须换成国内云平台端点或本地模型。
国内用Codex卡在哪:装得上,认证走不通
Codex CLI 是 OpenAI 推出的终端编程 Agent,用 Rust 编写,读取并修改当前目录的代码库、在沙箱策略下执行 Shell 命令、通过 MCP 协议对接外部工具,也可以非交互地接进 CI 流水线。它在 GitHub 上开源,仓库与 npm 包 @openai/codex 的许可均为 Apache-2.0。
开源这一点很关键:安装环节本身不校验 OpenAI 账号。npm、Homebrew、GitHub Releases 三条渠道都能装,装完也有 codex --version 可以验证。
卡点在认证。Codex 官方给出的登录方式是"Sign in with ChatGPT"和"OpenAI API Key"两条,而这两条都要求你先拥有一个 OpenAI 账号。据 OpenAI 帮助中心《为什么我会因为"国家/地区不受支持"而无法注册?》与 API 平台《Supported countries and territories》两份官方页面,中国大陆、中国香港、中国澳门均不在支持名单内;平台侧原文还明确警告:从名单以外的地区访问或提供访问,可能导致账号被封锁或暂停。
所以"能不能装"和"能不能用"是两个问题。国内使用的正确问法不是"怎么注册账号",而是"把 Codex CLI 接到哪个模型端点上"。
Codex的三种形态,可用性不一样
Codex 现在是一组产品,是否能在国内换成第三方模型,取决于它跑在哪:
| | |
|---|
| 本地终端(macOS / Linux / Windows 原生或 WSL2) | |
| 本地编辑器插件(VS Code、Cursor、Windsurf 等) | |
| OpenAI 托管(chatgpt.com/codex) | |
| | |
一句话判据:在你自己机器上跑、并且会读取你那份本地配置文件的形态,才可能换模型;跑在 OpenAI 云上的形态,换不了。
三条接入路径,先选路再配模型
国内可用的路子归纳起来只有三条,共同要求也只有一个:端点必须支持 OpenAI 的 Responses API(原因见后文 wire_api 一节)。
| | |
|---|
| 启动时加 --oss,配合 Ollama 或 LM Studio 在本机跑模型 | 零账号、零费用、代码不出本机;适合对数据最敏感的场景 |
| 阿里云百炼或火山引擎方舟的 API Key,两家官方文档都已给出 Codex 配置模板 | |
| 用 vLLM、SGLang 等框架把模型暴露成 OpenAI 兼容端点 | |
路径 A 的启动方式最简单,官方 CLI 参考页给出的写法是 codex --oss,可用 --local-provider 在 LM Studio 与 Ollama 之间指定,也可以设 oss_provider 作为默认值。代价是本地模型在长链路多文件改写上的稳定性通常弱于前沿模型,官方也建议本地模型配 64K 以上的上下文窗口。
配置只能写在用户级目录
这是国内配置 Codex 最容易踩、也最难自己查出来的一处。官方《Config basics》给出的配置层级与优先级是:命令行参数 → 项目级配置 .codex/config.toml(从项目根到当前目录,就近优先,且仅在你信任该项目时加载)→ --profile 指定的 profile 文件 → 用户级配置 ~/.codex/config.toml → 云端托管默认值 → 系统级 /etc/codex/config.toml → 内置默认值。
真正要注意的是官方紧随其后的一条限制:项目级 .codex/config.toml 会忽略若干"会改变凭据走向"的键,并在启动时打印警告,其中就包含 openai_base_url、chatgpt_base_url、model_provider、model_providers、profile、profiles、notify、otel。换句话说:换模型端点的配置只有写在用户级 ~/.codex/config.toml 才生效。写进项目配置不会报错,只会静默不生效——这是排查半天找不到原因的典型场景。
一份最小可用的自定义 provider 配置长这样:
密钥不写进配置文件,而是通过 env_key 指定的环境变量注入。阿里云百炼官方文档用的变量名就是 OPENAI_API_KEY,因此终端里设置 export OPENAI_API_KEY="你的平台密钥" 即可;想让配置长期生效,把这一行写进 ~/.zshrc 或 ~/.bash_profile。
另外两个官方限制也值得记住:自定义 provider 不能复用 openai、ollama、lmstudio 这三个保留 ID;如果要改内置 OpenAI provider 的地址,应该用顶层 openai_base_url,而不是新建 [model_providers.openai]。
如果用的是平台自定义模型名(例如带预览后缀的型号),还需要一个模型元数据文件 ~/.codex/model-catalog.local.json,告诉 Codex 这个模型的上下文窗口、推理档位、是否支持图片输入等参数,并在配置里用 model_catalog_json 指向它。阿里云百炼官方文档给了完整示例,不配的话常见表现是上下文长度识别不准。
国内可用的模型端点与清单
国内两家主流云平台都已经把 Codex 接入写进了官方文档,配置模板可以直接抄。
阿里云百炼(官方文档 help.aliyun.com/zh/model-studio/codex)提供三种计费方案:Token Plan 个人版、Token Plan 团队版、Coding Plan,以及按量计费。其中支持 Responses API、因此可以用最新版 Codex 的模型包括 qwen3.8-max-preview、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.6-flash;只支持 Chat/Completions 接口的模型(如 glm-5)官方给出的做法是把 Codex 降级安装到 0.80.0。
火山引擎方舟(官方文档 docs.volcengine.com/docs/82379)同样支持把 Codex CLI 接到 Coding Plan 或 Agent Plan 上,官方明确 Agent Plan 与 Coding Plan 均支持 Responses API、可用最新版 Codex CLI,并且提供了 ArkCLI Helper 辅助工具自动完成配置。
| | |
|---|
| https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3.7-max、qwen3.6-plus 等 |
| https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 | qwen3.8-max-preview、qwen3.7-max、qwen3.7-plus、qwen3.6-flash 等 |
| https://coding.dashscope.aliyuncs.com/v1 | qwen3.7-plus 等(仅 Chat/Completions,需降级 Codex) |
火山引擎方舟 · Coding Plan / Agent Plan | https://ark.cn-beijing.volces.com/api/coding/v3 | doubao-seed 系列、glm-5.3、glm-5.3-flash、deepseek-v4-flash、deepseek-v4-pro、minimax-m3、kimi-k2.7-code 等 |
| https://ark.cn-beijing.volces.com/api/v3 | |
火山方舟官方有一处提醒必须照做:接入 Coding Plan 时不要使用 https://ark.cn-beijing.volces.com/api/v3,那个地址不消耗 Coding Plan 额度,会产生额外费用。另外,方舟的 Model Name 也可以不直接写模型名,而配成 ark-code-latest,改由控制台切换模型(切换后 3 到 5 分钟生效,控制台侧还支持 Auto 自动选模型)。
还有一条口径必须记住:同一平台不同计费方案的密钥互不相通。阿里云百炼官方 FAQ 明确写了 Token Plan 团队版、Coding Plan 与按量计费的 API Key 互不相通,用错会在启动时直接报 401。
wire_api是硬门槛:chat已不被支持
自定义 provider 时,wire_api 决定 Codex 用哪种协议与后端通信。官方《Advanced Configuration》里所有自定义 provider 示例——代理、Azure、数据驻留——无一例外都写 wire_api = "responses"。
阿里云百炼官方 FAQ 里有一条报错直接印证了这一点:"报错 wire_api = chat is no longer supported",官方给出的原因是"Codex 新版本使用 Responses API,不支持 wire_api = "chat" 配置"。
实践后果很直接:只暴露 /v1/chat/completions 的端点,接新版 Codex 会直接失败。可选做法有两个——换一个真正支持 Responses 的端点(或自己加一层协议转换代理),或者按官方云文档的做法把 Codex 降级到 0.80.0 并保留 wire_api = "chat",代价是失去后续大半年的功能更新。
5个常见报错与原因
| | |
|---|
| 用错了方案的密钥、订阅已过期,或密钥复制不完整带空格 | 核对是否为所选方案的专属密钥;仍失败就到对应管理页重置密钥 |
| base_url 写错,常见于把 Coding Plan 地址与按量计费地址混用 | 按所选方案逐字核对端点,注意结尾路径是否需要 /v1 |
wire_api = chat is no longer supported | 新版 Codex 已不再支持 Chat/Completions 协议 | 把 wire_api 改成 responses 并确认端点支持;或按官方说明降级到 0.80.0 |
json: unknown field "client_metadata" | 火山方舟要求请求头携带指定的 User-Agent,客户端未带 | 升级 Codex 到带正确 UA 的版本;或把该 UA 在方舟侧加入白名单 |
第三方工具提示"不支持国内模型"或 400 检查被拒 | 部分管理工具切换供应商前会先发"健康检查"探测请求,格式与 Codex 真实请求不同,被网关拒绝 | 这只是探测失败,不代表模型不能用;直接在 ~/.codex/config.toml 里配好再启动即可 |
安装这一步:换镜像比找路子管用
官方主推的安装方式是独立安装脚本:macOS 与 Linux 用 curl -fsSL https://chatgpt.com/codex/install.sh | sh,Windows 用 irm https://chatgpt.com/codex/install.ps1 | iex。这个域名在国内无法访问,所以国内更实用的是 npm 渠道 + 国内镜像:先执行 npm config set registry https://registry.npmmirror.com,再执行 npm install -g @openai/codex。
本次核查实测(2026-09-11):国内镜像源上 @openai/codex 的 latest 版本与官方源完全一致,均为 0.154.0(官方 Changelog 显示该版本发布于 2026-09-09),说明镜像同步正常,不需要额外找安装渠道。所谓"最新版 Codex 不支持 chat 协议"这一变化,也正是 0.154.0 这一代版本的现状。
| | |
|---|
| | 不支持无人值守时可加 CODEX_NON_INTERACTIVE=1 |
| | 需 Node.js 22 或更高(以官方仓库要求为准) |
| | 命令为 brew install --cask codex |
| | 适合容器与无 Node.js 环境;解压后重命名为 codex 并加入 PATH |
这里有一个必须避开的坑:包名要认准 @openai/codex。npm 上另有一个叫 codex-cli 的包,与 Codex 完全没有关系,装错会得到一个功能毫不相干的命令行工具。
环境要求方面存在一处口径差异:官方仓库 README 写的是 Node.js 22 或更高(并推荐 LTS),而部分国内云平台文档写 18.0 以上。按官方 22+ 执行更稳妥,低版本常见表现是运行期出现难以定位的异常。系统层面官方要求 macOS 12+、Ubuntu 20.04+ 或 Debian 10+,Windows 走原生沙箱或 WSL2,内存建议 8GB。
三个必须提前知道的前提
- 沙箱默认就开着,不要为了省事关掉。Codex 的沙箱分 read-only、workspace-write、danger-full-access 三级;全自动模式下网络默认关闭、写入限制在当前工作目录。macOS 用系统自带的 Seatbelt 沙箱;Linux 官方不提供默认沙箱,建议用仓库内的容器脚本在 Docker 里跑。旧教程里流传的 --yolo(即跳过全部审批与沙箱的参数)除了一次性容器环境,不建议使用。
- 审批参数已经改过名。老教程里的 -a suggest、-a auto-edit、--full-auto 都不是当前口径。官方 CLI 参考页现在给出的是 --ask-for-approval(-a),取值为 untrusted | on-request | never;沙箱用 --sandbox(-s),取值为 read-only | workspace-write | danger-full-access。照旧教程写会被直接拒绝。
- 第三方转售渠道不在本文推荐范围。任何要求你把 API Key 交给第三方的做法,都同时承担密钥被挪用、端点随时失效,以及不符合 OpenAI 地区政策(官方明确警告可能导致账号被封)三重风险。个人和企业建议走本文的三条路径:本地模型、国内云平台官方端点、自建推理服务。
两处容易被教程带偏的说法
- "把 openai_base_url 改掉就能用"——这个字段确实是官方支持的,用于修改内置 OpenAI provider 的地址,但官方同时规定项目级配置里的 openai_base_url 会被忽略;而且这类教程通常不提 wire_api,一旦碰上只支持 Chat/Completions 的端点就会失败。
- "Codex 只对付费 ChatGPT 用户开放"——这句话只对 Codex Web 与桌面 App 成立,对 CLI 不成立。官方自定义 provider 提供了 env_key 机制,由你自己的环境变量承载密钥,因此接第三方端点时不依赖 ChatGPT 订阅;ChatGPT Plus / Pro / Business / Edu / Enterprise 包含 Codex 额度,指的是走 OpenAI 官方端点的情形。
常见问题
Q:Codex 在国内能直接用吗? A:CLI 本体可以安装和使用,但 OpenAI 的两条官方认证路径在国内都不适用(支持地区名单不含中国大陆、中国香港和中国澳门),必须把模型端点换成国内云平台或本地模型。
Q:用 Codex 一定要有 ChatGPT 付费订阅吗? A:走 OpenAI 官方端点需要(Plus、Pro、Business、Edu、Enterprise 计划包含 Codex 额度);接自定义 provider 端点不需要,Codex 通过 provider 的 env_key 读取你自己的密钥。
Q:国内最省事的做法是哪一种? A:不想花钱也不想出网,用 codex --oss 配 Ollama 跑本地模型;想用更强模型,用阿里云百炼或火山方舟的官方端点,两家官方文档都给了现成的 Codex 配置模板。
Q:配置写在项目目录里为什么不生效? A:官方规定项目级 .codex/config.toml 会忽略 model_provider、model_providers、openai_base_url 等键并打印启动警告,换模型的配置必须写在用户级 ~/.codex/config.toml。
Q:为什么地址和密钥都对,还是报错? A:先查两件事——wire_api 是否设为 responses(新版 Codex 已不支持 chat),以及密钥与 base_url 是否属于同一个计费方案(同平台不同方案的密钥互不相通)。
Q:可以用国产模型吗?能接哪些? A:可以。阿里云百炼可用最新版 Codex 的模型包括 qwen3.8-max-preview、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.6-flash;火山方舟提供 doubao-seed 系列、glm-5.3、glm-5.3-flash、deepseek-v4-flash、deepseek-v4-pro、minimax-m3、kimi-k2.7-code 等模型名。
Q:接国产模型后,Codex 的功能有损失吗? A:编码、调试、文件操作、代码审查、codex exec 自动化等核心能力正常;依赖 OpenAI 专有接口的少数云端能力不可用。模型能力上限、上下文档位与遥测口径都以你选择的端点为准,建议先在小项目上跑一周再全量切换。
Q:国内安装最常卡在哪一步? A:卡在官方一键脚本(下载域名 chatgpt.com 国内不可达)。改用 npm 并把 registry 换到国内镜像即可;包名务必认准 @openai/codex,Node.js 需 22 或更高。
Q:安全上最需要注意什么? A:默认保留沙箱、不要把 --dangerously-bypass-approvals-and-sandbox 当日常参数用;不要在系统目录、桌面或重要资料目录里直接启动 Codex,先新建一个练习目录;企业内部代码建议走本地模型或内网自建端点,保证代码不出内网。