# Codex 完整教程

> **最后核实**：2026-09-18 · 📄 依据官方文档（Codex CLI v0.155.0，2026-09-17 发布） · 5.4 的 profile 行为另经本机实测（✅ codex-cli 0.155.0，独立 HOME，未发模型请求）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | GPT ✅（Responses 腿）· Claude ❌ · 国产 ❌（Responses 腿不服务国产）· Gemini ❌ |
| 协议与 Base URL | Codex 用 OpenAI Responses：config.toml 里 `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` |
| 配置位置 | `~/.codex/config.toml`（Windows 在 `%USERPROFILE%\.codex\`） |
| 官方文档 | [openai/codex](https://github.com/openai/codex) |

> 📖 Codex `base_url` 和 Claude 的 `ANTHROPIC_BASE_URL` 为何不同？`/openai` 和 `/openai/v1` 怎么区分？见 [接入点与 API 格式](../getting-started/endpoints-and-api-paths)。

本文是一篇面向中国开发者的 **Codex CLI 完整教程**，从零开始带你安装、配置、使用 OpenAI Codex CLI，并通过 QCode.cc 享受低成本、低延迟的 AI 编程体验。无论你是第一次接触 AI 编程工具，还是已经在用 Claude Code 想尝试新工具，这篇教程都适合你。

---

## 一、Codex 简介

### 什么是 OpenAI Codex CLI？

[Codex CLI](https://github.com/openai/codex) 是 OpenAI 推出的**开源命令行 AI 编程助手**（Apache 2.0 许可），使用 Rust 编写，可以在终端中直接运行。它能够：

- **阅读和理解**你的代码仓库
- **编辑文件**并生成新代码
- **执行命令**（如运行测试、安装依赖）
- **自主迭代**直到任务完成

Codex 的核心哲学是**自主式代理（Autonomous Agent）**：你描述任务，Codex 在沙箱中自主完成，最后你审核结果。这与 Claude Code 的**交互式对话**风格形成互补。

### Codex 的发展历程

"Codex" 这个名字在 OpenAI 的产品线中经历了多次演变：

- **2021 年**：最早的 Codex 是 GPT-3 的代码微调版本，为 GitHub Copilot 提供动力
- **2024 年**：OpenAI 重新启用 Codex 品牌，推出云端异步 AI 编程代理
- **2025-2026 年**：Codex CLI 发展为成熟的本地命令行工具，使用 Rust 重写，支持 MCP、Skills、多 Agent 等高级功能

现在的 Codex 是一个多界面产品：包括 **CLI 命令行工具**（本文重点）、**macOS 桌面应用**、**IDE 插件**、以及集成在 ChatGPT 中的**云端代理**。通过 QCode.cc 使用的是 CLI 版本。

### Codex 与 Claude Code 的核心区别

| 维度 | Codex CLI | Claude Code |
|------|-----------|-------------|
| 执行风格 | 自主执行，完成后交付结果 | 交互式对话，逐步确认 |
| 开源 | 完全开源（Apache 2.0） | 不开源 |
| 编写语言 | Rust（启动快、资源占用低） | TypeScript |
| 沙箱安全 | 内置 Landlock/seccomp 沙箱 | 权限提示确认 |
| 指令文件 | `AGENTS.md` | `CLAUDE.md` |
| 云端代理 | 支持（ChatGPT 内置） | 不支持 |

简单来说：**Codex 擅长"甩手任务"**（给一个明确的需求，让它自己跑完），**Claude Code 擅长"结对编程"**（边讨论边修改，适合探索性任务）。两者配合使用效果最佳。

### 为什么通过 QCode.cc 使用 Codex？

Codex CLI 默认需要 OpenAI API Key 或 ChatGPT 订阅，但在中国大陆存在两个问题：

1. **网络不可达**：OpenAI API 无法直接访问
2. **费用高昂**：官方 GPT-5.3-Codex 的 token 价格不低

通过 QCode.cc，你可以：

- **全球多接入点低延迟访问**（`api.qcode.cc` 全球路由 / `us` / `eu` / `asia` 备用，CN 用户推荐 `asia.qcode.cc` 亚洲节点，HK/JP 就近），无需翻墙或自建代理
- **成本降低高达 80%**，相比官方价格大幅节省
- **Claude Code 与 Codex 共享套餐配额**，一份套餐两个工具都能用
- **多节点可用**（全球 Route 53 + HK / US / EU 备用），保障连接稳定性

---

## 二、安装 Codex CLI

### 系统要求

在安装之前，请确认你的环境满足以下条件：

- **操作系统**：macOS 12+、Ubuntu 20.04+、Windows 10+（推荐使用 WSL2）
- **Node.js**：v22 LTS 或更高版本（npm 安装方式需要）
- **Git**：2.x 或更高版本（Codex 需要 Git 来感知代码仓库）
- **磁盘空间**：约 200MB（包括 npm 依赖）

### 方法一：npm 安装（推荐）

这是最通用的安装方式，适用于所有操作系统：

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

> **提示**：如果遇到权限问题，macOS/Linux 用户可以加 `sudo`，或者使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 来避免权限问题。

> **中国用户**：如果 npm 下载速度慢，可以使用淘宝镜像：
> ```bash
> npm install -g @openai/codex --registry=https://registry.npmmirror.com
> ```

### 方法二：Homebrew 安装（macOS）

macOS 用户也可以通过 Homebrew 安装：

```bash
brew install --cask codex
```

Homebrew 的优势是会自动管理依赖和更新。

### 方法三：直接下载二进制（高级）

从 [GitHub Releases](https://github.com/openai/codex/releases) 页面下载对应平台的预编译二进制文件，放到 `PATH` 目录中即可。这种方式不依赖 Node.js。

```bash
# 示例：下载并安装 Linux x64 版本
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64
chmod +x codex-linux-x64
sudo mv codex-linux-x64 /usr/local/bin/codex
```

### 验证安装

```bash
codex --version
```

如果看到版本号输出，说明安装成功。不要拿文档里的数字当「当前最新」——以 [GitHub Releases](https://github.com/openai/codex/releases) 和 [npm `@openai/codex`](https://www.npmjs.com/package/@openai/codex) 为准，本机用 `codex --version` 查看。

### 配置 Shell 自动补全（可选）

Codex 支持 Shell 自动补全，输入命令时按 `Tab` 即可提示：

```bash
# Zsh 用户
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash 用户
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc
```

> 如果 Zsh 提示 `command not found: compdef`，在 `eval` 之前添加 `autoload -Uz compinit && compinit`。

---

## 三、QCode.cc 配置

Codex CLI 需要配置两个文件来连接 QCode.cc 服务：

- `~/.codex/config.toml` — 服务端点和模型配置
- `~/.codex/auth.json` — API 密钥认证

### 步骤 1：创建配置目录

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
mkdir $HOME\.codex
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

```bash
mkdir -p ~/.codex
```

</div>

<div data-os="linux" markdown="1">

**Linux：**

```bash
mkdir -p ~/.codex
```

</div>

### 步骤 2：创建 config.toml

在 `~/.codex/config.toml` 写入以下内容：

```toml
model_provider = "crs"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

**config.toml 字段详解：**

| 字段 | 说明 |
|------|------|
| `model_provider` | 使用的模型提供商名称，这里设为自定义的 `crs` |
| `model` | 默认模型，编程场景推荐 `gpt-5.6-terra` |
| `model_reasoning_effort` | 推理强度：`low`、`medium`、`high`。越高越准但越慢 |
| `disable_response_storage` | 禁止 OpenAI 存储对话内容（隐私保护） |
| `preferred_auth_method` | 认证方式，设为 `apikey` 使用 API 密钥 |
| `base_url` | QCode.cc 接入点地址（示例用 `api.qcode.cc` 全球入口；其他接入点见[接入点与 API 格式](../getting-started/endpoints-and-api-paths)）|
| `wire_api` | API 协议类型，Codex 使用 `responses` |
| `requires_openai_auth` | 需要携带 OpenAI 格式的认证头 |
| `env_key` | 环境变量名，Codex 会从该变量读取 API 密钥 |

### 步骤 3：创建 auth.json

在 `~/.codex/auth.json` 写入以下内容：

```json
{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}
```

> 将 `cr_xxxxxxxxxx` 替换为你的 [QCode.cc API 密钥](https://qcode.cc/dashboard)。密钥以 `cr_` 开头。

**auth.json 说明：**

- 此文件为 Codex 提供 API 密钥，等同于设置 `OPENAI_API_KEY` 环境变量
- 文件权限建议设为 `600`（仅本人可读写）：`chmod 600 ~/.codex/auth.json`
- 如果同时存在 `auth.json` 和环境变量，`auth.json` 优先

### 步骤 4：设置环境变量（可选替代方案）

如果你更喜欢通过环境变量提供密钥（而不是 `auth.json`），可以设置 `CRS_OAI_KEY`：

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
# 临时设置（当前会话）
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"

# 永久设置（写入用户环境变量）
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

```bash
# 临时设置
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# 永久设置
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

<div data-os="linux" markdown="1">

**Linux：**

```bash
# 临时设置
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# 永久设置（Bash）
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# 永久设置（Zsh）
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

使用环境变量时，将 `auth.json` 中的 `OPENAI_API_KEY` 设为 `null`：

```json
{
  "OPENAI_API_KEY": null
}
```

### 可用模型

通过 QCode.cc 可使用以下 Codex/GPT 模型：

| 模型 | 说明 | 推荐场景 |
|------|------|----------|
| **`gpt-5.5`** | 最新旗舰，1M 上下文 | 高端能力优先（推荐 ★）|
| **`gpt-5.4`** 🔥 | 最新一代 GPT，1M 上下文 | 日常复杂任务（推荐）|
| `gpt-5.6-mini` | 轻量版，272K 上下文，速度快 | 轻量/性价比 |
| `gpt-5.6-terra` | GPT-5.6 旗舰，针对代码优化 | 编程/Codex 场景（推荐）|

> 所有模型与 Claude Code **共享** QCode.cc 套餐配额。切换模型不需要额外付费。

---

## 四、基础使用教程

### 4.1 启动 Codex

打开终端，进入你的项目目录，然后运行：

```bash
cd /path/to/your/project
codex
```

Codex 会启动一个终端交互界面（TUI），你可以在其中输入自然语言指令。界面由以下部分组成：

- **顶部状态栏**：显示当前模型、审批模式、沙箱状态
- **主区域**：AI 的回复和操作日志
- **底部输入框**：你输入指令的地方

你也可以直接在命令行给出任务（非交互模式），适合脚本调用：

```bash
# 交互式启动
codex

# 非交互模式：执行单个任务后退出
codex "阅读这个项目的结构并给我一个概览"

# 附带图片的任务
codex -i screenshot.png "修复截图中显示的 UI 问题"

# 指定模型
codex -m gpt-5.4 "重构认证模块的错误处理"
```

### 4.2 第一个任务：让 Codex 写一个函数

让我们从一个简单的例子开始。在项目目录下运行 Codex，输入：

```text
写一个 Python 函数，接受一个字符串列表，返回其中最长的字符串。如果有多个同样长度的，返回第一个。保存到 utils.py 文件中。
```

Codex 会执行以下步骤：

1. **规划**：分析你的需求，制定实现方案
2. **生成代码**：创建 `utils.py` 并写入函数
3. **请求确认**：在默认模式下，Codex 会展示即将进行的文件修改，等你确认

你会看到类似这样的提示：

```text
Codex wants to create file: utils.py
─────────────────────────────────────
+ def find_longest(strings: list[str]) -> str:
+     """返回列表中最长的字符串，如有多个则返回第一个。"""
+     if not strings:
+         raise ValueError("列表不能为空")
+     return max(strings, key=len)

Accept? [y/n]
```

输入 `y` 确认，Codex 就会将代码写入文件。

接下来，你可以继续给出更多指令，Codex 会在同一会话中保持上下文：

```text
再为这个函数写一个单元测试，使用 pytest
```

Codex 会自动读取刚才创建的 `utils.py`，然后生成对应的测试文件。

### 4.3 理解 Codex 的沙箱执行模式

这是 Codex 最重要的安全特性之一。Codex 在**沙箱**中执行命令，有三个安全级别：

| 沙箱模式 | 文件读取 | 文件写入 | 命令执行 | 网络访问 |
|----------|---------|---------|---------|---------|
| `read-only` | 允许 | 需确认 | 需确认 | 需确认 |
| `workspace-write`（默认） | 允许 | 工作区内允许 | 工作区内允许 | 默认禁止 |
| `danger-full-access` | 允许 | 全部允许 | 全部允许 | 允许 |

默认的 `workspace-write` 模式是日常开发的最佳选择：Codex 可以在项目目录内自由读写文件和运行命令，但不能访问项目外的文件或网络。

**如果你的任务需要联网**（比如 `npm install`），可以临时启用网络访问：

```bash
codex -c 'sandbox_workspace_write.network_access=true' "安装依赖并运行测试"
```

### 4.4 审核和接受 Codex 的修改

Codex 对文件的修改遵循**审批策略（Approval Policy）**。默认情况下：

- **文件编辑**：展示 diff 并等你确认
- **Shell 命令**：展示命令内容并等你确认

当 Codex 提出修改时，你可以：

- **接受（y）**：应用修改
- **拒绝（n）**：跳过此修改
- **查看详情**：仔细阅读 diff 后再决定

> **提示**：使用 `/diff` 斜杠命令可以随时查看当前会话中所有已应用的修改。

### 4.5 常用交互技巧

**文件引用**：输入 `@` 后跟文件名，Codex 会自动读取该文件内容：

```text
查看 @src/app.py 并优化错误处理
```

**执行 Shell 命令**：以 `!` 开头可以直接运行命令，输出会传递给 Codex：

```text
!cat error.log
分析上面的错误日志，找出根本原因
```

**追加指令**：Codex 运行时，按 `Enter` 可以插入新指令，按 `Tab` 可以排队下一轮指令。

**回溯编辑**：在输入框为空时按 `Esc` 两次，可以回到上一条消息并修改重发。继续按 `Esc` 可以回溯到更早的消息，然后按 `Enter` 从该点分叉出新的对话线。

**管道输入**：可以将其他命令的输出通过管道传给 Codex 分析：

```bash
# 分析最近的 git 变更
git diff HEAD~3 | codex "审查这些变更，找出潜在问题"

# 分析错误日志
cat /var/log/app/error.log | codex "分析这些错误的根本原因"

# 审查 PR
gh pr diff 42 | codex "审查这个 PR 的代码质量和安全性"
```

**键盘快捷键**：

| 快捷键 | 功能 |
|--------|------|
| `Tab` | 自动补全文件路径（配合 `@` 使用） |
| `Enter` | 在 Codex 运行时插入新指令 |
| `Tab` | 在 Codex 运行时排队下一轮指令 |
| `Esc` x 2 | 回溯到上一条消息编辑 |
| `Ctrl+C` | 取消当前操作 |

**斜杠命令**：

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/mode` | 切换审批模式 |
| `/diff` | 查看所有变更 |
| `/mcp` | 查看已连接的 MCP 服务器 |
| `/status` | 显示当前会话状态 |
| `/compact` | 压缩对话历史以节省 token |
| `/permissions` | 查看和修改权限设置 |
| `/review` | 代码审查 |

---

## 五、高级配置

### 5.1 自定义指令文件（AGENTS.md）

Codex 支持 `AGENTS.md` 文件来给 AI 提供项目上下文和工作规范，作用类似 Claude Code 的 `CLAUDE.md`。

**项目级指令**：在项目根目录创建 `AGENTS.md`：

```markdown
# AGENTS.md

## 项目说明
这是一个 FastAPI 后端项目，使用 PostgreSQL 数据库。

## 代码规范
- 所有函数必须有类型注解
- 新增 API 端点需要同步编写测试
- 提交前运行 `make lint` 检查代码风格

## 测试命令
- 单元测试：`pytest tests/unit/`
- 集成测试：`pytest tests/integration/`
- 代码检查：`make lint`
```

**全局指令**：在 `~/.codex/AGENTS.md` 创建全局默认规则，所有项目都会继承：

```markdown
# 全局指令

- 始终使用中文进行交流
- 代码注释使用英文
- 偏好函数式编程风格
- 生成的代码必须包含错误处理
```

**子目录覆盖**：在特定目录下创建 `AGENTS.override.md` 可以覆盖上级规则：

```markdown
# services/payments/AGENTS.override.md

- 本目录下的所有变更必须写入审计日志
- 金额计算使用 Decimal 类型，不使用浮点数
```

Codex 按以下顺序查找指令文件：`AGENTS.override.md` > `AGENTS.md` > 配置的 fallback 文件。合并后的总大小上限默认为 32KB，可通过 `project_doc_max_bytes` 调整。

### 5.2 调整审批模式（Approval Mode）

Codex 的三种审批模式适合不同的使用场景：

#### Suggest 模式（最安全）

**所有操作都需要你手动确认**，包括文件编辑和命令执行。适合学习阶段或审查敏感代码。

```bash
codex --approval-mode suggest
```

#### Auto-Edit 模式（推荐日常使用）

**文件编辑自动执行，命令执行仍需确认**。在效率和安全之间取得良好平衡。

```bash
codex --approval-mode auto-edit
```

#### Full-Auto 模式（完全自主）

**所有操作都自动执行**，无需任何确认。仅建议在隔离环境（如 Docker 容器、CI/CD）中使用。

> 🔴 **`--full-auto` 已被移除。** 改用 `--sandbox workspace-write`：

```bash
codex --sandbox workspace-write
```

> **安全提示**：`--sandbox workspace-write` 保留沙箱保护（限制在工作区内）。如果你需要完全不受限，使用 `--dangerously-bypass-approvals-and-sandbox`，但**强烈不建议**在非隔离环境中使用。

**自动审核审批**（`--approve-for-me`，0.147.0 / 2026-08-07 新增）：让 Codex 在执行前自动审核并批准低风险操作，介于「每步都问」和「完全放开」之间。

```bash
codex --approve-for-me
```

> ⚠️ Codex 的 flag 变动很快（`--full-auto` 就是被删掉的例子）。**以 `codex --help` 的实际输出为准**，不要照抄任何文档里的 flag 清单，包括本页。

**在 config.toml 中设置默认模式**：

```toml
# 个人开发推荐
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

**会话中切换模式**：使用 `/mode` 命令无需重启即可切换：

```text
/mode suggest      # 切换到 suggest 模式
/mode auto-edit    # 切换到 auto-edit 模式
/mode full-auto    # 切换到 full-auto 模式
```

#### 各场景推荐配置

| 场景 | 审批模式 | 沙箱模式 |
|------|---------|---------|
| 个人日常开发 | `auto-edit` | `workspace-write` |
| 团队共享环境 | `suggest` | `workspace-write` |
| CI/CD 流水线 | `full-auto` | `workspace-write` |
| 学习和实验 | `suggest` | `workspace-write` |
| 一次性脚本任务 | `full-auto` | `danger-full-access` |

### 5.3 配置 MCP 服务器

Codex 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)，可以连接外部工具来扩展能力。

**通过命令行添加 MCP 服务器**：

```bash
codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json
```

**通过 config.toml 配置**：

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }
```

配置完成后重启 Codex，使用 `/mcp` 命令查看已连接的服务器。MCP 工具会自动出现在 Codex 的可用工具列表中，与内置工具并列。

**将 Codex 本身作为 MCP 服务器**：Codex 也可以反向运行为 MCP 服务器，被其他 AI Agent 调用。这在构建多 Agent 系统时非常有用。

### 5.4 配置 Profile（多环境管理）

如果你在不同项目里要用不同配置（例如工作项目一套、个人项目一套），用 Profile。**从 Codex 0.134.0 起，写在 `config.toml` 里的 `[profiles.<名称>]` 老写法已经作废**，改成「一个 profile 一个文件」：`~/.codex/<名称>.config.toml`。下面三段就是新写法的完整形态：

```toml
# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "crs"
model = "gpt-5.6-terra"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

```toml
# ~/.codex/work.config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
```

```toml
# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
model_reasoning_effort = "medium"
```

启动时指定：

```bash
codex --profile work "重构认证模块"
codex --profile personal "写一个小脚本"
```

✅ 下面三条是**本机实测**到的行为（codex-cli 0.155.0，linux-x86_64，独立沙箱 HOME，未发出任何模型请求），也是最常见的坑：

- 留着老表再 `--profile`，是**硬报错**而不是静默忽略：

  ```text
  Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.
  ```

- 顶层的 `profile = "work"` 选择器同样已废：

  ```text
  Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead
  ```
- **不传 `--profile` 时，残留的 `[profiles.*]` 表根本不参与解析**——`codex doctor` 照样显示 `config.toml parse ok`，用的仍是顶层值。所以「没报错」不等于「生效了」，迁移时把老表删掉。

另外 `--profile` 只对运行类子命令有效（`codex`、`exec`、`review`、`resume`、`queue`、`archive`、`delete`、`unarchive`、`fork`、`mcp`、`sandbox`、`debug prompt-input`）；挂到 `doctor` 上会直接报 `--profile only applies to runtime commands ...`。profile 文件是叠在用户配置之上、项目配置与命令行之下的一层，见 5.6。

### 5.5 非交互模式（脚本与自动化）

Codex 不仅可以交互使用，还可以在脚本和 CI/CD 流水线中作为非交互工具运行。直接传递 prompt 参数即可：

```bash
# 基本用法：执行任务后退出
codex "为 README.md 添加安装说明"

# Full-Auto + 非交互：完全自主执行
codex --sandbox workspace-write "运行测试套件，修复所有失败的测试"

# 输出 transcript 到文件（用于审计）
codex --sandbox workspace-write --transcript output.jsonl "重构错误处理模块"
```

**在 CI/CD 中使用 Codex**：

```yaml
# GitHub Actions 示例
- name: Auto-fix lint errors
  run: |
    npx @openai/codex --sandbox workspace-write "运行 eslint --fix 修复所有 lint 错误，然后提交修复"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}
```

**Codex SDK**：如果需要在自己的程序中调用 Codex，可以使用官方 SDK 进行编程式调用，将 Codex 嵌入到你自己的开发工具或工作流中。

### 5.6 配置优先级

当多个配置源存在冲突时，Codex 按以下优先级（从高到低）解析：

1. **命令行参数**（`--model`、`-c` 等）
2. **项目配置**（`.codex/config.toml`，从项目根到当前目录，最近的优先；目录被信任后才加载，而且项目层里的 `model_provider`、`model_providers`、`profile`、`profiles` 等键会被 Codex 忽略）
3. **Profile 文件**（`--profile <name>` 指定的 `~/.codex/<name>.config.toml`）
4. **用户配置**（`~/.codex/config.toml`）
5. **系统配置**（`/etc/codex/config.toml`，Unix 系统）
6. **内置默认值**

理解这个优先级有助于你在不同层级精准控制行为。例如，在 `~/.codex/config.toml` 设置通用默认值，在项目的 `.codex/config.toml` 中覆盖特定设置，再用命令行参数做一次性调整。

---

## 六、Claude Code vs Codex 对比

一句话：**Claude Code 是交互式结对编程，Codex 是自主任务执行**。Claude Code 适合探索性调试、复杂重构、架构理解；Codex 适合需求明确的功能开发、批量迁移、CI/CD 自动化。指令文件分别是 `CLAUDE.md` 与 `AGENTS.md`，两者都完整支持 MCP，并且**共享同一份 QCode.cc 套餐配额**，切换成本为零。

执行模式、上下文窗口、沙箱、多 Agent、是否开源等 13 个维度的逐项对比 → [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code)。

---

## 七、实战示例

下面通过几个真实场景演示 Codex 的使用方式。每个示例都包含具体命令和预期效果。

### 示例 1：理解一个新项目

当你接手一个不熟悉的代码库时：

```bash
cd /path/to/new/project
codex
```

在交互界面中：

```text
这个项目是做什么的？请分析目录结构、主要模块、技术栈，
并给出一个简洁的架构图（用 ASCII art）。
```

Codex 会扫描项目中的文件，分析 `package.json`、`requirements.txt`、`go.mod` 等依赖文件，阅读关键入口文件，然后给出全面的项目概览。

### 示例 2：代码审查

```bash
codex "审查 src/ 目录下最近一次 git commit 的所有修改。重点关注：
1. 潜在的 bug（空指针、边界条件）
2. 安全风险（SQL 注入、XSS、硬编码密钥）
3. 性能问题（N+1 查询、不必要的循环）
给出具体的代码位置和修复建议。"
```

### 示例 3：批量重构

```bash
codex --sandbox workspace-write "把项目中所有 Python 文件的 print() 调用替换为 logging 模块。
具体要求：
1. 在每个文件顶部 import logging
2. 创建 logger = logging.getLogger(__name__)
3. print() 替换为 logger.info()
4. 保持原有的格式化字符串
5. 替换完成后运行 pytest 确保没有破坏任何东西"
```

Codex 会逐个文件处理，保持代码一致性，并在最后运行测试验证。

### 示例 4：编写完整的测试套件

```bash
codex "为 src/services/user_service.py 编写完整的单元测试。要求：
1. 使用 pytest + pytest-mock
2. 覆盖所有公共方法
3. 包含正常路径和异常路径测试
4. Mock 外部依赖（数据库、HTTP 请求）
5. 测试文件保存到 tests/unit/test_user_service.py
6. 运行测试确认全部通过"
```

### 示例 5：自主修复测试

Full-Auto 模式的经典用例 — 让 Codex 自主修复失败的测试：

```bash
codex --sandbox workspace-write "运行所有测试。如果有失败的：
1. 分析失败原因
2. 修复代码（不是修复测试）
3. 重新运行测试
4. 重复以上步骤直到所有测试通过
最后给出修复摘要。"
```

### 示例 6：从设计稿实现 UI

```bash
codex -i design.png "根据这张设计稿，用 React + Tailwind CSS 实现这个页面。
要求：
1. 响应式布局（支持移动端）
2. 像素级还原设计稿
3. 组件拆分合理
4. 添加基本的交互状态（hover、focus）"
```

### 示例 7：数据库迁移

```bash
codex "我需要给 users 表添加一个 avatar_url 字段（varchar 500, nullable）。
请：
1. 创建 Alembic 迁移脚本
2. 更新 SQLAlchemy 模型
3. 更新相关的 Pydantic schema
4. 更新 CRUD 操作函数
5. 添加对应的 API 端点（GET/PUT）
6. 运行迁移并确认成功"
```

### 示例 8：在 CI/CD 中自动生成 Changelog

```bash
codex --sandbox workspace-write "分析从上次 release tag 到现在的所有 git commit，
按照 conventional commits 规范分类，
生成 CHANGELOG.md 的更新内容。
包含：新功能、Bug 修复、破坏性变更、其他改进。"
```

---

## 八、常见问题

### 配置文件未找到

**问题**：Codex 提示找不到配置文件或无法加载配置

**解决**：

1. 检查配置目录是否存在：`ls ~/.codex/`
2. 确认 `config.toml` 和 `auth.json` 两个文件都存在
3. 检查 `config.toml` 的 TOML 语法是否正确（常见错误：缺少引号、拼写错误）
4. 使用 `codex --config-dump` 查看实际加载的配置

### API 密钥认证失败

**问题**：提示 `401 Unauthorized` 或 API Key 无效

**解决**：

1. 确认 API 密钥格式正确（以 `cr_` 开头）
2. 检查 `auth.json` 中的密钥是否完整（没有多余空格或换行）
3. 如果使用环境变量，确认变量名是 `CRS_OAI_KEY`（与 `config.toml` 中的 `env_key` 一致）
4. 登录 [QCode.cc 控制台](https://qcode.cc/dashboard) 确认密钥状态和剩余配额

### 网络连接问题

**问题**：无法连接到 QCode.cc 服务，超时或拒绝连接

**解决**：

1. 检查网络是否正常：`curl -I https://api.qcode.cc`
2. 验证 `base_url` 配置是否正确（必须是 `https://api.qcode.cc/openai`）
3. 尝试备用节点：
   - 备用节点：`https://asia.qcode.cc/openai`
4. 如果使用公司代理/VPN，确认代理设置不会阻断 HTTPS 请求

### 模型选择建议

**问题**：不确定该选哪个模型

**建议**：

| 你的需求 | 推荐模型 | 理由 |
|---------|---------|------|
| 编程任务 | `gpt-5.6-terra` | 针对代码优化 |
| 复杂任务 | `gpt-5.4` | 通用能力强、1M 上下文 |
| 轻量任务 | `gpt-5.6-mini` | 消耗配额更少 |
| 最强能力 | `gpt-5.5` | 最新旗舰 |

在 `config.toml` 中设置默认模型后，也可以临时切换：

```bash
codex -m gpt-5.4 "分析这个复杂的并发 bug"
```

### 沙箱限制导致命令失败

**问题**：Codex 尝试执行的命令被沙箱拒绝

**解决**：

1. 如果是联网操作（如 `npm install`），临时启用网络：
   ```bash
   codex -c 'sandbox_workspace_write.network_access=true' "安装依赖"
   ```
2. 如果需要写入项目目录外的文件，可以临时扩展可写范围：
   ```bash
   codex --sandbox danger-full-access "将输出保存到 /tmp/result.txt"
   ```
3. 在会话中使用 `/permissions` 查看和调整当前权限

### 费用说明

**问题**：Codex 和 Claude Code 的费用如何计算？

**说明**：

- Codex 和 Claude Code **共享 QCode.cc 套餐配额**
- 同一份套餐可以同时被两个工具使用
- 费用按实际 token 消耗计算，不按工具区分
- Full-Auto 模式下 Codex 会自主迭代多轮，单次任务的 token 消耗可能较高，但节省了开发者的交互时间
- 建议使用 `/cost` 命令查看当前会话的 token 用量，或在 [QCode.cc 控制台](https://qcode.cc/dashboard) 查看整体配额使用情况

### AGENTS.md 与 CLAUDE.md 可以共存吗？

**可以**。如果你的项目同时被 Codex 和 Claude Code 使用：

- Codex 只读 `AGENTS.md`，忽略 `CLAUDE.md`
- Claude Code 只读 `CLAUDE.md`，忽略 `AGENTS.md`
- 两者互不干扰，你可以为不同工具维护各自的指令文件
- 建议保持两份文件的核心规范一致（如测试命令、代码风格等）

---

## 十、相关文档

- [环境变量配置](/docs/getting-started/environment) — Claude Code 的环境变量设置
- [快速上手](/docs/getting-started/quick-start) — Claude Code 快速入门
- [Aider 集成](/docs/ide/aider) — 另一个开源 AI 编程助手的配置
- [CLI 技巧](/docs/usage/cli-tips) — Claude Code 的命令行进阶用法
- [工作流技巧](/docs/usage/workflow-tips) — 提升 AI 编程效率的工作流建议