从安装到精通 — OpenAI Codex CLI 配合 QCode.cc 的完整使用指南
 

本文是一篇面向中国开发者的 Codex CLI 完整教程，从零开始带你安装、配置、使用 OpenAI Codex CLI，并通过 QCode.cc 享受低成本、低延迟的 AI 编程体验。无论你是第一次接触 AI 编程工具，还是已经在用 Claude Code 想尝试新工具，这篇教程都适合你。

Codex CLI 是 OpenAI 推出的开源命令行 AI 编程助手（Apache 2.0 许可），使用 Rust 编写，可以在终端中直接运行。它能够：

• 阅读和理解你的代码仓库
• 编辑文件并生成新代码
• 执行命令（如运行测试、安装依赖）
• 自主迭代直到任务完成

Codex 的核心哲学是自主式代理（Autonomous Agent）：你描述任务，Codex 在沙箱中自主完成，最后你审核结果。这与 Claude Code 的交互式对话风格形成互补。

“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 默认需要 OpenAI API Key 或 ChatGPT 订阅，但在中国大陆存在两个问题：

1. 网络不可达：OpenAI API 无法直接访问
2. 费用高昂：官方 GPT-5.3-Codex 的 token 价格不低

通过 QCode.cc，你可以：

• 亚太节点低延迟访问，无需翻墙或自建代理
• 成本降低高达 80%，相比官方价格大幅节省
• Claude Code 与 Codex 共享套餐配额，一份套餐两个工具都能用
• 多节点可用（亚太主节点、香港、深圳），保障连接稳定性

在安装之前，请确认你的环境满足以下条件：

• 操作系统：macOS 12+、Ubuntu 20.04+、Windows 10+（推荐使用 WSL2）
• Node.js：v22 LTS 或更高版本（npm 安装方式需要）
• Git：2.x 或更高版本（Codex 需要 Git 来感知代码仓库）
• 磁盘空间：约 200MB（包括 npm 依赖）

这是最通用的安装方式，适用于所有操作系统：

npm install -g @openai/codex 

提示：如果遇到权限问题，macOS/Linux 用户可以加 sudo，或者使用 nvm 管理 Node.js 来避免权限问题。

中国用户：如果 npm 下载速度慢，可以使用淘宝镜像： bash npm install -g @openai/codex –registry=https://registry.npmmirror.com

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.114.0（2026-03-11），支持 Skills 系统、Hooks 引擎、MCP 协议等新功能。

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。

Codex CLI 需要配置两个文件来连接 QCode.cc 服务：

• /.codex/config.toml — 服务端点和模型配置
• /.codex/auth.json — API 密钥认证

mkdir $HOME.codex 

mkdir -p ~/.codex 

mkdir -p ~/.codex 

在 ~/.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 字段详解：

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

{  “OPENAI_API_KEY”: “cr_xxxxxxxxxx” } 

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

auth.json 说明：

• 此文件为 Codex 提供 API 密钥，等同于设置 OPENAI_API_KEY 环境变量
• 文件权限建议设为 600（仅本人可读写）：chmod 600 ~/.codex/auth.json
• 如果同时存在 auth.json 和环境变量，auth.json 优先

如果你更喜欢通过环境变量提供密钥（而不是 auth.json），可以设置 CRS_OAI_KEY：

# 临时设置（当前会话） $env:CRS_OAI_KEY = “cr_xxxxxxxxxx”

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

# 临时设置 export CRS_OAI_KEY=“cr_xxxxxxxxxx”

# 永久设置 echo ‘export CRS_OAI_KEY=“cr_xxxxxxxxxx”’ >> /.zshrc source /.zshrc

# 临时设置 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 模型：

所有模型与 Claude Code 共享 QCode.cc 套餐配额。切换模型不需要额外付费。

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

cd /path/to/your/project codex 

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

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

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

# 交互式启动 codex

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

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

# 指定模型 codex -m gpt-5.1-codex-max “重构认证模块的错误处理”

让我们从一个简单的例子开始。在项目目录下运行 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，然后生成对应的测试文件。

这是 Codex 最重要的安全特性之一。Codex 在沙箱中执行命令，有三个安全级别：

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

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

codex -c ‘sandbox_workspace_write.network_access=true’ “安装依赖并运行测试” 

Codex 对文件的修改遵循审批策略（Approval Policy）。默认情况下：

• 文件编辑：展示 diff 并等你确认
• Shell 命令：展示命令内容并等你确认

当 Codex 提出修改时，你可以：

• 接受（y）：应用修改
• 拒绝（n）：跳过此修改
• 查看详情：仔细阅读 diff 后再决定

提示：使用 /diff 斜杠命令可以随时查看当前会话中所有已应用的修改。

文件引用：输入 @ 后跟文件名，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 的代码质量和安全性”

键盘快捷键：

斜杠命令：

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 调整。

Codex 的三种审批模式适合不同的使用场景：

所有操作都需要你手动确认，包括文件编辑和命令执行。适合学习阶段或审查敏感代码。

codex –approval-mode suggest 

文件编辑自动执行，命令执行仍需确认。在效率和安全之间取得良好平衡。

codex –approval-mode auto-edit 

所有操作都自动执行，无需任何确认。仅建议在隔离环境（如 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 模式 

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 系统时非常有用。

如果你在不同项目中使用不同配置（比如工作项目用一个 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 “写一个小脚本” 

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 嵌入到你自己的开发工具或工作流中。

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

1. 命令行参数（–model、-c 等）
2. Profile 值（–profile 指定的 Profile）
3. 项目配置（.codex/config.toml，从项目根到当前目录，最近的优先）
4. 用户配置（/.codex/config.toml）
5. 系统配置（/etc/codex/config.toml，Unix 系统）
6. 内置默认值

理解这个优先级有助于你在不同层级精准控制行为。例如，在 /.codex/config.toml 设置通用默认值，在项目的 .codex/config.toml 中覆盖特定设置，再用命令行参数做一次性调整。

如果你已经在使用 Claude Code，下面的对比可以帮你理解两个工具的定位差异：

选择 Claude Code 的场景：

• 探索性调试，需要边看边调整方向
• 复杂的代码重构，需要实时讨论方案
• 大型代码库的架构分析和理解
• 需要丰富的 IDE 工具集成（LSP、浏览器、搜索等）
• 需要超长上下文（1M token Beta）处理大量代码

选择 Codex 的场景：

• 需求明确的功能开发（”实现 XX 接口”）
• 批量文件处理和代码迁移
• CI/CD 流水线中的自动化任务
• 需要并行处理多个独立任务
• 偏好开源工具，需要审计和定制
• 使用 Docker 沙箱进行安全隔离

**实践：两者配合使用 — 用 Claude Code 做规划和探索，用 Codex 做执行和批量操作。两个工具共享 QCode.cc 套餐配额，切换成本为零。

下面通过几个真实场景演示 Codex 的使用方式。每个示例都包含具体命令和预期效果。

当你接手一个不熟悉的代码库时：

cd /path/to/new/project codex 

在交互界面中：

这个项目是做什么的？请分析目录结构、主要模块、技术栈， 并给出一个简洁的架构图（用 ASCII art）。 

Codex 会扫描项目中的文件，分析 package.json、requirements.txt、go.mod 等依赖文件，阅读关键入口文件，然后给出全面的项目概览。

codex “审查 src/ 目录下最近一次 git commit 的所有修改。重点关注： 1. 潜在的 bug（空指针、边界条件） 2. 安全风险（SQL 注入、XSS、硬编码密钥） 3. 性能问题（N+1 查询、不必要的循环） 给出具体的代码位置和修复建议。” 

codex –full-auto “把项目中所有 Python 文件的 print() 调用替换为 logging 模块。 具体要求： 1. 在每个文件顶部 import logging 2. 创建 logger = logging.getLogger(name) 3. print() 替换为 logger.info() 4. 保持原有的格式化字符串 5. 替换完成后运行 pytest 确保没有破坏任何东西” 

Codex 会逐个文件处理，保持代码一致性，并在最后运行测试验证。

codex “为 src/services/user_service.py 编写完整的单元测试。要求： 1. 使用 pytest + pytest-mock 2. 覆盖所有公共方法 3. 包含正常路径和异常路径测试 4. Mock 外部依赖（数据库、HTTP 请求） 5. 测试文件保存到 tests/unit/test_user_service.py 6. 运行测试确认全部通过” 

Full-Auto 模式的经典用例 — 让 Codex 自主修复失败的测试：

codex –full-auto “运行所有测试。如果有失败的： 1. 分析失败原因 2. 修复代码（不是修复测试） 3. 重新运行测试 4. 重复以上步骤直到所有测试通过 最后给出修复摘要。” 

codex -i design.png “根据这张设计稿，用 React + Tailwind CSS 实现这个页面。 要求： 1. 响应式布局（支持移动端） 2. 像素级还原设计稿 3. 组件拆分合理 4. 添加基本的交互状态（hover、focus）” 

codex “我需要给 users 表添加一个 avatar_url 字段（varchar 500, nullable）。 请： 1. 创建 Alembic 迁移脚本 2. 更新 SQLAlchemy 模型 3. 更新相关的 Pydantic schema 4. 更新 CRUD 操作函数 5. 添加对应的 API 端点（GET/PUT） 6. 运行迁移并确认成功” 

codex –full-auto “分析从上次 release tag 到现在的所有 git commit， 按照 conventional commits 规范分类， 生成 CHANGELOG.md 的更新内容。 包含：新功能、Bug 修复、破坏性变更、其他改进。” 

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

解决：

1. 检查配置目录是否存在：ls ~/.codex/
2. 确认 config.toml 和 auth.json 两个文件都存在
3. 检查 config.toml 的 TOML 语法是否正确（常见错误：缺少引号、拼写错误）
4. 使用 codex –config-dump 查看实际加载的配置

问题：提示 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.218.243.5/openai
5. 深圳节点：http://103.236.53.153/openai
6. 如果使用公司代理/VPN，确认代理设置不会阻断 HTTPS 请求

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

建议：

在 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 控制台 查看整体配额使用情况

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

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

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

 
            
    
              
 
               

                 团队 3 人以上？ 
               
 
               

                 企业团队版：独立域名 + 子Key管理 + 封号保障，人均低至 ¥250/月 
               
 了解企业版 →