# Codex 国内怎么用？

> Codex CLI 是 OpenAI 开源的终端编程智能体，能直接读仓库、改代码、跑测试。国内开发者不必依赖 OpenAI 账号，只需修改 ~/.codex/config.toml，就能给它换上提供 Responses 兼容接口的国产大模型或中转站。

Source: https://alwaysagent.app/zh/codex-china
更新于: 2026-11-05

## 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** 的接口。国内目前有三种可行的接入方案：

- **国产大模型直连** (`官方 Responses 接口`): DeepSeek、智谱 GLM、Kimi、MiniMax、阿里云百炼、火山方舟都有 Codex 接入官方文档，提供 Responses 兼容接口（个别套餐例外，见下表）。
- **第三方中转站 / OpenRouter** (`自定义 Base URL`): 通过中转服务或 OpenRouter 转发请求，一个 Key 调用多厂商模型；需确认服务商支持 `/responses` 端点。
- **OpenAI 官方账号 / Key** (`codex login`): 适合已有代理网络或海外云服务器，且持有 ChatGPT Plus/Pro 订阅或官方 `OPENAI_API_KEY` 的开发者。

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

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

- 

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

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

- 

### 检查版本并生成配置目录

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

`Terminal（macOS / Linux / Windows）`

```
# 方式 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` 结构示例：

`~/.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`，按下面任意一家配置一次，三端同时生效。

| 厂商 / 平台 | Codex 专用 Base URL（Responses 协议） | 常用模型示例与配置方式 | 官方文档 |
| --- | --- | --- | --- |
| DeepSeek | https://api.deepseek.com | deepseek-flash、deepseek-v4-pro；提供官方一键配置脚本 | [DeepSeek 文档](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex/) |
| 智谱 GLM（国内站） | https://open.bigmodel.cn/api/v1 | glm-5.3、glm-5-turbo；可手写配置或运行 npx @z_ai/coding-helper | [智谱文档](https://docs.bigmodel.cn/cn/coding-plan/tool/codex) |
| Kimi（月之暗面） | 国内站：https://api.moonshot.cn/v1国际站：https://api.moonshot.ai/v1（两边 Key 不通用） | kimi-k3.1-pro；设置环境变量 KIMI_API_KEY 直连 | [Kimi 文档](https://platform.moonshot.cn/docs/guide/codex-kimi) |
| MiniMax | 国内站：https://api.minimax.cn/v1国际站：https://api.minimax.io/v1 | MiniMax-M3.1-Flash；可运行 npx -y mmx-cli@latest agent setup | [MiniMax 文档](https://platform.minimaxi.com/docs/m-plan/codex) |
| 阿里云百炼（通义千问等） | Token Plan：https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1按量计费：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 | 千问等百炼模型；套餐 Key 与按量 Key 地址不同；Coding Plan 套餐走 Chat 协议、要求旧版 Codex，不适用本文方法 | [百炼文档](https://help.aliyun.com/zh/model-studio/codex) |
| 火山方舟（豆包 / DeepSeek 等） | 按量计费：https://ark.cn-beijing.volces.com/api/v3Coding Plan：https://ark.cn-beijing.volces.com/api/coding/v3Agent Plan：https://ark.cn-beijing.volces.com/api/plan/v3 | ark-code-latest 或具体模型名；支持通过 arkcli helper 一键配置 | [火山方舟文档](https://www.volcengine.com/docs/ark/ai-tools-codex) |

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

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

`Terminal（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
```

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

`~/.codex/config.toml（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`）：

`~/.codex/config.toml（智谱 GLM 配置）`

```
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 写进配置文件：

`~/.codex/config.toml（Kimi 配置）`

```
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`：

`Terminal`

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

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

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

**使用第三方中转站前，请务必评估以下三点风险：**

1. **代码与数据安全**：Codex CLI 在执行任务时，会将你项目里的代码片段、文件内容、目录结构以及终端命令的输出发送给模型接口。通过第三方中转站调用时，这些明文数据都会流经中转站服务器。请勿在涉及公司商业机密、生产环境密钥或敏感数据的代码仓库中使用来路不明的中转站，并且切勿向任何人分享含官方登录凭证的 `~/.codex/auth.json` 文件。

2. **协议兼容性与稳定性**：部分老旧中转站仅转发了 `/v1/chat/completions`，没有实现或正确透传 Codex 必需的 `/v1/responses` 接口、流式事件与工具调用（Tool Calls）字段，会导致请求报 404/400 或流式响应中断。

3. **计费透明度**：Agent 编程任务往往伴随高频的多轮上下文读取与推理（Reasoning tokens），Token 消耗量远大于普通聊天。使用中转站前请确认其倍率规则、缓存命中（Cached Input）计费是否透明，建议小额充值按量测试。

## 常见报错与排查方法

根据 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](https://alwaysagent.app) 上使用。

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），均不限流量、带每日自动快照，按小时服务器可一键转月付并迁移数据。

## 常见问题

### Codex CLI 接国产模型，为什么很多旧教程里的配置用不了了？

因为早期版本的 Codex CLI 允许使用 Chat Completions 协议（`wire_api = "chat"`），而新版 Codex CLI 已经只支持 OpenAI Responses API（`wire_api = "responses"`）。如果照搬旧教程填 `wire_api = "chat"` 或填了仅支持 `/chat/completions` 的接口地址，启动或请求时就会报错。请使用本文表格中各厂商原生支持 Responses 协议的 Base URL。

### 为什么我在项目的 .codex/config.toml 里配了 model_providers 却被忽略了？

这是 OpenAI Codex 的安全限制。根据官方文档，项目级的 `.codex/config.toml` 不允许覆盖机器本地的提供方与认证设置，写在里面的 `model_provider`、`model_providers` 和 `openai_base_url` 都会被直接忽略并弹出警告。请把自定义模型提供方写在用户主目录的 `~/.codex/config.toml` 中。

### 如何在不改动默认配置的情况下，在多个国产模型或官方模型之间快速切换？

可以使用 Codex 的 Profile 功能。先在 `~/.codex/config.toml` 里把各个厂商的 `[model_providers.]` 定义好，然后在 `~/.codex/` 目录下为不同模型创建单独的 `.config.toml`（例如 `~/.codex/deepseek.config.toml`），里面写上对应的顶层 `model_provider` 和 `model`。平时启动时通过 `codex --profile deepseek` 即可按需切换。

### 国产模型厂商的 Coding Plan（编程套餐）Key 和普通按量 API Key 有什么区别？

智谱 GLM、阿里云百炼、火山方舟等厂商都推出了包月制的编程套餐（如 Coding Plan、Token Plan）。需要特别注意：这些套餐生成的专属 API Key 与平台标准的按量付费 API Key 是隔离管理的，两者不仅不能混用，在 Codex 里填写的 `base_url` 往往也不一样。配置前请核对你手头 Key 的类型，填错地址会导致 401 报错或产生套餐外的按量扣费。

### Codex CLI、Codex 桌面端和 VS Code 插件需要分别配置吗？

不需要。OpenAI 官方文档明确说明，Codex CLI、桌面端应用和 IDE 扩展共享同一份用户级配置文件 `~/.codex/config.toml`。你在 `~/.codex/config.toml` 中配置好自定义 `model_providers` 后，重启命令行或桌面应用即可生效。

### AlwaysAgent 服务器在海外，既能连 OpenAI 官方又能连国产模型吗？

可以。AlwaysAgent 为每位用户分配独立公网 IP 的云端 Linux 服务器，既可以直接使用 OpenAI / Anthropic 官方接口与 OpenRouter，也可以直连 DeepSeek、智谱、Kimi、MiniMax、阿里云百炼、火山方舟等公网 API 接口。连接多站点厂商（如智谱国内站 `open.bigmodel.cn` 与国际站 `api.z.ai`、MiniMax 国内站 `api.minimax.cn` 与国际站 `api.minimax.io`）时，只需确保所填的 Base URL 与你开通 API Key 的站点一致即可。