Codex CLI 国内使用完整教程：从安装到第一个任务（2026 最新版）
发布日期：2026-05-19 | 适用版本：Codex CLI v0.131.0（2026-05-18）
核心定义：OpenAI Codex CLI（GitHub 83,200+⭐）是运行在终端的开源 AI 编程智能体，国内使用的核心操作是在 ~/.codex/config.toml 中设置 openai_base_url 指向国内兼容 API 端点，替代默认的 api.openai.com，从而无需翻墙、无需境外账号完成配置。
Codex CLI 是什么？
Codex CLI 是 OpenAI 于 2026 年开源的终端 AI 编程智能体（Rust 实现，Apache-2.0），能：
● 读取并修改代码文件：理解项目结构，跨文件重构
● 执行终端命令：运行测试、git 操作、构建脚本
● 多步骤自主完成任务：拆解任务并逐步执行，遇到不确定操作暂停确认
● 接入任意兼容 OpenAI 协议的 API：通过 openai_base_url 替换后端
国内核心问题：默认调用 api.openai.com，大陆无法直连。解法是一行配置：把 openai_base_url 指向国内兼容端点，Codex 的其他功能完全不变。
第一步：安装 Codex CLI
选择最适合你环境的方式：
# 方式一：npm（推荐，Node 18+ 环境）
npm install -g @openai/codex
# 方式二：Homebrew（macOS）
brew install --cask codex
# 方式三：从 GitHub Releases 直接下载二进制（网络受限时用）
# macOS Apple Silicon
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-aarch64-apple-darwin.tar.gz | tar -xz
sudo mv codex /usr/local/bin/
# macOS Intel
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-x86_64-apple-darwin.tar.gz | tar -xz
sudo mv codex /usr/local/bin/
# Linux x86_64（musl 静态链接，不依赖系统 glibc，推荐）
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-x86_64-unknown-linux-musl.tar.gz | tar -xz
sudo mv codex /usr/local/bin/
验证安装：
codex --version
# 输出：codex 0.131.0
第二步：国内核心配置（3 分钟完成）
2.1 创建配置目录和文件
mkdir -p ~/.codex
创建或编辑 ~/.codex/config.toml：
#:schema https://developers.openai.com/codex/config-schema.json # ① 替换为国内兼容端点（七牛云 AI） openai_base_url = "https://api.qnaigc.com/v1" # ② 选择模型（以七牛云模型广场实际名称为准） model = "deepseek-v4-pro" # ③ 沙盒模式：允许修改当前项目目录的文件 sandbox_mode = "workspace-write" # ④ 关闭联网搜索（国内连接 Bing Search API 不稳定） web_search = "disabled" # ⑤ 审批策略：非破坏性命令自动执行，不确定时暂停确认 approval_policy = "on-request" 2.2 设置 API Key 环境变量
# 永久写入 shell 配置（zsh 用户）
echo 'export OPENAI_API_KEY="你的七牛云API Key"' >> ~/.zshrc
source ~/.zshrc
# bash 用户
echo 'export OPENAI_API_KEY="你的七牛云API Key"' >> ~/.bashrc
source ~/.bashrc
七牛云 API Key 申请地址：portal.qiniu.com/ai-inference/api-key（国内手机号注册，新用户有免费额度）
2.3 用 codex doctor 验证配置
v0.131.0 新增了 codex doctor 诊断命令，配置完成后必跑：
codex doctor
doctor 会检查：
● ✅ 运行时环境（Node 版本、二进制完整性）
● ✅ 认证状态（API Key 是否存在）
● ✅ 网络连通性（能否到达 openai_base_url）
● ✅ config.toml 格式合法性
● ✅ 沙盒配置是否有效
所有项目绿色即可开始使用。出现红色项目，按提示修复再继续。
第三步：第一个任务
进入你的项目目录，启动 Codex：
cd ~/your-project
codex
示例任务 1：代码审查
> 检查这个项目里有没有明显的 Bug 或安全问题，列出 Top 5
示例任务 2：添加新功能
> 给 src/auth.py 的 login() 函数添加速率限制，每个 IP 每分钟最多 10 次请求
示例任务 3：用 @ 提及特定文件（v0.131.0 新功能）
v0.131.0 支持在 Prompt 中用 @ 直接提及文件或目录：
> 对比 @src/old_parser.py 和 @src/new_parser.py 的性能差异，给出优化建议
输入 @ 后会弹出文件搜索框，支持模糊匹配项目内所有文件。
示例任务 4：非交互式单次任务（适合脚本）
# 直接传入任务，不进入交互界面
codex -q "为所有 Python 文件的公开函数添加类型注解"
# 使用 -z 获取纯净输出（无 banner、无 spinner，适合管道）
codex -z "列出这个项目的所有 TODO 注释" > todos.txt
沙盒模式详解：控制 Codex 的操作权限
sandbox_mode 控制 Codex 能对文件系统做什么：
# 推荐日常开发配置 sandbox_mode = "workspace-write" approval_policy = "on-request" # 遇到破坏性命令暂停确认 approval_policy 控制 Codex 何时暂停等待你确认：
● on-request：默认值，不确定的命令暂停等确认
● never：自动批准所有操作（相当于 --yolo 模式）
● untrusted：每个操作都要确认
切换到其他国内模型
七牛云 AI 统一接入多个模型，修改 config.toml 中的 model 字段即可切换，base_url 和 API Key 不变：
# DeepSeek V4（默认推荐，代码能力强） model = "deepseek-v4-pro" # DeepSeek R1（推理增强，适合复杂架构分析） model = "deepseek-r1" # Claude Sonnet 4.6（视觉能力强，适合带截图的任务） model = "claude-sonnet-4-6" # Kimi K2（长上下文，适合大型代码库） model = "kimi-k2" 以七牛云 AI 模型广场（qiniu.com/ai/models）实际支持的模型标识符为准。
也可以使用 model_providers 配置多个备用端点：
[model_providers.qiniu] base_url = "https://api.qnaigc.com/v1" env_key = "OPENAI_API_KEY" name = "七牛云 AI" [model_providers.deepseek] base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" name = "DeepSeek 官方" model_provider = "qiniu" model = "deepseek-v4-pro"
常用命令速查
# 进入交互式对话（最常用）
codex
# 单次任务（不进入交互界面）
codex -q "任务描述"
# 纯净输出（适合脚本/管道）
codex -z "任务描述"
# 临时切换模型（不改 config.toml）
codex --model deepseek-r1 -q "分析这个算法的时间复杂度"
# 临时使用完全访问模式
codex --full-access -q "清理临时文件"
# 诊断配置和网络（v0.131.0 新增）
codex doctor
# 查看所有可用选项
codex --help
会话内常用斜杠命令
常见问题排查
API 连接超时 / 无响应
# 先跑 codex doctor 定位问题
codex doctor
# 手动测试端点连通性
curl -s https://api.qnaigc.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200
若 curl 正常但 Codex 超时，检查 config.toml 中 openai_base_url 末尾是否多了斜杠（/v1/ 应写为 /v1）。
OPENAI_API_KEY 未设置报错
echo $OPENAI_API_KEY # 若为空，重新执行 source ~/.zshrc
npm 安装报 EACCES 权限错误
# 推荐用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install --lts
npm install -g @openai/codex
model not found 报错
登录七牛云 AI 模型广场查看当前可用模型的准确名称，更新 config.toml 的 model 字段。模型名称大小写和版本后缀需完全一致。
FAQ
Q：Codex 会不会自动删文件或跑危险命令？
A：不会，默认 approval_policy = "on-request" 下，删除文件、运行数据库迁移等破坏性命令会暂停并等待你确认。只有明确设置 approval_policy = "never" 或使用 --yolo 参数时才会自动执行所有命令。日常开发保持 on-request 是最安全的选择。
Q：Codex 和 Claude Code 有什么区别，国内该用哪个？
A：两者都是终端 AI 编程智能体。Codex CLI 开源（Apache-2.0），配置 openai_base_url 接国内 API；Claude Code 是 Anthropic 出品，配置 ANTHROPIC_BASE_URL 接国内 API（如七牛云 Claude 端点）。功能定位相近，选择哪个主要取决于习惯和模型偏好。两者都可以通过七牛云 AI 的统一端点访问 DeepSeek 和 Claude。
Q：config.toml 改了之后要重启 Codex 吗？
A：是的，config.toml 的修改在下次 codex 启动时生效，当前会话不会热更新。用 codex doctor 可以在不启动完整会话的情况下验证配置是否合法。
Q：国内 npm 安装速度很慢怎么办？
A：切换为淘宝镜像：npm install -g @openai/codex --registry https://registry.npmmirror.com；或直接从 GitHub Releases 下载预编译二进制文件，参见第一步的"方式三"。
Q：Codex 支持中文 Prompt 吗？
A：支持。Codex 对中文有完整理解能力，直接用中文描述任务即可。回复语言跟随 Prompt 语言，也可以在 developer_instructions 里固定：“始终用中文回复”。
developer_instructions = "始终用中文回复，代码注释保持英文"
总结
国内使用 Codex CLI 的完整流程：安装（npm / brew / 二进制三选一）→ 三行 config.toml 配置（base_url + model + sandbox_mode）→ 设置 API Key 环境变量 → codex doctor 验证 → 进入项目目录运行 codex，整个过程约 5 分钟。
七牛云 AI（api.qnaigc.com/v1）通过 OpenAI 兼容协议接入 DeepSeek V4、Claude、Kimi 等模型，一个 API Key 可在 config.toml 中切换不同模型，是目前国内 Codex 用户使用最广泛的接入方案之一。
本文配置基于 Codex CLI v0.131.0（2026-05-18）官方 Config Reference。
参考资源
● Codex CLI GitHub：https://github.com/openai/codex（83,200+⭐）
