Codex 快速上手

5 分钟完成 Codex CLI 安装和配置 -- 通过 QCode.cc 快速开始 AI 编程

Codex 快速上手 ¶

如果你已经在用 Claude Code，这篇教程让你 5 分钟内也用上 Codex CLI。两者共享 QCode.cc 套餐配额，使用同一个 API 密钥，配置完成后即可在两款工具间自由切换。

如果你还没有 QCode.cc 账号，请先注册并选择套餐。

前置条件 ¶

在开始之前，确保你的环境满足以下要求：

条件	要求	检查方式
Node.js	v22 或更高版本	`node --version`
npm	v10 或更高版本	`npm --version`
Git	任意版本	`git --version`
操作系统	macOS / Linux / Windows（WSL）	-
QCode.cc 密钥	`cr_` 开头的 API 密钥	控制台

注意：Codex 的内核级沙箱功能在 Linux 上表现最佳。macOS 和 Windows WSL 也完全支持，但部分沙箱功能可能受限。

第一步：安装 Codex CLI ¶

选择以下任一方式安装：

方式一：npm 全局安装（推荐）¶

npm install -g @openai/codex

方式二：Homebrew（macOS）¶

brew install openai-codex

方式三：从源码构建 ¶

git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/

安装完成后验证：

codex --version
# 输出类似：codex v0.114.0

第二步：配置 QCode.cc ¶

2.1 创建配置目录 ¶

mkdir -p ~/.codex

2.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"

配置项说明：

字段	说明
`model_provider`	使用自定义 provider `crs`
`model`	默认模型，可选 `gpt-5.4` / `gpt-5.3-codex-spark` 等
`model_reasoning_effort`	推理深度，可选 `low` / `medium` / `high`
`base_url`	QCode.cc 亚太节点地址
`wire_api`	API 协议，使用 `responses`
`env_key`	读取 API 密钥的环境变量名

2.3 创建 auth.json ¶

创建 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "cr_你的密钥"
}

将 cr_你的密钥 替换为你在 QCode.cc 控制台获取的 API 密钥。

2.4 设置环境变量 ¶

环境变量方式作为 auth.json 的替代方案（二选一即可）：

# 临时设置（当前终端有效）
export CRS_OAI_KEY="cr_你的密钥"

# 永久设置（Bash 用户）
echo 'export CRS_OAI_KEY="cr_你的密钥"' >> ~/.bashrc
source ~/.bashrc

# 永久设置（Zsh 用户）
echo 'export CRS_OAI_KEY="cr_你的密钥"' >> ~/.zshrc
source ~/.zshrc

提示：这个密钥与 Claude Code 使用的是同一个。如果你已经在用 Claude Code，密钥在控制台的同一个位置。

第三步：验证配置 ¶

运行一个简单任务测试连接：

codex "输出 hello world"

如果看到 Codex 正常启动并返回响应，说明配置成功。

检查清单 ¶

Codex 能正常启动（无报错）
API 请求通过 QCode.cc 中转（无网络超时）
模型响应正常（能理解中文指令）

如果遇到问题，请跳到常见问题部分。

第四步：第一个实战任务 ¶

让我们用一个实际场景来体验 Codex 的能力。进入一个项目目录：

cd /path/to/your/project

示例 1：分析项目结构 ¶

codex "分析这个项目的目录结构和技术栈，给出简要概述"

示例 2：生成代码 ¶

codex "创建一个 utils/date-formatter.ts 文件，包含以下功能：
  1. 格式化日期为 YYYY-MM-DD
  2. 计算两个日期之间的天数差
  3. 判断是否为工作日
  4. 为每个函数添加完整的 JSDoc 注释和单元测试"

示例 3：批量修改 ¶

codex "将 src/ 下所有 .js 文件转换为 .ts 文件，添加类型注解"

Codex 会在沙箱环境中自主完成任务，执行完毕后展示改动摘要供你审查。

三种权限模式 ¶

Codex 提供三种权限模式，控制自动化程度：

suggest（建议模式）¶

codex --suggest "重构 auth 模块"

只分析和建议，不自动修改任何文件
你需要手动应用建议的改动
适合：学习代码、评估方案

auto-edit（自动编辑模式）¶

codex --auto-edit "添加错误处理"

自动编辑文件，但执行命令前会请求确认
适合：日常开发（推荐的默认模式）

full-auto（完全自动模式）¶

codex --full-auto "运行测试并修复所有失败项"

自动编辑文件 + 自动执行命令，全程无需确认
所有操作在沙箱内进行，不会影响沙箱外的系统
适合：CI/CD 集成、批量任务

你也可以在 config.toml 中设置默认模式：approval_mode = "auto-edit"

常用命令速查 ¶

命令	说明
`codex "你的指令"`	启动 Codex 执行任务
`codex --model gpt-5.4`	指定模型
`codex --full-auto "指令"`	完全自动模式
`codex --suggest "指令"`	仅建议不执行
`codex --auto-edit "指令"`	自动编辑，命令需确认
`codex --version`	查看版本
`codex --help`	查看帮助

可用模型 ¶

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

模型	说明	推荐场景
`gpt-5.4`	最新旗舰模型，1M 上下文	复杂任务
`gpt-5.3-codex-spark`	代码优化版，性价比高	日常开发（推荐）
`gpt-5.2-codex`	稳定版	追求稳定性
`gpt-5.1-codex-max`	高性能版	大型代码库

项目配置：AGENTS.md ¶

在项目根目录创建 AGENTS.md 可以定义 Codex 在该项目中的行为规范，类似 Claude Code 的 CLAUDE.md：

# AGENTS.md

- 使用 TypeScript strict 模式
- 代码风格遵循 ESLint + Prettier
- 测试框架使用 Vitest
- 提交前运行 `npm run lint && npm test`
- 组件文件使用 PascalCase 命名

详细配置请参考 AGENTS.md 配置指南。

与 Claude Code 配合使用 ¶

既然两者共享 QCode.cc 配额，最佳实践是配合使用：

# 终端 1：用 Claude Code 分析问题
$ claude
> 这个性能瓶颈在哪里？帮我分析一下方案

# 终端 2：用 Codex 批量执行
$ codex "按照以下方案优化 src/api/ 下的所有数据库查询：
  1. 添加查询缓存
  2. 优化 N+1 查询
  3. 添加索引建议注释"

更多配合模式请参考 Codex vs Claude Code 深度对比。

下一步 ¶

配置完成，你已经可以开始使用 Codex 了。推荐继续阅读：

AGENTS.md 配置指南 -- 定制 Codex 的项目行为
Codex vs Claude Code 深度对比 -- 了解两者差异和配合技巧
Codex 集成配置 -- 完整配置参考（含 Windows 和多操作系统详细步骤）
命令行技巧 -- Claude Code 高效使用技巧

常见问题 ¶

Q：安装时报错 `npm ERR! EACCES`¶

原因：npm 全局安装目录的权限不足。

解决：

# 方式一：使用 sudo（不推荐长期使用）
sudo npm install -g @openai/codex

# 方式二：配置 npm 使用用户目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex