Codex 完整教程
从安装到精通 — OpenAI Codex CLI 配合 QCode.cc 的完整使用指南
Codex 完整教程¶
📖 Codex
base_url和 Claude 的ANTHROPIC_BASE_URL为何不同?/openai和/openai/v1怎么区分?见 接入点与 API 格式。
本文是一篇面向中国开发者的 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 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 订阅,但在中国大陆存在两个问题:
- 网络不可达:OpenAI API 无法直接访问
- 费用高昂:官方 GPT-5.3-Codex 的 token 价格不低
通过 QCode.cc,你可以:
- 全球多接入点低延迟访问(
api.qcode.cc全球路由 /us/eu/asia备用 / 中国大陆深圳直连 IP),无需翻墙或自建代理 - 成本降低高达 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.118.0(2026-04),支持 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:创建配置目录¶
Windows (PowerShell):
mkdir $HOME\.codex
macOS:
mkdir -p ~/.codex
Linux:
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 = "http://103.236.53.153/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
config.toml 字段详解:
| 字段 | 说明 |
|---|---|
model_provider |
使用的模型提供商名称,这里设为自定义的 crs |
model |
默认模型,推荐 gpt-5.3-codex-spark |
model_reasoning_effort |
推理强度:low、medium、high。越高越准但越慢 |
disable_response_storage |
禁止 OpenAI 存储对话内容(隐私保护) |
preferred_auth_method |
认证方式,设为 apikey 使用 API 密钥 |
base_url |
QCode.cc 接入点地址(示例用深圳直连 IP;其他接入点见接入点与 API 格式) |
wire_api |
API 协议类型,Codex 使用 responses |
requires_openai_auth |
需要携带 OpenAI 格式的认证头 |
env_key |
环境变量名,Codex 会从该变量读取 API 密钥 |
步骤 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:
Windows (PowerShell):
# 临时设置(当前会话)
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"
# 永久设置(写入用户环境变量)
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
macOS:
# 临时设置
export CRS_OAI_KEY="cr_xxxxxxxxxx"
# 永久设置
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
Linux:
# 临时设置
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 模型:
| 模型 | 说明 | 推荐场景 |
|---|---|---|
gpt-5.5 |
最新旗舰模型,全面升级 | 复杂任务、长上下文(推荐 ★) |
gpt-5.4 |
最新一代 GPT,全面升级 | 日常开发(推荐) |
gpt-5.4-pro (gpt-5.4 Pro) |
5.4 专业版,增强推理 | 复杂架构和推理 |
gpt-5.4-codex |
5.4 Codex 版,代码专精 | 代码密集任务 |
gpt-5.3-codex-spark |
5.3 轻量版,速度快 | 性价比优先 |
gpt-5.3-codex |
5.3 Codex 标准版 | 稳定输出 |
所有模型与 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 会执行以下步骤:
- 规划:分析你的需求,制定实现方案
- 生成代码:创建
utils.py并写入函数 - 请求确认:在默认模式下,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 在沙箱中执行命令,有三个安全级别:
| 沙箱模式 | 文件读取 | 文件写入 | 命令执行 | 网络访问 |
|---|---|---|---|---|
read-only |
允许 | 需确认 | 需确认 | 需确认 |
workspace-write(默认) |
允许 | 工作区内允许 | 工作区内允许 | 默认禁止 |
danger-full-access |
允许 | 全部允许 | 全部允许 | 允许 |
默认的 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 的代码质量和安全性"
键盘快捷键:
| 快捷键 | 功能 |
|---|---|
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:
# 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 模式
各场景推荐配置¶
| 场景 | 审批模式 | 沙箱模式 |
|---|---|---|
| 个人日常开发 | 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),可以连接外部工具来扩展能力。
通过命令行添加 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 = "http://103.236.53.153/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 按以下优先级(从高到低)解析:
- 命令行参数(
--model、-c等) - Profile 值(
--profile <name>指定的 Profile) - 项目配置(
.codex/config.toml,从项目根到当前目录,最近的优先) - 用户配置(
~/.codex/config.toml) - 系统配置(
/etc/codex/config.toml,Unix 系统) - 内置默认值
理解这个优先级有助于你在不同层级精准控制行为。例如,在 ~/.codex/config.toml 设置通用默认值,在项目的 .codex/config.toml 中覆盖特定设置,再用命令行参数做一次性调整。
六、Claude Code vs Codex 对比¶
如果你已经在使用 Claude Code,下面的对比可以帮你理解两个工具的定位差异:
| 维度 | Claude Code | Codex CLI |
|---|---|---|
| 执行模式 | 交互式、开发者在回路中 | 自主式、任务驱动 |
| 交互风格 | 对话式,逐步讨论和确认 | 给出任务后自主完成 |
| 核心模型 | Claude Opus 4.6 / Sonnet 4.6 | GPT-5.3-Codex-Spark |
| 上下文窗口 | 200K 标准 / 1M Beta | 400K |
| 沙箱安全 | 权限提示确认 | 内置 Landlock/seccomp 沙箱 |
| 指令文件 | CLAUDE.md |
AGENTS.md |
| MCP 支持 | 完整支持 | 完整支持 |
| Git 集成 | /commit、/review 等命令 |
内置 Git 感知 |
| 多 Agent | Agent Teams(研究预览) | 多 Agent 并行(Subagents) |
| 非交互模式 | claude -p "task" |
codex "task" |
| 开源 | 不开源 | 开源(Apache 2.0) |
| 桌面应用 | 无(纯终端) | macOS 桌面应用 |
| QCode.cc 配额 | 共享套餐配额 | 共享套餐配额 |
哪个更适合你?¶
选择 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 提示找不到配置文件或无法加载配置
解决:
- 检查配置目录是否存在:
ls ~/.codex/ - 确认
config.toml和auth.json两个文件都存在 - 检查
config.toml的 TOML 语法是否正确(常见错误:缺少引号、拼写错误) - 使用
codex --config-dump查看实际加载的配置
API 密钥认证失败¶
问题:提示 401 Unauthorized 或 API Key 无效
解决:
- 确认 API 密钥格式正确(以
cr_开头) - 检查
auth.json中的密钥是否完整(没有多余空格或换行) - 如果使用环境变量,确认变量名是
CRS_OAI_KEY(与config.toml中的env_key一致) - 登录 QCode.cc 控制台 确认密钥状态和剩余配额
网络连接问题¶
问题:无法连接到 QCode.cc 服务,超时或拒绝连接
解决:
- 检查网络是否正常:
curl -I http://103.236.53.153 - 验证
base_url配置是否正确(必须是http://103.236.53.153/openai) -
尝试备用节点:
-
深圳节点:
http://103.236.53.153/openai - 如果使用公司代理/VPN,确认代理设置不会阻断 HTTPS 请求
模型选择建议¶
问题:不确定该选哪个模型
建议:
| 你的需求 | 推荐模型 | 理由 |
|---|---|---|
| 日常开发 | gpt-5.3-codex-spark |
速度快、性价比高 |
| 复杂推理 | gpt-5.1-codex-max |
推理能力更强 |
| 简单任务 | gpt-5.2-2025-12-11 |
消耗配额更少 |
| 最稳定输出 | gpt-5.2-codex |
经过充分验证 |
在 config.toml 中设置默认模型后,也可以临时切换:
codex -m gpt-5.1-codex-max "分析这个复杂的并发 bug"
沙箱限制导致命令失败¶
问题:Codex 尝试执行的命令被沙箱拒绝
解决:
- 如果是联网操作(如
npm install),临时启用网络:bash codex -c 'sandbox_workspace_write.network_access=true' "安装依赖" - 如果需要写入项目目录外的文件,可以临时扩展可写范围:
bash codex --sandbox danger-full-access "将输出保存到 /tmp/result.txt" - 在会话中使用
/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 优势¶
| 优势 | 说明 |
|---|---|
| 成本节省 80% | 相比官方价格大幅降低,同样的配额用更少的钱 |
| 共享配额 | Claude Code 与 Codex 共享套餐配额,一份套餐两个工具 |
| 99.9% 可用性 | 企业级稳定服务,多节点互为备份 |
| 亚太优化 | 部署在亚太区域,中国大陆访问低延迟 |
| 免翻墙 | 无需配置代理或 VPN,开箱即用 |
| 多节点 | 深圳直连 + 全球路由 + US / EU / Asia 备用,智能路由保障连接 |