Codex CLI 使用指南
Codex 是 OpenAI 官方的命令行 AI 编程助手，支持通过 Codex API Hub 代理使用。注意：Codex 使用 OpenAI 兼容格式，端点需要包含 /v1 路径。

环境准备：安装 Node.js

claude 需要 Node.js 环境才能运行（需 v18 或更高版本）。

方法一：使用 Homebrew（推荐）
bash
# 更新 Homebrew
brew update
# 安装 Node.js
brew install node
方法二：官网下载
  1. 访问 https://nodejs.org/
  2. 下载适合 macOS 的 LTS 版本（需 v18 或更高）
  3. 打开下载的 .pkg 文件，按照安装向导完成

验证 Node.js 安装

安装完成后，打开终端/命令行，输入以下命令验证：

bash
node --version
npm --version

如果显示版本号，说明安装成功了！

安装 codex codex

执行：

bash
npm i -g @openai/codex --registry=https://registry.npmmirror.com

验证安装：

bash
codex --version

连接 Codex API Hub 服务

配置文件设置

  1. 打开文件资源管理器，找到 ~/.codex 文件夹（不存在则创建）
  2. 创建 config.toml 文件
  3. 使用文本编辑器打开，添加以下内容：

创建 config.toml 文件（使用 auth.json 存储密钥时，无需 env_key 字段）：

toml
model_provider = "cch"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
disable_response_storage = true
sandbox_mode = "workspace-write"
[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false
streamable_shell = false
rmcp_client = true

[model_providers.cch]
name = "cch"
base_url = "当前站点地址/v1"
wire_api = "responses"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

创建 auth.json 文件，添加：

json
{
  "OPENAI_API_KEY": "your-api-key-here"
}

提示此方式通过 auth.json 文件存储 API 密钥，config.toml 中无需配置 env_key 字段。

重要提示

  • 将 your-api-key-here 替换为您的 Codex API Hub API 密钥
  • 注意：Codex 使用 OpenAI 兼容格式，端点包含 /v1 路径

VS Code 扩展配置

  1. 在 VS Code 扩展中搜索并安装 Codex – OpenAI's coding agent
  2. 确保已按照上述步骤配置好 config.toml 和 auth.json
  3. 设置环境变量 CCH_API_KEY

重要

env_key 只能是环境变量名称（如 CCH_API_KEY），不能是完整的密钥。如果直接填写密钥，会报错找不到令牌或令牌配置错误。

启动 codex

在项目目录下运行：

bash
cd /path/to/your/project
codex

首次启动时，codex 会进行初始化配置。

常见问题

1. 命令未找到

bash
# 检查 npm 全局安装路径并添加到 PATH（如果不在）
npm config get prefix

# # 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 连接失败

bash
# # 检查环境变量
echo $CCH_API_KEY

# # 测试网络连接
curl -I 当前站点地址

3. 更新 codex

bash
npm i -g @openai/codex --registry=https://registry.npmmirror.com