跳到主要内容

使用 Codex CLI

Codex CLI 是运行在终端中的 AI 编码工具。完成本页配置后，它会通过 ClawdRouter 调用你有权限使用的模型。

使用前准备​

  • Windows、macOS 或 Linux 电脑。
  • Node.js 18 或更高版本，以及 npm。
  • API Key。
  • 可调用的模型 ID。
注意

请勿将真实 API Key 写入代码仓库、公开文档或截图。本文中的 YOUR_API_KEY 和 YOUR_MODEL_ID 均为占位符。

快速开始​

按以下顺序完成操作：

  1. 安装 Node.js 和 npm。
  2. 安装 Codex CLI。
  3. 创建 config.toml。
  4. 设置 API Key。
  5. 验证连接并启动 Codex CLI。

1. 安装 Node.js 和 npm​

Windows​

在 PowerShell 中执行：

winget install OpenJS.NodeJS.LTS

安装完成后，重新打开 PowerShell：

node --version
npm --version

 

Linux​

在终端中执行：

sudo apt update
sudo apt install -y nodejs npm
node --version
npm --version

macOS​

如未安装 Node.js，可先在“终端”中执行：

brew install node
node --version
npm --version

2. 安装 Codex CLI​

Windows​

npm install -g @openai/codex
codex --version

Linux​

sudo npm install -g @openai/codex
codex --version

macOS​

npm install -g @openai/codex
codex --version

3. 创建配置文件​

Windows​

在 PowerShell 中执行：

New-Item -ItemType Directory -Force $HOME\.codex
notepad $HOME\.codex\config.toml

Linux或macOS​

在终端中执行：

mkdir -p ~/.codex
nano ~/.codex/config.toml

先将以下公共配置写入 config.toml：

model_provider = "clawdrouter"
model = "YOUR_MODEL_ID"

[model_providers.clawdrouter]
name = "ClawdRouter"
base_url = "__DOCS_API_ORIGIN__/v1"
wire_api = "responses"

将 YOUR_MODEL_ID 替换为当前 API Key 有权限调用的模型 ID。

4. 配置 API Key 读取方式​

在第 3 步的 config.toml 末尾，根据操作系统添加对应配置。

Windows​

[model_providers.clawdrouter.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:YOUR_API_KEY"]

Linux 或 macOS​

[model_providers.clawdrouter.auth]
command = "sh"
args = ["-c", "echo $YOUR_API_KEY"]

保存并退出配置文件：

  • Windows：在记事本中按 Ctrl + S 保存，然后关闭窗口。
  • Linux 或 macOS：在 nano 中按 Ctrl + O，按 Enter 确认保存，再按 Ctrl + X 退出。

5. 设置 API Key​

Windows​

仅在当前 PowerShell 会话中使用时，执行以下命令。关闭该窗口后，Key 会失效：

$env:YOUR_API_KEY = "YOUR_API_KEY"

如需在以后新打开的 PowerShell 中自动生效，执行以下命令：

setx YOUR_API_KEY "YOUR_API_KEY"

setx 不会更新当前已打开的 PowerShell。执行后请关闭并重新打开 PowerShell，再继续下一步。

Linux​

临时设置（仅当前终端有效）：

export YOUR_API_KEY="YOUR_API_KEY"

如需在以后打开终端时自动生效，可安全输入 Key 并写入 Bash 配置：

read -rsp "请输入 API Key: " YOUR_API_KEY; echo
printf '\nexport YOUR_API_KEY=%q\n' "$YOUR_API_KEY" >> ~/.bashrc
unset YOUR_API_KEY
source ~/.bashrc

该操作会将真实 Key 保存在本机的 ~/.bashrc 中。仅建议在个人受信任设备上使用；不要同步、提交或截图该文件。

macOS​

临时设置（仅当前“终端”窗口有效）：

export YOUR_API_KEY="YOUR_API_KEY"

如需在以后打开终端时自动生效，可安全输入 Key 并写入 Zsh 配置：

read -rsp "请输入 API Key: " YOUR_API_KEY; echo
printf '\nexport YOUR_API_KEY=%q\n' "$YOUR_API_KEY" >> ~/.zshrc
unset YOUR_API_KEY
source ~/.zshrc

该操作会将真实 Key 保存在本机的 ~/.zshrc 中。仅建议在个人受信任设备上使用；不要同步、提交或截图该文件。

检查 API Key 是否已设置​

Windows：

[bool]$env:YOUR_API_KEY

Linux 或 macOS：

[ -n "$YOUR_API_KEY" ] && echo "API Key is set" || echo "API Key is not set"

正常情况下，Windows 会输出 True，Linux 或 macOS 会输出 API Key is set。

6. 验证连接​

在任意目录执行：

codex exec --skip-git-repo-check "Reply with exactly: connection successful."

连接成功时，输出中会包含：

connection successful.

7. 启动 Codex CLI​

进入你的代码项目目录。

Windows：

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

Linux 或 macOS：

cd /path/to/your/project
codex

启动后，直接在终端中输入你的编码需求即可。

配置参考​

基础配置​

配置项说明
model_provider当前使用的模型提供商标识，应为 clawdrouter。
model模型 ID，填写有调用权限的 YOUR_MODEL_ID。
name提供商显示名称。
base_url服务请求地址。
wire_api调用协议，本配置使用 responses。

认证配置​

配置项说明
auth.commandCodex CLI 用来读取 API Key 的命令。Windows 使用 powershell，Linux 和 macOS 使用 sh。
auth.args读取 YOUR_API_KEY 环境变量的命令参数。
YOUR_API_KEY保存真实 API Key 的环境变量名称。

项目可信级别​

Codex CLI 可按项目设置可信级别。将以下内容添加到 config.toml，并替换为实际项目路径。

Windows​

[projects."C:\\path\\to\\your\\project"]
trust_level = "trusted"

Linux 与 macOS​

[projects."/path/to/your/project"]
trust_level = "trusted"

仅应将你信任的项目设为 trusted。对于来源不明的项目，请保持受限状态。

常见问题​

codex: command not found 或“不是内部或外部命令”​

Codex CLI 未安装成功，或 npm 全局安装目录未被终端识别。

  1. 关闭并重新打开终端。
  2. 执行 codex --version。
  3. 如仍失败，重新执行第 2 步的安装命令，并确认 node --version、npm --version 均能正常输出。

PowerShell 提示无法识别 winget​

Windows 版本可能不包含 Windows Package Manager。请从 Node.js 官网 安装 LTS 版本，安装完成后重新打开 PowerShell。

npm install -g @openai/codex 因权限失败​

  • Windows：使用“以管理员身份运行”的 PowerShell 后重试。
  • Linux：使用本文的 sudo npm install -g @openai/codex 命令。

提示找不到 YOUR_API_KEY​

请重新执行第 5 步的 API Key 设置命令。

  • Windows：使用 setx 后必须关闭并重新打开 PowerShell。
  • Linux：如果使用临时设置，请在启动 codex 的同一个终端中执行 export YOUR_API_KEY="YOUR_API_KEY"；如已写入 ~/.bashrc，请重新打开终端。

401 Unauthorized 或 API Key 无效​

请重新复制 API Key，确认没有包含多余的空格、引号或换行符，然后重新设置。

403 Forbidden​

当前 API Key 无权使用所填模型。请更换有权限的 API Key，或修改 YOUR_MODEL_ID。

404、模型不存在或模型调用失败​

请检查 config.toml 中的 YOUR_MODEL_ID 是否填写正确，并确认当前 API Key 可以调用该模型。

Encrypted content is not supported with this model​

当前模型不支持 Codex CLI 所需能力。请更换为服务商支持的 Codex 模型。

429 Too Many Requests​

当前请求超过速率或并发限制。请稍后重试；如持续发生，请检查账户套餐、限流配置或联系管理员。

连接超时、ECONNREFUSED 或无法访问服务​

请确认：

  1. config.toml 中的 base_url 未被误改。
  2. 当前网络可以访问服务。
  3. 公司网络、代理或防火墙没有拦截连接。

修改 config.toml 后没有生效​

退出 Codex CLI，关闭终端后重新打开，再次设置 API Key 并运行 codex。

出现 Unknown model 或 fallback metadata 警告​

请确认已按第 4 步添加与操作系统对应的 [model_providers.clawdrouter.auth] 配置，并在设置 API Key 后重新启动 Codex CLI。

Linux 提示找不到 bubblewrap​

这是 Linux 沙箱相关的提示。它通常不会阻止 API 连接；如需使用完整沙箱能力，请按系统提示安装 bubblewrap。

Windows 中无法保存 config.toml​

请确认文件路径为：

%USERPROFILE%\.codex\config.toml

使用记事本保存时，请确认文件名是 config.toml，而不是 config.toml.txt。

相关链接​