Codex 完整教程

从安装到精通 — OpenAI Codex CLI 配合 QCode.cc 的完整使用指南

Codex 完整教程¶

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

一、Codex 简介¶

什么是 OpenAI Codex CLI？¶

Codex CLI 是 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 擅长"甩手任务"（给一个明确的需求，让它自己跑完），Claude Code 擅长"结对编程"（边讨论边修改，适合探索性任务）。两者配合使用效果最佳。

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

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

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

通过 QCode.cc，你可以：

• 亚太节点低延迟访问，无需翻墙或自建代理
• 成本降低高达 80%，相比官方价格大幅节省
• Claude Code 与 Codex 共享套餐配额，一份套餐两个工具都能用
• 多节点可用（亚太主节点、香港、深圳），保障连接稳定性

二、安装 Codex CLI¶

系统要求¶

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

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

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

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

npm install -g @openai/codex

提示：如果遇到权限问题，macOS/Linux 用户可以加 sudo，或者使用 nvm 管理 Node.js 来避免权限问题。

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

方法二：Homebrew 安装（macOS）¶

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

brew install openai-codex

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

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

从 GitHub Releases 页面下载对应平台的预编译二进制文件，放到 PATH 目录中即可。这种方式不依赖 Node.js。

# 示例：下载并安装 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

验证安装¶

codex --version

如果看到版本号输出（如 0.114.0），说明安装成功。

当前最新版本：v0.114.0（2026-03-11），支持 Skills 系统、Hooks 引擎、MCP 协议等新功能。

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

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

# 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：创建配置目录¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

步骤 2：创建 config.toml¶

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

model_provider = "crs"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

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

config.toml 字段详解：

步骤 3：创建 auth.json¶

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

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

将 cr_xxxxxxxxxx 替换为你的 QCode.cc API 密钥。密钥以 cr_ 开头。

auth.json 说明：

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

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

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

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

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

# 临时设置
export CRS_OAI_KEY="cr_xxxxxxxxxx"

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

# 临时设置
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

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

{
  "OPENAI_API_KEY": null
}

可用模型¶

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

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

四、基础使用教程¶

4.1 启动 Codex¶

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

cd /path/to/your/project
codex

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

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

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

# 交互式启动
codex

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

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

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

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

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

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

Codex 会执行以下步骤：

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

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

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 会在同一会话中保持上下文：

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

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

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

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

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

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

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

4.4 审核和接受 Codex 的修改¶

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

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

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

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

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

4.5 常用交互技巧¶

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

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

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

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

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

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

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

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

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

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

键盘快捷键：

斜杠命令：

五、高级配置¶

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

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

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

# AGENTS.md

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

## 代码规范

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

## 测试命令

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

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

# 全局指令

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

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

# services/payments/AGENTS.override.md

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

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

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

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

Suggest 模式（最安全）¶

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

codex --approval-mode suggest

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

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

codex --approval-mode auto-edit

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

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

codex --full-auto
# 等同于：--approval-mode full-auto --sandbox workspace-write

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

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

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

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

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

各场景推荐配置¶

5.3 配置 MCP 服务器¶

Codex 支持 Model Context Protocol (MCP)，可以连接外部工具来扩展能力。

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

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

通过 config.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（多环境管理）¶

如果你在不同项目中使用不同配置（比如工作项目用一个 API Key，个人项目用另一个），可以利用 Profile 功能：

# ~/.codex/config.toml

# 默认配置
model_provider = "crs"
model = "gpt-5.3-codex-spark"

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

# 工作项目 Profile
[profiles.work]
model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"

# 个人项目 Profile（省费用）
[profiles.personal]
model = "gpt-5.2-codex"
model_reasoning_effort = "medium"

使用指定 Profile 启动：

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

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

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

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

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

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

在 CI/CD 中使用 Codex：

# GitHub Actions 示例

- name: Auto-fix lint errors
  run: |
    npx @openai/codex --full-auto "运行 eslint --fix 修复所有 lint 错误，然后提交修复"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}

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

5.6 配置优先级¶

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

1. 命令行参数（--model、-c 等）
2. Profile 值（--profile <name> 指定的 Profile）
3. 项目配置（.codex/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，下面的对比可以帮你理解两个工具的定位差异：

哪个更适合你？¶

选择 Claude Code 的场景：

• 探索性调试，需要边看边调整方向
• 复杂的代码重构，需要实时讨论方案
• 大型代码库的架构分析和理解
• 需要丰富的 IDE 工具集成（LSP、浏览器、搜索等）
• 需要超长上下文（1M token Beta）处理大量代码

选择 Codex 的场景：

• 需求明确的功能开发（"实现 XX 接口"）
• 批量文件处理和代码迁移
• CI/CD 流水线中的自动化任务
• 需要并行处理多个独立任务
• 偏好开源工具，需要审计和定制
• 使用 Docker 沙箱进行安全隔离

最佳实践：两者配合使用 — 用 Claude Code 做规划和探索，用 Codex 做执行和批量操作。两个工具共享 QCode.cc 套餐配额，切换成本为零。

七、实战示例¶

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

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

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

cd /path/to/new/project
codex

在交互界面中：

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

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

示例 2：代码审查¶

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

示例 3：批量重构¶

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

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

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

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 自主修复失败的测试：

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

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

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

示例 7：数据库迁移¶

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¶

codex --full-auto "分析从上次 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 控制台 确认密钥状态和剩余配额

网络连接问题¶

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

解决：

1. 检查网络是否正常：curl -I https://asia.qcode.cc
2. 验证 base_url 配置是否正确（必须是 https://asia.qcode.cc/openai）

3. 尝试备用节点：

4. 香港节点：http://103.218.243.5/openai

5. 深圳节点：http://103.236.53.153/openai
6. 如果使用公司代理/VPN，确认代理设置不会阻断 HTTPS 请求

模型选择建议¶

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

建议：

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

codex -m gpt-5.1-codex-max "分析这个复杂的并发 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 控制台 查看整体配额使用情况

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

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

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

九、QCode.cc 优势¶

十、相关文档¶

• 环境变量配置 — Claude Code 的环境变量设置
• 快速上手 — Claude Code 快速入门
• Aider 集成 — 另一个开源 AI 编程助手的配置
• CLI 技巧 — Claude Code 的命令行进阶用法
• 工作流技巧 — 提升 AI 编程效率的工作流建议