# Codex 快速上手

> ⚡ **推荐：一键配置** —— `curl -fsSL https://qcode.cc/install/codex.sh | bash`（Windows：`irm https://qcode.cc/install/codex.ps1 | iex`）自动完成安装 CLI、写入 `~/.codex` 配置、连通验证。详见 [一键配置脚本](/docs/getting-started/one-click-install)。手动配置请继续阅读。

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

如果你还没有 QCode.cc 账号，请先 [注册并选择套餐](https://qcode.cc/pricing)。

---

## 前置条件

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

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

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

---

## 第一步：安装 Codex CLI

选择以下任一方式安装：

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

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

# 中国用户可用淘宝镜像加速
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```

### 方式二：Homebrew（macOS）

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

### 方式三：从源码构建

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

安装完成后验证：

```bash
codex --version
# 应打印版本号（以本机 `codex --version` 为准，不要对照网上过期数字）
```

---

## 第二步：配置 QCode.cc

### 2.1 创建配置目录

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

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

配置项说明：

| 字段 | 说明 |
|------|------|
| `model_provider` | 使用自定义 provider `crs` |
| `model` | 默认模型，推荐 `gpt-5.6-terra`；完整清单见下文「可用模型」 |
| `model_reasoning_effort` | 推理深度，可选 `low` / `medium` / `high` |
| `base_url` | QCode.cc 亚太节点地址 |
| `wire_api` | API 协议，使用 `responses` |
| `env_key` | 读取 API 密钥的环境变量名 |

### 2.3 创建 auth.json

创建 `~/.codex/auth.json`：

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

> 将 `cr_你的密钥` 替换为你在 [QCode.cc 控制台](https://qcode.cc/dashboard) 获取的 API 密钥。

### 2.4 设置环境变量

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

```bash
# 临时设置（当前终端有效）
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，密钥在 [控制台](https://qcode.cc/dashboard) 的同一个位置。

---

## 第三步：验证配置

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

```bash
codex "输出 hello world"
```

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

### 检查清单

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

如果遇到问题，请跳到 [常见问题](#常见问题) 部分。

---

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

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

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

### 示例 1：分析项目结构

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

### 示例 2：生成代码

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

### 示例 3：批量修改

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

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

---

## 三种权限模式

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

### suggest（建议模式）

```bash
codex --suggest "重构 auth 模块"
```

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

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

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

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

### 全自动（`--sandbox workspace-write`）

```bash
codex --sandbox workspace-write "运行测试并修复所有失败项"
```

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

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

---

## 常用命令速查

| 命令 | 说明 |
|------|------|
| `codex "你的指令"` | 启动 Codex 执行任务 |
| `codex --model gpt-5.4` | 指定模型 |
| `codex --sandbox workspace-write "指令"` | 全自动（可写工作区）|
| `codex --suggest "指令"` | 仅建议不执行 |
| `codex --auto-edit "指令"` | 自动编辑，命令需确认 |
| `codex --version` | 查看版本 |
| `codex --help` | 查看帮助 |

### 可用模型

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

| 模型 | 说明 | 推荐场景 |
|------|------|---------|
| `gpt-5.6-terra` | GPT-5.6 旗舰 | 编程 / 复杂任务（推荐 ★）|
| `gpt-5.6-sol` / `gpt-5.6-luna` | GPT-5.6 旗舰系列 | 高端能力 |
| `gpt-5.5` | 上一代旗舰，1M 上下文 | 日常复杂任务 |
| `gpt-5.4` | 稳定版本，1M 上下文 | 日常任务 / 性价比 |
| `gpt-5.6-mini` / `gpt-5.6-nano` | 轻量快速 | 轻量任务 |

---

## 项目配置：AGENTS.md

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

```markdown
# AGENTS.md

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

> 详细配置请参考 [AGENTS.md 配置指南](/docs/usage/agents-md)。

---

## 与 Claude Code 配合使用

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

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

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

> 更多配合模式请参考 [Codex vs Claude Code 深度对比](/docs/getting-started/codex-vs-claude-code)。

---

## 下一步

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

- [AGENTS.md 配置指南](/docs/usage/agents-md) -- 定制 Codex 的项目行为
- [Codex vs Claude Code 深度对比](/docs/getting-started/codex-vs-claude-code) -- 了解两者差异和配合技巧
- [Codex 集成配置](/docs/ide/codex) -- 完整配置参考（含 Windows 和多操作系统详细步骤）
- [命令行技巧](/docs/usage/cli-tips) -- Claude Code 高效使用技巧

---

## 常见问题

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

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

**解决**：

```bash
# 方式一：使用 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
```

### Q：提示 `API key not found` 或认证失败

**排查步骤**：

1. 确认 `~/.codex/auth.json` 中的密钥以 `cr_` 开头
2. 确认环境变量 `CRS_OAI_KEY` 已设置：`echo $CRS_OAI_KEY`
3. 确认密钥未过期：访问 [QCode.cc 控制台](https://qcode.cc/dashboard) 检查
4. 检查 `config.toml` 中的 `env_key` 是否拼写正确

### Q：连接超时或网络错误

**排查步骤**：

1. 确认 `base_url` 为 `https://api.qcode.cc/openai`
2. 测试网络连通性：`curl -I https://api.qcode.cc`
3. 如果主节点不可用，尝试备用节点：
   - 亚洲备用：`https://asia.qcode.cc/openai`

### Q：Codex 和 Claude Code 的密钥一样吗？

**是的**。两者使用同一个 QCode.cc API 密钥，配额共享。你不需要申请额外的密钥。

### Q：在 Windows 上能用吗？

**可以**，但推荐通过 WSL（Windows Subsystem for Linux）使用。原生 Windows 支持也在改进中。详细的 Windows 配置步骤请参考 [Codex 集成配置](/docs/ide/codex)。