Codex 国内怎么用？

Codex CLI 是什么？国内使用难在哪

Codex CLI（命令为 codex）是 OpenAI 推出的终端编程智能体（Coding Agent）。它在你的本地目录或服务器里运行，能理解整个代码库、跨文件修改代码、执行终端命令并自动根据报错修复问题。此外，Codex CLI 与桌面端应用（codex app）、VS Code / Cursor 等 IDE 扩展共用同一套底层配置（~/.codex/config.toml）。

国内开发者直接使用官方服务，通常会遇到两道门槛：

• 地区限制：中国大陆不在 OpenAI 官方支持的国家和地区列表内，直接使用官方接口和账号存在不确定性。
• 账号与付款门槛：Codex 支持 ChatGPT 账号登录（不同套餐额度不同）或 OpenAI API Key，两者都需要在 OpenAI 开户和付款，对国内用户不够方便。

好在 OpenAI 将 Codex CLI 的模型接入层设计成了可插拔架构。通过用户级配置文件 ~/.codex/config.toml 中的 model_providers 字段，你可以把请求发往任何兼容 OpenAI Responses API 的接口。国内目前有三种可行的接入方案：

第一步：安装 Codex CLI（官方方式）

OpenAI 官方提供了独立安装脚本、npm 和 Homebrew 三种安装渠道。国内或云服务器环境下，可以根据你机器上的工具链任选一种：

1. 使用官方独立安装脚本或包管理器安装

   macOS 和 Linux 可以直接运行官方独立安装脚本（无需预装 Node.js）。如果你已经装好了 Node.js，使用 npm 全局安装是最通用的做法（各家国产模型的配置向导也普遍采用此方式）。

2. 检查版本并生成配置目录

   安装完成后运行 codex --version 确认命令可用。首次配置前，建议先运行一次 codex 或手动执行 mkdir -p ~/.codex，确保用户主目录下存在 ~/.codex 文件夹。

# 方式 A：使用 npm 全局安装（通用，需 Node.js 环境）
npm install -g @openai/codex

# 方式 B：macOS / Linux 官方独立安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 方式 C：macOS Homebrew 安装
brew install --cask codex

# 方式 D：Windows PowerShell 官方独立安装脚本
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# 验证安装并创建配置目录
codex --version
mkdir -p ~/.codex

如果你有海外网络和官方账号，安装后直接运行 codex 会拉起登录界面；在无桌面环境的远程服务器上，可运行 codex login --device-auth 使用设备码登录，或通过管道传入官方 API Key：printenv OPENAI_API_KEY | codex login --with-api-key。而如果在国内接国产模型或中转站，则不需要登录 OpenAI 账号，直接看下面的配置文件写法。

第二步：理解 config.toml 与 Responses API 协议要求

在动手改配置前，有两个来自 OpenAI 官方文档的关键规则必须弄清楚，否则很容易踩坑：

• 必须兼容 Responses API（wire_api = "responses"）：新版 Codex CLI 已废弃旧的 wire_api = "chat"（Chat Completions 协议）。根据官方配置参考文档，model_providers.<id>.wire_api 目前唯一合法的值就是 "responses"（省略时默认也是它）。这意味着你接入的模型厂商或中转站，后端必须提供 /responses 路径的接口，只支持传统 /chat/completions 的旧接口无法直连。
• 只能在用户级配置文件中定义提供方：Codex 的用户级配置文件位于 ~/.codex/config.toml（Windows 原生环境为 %USERPROFILE%\.codex\config.toml，若设置了环境变量 CODEX_HOME 则为 $CODEX_HOME/config.toml）。为了安全，Codex 会忽略项目目录 .codex/config.toml 里的 model_provider 和 model_providers 键——自定义模型提供方必须写在用户级的 ~/.codex/config.toml 中。

下面是一个标准的自定义提供方 ~/.codex/config.toml 结构示例：

# 注意：TOML 语法要求顶层键值必须写在所有 [table] 表头之前
model_provider = "my_provider"
model = "模型名称"
model_reasoning_effort = "high"

[model_providers.my_provider]
name = "Custom Provider"
base_url = "https://example.com/v1"
env_key = "MY_PROVIDER_API_KEY"
wire_api = "responses"

核心配置键说明：

• model_provider：指定当前启用的提供方 ID，必须与下方 [model_providers.<id>] 中的 <id> 完全一致（不要使用 openai、ollama、lmstudio 等内置保留名）。
• model：要调用的模型 ID（如 deepseek-flash、glm-5.3、kimi-k3.1-pro 等）。
• base_url：接口基础地址。Codex 请求时会自动在末尾拼接 /responses。
• env_key：存放 API Key 的环境变量名称（注意：这里填的是变量名如 ARK_API_KEY，而不是以 sk- 开头的密钥本身，密钥值需在终端里通过 export 设置）。部分厂商文档也会使用 experimental_bearer_token 字段直接填入密钥字符串（OpenAI 官方标注为不推荐，优先用 env_key）。
• wire_api：通信协议，固定填 "responses"。
• model_catalog_json（可选）：指向本地模型元数据 JSON 文件（如 ~/.codex/models.json），用于向 Codex 声明第三方模型的上下文窗口大小和思考强度档位（low / medium / high / max）。

第三步：接入国产大模型（官方原生支持列表）

截至 2026 年 11 月，下面 6 家都发布了 Codex CLI 的官方接入文档，多数还提供一键配置工具。官方手动配置通常还需要一个模型目录文件 ~/.codex/models.json（通过 model_catalog_json 引用），下面的示例只展示核心结构，完整写法以各家文档为准。由于 Codex CLI、桌面端和 IDE 插件共用 ~/.codex/config.toml，按下面任意一家配置一次，三端同时生效。

配置示例 1：接入 DeepSeek（一键脚本或手动配置）

DeepSeek 官方 API 已原生支持 Responses API。最省事的方法是先确保已安装并启动过一次 codex，然后在终端运行 DeepSeek 官方的一键配置脚本，脚本会自动备份原配置、写入模型目录 ~/.codex/models.json 并修改 ~/.codex/config.toml：

# 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

如果你倾向于手动修改，下面是核心结构示意。官方手动配置还要先创建 ~/.codex/models.json，并加上登录方式等若干项，完整内容以 DeepSeek 文档为准：

model = "deepseek-flash"
model_provider = "deepseek"
model_catalog_json = "~/.codex/models.json"

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "你的 DeepSeek API Key"

配置示例 2：接入智谱 GLM（GLM-5.3）

注意智谱 GLM 接入 Codex 时，必须使用其 OpenAI Response 协议专用端点 https://open.bigmodel.cn/api/v1（如果是海外站 Z.ai 则是 https://api.z.ai/api/v1），而不是传统的 /api/paas/v4。你可以运行智谱官方工具 npx @z_ai/coding-helper 自动配置，或者按官方文档手动编辑（同样需要先建 ~/.codex/models.json）：

model_provider = "ZAI"
model = "glm-5.3"
model_reasoning_effort = "max"
model_catalog_json = "~/.codex/models.json"

[model_providers.ZAI]
name = "ZAI"
base_url = "https://open.bigmodel.cn/api/v1"
experimental_bearer_token = "你的智谱 API Key"
wire_api = "responses"

配置示例 3：接入 Kimi 或火山方舟（使用 env_key 环境变量）

不想把明文 Key 直接写进配置文件的开发者，可以用 env_key 指定环境变量名。以 Kimi 国内站（kimi-k3.1-pro）为例，Kimi 官方也明确建议不要把 Key 写进配置文件：

model = "kimi-k3.1-pro"
model_provider = "kimi"
model_context_window = 1048576

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.cn/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"

保存后，在终端（或写入 ~/.bashrc / ~/.zshrc）导出对应的环境变量即可启动 codex：

export KIMI_API_KEY="sk-你的Kimi密钥"
codex

使用第三方中转站的注意事项

除了直连国产大模型，不少国内开发者为了在 Codex 里调用 GPT 系列模型或跨厂商切模型，会选择 OpenRouter 或各类第三方 API 中转站（前提是对方支持 Responses 接口）。中转站在 ~/.codex/config.toml 里的配置方法与上面完全一致，只需把 base_url、env_key 和 model 换成服务商提供的信息。

常见报错与排查方法

根据 OpenAI Codex 官方仓库与各模型厂商文档，配置自定义模型时最常见的报错及解决方法如下：

• 报错 `wire_api = "chat"` is no longer supported
  原因：你参考了早期版本的旧教程，在配置里写了 wire_api = "chat"。
  解决：打开 ~/.codex/config.toml，将该字段改为 wire_api = "responses"，并确认所填的 base_url 对应的是厂商支持 Responses API 的端点。
• 警告 Ignored unsupported project-local config keys in .../.codex/config.toml: model_provider, model_providers
  原因：你把 model_provider 和 model_providers 写进了项目目录下的 .codex/config.toml。
  解决：Codex 规定提供方配置只能放在用户级配置文件中。请将这两项移至 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml）。
• 报错 legacy `profile = "x"` config is no longer supported; use `--profile x` with `x.config.toml` instead
  原因：在 config.toml 顶层设置了旧写法 profile = "x"，或用 --profile x 时与旧的 [profiles.x] 同名。
  解决：删除顶层的 profile = ...（以及同名的旧 [profiles.x]）。如果需要保存多套模型配置随时切换，按官方新规范在 ~/.codex/ 下新建独立的 <名称>.config.toml 文件（如 ~/.codex/kimi.config.toml，里面直接写顶层键值），启动时运行 codex --profile <名称>。
• 请求返回 401 Unauthorized
  原因：自定义提供方默认不会去读 ~/.codex/auth.json 里的官方 Key；或者你混用了不同计费类型的 Key。
  解决：第一，确认 env_key 写的是环境变量名（如 KIMI_API_KEY），且当前终端已执行 export KIMI_API_KEY=sk-xxx（等号两侧无空格）；第二，检查国内厂商的套餐 Key（Coding Plan / Token Plan）与普通按量计费 Key 是否混用——智谱、阿里云百炼、火山方舟的编程套餐 Key 与按量标准 API Key 均分开管理，对应的 base_url 也不同，不能混填。
• 请求返回 404 Not Found 或修改配置后不生效
  原因：TOML 语法把顶层键写在了 [table] 后面，导致 model_provider 被解析成了某个表的子属性；或者 Base URL 写成了 Chat Completions 路径。
  解决：确保 model_provider 和 model 等顶层键位于文件最上方（任何 [...] 表头之前），彻底关闭所有正在运行的 Codex 终端或桌面端窗口后重新启动。

在 AlwaysAgent 上直接用 Codex（免装环境）

如果你不想在本地电脑上处理 Node.js 权限、跨平台配置文件路径或网络问题，也可以直接在 AlwaysAgent 上使用。

AlwaysAgent 为每位用户提供一台独享的云端 Linux 服务器，拥有独立公网 IP，出厂已预装好 OpenAI Codex 与 Claude Code。你不用装任何 App，也不用配 SSH，直接在电脑或手机浏览器里打开工作台（内置 AI 对话、文件管理、终端、远程浏览器预览、版本记录）就能开始写代码。

• 自带接口，平台不加价：在工作台设置里直接填入你的 Base URL 与 API Key（无论是 OpenAI / Anthropic 官方 Key、上面列出的国产大模型官方接口，还是第三方中转站、OpenRouter 均可）。密钥只保存在你自己的服务器上，平台不经手 AI 调用、不加价、也不转售模型额度。
• 7×24 小时云端在线：服务器全天候运行，合上电脑或关掉手机浏览器后，Codex 的长任务和测试依然在云端继续跑，随时打开浏览器就能接着看结果。
• 计费透明灵活：支持按小时试用，充值 $10 起，约 $0.05/小时（删除服务器即停止计费，关机也计费；充值 14 天内未消费余额可退，扣手续费）。长期使用可选月付套餐：Starter $9.9（2 核 4GB 40GB）、Developer $17.9（4 核 8GB 75GB）、Pro $24.9（6 核 12GB 100GB）、Power $44.9（8 核 24GB 200GB），均不限流量、带每日自动快照，按小时服务器可一键转月付并迁移数据。