Codex CLI 安装配置教程（config.toml）

Codex CLI 0.164.0 安装与 config.toml 配置：用 QCode.cc 的 cr_ 密钥接入 GPT，含 /presets 与 /model 行内参数。

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

最后核实：2026-10-26 · 📄 依据官方文档（Codex CLI 最新稳定版 v0.164.0，2026-10-23 发布；本次重新核对了 config 配置项、0.164.0 的命令变化、安装方式） · 5.4 的 profile 行为另经本机实测（✅ codex-cli 0.155.0，独立 HOME，未发模型请求）

接入速览¶

📖 Codex base_url 和 Claude 的 ANTHROPIC_BASE_URL 为何不同？/openai 和 /openai/v1 怎么区分？见 接入点与 API 格式。

本文是一篇面向中国开发者的 Codex CLI 完整教程：从安装、写入 ~/.codex/config.toml 与 auth.json，到通过 QCode.cc 的 cr_ 密钥接入 GPT 模型，再讲到基础使用、审批与沙箱、Profile 多环境配置和常见问题。

一、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 擅长"甩手任务"（给一个明确的需求，让它自己跑完），Claude Code 擅长"结对编程"（边讨论边修改，适合探索性任务）。两者配合使用效果最佳。

为什么通过 QCode.cc 使用 Codex？¶

Codex CLI 默认需要 OpenAI API Key 或 ChatGPT 订阅，而在中国大陆，OpenAI 的 API 无法直接访问。

通过 QCode.cc，你可以：

• 一把 Key 调用 Claude、GPT 与主流国产模型：Codex 使用其中的 GPT 系模型，Claude Code 使用 Claude，两者共用同一把 QCode API Key
• 多个接入点：api.qcode.cc 是全球入口，us.qcode.cc 面向北美与欧洲，asia.qcode.cc 面向亚洲，中国大陆用户推荐 asia.qcode.cc，无需自建代理
• 按 token 计费，各模型单价见 qcode.cc/models
• 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 --cask codex

Homebrew 的优势是会自动管理依赖和更新。

方法三：直接下载二进制（高级）¶

从 GitHub Releases 页面下载对应平台的预编译二进制文件，放到 PATH 目录中即可。这种方式不依赖 Node.js。截至 2026-10-26，最新稳定版是 v0.164.0（2026-10-23 发布）；本页 2026-10-15 核对时为 v0.162.1（2026-10-09 发布）。资产名按平台命名，例如 Linux x64 是 codex-x86_64-unknown-linux-musl.tar.gz，macOS Apple 芯片是 codex-aarch64-apple-darwin.tar.gz，Windows x64 是 codex-x86_64-pc-windows-msvc.exe。

# 示例：下载并安装 Linux x64 版本
curl -fsSLO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

方法四：官方安装脚本（macOS / Linux）¶

OpenAI 官方 Codex 文档（截至 2026-10-26）也提供了独立安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装后用 codex --version 确认。

验证安装¶

codex --version

如果看到版本号输出，说明安装成功。不要拿文档里的数字当「当前最新」——以 GitHub Releases 和 npm @openai/codex 为准，本机用 codex --version 查看。

配置 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：创建配置目录¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

步骤 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

config.toml 字段详解：

步骤 3：创建 auth.json¶

在 ~/.codex/auth.json 写入以下内容：

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

将 cr_xxxxxxxxxx 替换为你的 QCode.cc API 密钥。密钥以 cr_ 开头。

auth.json 说明：

• 此文件为 Codex 提供 API 密钥（requires_openai_auth = true 时读取其中的 OPENAI_API_KEY）
• 文件权限建议设为 600（仅本人可读写）：chmod 600 ~/.codex/auth.json

步骤 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"

然后设置环境变量：

# 临时设置（当前会话）
$env:QCODE_API_KEY = "cr_xxxxxxxxxx"

# 永久设置（写入用户环境变量）
[System.Environment]::SetEnvironmentVariable("QCODE_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)

# 临时设置
export QCODE_API_KEY="cr_xxxxxxxxxx"

# 永久设置
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 临时设置
export QCODE_API_KEY="cr_xxxxxxxxxx"

# 永久设置（Bash）
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# 永久设置（Zsh）
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

可用模型¶

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

QCode 暂不提供 gpt-6-luna / gpt-5.6-luna，请使用其他 GPT 模型（gpt-6.1-sol / gpt-6.1-terra / gpt-6-sol / gpt-5.6-terra）。

Claude Code 与 Codex 使用同一把 QCode API Key，切换模型不需要额外开通。QCode 按 token 计费，各模型单价见 qcode.cc/models。

四、基础使用教程¶

4.1 启动 Codex¶

打开终端，进入你的项目目录，然后运行：

cd /path/to/your/project
codex

Codex 会启动一个终端交互界面（TUI），你可以在其中输入自然语言指令。界面由以下部分组成：

• 顶部状态栏：显示当前模型、审批模式、沙箱状态
• 主区域：AI 的回复和操作日志
• 底部输入框：你输入指令的地方

你也可以直接在命令行给出任务（非交互模式），适合脚本调用：

# 交互式启动
codex

# 非交互模式：执行单个任务后退出
codex "阅读这个项目的结构并给我一个概览"

# 附带图片的任务
codex -i screenshot.png "修复截图中显示的 UI 问题"

# 指定模型
codex -m gpt-6-sol "重构认证模块的错误处理"

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

默认的 workspace-write 模式是日常开发的最佳选择：Codex 可以在项目目录内自由读写文件和运行命令，但不能访问项目外的文件或网络。

如果你的任务需要联网（比如 npm install），可以临时启用网络访问：

codex -c 'sandbox_workspace_write.network_access=true' "安装依赖并运行测试"

4.4 审核和接受 Codex 的修改¶

Codex 对文件的修改遵循审批策略（Approval Policy）。据官方文档（截至 2026-10-26），在 Git 仓库里默认是「工作区可写 + 按需审批」预设：

• 工作区内的文件编辑与命令：自动执行
• 写工作区之外、联网等操作：展示内容并等你确认
• 非 Git 目录：默认只读，要改动先问你

当 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 的代码质量和安全性"

键盘快捷键：

斜杠命令：

4.6 Codex CLI 0.164.0 的命令变化（2026-10-23）¶

Codex CLI 0.164.0 于 2026-10-23 发布。官方发布说明列出了以下与命令、配置相关的条目：

• 在十个编号的 /presets 槽位里保存可复用的提示词与斜杠命令，并提供键盘菜单快速调用。
• 直接用行内 /model 与 /permissions 参数设置模型、推理强度、速度与权限档。
• 用符合条件的 Codex 账号授权或专用登录来认证企业 MCP 连接，包括需要 secret 的 OAuth 客户端。
• 在受支持的远程 Bash 命令与 Zsh 快照会话中掩码凭据，包括来自自定义服务商的凭据。

上文配置用到的键在 2026-10-26 核对的官方配置参考里仍然存在：model_provider、[model_providers.<id>]、base_url、wire_api、requires_openai_auth。同日核对的官方 README 里安装命令未变：npm install -g @openai/codex、brew install --cask codex，或 curl -fsSL https://chatgpt.com/codex/install.sh | sh。

五、高级配置¶

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 调整审批与沙箱¶

Codex 的安全控制由两层组成：沙箱模式决定 Codex 技术上能做什么（能写哪里、能否联网），审批策略决定什么时候必须先问你。截至 2026-10-26，据 OpenAI 官方文档，命令行用两个参数分别控制：

常见组合（官方文档）：

🔴 旧教程里的 --full-auto、--suggest、--auto-edit、--approval-mode 写法不在官方当前的参数清单里。需要「全自动写文件」时用 --sandbox workspace-write；非交互场景用 codex exec --sandbox workspace-write。

⚠️ Codex 的 flag 变动很快。以 codex --help 的实际输出为准，不要照抄任何文档里的 flag 清单，包括本页。

在 config.toml 中设置默认值：

# 个人开发推荐
approval_policy = "on-request"
sandbox_mode = "workspace-write"

approval_policy 的取值是 on-request、never，或按类别细分的 granular 表。官方已经不再支持 approval_policy = "untrusted"，旧配置里如果还留着这一行，可能导致客户端无法启动，请删除。

会话中切换：用 /permissions 命令无需重启即可在默认预设和只读之间切换。

各场景推荐配置¶

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（多环境管理）¶

如果你在不同项目里要用不同配置（例如工作项目一套、个人项目一套），用 Profile。从 Codex 0.134.0 起，写在 config.toml 里的 [profiles.<名称>] 老写法已经作废，改成「一个 profile 一个文件」：~/.codex/<名称>.config.toml。下面三段就是新写法的完整形态：

# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "qcode"
model = "gpt-6-sol"

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

# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"

# ~/.codex/personal.config.toml
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

启动时指定：

codex --profile work "重构认证模块"
codex --profile personal "写一个小脚本"

✅ 下面三条是本机实测到的行为（codex-cli 0.155.0，linux-x86_64，独立沙箱 HOME，未发出任何模型请求），也是最常见的坑：

• 留着老表再 --profile，是硬报错而不是静默忽略：

text Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.

• 顶层的 profile = "work" 选择器同样已废：

text Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead

• 不传 --profile 时，残留的 [profiles.*] 表根本不参与解析——codex doctor 照样显示 config.toml parse ok，用的仍是顶层值。所以「没报错」不等于「生效了」，迁移时把老表删掉。

另外 --profile 只对运行类子命令有效（codex、exec、review、resume、queue、archive、delete、unarchive、fork、mcp、sandbox、debug prompt-input）；挂到 doctor 上会直接报 --profile only applies to runtime commands ...。profile 文件是叠在用户配置之上、项目配置与命令行之下的一层，见 5.6。

5.5 非交互模式（脚本与自动化）¶

Codex 不仅可以交互使用，还可以在脚本和 CI/CD 流水线中非交互地运行：用 codex exec 执行任务后退出（官方文档：非交互运行，结果输出到 stdout 或 JSONL）。

# 基本用法：执行任务后退出
codex exec "为 README.md 添加安装说明"

# 允许写工作区：完全自主执行
codex exec --sandbox workspace-write "运行测试套件，修复所有失败的测试"

# 以 JSONL 事件流输出（用于审计或后处理）
codex exec --json "重构错误处理模块"

在 CI/CD 中使用 Codex：

# GitHub Actions 示例

- name: Auto-fix lint errors
  run: |
    # 环境变量写法：config.toml 里用 env_key，不写 requires_openai_auth
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'EOF'
    model_provider = "qcode"
    model = "gpt-6.1-sol"

    [model_providers.qcode]
    name = "qcode"
    base_url = "https://api.qcode.cc/openai"
    wire_api = "responses"
    env_key = "QCODE_API_KEY"
    EOF
    npx @openai/codex exec --sandbox workspace-write "运行 eslint --fix 修复所有 lint 错误，然后提交修复"
  env:
    QCODE_API_KEY: ${{ secrets.QCODE_API_KEY }}

Codex SDK：如果需要在自己的程序中调用 Codex，可以使用官方 SDK 进行编程式调用，将 Codex 嵌入到你自己的开发工具或工作流中。

5.6 配置优先级¶

当多个配置源存在冲突时，Codex 按以下优先级（从高到低）解析：

1. 命令行参数（--model、-c 等）
2. 项目配置（.codex/config.toml，从项目根到当前目录，最近的优先；目录被信任后才加载，而且项目层里的 model_provider、model_providers、profile、profiles 等键会被 Codex 忽略）
3. Profile 文件（--profile <name> 指定的 ~/.codex/<name>.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 是交互式结对编程，Codex 是自主任务执行。Claude Code 适合探索性调试、复杂重构、架构理解；Codex 适合需求明确的功能开发、批量迁移、CI/CD 自动化。指令文件分别是 CLAUDE.md 与 AGENTS.md，两者都完整支持 MCP，并且共享同一份 QCode.cc 套餐配额，切换成本为零。

执行模式、上下文窗口、沙箱、多 Agent、是否开源等 13 个维度的逐项对比 → Codex vs Claude Code。

七、实战示例¶

下面通过几个真实场景演示 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 --sandbox workspace-write "把项目中所有 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：自主修复测试¶

全自主场景的经典用例 — 让 Codex 自主修复失败的测试：

codex --sandbox workspace-write "运行所有测试。如果有失败的：
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 --sandbox workspace-write "分析从上次 release tag 到现在的所有 git commit，
按照 conventional commits 规范分类，
生成 CHANGELOG.md 的更新内容。
包含：新功能、Bug 修复、破坏性变更、其他改进。"

八、常见问题¶

配置文件未找到¶

问题：Codex 提示找不到配置文件或无法加载配置

解决：

1. 检查配置目录是否存在：ls ~/.codex/
2. 确认 config.toml 和 auth.json 两个文件都存在
3. 检查 config.toml 的 TOML 语法是否正确（常见错误：缺少引号、拼写错误）
4. 运行 codex doctor 生成诊断报告，检查安装、配置和认证状态

API 密钥认证失败¶

问题：提示 401 Unauthorized 或 API Key 无效

解决：

1. 确认 API 密钥格式正确（以 cr_ 开头）
2. 检查 auth.json 中的密钥是否完整（没有多余空格或换行）
3. 如果用环境变量写法，确认 provider 里写的是 env_key = "QCODE_API_KEY"、没有 requires_openai_auth = true，且变量已 export
4. 登录 QCode.cc 控制台 确认密钥状态和剩余配额

网络连接问题¶

问题：无法连接到 QCode.cc 服务，超时或拒绝连接

解决：

1. 检查网络是否正常：curl -I https://api.qcode.cc
2. 验证 base_url 配置是否正确（必须是 https://api.qcode.cc/openai）

3. 换用其他接入点：

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

5. 如果使用公司代理/VPN，确认代理设置不会阻断 HTTPS 请求

模型选择建议¶

问题：不确定该选哪个模型

建议：

在 config.toml 中设置默认模型后，也可以临时切换：

codex -m gpt-6-sol "分析这个复杂的并发 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 消耗计算，不按工具区分
• 让 Codex 自主迭代多轮时，单次任务的 token 消耗可能较高，但节省了开发者的交互时间
• QCode 按 token 计费，各模型单价见 qcode.cc/models；可在 QCode.cc 控制台 查看用量

AGENTS.md 与 CLAUDE.md 可以共存吗？¶

可以。如果你的项目同时被 Codex 和 Claude Code 使用：

• Codex 只读 AGENTS.md，忽略 CLAUDE.md
• Claude Code 只读 CLAUDE.md，忽略 AGENTS.md
• 两者互不干扰，你可以为不同工具维护各自的指令文件
• 建议保持两份文件的核心规范一致（如测试命令、代码风格等）

十、相关文档¶

• 环境变量配置 — Claude Code 的环境变量设置
• 快速上手 — Claude Code 快速入门
• Aider 集成 — 另一个开源 AI 编程助手的配置
• CLI 技巧 — Claude Code 的命令行进阶用法
• 工作流技巧 — 提升 AI 编程效率的工作流建议

企业团队版 →