Codex 配置教程（CLI + VS Code 插件)

# Codex 配置教程（CLI + VS Code 插件）

> **适用对象**：已装好 Node.js，准备把 Codex CLI 或 VS Code 里的 Codex 接进中转站的人  
> **来源**：APINebula 文档站「CLI 配置教程 → Codex 配置」（原文含 Windows / macOS / Linux 三段）  
> **目标**：终端敲 `codex` 能进对话界面并正常回复；VS Code 插件面板同样能回  
> **本篇统一使用的地址**：`https://api.zaimod.com/v1`

---

## 一、先看清：Codex 只认两个文件

原文一开头就说了这句，但它值得单独强调——**Codex 不读环境变量里的地址，也不读某个界面里的设置框**，它只认 `~/.codex/` 下的两个文件：

| 文件            | 作用               | 你要改什么            |
| ------------- | ---------------- | ---------------- |
| `config.toml` | 服务地址、请求协议、模型、MCP | `base_url` 换成中转站 |
| `auth.json`   | 存放 API Key       | 换成你在中转站的令牌       |

对应到各系统：

| 系统      | 配置目录                   | 完整路径示例                   |
| ------- | ---------------------- | ------------------------ |
| Windows | `%USERPROFILE%\.codex` | `C:\Users\你的用户名\.codex\` |
| macOS   | `~/.codex`             | `/Users/你的用户名/.codex/`   |
| Linux   | `~/.codex`             | `/home/你的用户名/.codex/`    |

> **配置文件位置可以搬**：Codex 支持 `CODEX_HOME` 环境变量指定配置目录。如果你设过它，`~/.codex` 就不是生效目录——改了没反应时先 `echo $env:CODEX_HOME`（Windows）或 `echo $CODEX_HOME` 确认一下。

---

## 二、三个字段决定成败

原文的 `config.toml` 只有 8 行，但其中 4 行是"删了就报错、且报错看不出原因"的关键项。先把它们讲清楚，后面照抄才不会踩坑。

```toml
model = "gpt-6-astra"                   # ① 模型名：必须是你的分组里真实存在的
model_provider = "codex"                # ② 指向下面那张表的表名
model_reasoning_effort = "medium"       # ③ 推理强度：取值随模型而定

[model_providers.codex]
name = "codex"
base_url = "https://api.zaimod.com/v1"   # ④ 必须带 /v1，且只到 /v1
wire_api = "responses"                  # ⑤ 走 Responses 协议，不是 chat/completions
requires_openai_auth = true             # ⑥ 让 Codex 用 auth.json 里的 Key 鉴权
```

| 字段                     | 作用                                                       | 写错的后果                                                                           |
| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `base_url`             | Codex 只在这个地址后面拼 `/responses`                             | 少了 `/v1` → 请求打到站点前端，返回 **200 + 一整页 HTML**，客户端报 JSON 解析错误（不是 404，很容易误判）          |
| `wire_api`             | 选择协议：当前版本只接受 `responses`                                 | 写成 `chat` / `chat_completions` → 旧版能跑，新版不认；你的中转站若只支持 `/chat/completions`，就得换客户端 |
| `requires_openai_auth` | `true` = 用 OpenAI 认证（读 `auth.json` 里的 Key），并忽略 `env_key` | **删掉这行或写 `false` → 请求不带 `Authorization` → 一律 401**，而你会以为是 Key 错了                |
| `model_provider`       | 必须等于 `[model_providers.xxx]` 里的 `xxx`                    | 名字对不上 → 仍走默认 `openai` 官方地址，看着配了却完全没生效                                           |
| 表名 `codex`             | 自定义 provider 的 id                                        | **不能叫 `openai` / `ollama` / `lmstudio`**，这三个是内置保留 id，自定义内容会被忽略                  |

> **⚠️ 这三个 id 不能用作表名**  
> 官方配置参考原文：内置 provider ID（`openai`、`ollama`、`lmstudio`）为保留值，不可覆盖。很多别家中转教程教你写 `[model_providers.openai]` + `base_url`，在当前版本里这一整块会被**静默丢弃**——配置看着改对了，请求依旧发往官方。原文用 `codex` 作表名是对的做法，别自己"优化"成 `openai`。

---

## 三、我在 `api.zaimod.com` 上的实测

原文提到「可在数据看板的 API 信息模块查看服务器地址」。那个位置长这样（截图取自原站，红框是地址栏，本教程一律改成 `https://api.zaimod.com/v1`）：

![](/uploads/editor/20261101/img_6ae61c18895242.32481602.png)

原文只说"`base_url` 必须保留 `/v1`"，没说为什么。以下是四种写法的真实响应，能解释所有"莫名其妙"的报错：

| 请求                                               | 返回                  | 含义                      |
| ------------------------------------------------ | ------------------- | ----------------------- |
| `POST https://api.zaimod.com/v1/responses`        | `401 Invalid token` | ✅ 路径正确，只差鉴权             |
| `POST https://api.zaimod.com/responses`           | `200` + 整页 HTML     | 打到了站点前端，路径错             |
| `POST https://api.zaimod.com/v1/chat/completions` | `401 Invalid token` | ✅ 备用链路（换 `wire_api` 时用） |
| `POST https://api.zaimod.com/v1/models`           | `404 Invalid URL`   | `/v1/models` 只支持 GET    |

结论：`base_url` 填 `https://api.zaimod.com/v1`，Codex 补 `/responses` → 正好命中第一个。**多写一段（`/v1/v1`）或少写一段（只到域名）都会失败，且后者不会 404**。

---

## 四、Windows 步骤

### 4.1 安装

按 `Win + R` 输入 `powershell` 回车，在 PowerShell 里执行：

```powershell
npm install -g @openai/codex@latest
```

### 4.2 验证安装

```powershell
codex --version
```

能打印出版本号（形如 `0.166.0`）就说明装好了。

![](/uploads/editor/20261101/img_6ae61c338da193.79150790.png)

> **⚠️ 这张图不能当"验证通过"的凭证**  
> 原文把它放在「验证安装」小节下，但图里只有 `npm i -g @openai/codex@latest` 和一句 `changed 2 packages in 2s`——**根本没有 `codex --version` 的输出**。而且 `changed 2 packages` 是"升级了 2 个包"的说法，全新安装通常显示 `added N packages`。这只是作者本机的一次升级记录，你不能拿它对照自己的屏幕。

### 4.3 写 `config.toml`

不用手动找目录，PowerShell 里两条命令搞定（目录不存在会自动建，文件不存在记事本保存时会创建）：

```powershell
New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
notepad "$HOME\.codex\config.toml"
```

把原有内容全部删掉，粘贴下面这份（`base_url` 已替换为中转站地址）：

```toml
model = "gpt-6-astra"
model_provider = "codex"
model_reasoning_effort = "medium"

[model_providers.codex]
name = "codex"
base_url = "https://api.zaimod.com/v1"
wire_api = "responses"
requires_openai_auth = true
```

保存后关闭记事本。

> **⚠️ 两个会让配置"静默失效"的细节**
>
> 1. **根键必须写在表头之前**。`model` / `model_provider` / `model_reasoning_effort` 三行如果被粘到 `[model_providers.codex]` 后面，TOML 会把它们当成该表内的键，Codex 读不到 → 仍然用默认模型和默认 provider。原文的顺序是对的，但你往已有的 `config.toml` 里"追加"时最容易出错。
> 2. **记事本可能存成 `config.toml.txt`**。Windows 默认隐藏扩展名，你以为文件叫 `config.toml`，其实是 `.txt`；Codex 找不到就默默用默认配置。资源管理器 →「查看」→ 勾上「文件扩展名」，一条命令确认：
>    ```powershell
>    Get-ChildItem "$HOME\.codex"
>    ```

### 4.4 写 `auth.json`

```powershell
notepad "$HOME\.codex\auth.json"
```

删掉原有内容，只留这一行 Key：

```json
{
  "OPENAI_API_KEY": "你的API_KEY"
}
```

先别急着把 `你的API_KEY` 当真——下一步拿到令牌再回来替换。

### 4.5 创建令牌并回填

1. 进中转站控制台 →「令牌管理」→「创建令牌」；
2. **令牌分组选 `CODEX`**（截图里红框那一项）；
3. **「模型可用列表」留空**，不要填；
4. 提交后回到列表，点密钥右侧的复制图标 → 选**「复制密钥」**；
5. 回到 `auth.json`，只选中 `你的API_KEY` 这几个字，粘贴替换，保存。

![](/uploads/editor/20261101/img_6ae61c97c59e13.97767415.png)

> **⚠️ 第 3 步不是可选项，是防 403 的关键**  
> 原文写了这句但很轻：「填写后，若列表中不包含当前使用的模型，请求可能返回 `403`」。实际现象是——你在 Codex 里换成任何模型都会 403，且报错文案看不出跟"模型可用列表"有关。**留空 = 不限制**，这是省事的正解；确实要限制时，记得把 Codex 里会用的模型全部加进去。

> **⚠️ 复制密钥 ≠ 复制连接信息**  
> 密钥栏里的内容是打码的，必须点右侧图标调出菜单。菜单里有两项：**「复制密钥」**（只有 `sk-...` 本身）和**「复制连接信息」**（一段含地址的配置片段）。粘错的话，`auth.json` 里会混进网址和换行，直接变成非法 JSON。

![](/uploads/editor/20261101/img_6ae61cf6cd67c7.14701071.png)

### 4.6 启动测试

```powershell
codex
```

能进对话界面、发一句「你好」能收到回复，就说明通了。

![](/uploads/editor/20261101/img_6ae61d058aeba9.94608819.png)

> **这张图里有两个数字要留意**
>
> 1. 版本 `v0.137.0` —— npm 上当前已是 `0.166.x`，你这台机器装到更新版本是正常的。
> 2. **模型显示 `gpt-5.5 medium`，不是配置里写的 `gpt-6-astra`** —— 说明 `model` 这个字段不是"配一次就不变"的（见第六节）。验收时要看这行显示的模型名，是不是你分组里真实可用的那个。

---

## 五、macOS 与 Linux

三平台的 `config.toml` / `auth.json` **内容完全一致**，只有"怎么打开文件"不同。原文把同样的内容抄了三遍，这里合成一张对照表：

| 动作            | macOS                                                                                     | Linux                                                |
| ------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| 安装            | `npm install -g @openai/codex@latest`                                                     | 同左                                                   |
| 建目录并打开 config | `mkdir -p ~/.codex`<br />`touch ~/.codex/config.toml`<br />`open -e ~/.codex/config.toml` | `mkdir -p ~/.codex`<br />`nano ~/.codex/config.toml` |
| 打开 auth       | `touch ~/.codex/auth.json`<br />`open -e ~/.codex/auth.json`                              | `nano ~/.codex/auth.json`                            |
| 保存退出          | `Command + S`，关掉窗口                                                                        | `Ctrl+O` → 回车 → `Ctrl+X`                             |

macOS 打开终端：`Command + 空格` → 输入「终端」或 `Terminal` → 回车。

> **⚠️ 别用 `sudo npm install -g`**  
> 原文在 macOS / Linux 段写着"如果遇到权限不足，请输入 `sudo npm install -g ...`"。这条路能装上，但会把包写进 `/usr/local/lib/node_modules`，之后**每个全局包都得 sudo**，还容易和 nvm 打架。官方文档明确不建议。更稳的两种做法：
>
> ```bash
> # 方案 A：用版本管理器（推荐，顺手解决 Node 版本问题）
> ```

|   |   |
| - | - |

> curl -o- <https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh> | bash  
> nvm install --lts && npm install -g @openai/codex@latest
>
> # 方案 B：把全局目录挪到用户目录
>
> npm config set prefix ~~/.npm-global  
> echo 'export PATH=~~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc  
> npm install -g @openai/codex@latest
>
> ```
> ```

> **⚠️ 文本编辑的"智能引号"**  
> macOS 的「文本编辑」默认会把直引号 `"` 自动替换成弯引号 `"`，在 `config.toml` 里粘贴没问题（粘贴不触发替换），但**手打**就会坏，TOML 直接解析失败。如果不放心，用 `nano` 或 VS Code 打开这两个文件。

---

## 六、模型名到底该填什么

原文在最后补了一句「模型名称以控制台为准」，这是全篇最该前置的一句话。原因是**同一份配置下，三个地方显示的模型名可以都不一样**：

| 位置               | 截图里显示的模型         |
| ---------------- | ---------------- |
| `config.toml` 示例 | `gpt-6-astra`    |
| Codex CLI 启动界面   | `gpt-5.5 medium` |
| VS Code 插件面板右下角  | `5.6 Sol 极高`     |

这三处不一致不是截图出错，而是机制决定的：

- CLI 里输入 `/model` 可以当场换模型，换完这个选择会覆盖配置；
- VS Code 插件有**自己的模型选择器**（面板输入框右下角那个胶囊），它不一定跟 `config.toml` 同步；
- 所以 `config.toml` 里的 `model` 更像"默认值"，不是"最终值"。

**正确做法**：去控制台的「模型广场」看你选的 `CODEX` 分组实际有哪些模型，把名字原样复制进 `config.toml`。名字对不上时的报错通常是 `model not found` 或 `400`，不是 401——**看到 401 说明路径和 Key 都没问题，只是令牌或分组不对**。

`model_reasoning_effort`（推理强度）同理：`medium` 只是原文的示例值，当前版本接受 `minimal` / `low` / `medium` / `high` / `xhigh`（面板里显示为「极高」）/ `max` / `ultra`，**具体支持哪几档取决于模型本身**。填了模型不支持的档位，一般会报参数错误。

---

## 七、VS Code 插件

### 7.1 装哪个

扩展市场搜 `Codex`，认**发布者 OpenAI**、名字是 `Codex – OpenAI's coding agent` 的那个（扩展 id `openai.chatgpt`）。同名的第三方扩展有十几个（`codex-history-viewer`、`vscode-codex-cli-launcher`、`gaussian-codex-for-copilot` 等），装错了配置方式完全不同。

新版 VS Code 会把 Codex 当成一个"聊天代理"放进 Chat 面板的标签页里，和 `Copilot`、`Claude Code` 并列——截图顶部那三个 `聊天 / CLAUDE CODE / CODEX` 标签就是这个：

![](/uploads/editor/20261101/img_6ae61d32e23b01.51408410.png)

### 7.2 它读哪份配置

和 CLI **共用** `~/.codex/config.toml` 与 `~/.codex/auth.json`。所以第四节的配置写完，插件里不用再填一遍地址和 Key——这也是为什么原文把插件验收放在"第三步"。

但模型选择是例外：

![](/uploads/editor/20261101/img_6ae61d426fc058.59768558.png)

> **⚠️ 插件里先确认模型**  
> 点这个胶囊换成你分组里真实存在的模型。如果它停在某个你没权限的模型上，表现是"能进面板、一发消息就报错"，而 CLI 那边却是正常的——同一个 Key、同一份配置，只差这一处选择。

---

## 八、验收清单

原文的验收标准只有一句"能正常回复"。下面四条能一次定位问题出在哪一层：

| 检查      | 命令 / 位置           | 通过标准                |
| ------- | ----------------- | ------------------- |
| 1. 版本   | `codex --version` | 打印出版本号（≥ 0.137）     |
| 2. 配置生效 | `codex` 启动界面      | 显示的模型名 = 你分组里的模型    |
| 3. 请求通路 | 发一句「你好」           | 有回复，不报 401 / 403    |
| 4. 计费确认 | 控制台「使用日志」         | 有一条带模型名的调用记录，余额相应减少 |

第 4 条最容易被忽略：**界面回得快不代表走的是你的余额**。看到调用记录，才算真的接上了中转站。

---

## 九、常见问题

| 现象                                | 原因                                                                    | 处理                                                                                   |
| --------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `401 Invalid token`               | ① `requires_openai_auth` 没写或写了 `false`；② Key 被复制成"连接信息"；③ 令牌被禁用       | 先查 `config.toml` 有没有那行，再查 `auth.json` 是不是纯 JSON                                      |
| `403`                             | 令牌的「模型可用列表」不包含当前模型，或分组不含该模型                                           | 把列表留空，或补齐模型                                                                          |
| 报 JSON 解析错 / 一堆 `<!doctype html>` | `base_url` 少了 `/v1`，请求打到站点前端                                          | 改成 `https://api.zaimod.com/v1`                                                        |
| `404 Invalid URL`                 | `base_url` 多写了段（如 `/v1/v1`、末尾带 `/responses`）                          | 只写到 `/v1`，不要带尾斜杠                                                                     |
| `model not found` / `400`         | `model` 名不在该分组                                                        | 从控制台模型广场复制，注意带日期后缀的写法不同                                                              |
| 一直 `Reconnecting 1/5 … 5/5` 才回话   | Codex 先尝试 Responses 的 WebSocket 传输，中转站多数不支持，要等它超时回落                   | 在 `[model_providers.codex]` 里加 `supports_websockets = false`（字段名随版本可能不同；写错不报错，只是不生效） |
| 改完完全没反应                           | ① 文件存成了 `.txt`；② 根键写在表头后面；③ 没重启；④ `CODEX_HOME` 指向别处                   | 逐条对照第二节的表格                                                                           |
| 之前能登 ChatGPT，现在 401               | `codex login` 会把 `auth.json` 重写成 `tokens` 结构，覆盖掉你手写的 `OPENAI_API_KEY` | **不要执行 `codex login`**；已覆盖就按 4.4 重写一遍                                                |

> **还有一处原文没提、但很常见**：如果你之前设过 `OPENAI_API_KEY` 环境变量，它和 `auth.json` 里可能同时存在两把 Key。排查时先 `echo $env:OPENAI_API_KEY`（Windows）/ `echo $OPENAI_API_KEY`（macOS、Linux）看一眼，别在错误的那把上反复试。

---

## 十、安全边界

- `auth.json` 是**明文** Key，就在用户目录里。macOS / Linux 建议 `chmod 600 ~/.codex/auth.json`。
- Codex 会把**你让它读的代码**发给服务端——接中转站意味着这些内容经过第三方，机密仓库别用。
- 令牌按 `CODEX` 分组单独建一把，**不要复用主账号令牌**，出问题时一键禁用即可。
- 令牌页显示的分组倍率（如 `CODEX` 0.35x、`Claude Code全球高防` 1.8x）直接决定扣费，选错分组会多花钱。

---

## 附录 A · 字段速查

| 字段 | 必填 | 说明 |
|---|---|---|
| `model` | 是 | 你的分组里真实存在的模型名 |
| `model_provider` | 是 | 等于 `[model_providers.<id>]` 的 id |
| `model_reasoning_effort` | 否 | 推理强度，取值随模型 |
| `model_providers.<id>.base_url` | 是 | 到 `/v1` 为止，Codex 只补 `/responses` |
| `model_providers.<id>.wire_api` | 否 | 当前版本只接受 `responses` |
| `model_providers.<id>.requires_openai_auth` | 是 | `true` 才会带 `auth.json` 的 Key |
| `model_providers.<id>.env_key` | 可选 | 改用环境变量提供 Key 时填；与 `requires_openai_auth` 二选一 |
| `model_providers.<id>.supports_websockets` | 可选 | 中转站不支持 WS 时设 `false` |

## 附录 B · 地址对照与迁移

| 项目 | 原地址 | 现地址 |
|---|---|---|
| `base_url` | `https://apinebula.ai/v1` | `https://api.zaimod.com/v1` |
| 其余配置文件内容、字段名、协议 | 不变 | 不变 |

迁移提示：

1. 令牌不能跨站复用，需要在 `api.zaimod.com` 重新生成；
2. `config.toml` 只改 `base_url` 一处，**不要顺手把 `/v1` 删掉**，也不要改成 `/v1/responses`；
3. 原站若给过"海外线路 / 备用域名"，换站后一律作废，本平台只有一个入口。

## 附录 C · 本次整理修正的原文问题

| # | 问题 | 处理 |
|---|---|---|
| 1 | 三平台「验证安装」共用同一张 PowerShell 截图（三张图字节完全相同），mac / Linux 读者无法对照 | 只保留一张并注明是 Windows |
| 2 | 该截图里没有 `codex --version` 输出，只有 `npm i` 的 `changed 2 packages` | 加提示，说明它不能当验证凭证 |
| 3 | 未解释 `requires_openai_auth` 的作用（删掉即 401） | 第二节展开 |
| 4 | 未说明 provider 表名不能用 `openai` / `ollama` / `lmstudio` | 第二节加警告 |
| 5 | 未说明 `base_url` 为何必须带 `/v1`（只拼 `/responses`） | 第三节用四种实测响应对照 |
| 6 | 未提 TOML 根键必须在表头之前 | 4.3 加提示 |
| 7 | 未提可能存成 `config.toml.txt` | 4.3 加检查命令 |
| 8 | macOS / Linux 建议 `sudo npm install -g` | 改为 nvm / 自定义 prefix |
| 9 | 「在密钥栏直接复制 API Key」与实际 UI 不符（需点图标 → 选「复制密钥」） | 4.5 补菜单区分 |
| 10 | 「模型可用列表留空」只写了一句，没说 403 的现象 | 4.5 说明后果 |
| 11 | `model` 示例值与截图显示的模型三处不一致 | 第六节做对照表 |
| 12 | 未提 `codex login` 会覆盖 `auth.json` | FAQ 补 |
| 13 | 未提 `CODEX_HOME` 环境变量可能改变配置目录 | 第一节补 |
| 14 | 验收标准只有"能正常回复" | 第八节改为四条判据 |
| 15 | 未提 `auth.json` 明文存储与令牌分组倍率 | 第十节补 |

---

**继续阅读**：Node.js 环境安装教程 → [本篇] Codex 配置 → Claude Code CLI 配置 → Gemini CLI 配置

上一篇：Node.js 环境安装教程{else}上一篇：没有了下一篇：Claude Code 配置{else}下一篇：没有了