Codex CLI

OpenAI 官方编码 CLI，使用 GPT-5.4 / GPT-5.5 系列模型 + Responses API。

待验证（TODO/VERIFY）：-codex 专调模型

旧平台实测（2026-06-10）：gpt-5.1-codex 等 -codex 后缀专调模型已下架。Shuro 当前在售 GPT 模型为 gpt-5.5 / gpt-5.4 / gpt-5.4-mini，同样不含 -codex 后缀模型，配置 model = "gpt-5.5" 即可正常使用。

版本说明

本文最后验证：Codex CLI 0.129.0（2026-05，旧平台验证）

安装

macOS / Linux

# 用户级 npm（推荐，避免 sudo）
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
npm install -g @openai/codex

# 加进 PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
exec $SHELL

Windows

npm install -g @openai/codex

Fish Shell

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
npm install -g @openai/codex
fish_add_path ~/.npm-global/bin

验证

codex --version
# 应输出: codex-cli 0.129.0 或更高

配置 Shuro

Codex 配置分两个文件，两个都要。

文件 1：~/.codex/config.toml

Windows 路径：%USERPROFILE%\.codex\config.toml

model_provider = "Shuro"
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
disable_response_storage = true

[model_providers.Shuro]
name = "Shuro"
base_url = "https://shuro.vip/v1"
wire_api = "responses"
requires_openai_auth = true

base_url 要带 /v1

和 Claude Code 不同，Codex 这里 必须带 /v1：

• ✅ https://shuro.vip/v1
• ❌ https://shuro.vip

文件 2：~/.codex/auth.json

Windows 路径：%USERPROFILE%\.codex\auth.json

{
  "OPENAI_API_KEY": "<您的 API Key>"
}

为什么不用环境变量？

配 requires_openai_auth = true 后，Codex 从 auth.json 读 key，不再依赖环境变量。这是最干净的持久化方式。

如果你坚持用环境变量，把 config.toml 里 requires_openai_auth = true 改成 env_key = "OPENAI_API_KEY"，然后 export OPENAI_API_KEY=...。

验证

codex exec --skip-git-repo-check "Reply with exactly one word: pong"

预期输出：

provider: Shuro
model: gpt-5.5
codex
pong
tokens used: 13,xxx

日常使用

# 进入项目
cd ~/your-project

# 交互模式
codex

# 一次性命令
codex exec "把 main.py 重构成模块化结构"

# 不在 git 仓库时
codex exec --skip-git-repo-check "解释这段代码"

切换模型

修改 config.toml 的 model 字段：

模型 ID	适用	备注
gpt-5.5	编码首选	最新主力，1.1M 上下文
gpt-5.4	通用	思考能力强，400K 上下文
gpt-5.4-mini	轻量任务	速度快、成本低，400K 上下文
claude-opus-4-7	切到 Claude	该模型双协议均在售；经 Codex（Responses API）调用 Claude 是否可用待验证（TODO/VERIFY）

model_reasoning_effort 可选 high / medium / low，影响思考预算与价格。

⚠️ 常见错误

404 Not Found: /v1/responses

base_url 写错或 key 没 OpenAI 权限。检查：

• base_url 是否带 /v1
• key 是不是带 GPT 模型权限（部分套餐只有 Claude）

Not inside a trusted directory

在 git 仓库外运行 codex exec 时常见。解决：

codex exec --skip-git-repo-check "..."

或在 config.toml 加：

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

Codex could not find bubblewrap (仅 Linux)

不影响使用，可选安装：

sudo apt install bubblewrap     # Debian/Ubuntu
sudo dnf install bubblewrap     # Fedora

Falling back from WebSockets to HTTPS transport

Codex 优先用 WebSocket，中转平台通常只提供 HTTPS，自动 fallback，不影响功能，可以无视这条 warning。（旧平台观察，Shuro 上待复测 ）

Missing environment variable: OPENAI_API_KEY

auth.json 没被读取。原因：config.toml 里写的是 env_key = "OPENAI_API_KEY" 而非 requires_openai_auth = true。两种二选一，别混用。

配置 ≠ 环境变量

误区警告

网上很多教程让你写 ~/.codex/auth.json 并依赖环境变量，但 auth.json 只对 requires_openai_auth = true 的 provider 生效。

config.toml 配置	API Key 来源
env_key = "OPENAI_API_KEY"	环境变量（auth.json 无效）
requires_openai_auth = true	auth.json（环境变量无效）

两个开关互斥，按你的部署偏好二选一。

配套工具

• CC Switch 也支持 Codex 配置切换
• ccapi 多中转站延迟测试