Codex 安装与配置文档 API平台接入教程

# Codex 安装与配置教程

> 支持平台：Windows 10/11、macOS 12+、主流 Linux 发行版  
> 中转平台地址：`https://api.zaimod.com`　接口版本：`/v1`（Responses API）  
> 配置完成后，命令行 `codex` 与 VSCode 的 Codex 插件均可使用。

本文按「准备 → 安装 → 取令牌 → 写配置 → 启动」的顺序组织：前两步装环境，后三步接中转平台。三个系统的差异只在命令和文件路径，配置内容完全一致。

---

## 一、开始之前

### 1.1 系统要求

| 项目      | 要求                                                                 |
| ------- | ------------------------------------------------------------------ |
| 操作系统    | Windows 10 / 11、macOS 12+、Ubuntu 20.04+ / Debian 10+ / CentOS 7+ 等 |
| Node.js | 22 或更高版本                                                           |
| npm     | 10 或更高版本                                                           |
| 网络      | 可访问 `https://api.zaimod.com`                                        |

### 1.2 准备清单

| 项目         | 说明                                           |
| ---------- | -------------------------------------------- |
| Node.js 环境 | 未安装先按第二章装好                                   |
| Git Bash   | **仅 Windows 需要**，Codex 在 Windows 上依赖 bash 环境 |
| API Key    | 在 `https://api.zaimod.com` 控制台创建，`sk-` 开头     |
| 令牌分组       | 创建令牌时必须选择 **Codex 专属**类分组，详见 1.3             |

### 1.3 关于令牌分组（关键）

创建令牌时，如果分组选错，配置再正确也无法调用。规则：

- 分组必须选择名称中带 **Codex 专属** 的分组（控制台中通常显示为 `Codex专属`）。
- 不同版本控制台的分组名称可能略有差异（如 `Codex专属`、`codex渠道-gpt` 等），**以控制台列表里实际显示的名称为准**，不要照抄文字。
- 令牌额度建议设为**无限额度**、过期时间选**永不过期**，避免使用中途失效。
- 令牌名称可任意填写，仅用于自己识别。

---

## 二、安装 Codex CLI

### 2.1 Windows

**前置步骤（必做）：安装 Git Bash**

访问 <https://git-scm.com/downloads> 下载对应系统版本，安装过程中一直点击「下一步」即可完成。

**步骤 1：安装 Node.js**

访问 <https://nodejs.org/> 下载并安装最新 **LTS** 版本。

**步骤 2：安装 codex**

打开命令提示符（CMD）或 PowerShell，运行：

```bash
npm install -g @openai/codex
```

**步骤 3：验证安装**

```bash
codex --version
```

能输出版本号即安装成功。

### 2.2 macOS

**步骤 1：安装 Node.js**

- 方式一：访问 <https://nodejs.org/> 下载安装最新 LTS 版本。
- 方式二：使用 Homebrew（推荐）

```bash
# 如尚未安装 Homebrew，先运行这一行
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node
```

**步骤 2：安装 codex**

打开终端（Terminal），运行（如提示权限不足请加 `sudo`）：

```bash
npm install -g @openai/codex
```

**步骤 3：验证安装**

```bash
codex --version
```

### 2.3 Linux

**步骤 1：安装 Node.js**（按发行版选择一种）

Ubuntu / Debian：

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

CentOS / RHEL / Fedora：

```bash
# Fedora 用 dnf，CentOS / RHEL 用 yum
sudo dnf install nodejs npm
# 或
sudo yum install nodejs npm
```

Arch Linux：

```bash
sudo pacman -S nodejs npm
```

**步骤 2：安装 codex**

```bash
sudo npm install -g @openai/codex
```

**步骤 3：验证安装**

```bash
codex --version
```

---

## 三、获取 API 令牌

1. 打开 <https://api.zaimod.com>，登录后进入 **控制台 → API令牌**。
2. 点击 **添加令牌**。
3. 按 1.3 的规则填写：
   - **名称**：随意，如 `codex`
   - **分组优先级选择**：选择带 **Codex 专属** 的分组（务必选，否则无法使用）
   - **过期时间**：建议 **永不过期**
   - **新建数量**：默认 1
   - 其他选项保持默认
4. 点击 **提交**，随后复制生成的令牌（`sk-` 开头），下一步要用。

![](/uploads/editor/20261031/img_6ae5e62b013904.24523321.png)

---

## 四、写配置文件

Codex 的配置放在用户目录下的 `.codex` 文件夹里，需要 `auth.json` 和 `config.toml` 两个文件。

| 系统            | 配置目录                      |
| ------------- | ------------------------- |
| Windows       | `C:\Users\<你的用户名>\.codex` |
| macOS / Linux | `~/.codex`                |

### 4.1 Windows：创建目录与文件

1. 打开文件资源管理器，进入 `C:\Users\<你的用户名>`。
2. 若看不到 `.codex` 文件夹，先开启显示隐藏项目：**查看 → 勾选「隐藏的项目」**。

![](/uploads/editor/20261031/img_6ae5e650324ca2.35397232.png)

1. 若没有 `.codex` 文件夹，手动新建该文件夹，并在其中创建 `config.toml`、`auth.json` 两个文件（新建文本文档后改扩展名即可，注意不要留下 `.txt` 后缀）。

![](/uploads/editor/20261031/img_6ae5e65b781b10.45638053.png)

### 4.2 macOS / Linux：创建目录与文件

```bash
mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml
```

用 `vi` 编辑文件：按 `i` 进入插入模式，粘贴内容，按 `ESC`，输入 `:wq` 回车保存退出。

```bash
vi ~/.codex/auth.json
vi ~/.codex/config.toml
```

### 4.3 auth.json

把 `sk-xxx` 替换为你自己的令牌：

```json
{"OPENAI_API_KEY": "sk-xxx"}
```

> 这里只填 Key 本身，**不要**加 `Bearer ` 前缀。

### 4.4 config.toml

整段复制，只需确认 `base_url` 和（可选的）`model`：

```toml
model_provider = "api111"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

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

字段说明：

| 字段                         | 作用                                                                  |
| -------------------------- | ------------------------------------------------------------------- |
| `model_provider`           | 指定使用下面定义的哪个 provider，需与 `[model_providers.xxx]` 同名                  |
| `model`                    | 使用的模型，如 `gpt-5-codex`，需为平台实际提供的模型名                                  |
| `model_reasoning_effort`   | 思考强度，可选 `high` / `medium` / `low`（高 / 中 / 低）                        |
| `disable_response_storage` | `true` 表示不在服务端保存对话记录                                                |
| `preferred_auth_method`    | `apikey` 表示用 API Key 鉴权，而非登录账号                                      |
| `base_url`                 | 中转平台接口地址，填入 `https://api.zaimod.com/v1`                              |
| `wire_api`                 | 接口协议，填 `responses`（Responses API）；若平台仅支持 Chat Completions，改用 `chat` |
| `requires_openai_auth`     | 走 OpenAI 兼容鉴权，保持 `true`                                             |

> `api111` 只是自定义的 provider 标识，可以改成任意名字（如 `cxhao`），但 `model_provider`、`[model_providers.api111]`、`name` 三处必须保持一致，否则 Codex 找不到该 provider。

---

## 五、启动 codex

**先重启终端**（否则新的 PATH 与配置不生效），然后进入工程目录并启动：

```bash
cd your-project-folder
codex
```

出现 Codex 的欢迎界面即启动成功：

![](/uploads/editor/20261031/img_6ae5e6a8819415.70362895.png)

常用内置命令：

| 命令           | 作用                             |
| ------------ | ------------------------------ |
| `/init`      | 生成 `AGENTS.md`，写入给 Codex 的项目说明 |
| `/status`    | 查看当前会话配置与 token 用量             |
| `/model`     | 切换模型与思考强度                      |
| `/approvals` | 设置哪些操作需要人工确认                   |

---

## 六、VSCode 插件 Codex

1. 打开 VSCode，进入扩展商店，搜索 `codex`。
2. 选择发布者为 **OpenAI** 的 **Codex – OpenAI's coding agent**（列表第一个，图标为 OpenAI 标志），点击 **Install**。

![](/uploads/editor/20261031/img_6ae5e6b668e606.64459761.png)

1. 安装完成后，左侧活动栏会出现 Codex 图标，点击即可开始对话。

![](/uploads/editor/20261031/img_6ae5e6c19d06a1.74902129.png)

> 插件与命令行共用 `~/.codex` 下的配置，**必须先完成第四章的配置**，插件才能正常调用。商店里存在多个同名插件，认准发布者 OpenAI。

---

## 七、常见问题

| 现象                             | 排查方向                                                                 |
| ------------------------------ | -------------------------------------------------------------------- |
| `codex: command not found`     | 未重启终端；或 npm 全局目录不在 PATH 中，检查 `npm config get prefix` 后将其加入 PATH      |
| Windows 提示找不到 bash             | 未安装 Git Bash，按 2.1 前置步骤安装                                            |
| `401` / Invalid token          | Key 复制错误（含空格或换行）、令牌已过期，或**分组未选 Codex 专属**——请回控制台重新创建一个令牌             |
| `404` / model not found        | `base_url` 写成 `https://api.zaimod.com`（漏 `/v1`）；或 `model` 名称不在平台可用列表中 |
| 启动后一直转圈、对话中断                   | `wire_api` 与平台接口不匹配：优先用 `responses`，报错时改 `chat` 再试                   |
| 看不到 `.codex` 文件夹               | Windows 未开启「隐藏的项目」；或目录还没创建，按 4.1 手动新建                                |
| 改了配置但没生效                       | 未重启终端；或配置文件里 `model_provider` 与 provider 段名不一致                       |
| Windows 文件变成 `config.toml.txt` | 资源管理器隐藏了扩展名，需先在「查看」中勾选「文件扩展名」再改名                                     |

---

## 附录 A：接口地址变更对照

| 位置                          | 原地址                         | 现地址                        |
| --------------------------- | --------------------------- | -------------------------- |
| `config.toml` 中的 `base_url` | `https://api.zaimod.com/v1` | `https://api.zaimod.com/v1` |
| 控制台 / 令牌获取入口                | `https://api.zaimod.com`    | `https://api.zaimod.com`    |

> Key 由新平台签发，迁移后需在 `https://api.zaimod.com` 重新创建令牌，并同步替换 `auth.json` 中的 `OPENAI_API_KEY`。

## 附录 B：本次整理修正的原文问题

| 原文问题                                                                    | 处理方式                             |
| ----------------------------------------------------------------------- | -------------------------------- |
| Windows / Mac / Linux 三套内容完全重复，同一份配置写了三遍                                | 合并为「通用配置 + 各系统差异」结构，配置只出现一次      |
| 代码块围栏错乱（`npm install -g @openai/codex` 后多了一个反引号），复制会带上多余字符              | 已修正，代码块可直接复制运行                   |
| Homebrew 安装命令中的链接被 Markdown 语法污染，写成 `[https://...](https://...)`，命令无法执行 | 已改为纯文本 URL，可直接复制执行               |
| 「重要提示：把 sk-xxx 替换成真实密钥」连续重复 3 遍                                         | 合并为一处说明                          |
| Mac、Linux 章节中的图片是「[图片]」占位符（原图缺失）                                        | 复用 Windows 同流程截图，并保留文字说明         |
| Linux 章节的终端截图实为 Windows 截图（路径显示 `D:\project\my\FastGPT`）                | 保留图并注明为启动效果示意                    |
| 三个系统写的令牌分组名不一致（`codex专属` / `codex特供` / `codex渠道-gpt`）                   | 统一表述为「Codex 专属类分组」，并说明以控制台实际名称为准 |
| 文末残留空的代码块围栏                                                             | 已删除                              |

上一篇：RikkaHub 配置教程{else}上一篇：没有了下一篇：Clawdbot 中转站配置教程{else}下一篇：没有了