Codex CLI 使用指南

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

macOS

环境准备：安装 Node.js

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

方法一：使用 Homebrew（推荐）

 更新 Homebrew
brew update
 安装 Node.js
brew install node

方法二：官网下载

1. 访问 https://nodejs.org/ https://nodejs.org/
2. 下载适合 macOS 的 LTS 版本（需 v18 或更高）
3. 打开下载的 .pkg 文件，按照安装向导完成

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

node --version
npm --version

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

安装 codex codex

执行：

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

验证安装：

codex --version

连接 cch 服务

配置文件设置

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

配置文件方式

环境变量方式

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

model_provider = "cch"
model = "gpt-5.4"
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 文件，添加：

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

提示

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

重要提示

• 将 your-api-key-here 替换为您的 cch 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

在项目目录下运行：

cd /path/to/your/project
codex

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

常见问题

1. 命令未找到

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

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

2. API 连接失败

 检查环境变量
echo $CCH_API_KEY

 测试网络连接
curl -i 当前站点地址/v1/messages

3. 更新 codex

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

Windows

环境准备：安装 Node.js

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

方法一：官网下载（推荐）

1. 访问 https://nodejs.org/ https://nodejs.org/
2. 下载 LTS 版本（需 v18 或更高）
3. 双击 .msi 文件，按向导安装（保持默认设置）

方法二：使用包管理器

 使用 Chocolatey
choco install nodejs

 或使用 Scoop
scoop install nodejs

提示

建议使用 PowerShell 而不是 CMD，以获得更好的体验

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

node --version
npm --version

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

安装 codex codex

以管理员身份运行 PowerShell，执行：

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

验证安装：

codex --version

连接 cch 服务

配置文件设置

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

配置文件方式

环境变量方式

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

model_provider = "cch"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
sandbox_mode = "workspace-write"
windows_wsl_setup_acknowledged = true

[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 文件，添加：

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

提示

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

重要提示

• 将 your-api-key-here 替换为您的 cch 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

在项目目录下运行：

cd C:\path\to\your\project
codex

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

常见问题

1. 命令未找到

• 确保 npm 全局路径（通常是 C:\Users\你的用户名\AppData\Roaming\npm）已添加到系统 PATH
• 重新打开 PowerShell 窗口

2. API 连接失败

 检查环境变量
echo $env:CCH_API_KEY

 测试网络连接
Test-NetConnection -ComputerName 当前站点地址 -Port 443

3. 更新 codex

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

Linux

环境准备：安装 Node.js

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

方法一：使用官方仓库（推荐）

 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系统包管理器

 Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

 CentOS/RHEL/Fedora
sudo dnf install nodejs npm

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

node --version
npm --version

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

安装 codex codex

执行：

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

验证安装：

codex --version

连接 cch 服务

配置文件设置

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

配置文件方式

环境变量方式

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

model_provider = "cch"
model = "gpt-5.4"
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 文件，添加：

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

提示

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

重要提示

• 将 your-api-key-here 替换为您的 cch 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

在项目目录下运行：

cd /path/to/your/project
codex

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

常见问题

1. 命令未找到

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

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

2. API 连接失败

 检查环境变量
echo $CCH_API_KEY

 测试网络连接
curl -i 当前站点地址/v1/messages

3. 更新 codex

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