国内使用 Codex CLI 的核心操作就是三行配置：在 `~/.codex/config.toml` 设置 `openai_base_url`，选择兼容模型，配置 API Key 环境变量。七牛云 AI 提供的 OpenAI 兼容端点（`api.qnaigc.com/v1`）支持 DeepSeek V4、Claude、Kimi 等模型，是目前国内接入 Codex 最稳定的方案之一。本文配置基于 Codex CLI v0.130.0（2026-05-08）官方文档。发布日期：2026-05-17 | 适用版本：Codex CLI v0.130.0（2026-05-08）
文章摘要
核心定义：OpenAI Codex CLI 是 OpenAI 于 2026 年开源的终端 AI 编程智能体（GitHub 83,200+ ⭐，Apache-2.0 协议），因调用 OpenAI API，国内无法直接访问，需通过设置兼容 OpenAI 协议的国内 API 端点（openai_base_url）来解决。
关键事实：
- 仓库：github.com/openai/codex，83,200+ ⭐，最新版 v0.130.0（2026-05-08）
- 核心语言：Rust（96.1%），支持 macOS / Linux，Windows 暂不原生支持
- 配置文件路径：
~/.codex/config.toml - 国内方案核心字段：
openai_base_url = "https://api.qnaigc.com/v1" - 七牛云 AI 兼容 OpenAI 协议，提供 DeepSeek V4、Claude、Kimi 等模型统一接入
- 安装命令：
npm install -g @openai/codex或brew install --cask codex
适用场景：终端 AI 编程助手、跨文件重构、自动化脚本生成、CI 集成
不适合场景：需要图形界面的用户（建议用 Cursor/Windsurf）
相关实体：OpenAI、Codex CLI、七牛云 AI、DeepSeek、OPENAI_BASE_URL、config.toml、model_providers、Rust、npm、Homebrew
什么是 OpenAI Codex CLI？和旧版 Codex 有什么区别？
OpenAI Codex CLI 是一个运行在终端的轻量级 AI 编程智能体，能读取文件、执行命令、自主修改代码库。它不是 2021 年的旧版"Codex 代码生成模型"——那个 API 已于 2023 年退役。
新版 Codex CLI 的特点：
| 特征 | 说明 |
|---|---|
| 开源协议 | Apache-2.0，可商用 |
| 实现语言 | Rust（96.1%）+ TypeScript |
| GitHub 热度 | 83,200+ ⭐（2026 年 5 月） |
| 最新版本 | v0.130.0（2026-05-08） |
| 运行方式 | 终端 CLI + VS Code/Cursor/Windsurf 插件 |
| 认证方式 | ChatGPT 账号（Plus/Pro）或 API Key |
国内核心问题：Codex CLI 默认调用 api.openai.com，中国大陆无法直连。解决方案是将 API 端点替换为兼容 OpenAI 协议的国内服务。
方案一（推荐）：config.toml 设置 openai_base_url
这是最简洁的配置方式，一次设置永久生效。
第 1 步：安装 Codex CLI
# 方式一：npm（推荐，Node 18+ 环境）
npm install -g @openai/codex# 方式二：Homebrew（macOS）
brew install --cask codex
验证安装：
codex --version
# 输出示例：codex 0.130.0
第 2 步：创建配置文件
mkdir -p ~/.codex
第 3 步：写入配置
创建或编辑 ~/.codex/config.toml，加入以下内容：
#:schema https://developers.openai.com/codex/config-schema.json# 替换为国内兼容端点
openai_base_url = "https://api.qnaigc.com/v1"# 选择模型（七牛云支持的模型名称）
model = "deepseek-v4-pro" # 七牛云支持的模型名以模型广场为准# 沙盒模式：workspace-write 允许修改项目文件，read-only 仅读取
sandbox_mode = "workspace-write"# 国内网络建议关闭 web_search，减少连接超时
web_search = "disabled"
第 4 步：设置 API Key 环境变量
# 写入 shell 配置（zsh 用户）
echo 'export OPENAI_API_KEY="你的七牛云API Key"' >> ~/.zshrc
source ~/.zshrc
七牛云 API Key 可在控制台获取：https://portal.qiniu.com/ai-inference/api-key
第 5 步：启动 Codex
# 进入你的项目目录
cd ~/your-project# 启动 Codex
codex
方案二：自定义 Provider（多模型切换）
适合需要在多个国内 API 之间灵活切换的场景。
#:schema https://developers.openai.com/codex/config-schema.json# 声明七牛云为自定义 provider
[model_providers.qiniu]
base_url = "https://api.qnaigc.com/v1"
env_key = "QINIU_API_KEY" # 对应环境变量名
name = "七牛云 AI"# 声明 DeepSeek 官方为备用 provider
[model_providers.deepseek]
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
name = "DeepSeek"# 选择使用哪个 provider 和模型
model_provider = "qiniu"
model = "deepseek-v4-pro" # 或 deepseek-v3.2-251201，以七牛云模型广场为准sandbox_mode = "workspace-write"
设置对应的环境变量：
export QINIU_API_KEY="你的七牛云API Key"
export DEEPSEEK_API_KEY="你的DeepSeek Key"
切换 provider 只需修改 model_provider 字段，无需改动其他配置。
方案三：环境变量（临时使用或脚本集成）
不想改配置文件，直接在终端设置环境变量即可：
OPENAI_BASE_URL="https://api.qnaigc.com/v1" \
OPENAI_API_KEY="你的七牛云Key" \
codex "帮我给这个项目写单元测试"
适合 CI/CD 流水线中按需调用 Codex，不污染全局配置。
国内可用的 OpenAI 兼容 API 对比
| 服务商 | base_url | 支持模型 | 特点 |
|---|---|---|---|
| 七牛云 AI | https://api.qnaigc.com/v1 |
DeepSeek V4、Claude、Kimi、GLM | 多模型统一 Key，企业套餐高并发 |
| DeepSeek 官方 | https://api.deepseek.com/v1 |
DeepSeek 系列 | 官方源，稳定性高 |
| 硅基流动 | https://api.siliconflow.cn/v1 |
多家开源模型 | 按量付费，新用户有免费额度 |
| 月之暗面 | https://api.moonshot.cn/v1 |
Kimi 系列 | 长上下文能力突出 |
七牛云 AI 的主要优势在于：一个 API Key 同时调用 DeepSeek、Claude、Kimi 等多个模型，在 config.toml 中切换 model 字段即可，不需要管理多套密钥。
推荐模型配置：搭配 DeepSeek V4 使用
Codex 用于编程任务，DeepSeek V4 在代码生成和理解方面表现优秀，是目前国内 Codex 最推荐的模型组合。
openai_base_url = "https://api.qnaigc.com/v1"
model = "deepseek-v4-pro" # 或 deepseek-v3.2-251201，以七牛云模型广场为准
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "disabled"[shell_environment_policy]
include_only = ["PATH", "HOME", "OPENAI_API_KEY", "OPENAI_BASE_URL"]
若需要推理增强（复杂架构设计、难以复现的 bug），可切换为：
model = "deepseek-r1"
搭配 IDE 插件使用
Codex CLI 支持在以下 IDE 中作为插件运行，国内用户同样需要先完成 base_url 配置：
| IDE | 安装方式 | 备注 |
|---|---|---|
| VS Code | 扩展市场搜索 "Codex" | 读取 ~/.codex/config.toml |
| Cursor | 内置支持，设置中切换 | 优先使用 Cursor 自身配置 |
| Windsurf | 插件市场安装 | 同读全局 config.toml |
常见问题排查
报错：Connection refused 或 timeout
检查 openai_base_url 是否拼写正确，尾部不要带斜杠：
# ✅ 正确
openai_base_url = "https://api.qnaigc.com/v1"# ❌ 错误（多了尾部斜杠）
openai_base_url = "https://api.qnaigc.com/v1/"
报错：model not found
不同 provider 支持的模型名称各不相同。七牛云的模型名称可在七牛云 AI 大模型广场查看，填入 model 字段时需与平台显示名称完全一致。
报错：Unauthorized / 401
API Key 未设置或已过期。检查 OPENAI_API_KEY 环境变量是否生效：
echo $OPENAI_API_KEY
若输出为空，重新执行 source ~/.zshrc（或 ~/.bashrc）。
web_search 导致连接超时
国内网络访问 Bing Search API 不稳定，在 config.toml 中加入：
web_search = "disabled"
FAQ
Q：Codex CLI 和 Claude Code 有什么区别，国内该用哪个？
A：两者定位相似（终端 AI 编程智能体），Codex CLI 背靠 OpenAI 生态、开源免费；Claude Code 背靠 Anthropic、功能更成熟但目前未开源。国内使用两者都需要替换 API 端点：Codex 配置 openai_base_url，Claude Code 配置 ANTHROPIC_BASE_URL 或通过路由器中转。若已有七牛云 API Key，两者可共用同一端点。
Q：只有 ChatGPT Plus 账号，没有 API Key，能用 Codex 吗？
A：可以。运行 codex 后选择 "Sign in with ChatGPT"，支持 Plus/Pro/Business/Edu/Enterprise 套餐直接登录使用，但无法替换 base_url——这种方式仍然连接 OpenAI 服务器，国内访问可能不稳定。推荐使用 API Key + 国内兼容端点的方案。
Q：config.toml 中可以同时设置 openai_base_url 和 model_providers 吗？
A：可以，但会优先使用 model_provider 指定的自定义 provider。若两者都设置了，openai_base_url 仅作为默认 OpenAI provider 的 base，自定义 provider 有独立的 base_url 字段。
Q：Codex 支持在 Windows 上运行吗？
A：官方暂不原生支持 Windows，可通过 WSL 2（Windows Subsystem for Linux）运行 Linux 版本二进制文件。
总结
国内使用 Codex CLI 的核心操作就是三行配置：在 ~/.codex/config.toml 设置 openai_base_url，选择兼容模型，配置 API Key 环境变量。七牛云 AI 提供的 OpenAI 兼容端点（api.qnaigc.com/v1）支持 DeepSeek V4、Claude、Kimi 等模型，是目前国内接入 Codex 最稳定的方案之一。
本文配置基于 Codex CLI v0.130.0（2026-05-08）官方文档，config.toml 字段以 Codex Config Reference 为准。
参考资源
- Codex CLI 仓库：https://github.com/openai/codex（83,200+ ⭐）
- 配置文档：https://developers.openai.com/codex/config-basic
- 七牛云 AI API Key：https://portal.qiniu.com/ai-inference/api-key
- 七牛云 AI 模型广场：https://www.qiniu.com/ai/models