Codex CLI

手把手教你安装 Codex CLI，并用 OpenAI Hub 国内直连 API 替代官方接口。详细讲解 Node.js 环境、auth.json 和 config.toml 配置格式、常见问题排查。

用 OpenAI Hub 接入 Codex CLI

这篇教程要解决的事很简单：让你在本地跑起来 Codex CLI，并且用 OpenAI Hub 的国内直连 API 来替代官方接口。这样配置稳定、速度快，不需要再折腾代理。

一、环境准备

要让 Codex CLI 启动，系统环境必须满足：

  • Node.js ≥ 22
  • npm ≥ 10
  • 稳定的网络连接

如果你用的是 Windows，还要注意官方对原生支持偏“实验性”，更靠谱的做法是装 WSL。

搞定环境之后，开始安装。

二、安装 Codex CLI

Windows 用户

  1. 先安装 Git Bash，一路“下一步”就行。

  2. 再从 Node.js 官网 装个最新 LTS 版。

  3. 环境就绪后，在 CMD 或 PowerShell 里执行：

    npm install -g @openai/codex   # 全局安装 Codex CLI
codex --version                # 输出版本号说明安装成功

    注意这里有个坑：如果提示 “找不到命令 codex”，通常是 npm 的全局安装目录没加进 PATH，把路径加上就行。

macOS 用户

sudo npm install -g @openai/codex   # 用 npm 装 Codex CLI，权限不足就加 sudo 
codex --version                     # 检查是否安装成功

或用 Homebrew（可选方式）：

brew install codex

Linux 用户

大部分发行版都通用：

sudo npm install -g @openai/codex   # 全局安装
codex --version                     # 验证可执行命令是否能识别

搞定安装后，下一步就是让它用上 OpenAI Hub 的 API。

三、配置第三方 API 接入

Codex CLI 启动时，会读取你用户目录下的 ~/.codex（Windows 是 C:\Users\你的用户名\.codex）。

没有这个文件夹？就手动建一个。

进去之后要准备两份配置：auth.json 和 config.toml。

1. 写入密钥

auth.json 文件内容如下：

{
  "OPENAI_API_KEY": "sk-your-api-key"
}

注意这里有个坑：Key 前后不要有空格，很多人复制的时候不小心多了空格，会导致认证失败。

2. 指定模型与网关

config.toml 文件内容如下：

model_provider = "openai-hub"
model = "gpt-4o-codex"               # 可以按你实际使用的模型写
model_reasoning_effort = "high"      # 控制推理深度
disable_response_storage = true      # 不保存响应历史
preferred_auth_method = "apikey"     # 认证方式用 API Key

[model_providers.openai-hub]
name = "openai-hub"
base_url = "https://api.openai-hub.com/v1"

这个配置的逻辑很好理解：Codex CLI 就像司机，config.toml 告诉它去哪儿（base_url）开车，auth.json 则是它的通行证（API Key）。

保存完毕后，启动终端输入：

codex

如果能正常进入交互界面，就说明已成功接入 OpenAI Hub 的网关。

四、验证调用是否生效

在 Codex CLI 里可以简单试一句：

# 示例对话
请帮我写一个能解析 CSV 文件的 Node.js 工具函数。

正常输出代码说明请求已通过 OpenAI Hub 的代理通道完成。

如果报错 Invalid auth 或 Connection failed，就回去检查：

  • API Key 是否写对
  • base_url 是否是 https://api.openai-hub.com/v1
  • 网络是否能连到该地址（国内一般没问题）

五、常见问题

问：为什么运行时提示模型不可用？
Codex CLI 的模型配置要和 Hub 上支持的模型名一致，比如 gpt-4o-codex、gpt-4-turbo 等，可以在控制台的「模型列表」查询。

问：auth.json 和 config.toml 要放到 VS Code 项目里吗？
不用。它们是全局配置，只要在用户目录下有即可。

问：CLI 需要登录 OpenAI 官方账户吗？
不需要。你直接用 OpenAI Hub 的 API Key 完成认证。

下一步可以试试在 VS Code 里配置 Codex 插件，用它直接帮你重构代码片段或者做项目自动修复，这才是它最强的部分。