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 订阅,但在中国大陆存在两个问题:

  1. 网络不可达:OpenAI API 无法直接访问
  2. 费用高昂:官方 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 推理强度:lowmediumhigh。越高越准但越慢
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 会执行以下步骤:

  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 在沙箱中执行命令,有三个安全级别:

沙箱模式 文件读取 文件写入 命令执行 网络访问
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 按以下优先级(从高到低)解析:

  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 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.jsonrequirements.txtgo.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.tomlauth.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 http://103.236.53.153
  2. 验证 base_url 配置是否正确(必须是 http://103.236.53.153/openai
  3. 尝试备用节点:

  4. 深圳节点:http://103.236.53.153/openai

  5. 如果使用公司代理/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 尝试执行的命令被沙箱拒绝

解决

  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 优势

优势 说明
成本节省 80% 相比官方价格大幅降低,同样的配额用更少的钱
共享配额 Claude Code 与 Codex 共享套餐配额,一份套餐两个工具
99.9% 可用性 企业级稳定服务,多节点互为备份
亚太优化 部署在亚太区域,中国大陆访问低延迟
免翻墙 无需配置代理或 VPN,开箱即用
多节点 深圳直连 + 全球路由 + US / EU / Asia 备用,智能路由保障连接

十、相关文档

🚀
开始使用 QCode — Claude Code & Codex
一份套餐同时加速 Claude Code 和 Codex,亚太低延迟
查看套餐定价 → 注册账号
团队 3 人以上?
企业团队版:独立域名 + 子Key管理 + 封号保障,人均低至 ¥250/月
了解企业版 →