Codex CLI 快速上手：5 分钟接入 QCode

2026 年 5 分钟 Codex CLI 安装与 QCode.cc 配置：写入 config.toml 和 auth.json，验证任务；密钥与 Claude Code 共用。

需要 API Key？ 前往注册 →·端点与 Base URL →

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

这篇教程用 5 分钟让 Codex CLI 通过 QCode.cc 跑起来：安装 CLI、写入 ~/.codex 下的 config.toml 和 auth.json、跑第一个任务验证；密钥与 Claude Code 共用，一份套餐配额两款工具都能用。

如果你还没有 QCode.cc 账号，请先 选方案并拿 Key（任何方案的 Key 用法都一样）。

前置条件¶

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

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

第一步：安装 Codex CLI¶

选择以下任一方式安装：

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

npm install -g @openai/codex

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

方式二：Homebrew（macOS）¶

brew install --cask codex

方式三：从源码构建¶

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

安装完成后验证：

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

第二步：配置 QCode.cc¶

2.1 创建配置目录¶

mkdir -p ~/.codex

2.2 编写 config.toml¶

创建 ~/.codex/config.toml：

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

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

配置项说明：

2.3 创建 auth.json¶

创建 ~/.codex/auth.json：

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

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

2.4 设置环境变量¶

想改用环境变量传 Key，就把 [model_providers.qcode] 里的 requires_openai_auth = true 换成 env_key = "QCODE_API_KEY"，并 export 这个变量。两种写法只能选一种：官方文档写明 requires_openai_auth = true 时 Codex 会忽略 env_key。环境变量写法的完整配置：

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"

然后设置环境变量：

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

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

# 永久设置（Zsh 用户）
echo 'export QCODE_API_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 用两个参数分别控制「能做什么」（--sandbox）和「何时问你」（--ask-for-approval）。以下取自 OpenAI 官方文档（截至 2026-10-15）。

默认：工作区可写，按需审批¶

codex "重构 auth 模块"

• 在 Git 仓库里不加参数就是这个预设：能读文件，在工作区内改文件、运行命令；写工作区之外或联网会先问你
• 适合：日常开发（推荐的默认设置）

只读：只看不改¶

codex --sandbox read-only --ask-for-approval on-request "分析 auth 模块并给出重构建议"

• 只读沙箱，不修改任何文件
• 适合：学习代码、评估方案

非交互与自动化¶

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

• codex exec 非交互运行，结果输出到标准输出（或用 --json 输出 JSONL）
• 沙箱限制在工作区内，不会影响工作区外的系统
• 适合：CI/CD 集成、批量任务

也可以在 config.toml 中设置默认值：approval_policy = "on-request" 与 sandbox_mode = "workspace-write"。旧教程里的 --suggest、--auto-edit、approval_mode 写法不在官方当前的参数清单里；具体以 codex --help 为准。

常用命令速查¶

可用模型¶

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

QCode 暂不提供 gpt-6-luna / gpt-5.6-luna，请使用其他 GPT 模型。QCode 按 token 计费，各模型单价见 qcode.cc/models。

/model 菜单里没有 gpt-6.1-sol？ 按上面的配置接入时，Codex 的 /model 菜单列的是客户端自带的型号清单，跟 Codex 版本走：gpt-6.1-sol 从 Codex 0.160.0 起才出现在菜单里。升级到最新版即可（npm install -g @openai/codex@latest，Homebrew 用 brew upgrade --cask codex）。不升级也能用：config.toml 里的 model = "gpt-6.1-sol"（或 codex --model gpt-6.1-sol）不依赖菜单。反过来，菜单里可能出现 gpt-6-luna，但 QCode 暂不提供，选了会报错。

项目配置：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

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

排查步骤：

1. 确认 ~/.codex/auth.json 中的密钥以 cr_ 开头
2. 如果用环境变量写法，确认 provider 里是 env_key = "QCODE_API_KEY"（没有 requires_openai_auth = true），且已 export：echo $QCODE_API_KEY
3. 确认密钥未过期：访问 QCode.cc 控制台 检查
4. 检查 config.toml 的 TOML 语法与 provider 名是否正确

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

排查步骤：

1. 确认 base_url 为 https://api.qcode.cc/openai
2. 测试网络连通性：curl -I https://api.qcode.cc

3. 如果当前接入点不可用，换用其他接入点：

4. 亚洲接入点：https://asia.qcode.cc/openai

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

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

Q：在 Windows 上能用吗？¶

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

企业团队版 →