发布日期：2026-05-18 | 适用版本：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