OpenAI Codex CLI 配置教程

更新日期：2026-06-06

Codex CLI 是 OpenAI 的终端编码代理工具，适合在本地仓库中做代码修改、审查、批量重构和命令协作。对接 Crazyrouter 时，推荐使用当前官方支持的 config.toml 自定义 provider 方式，而不是旧版配置思路。

概览

通过 ~/.codex/config.toml 配置自定义 provider，Codex CLI 可以把请求发到 Crazyrouter：

推荐协议：OpenAI-compatible API
走的接口类型：Responses API
Base URL：https://api.crazyrouter.com/v1
认证变量：OPENAI_API_KEY
推荐默认模型：gpt-5.5

如果你之前只用过 ChatGPT 登录方式，接 Crazyrouter 时请切换到 API Key + 自定义 provider 配置。这样模型、日志、额度和计费都更可控。

查看 Codex 一键配置仓库

如果你想直接使用脚本写入环境变量和 Codex 配置，可以查看 crazyrouter-codex-cli 仓库。

适合谁用

想把 Crazyrouter 接到终端代理式编码工作流的人
想在本地仓库里做批量修改、代码审查和自动执行的人
想把 Codex、Cursor、Claude Code 的流量拆分计费的人
想优先使用当前已验证过的最新 OpenAI 模型做终端代理编码的人

使用协议

推荐协议：OpenAI-compatible API Codex CLI 当前推荐通过自定义 model_provider 使用 OpenAI 兼容 provider，并指定：

base_url = "https://api.crazyrouter.com/v1"
wire_api = "responses"

Crazyrouter 支持 /v1/responses，因此 Codex CLI 这条接法可以直接走 Responses API。但当前这条路径按 GPT 模型理解即可，Claude 不支持 POST /v1/responses。

系统要求与前置条件

项目	说明
Crazyrouter 账号	先在 crazyrouter.com 注册
Crazyrouter token	建议为 Codex 单独创建一个 `sk-...` token
Git	建议 `git 2.23+`
Node.js	建议 `Node.js 20+`
Codex CLI	建议当前稳定版
可用模型	至少放行一个适合编码的模型，如 `gpt-5.5`

建议初始白名单：

gpt-5.5

按操作系统的完整安装路径

Windows 推荐路径

Codex 在 Windows 上最简单的路径是：Git + Node.js + npm 全局安装 Codex + PowerShell 配置环境变量。推荐顺序：

安装 Git
安装 Node.js LTS
用 npm 安装 Codex CLI
用 PowerShell 写入 OPENAI_API_KEY
用 PowerShell 写入 $HOME/.codex/config.toml

推荐验证命令：

git --version
node -v
npm -v
codex --version
where.exe git
where.exe node
where.exe codex

如果 codex --version 找不到命令，先关闭并重新打开 PowerShell，再试一次。

macOS 推荐路径

macOS 上最顺手的路径通常是：Homebrew + Git + Node.js + brew 或 npm 安装 Codex CLI + ~/.zshrc 持久化环境变量。推荐顺序：

安装 Xcode Command Line Tools
安装 Homebrew（如果你还没有）
安装 Git、Node.js
安装 Codex CLI
写入 ~/.zshrc
写入 ~/.codex/config.toml

推荐验证命令：

git --version
node -v
npm -v
codex --version
which git
which node
which codex

Codex CLI 安装备选路径

除了包管理器，Codex 官方仓库也提供 GitHub Releases 二进制包。对大多数用户来说，仍然优先推荐：

Windows：npm install -g @openai/codex
macOS：brew install --cask codex 或 npm install -g @openai/codex

如果你想用脚本自动写入 Crazyrouter 相关配置，可以查看 crazyrouter-codex-cli。该仓库提供 Windows、macOS 和 Linux 的一键配置脚本；本文档仍保留完整手动配置步骤，便于你审查每一项配置。

从零开始完整安装

第 1 步：安装 Git

如果你还没有 Git，先装 Git，并补齐全局身份配置。

Windows PowerShell
macOS
Ubuntu / Debian

winget install --id Git.Git -e --source winget
git --version

xcode-select --install
git --version

或：

brew install git
git --version

sudo apt update
sudo apt install -y git
git --version

建议顺手执行：

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

第 2 步：安装 Node.js 20+

Codex CLI 是 Node.js 工具。先确认 Node 和 npm 已就绪。

Windows PowerShell
macOS
Ubuntu / Debian

winget install OpenJS.NodeJS.LTS
node -v
npm -v

brew install node
node -v
npm -v

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

如果你的发行版默认安装版本太旧，请升级到更高版本后再继续。

第 3 步：安装 Codex CLI

Windows PowerShell
macOS

推荐直接使用 npm 全局安装：

npm install -g @openai/codex
codex --version
where.exe codex

推荐优先使用 Homebrew：

brew install --cask codex
codex --version
which codex

如果你更习惯 npm，也可以：

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

第 4 步：在 Crazyrouter 创建 Codex 专用 token

在 Crazyrouter 后台创建一个名为 codex 的 token，第一次只建议放行：

gpt-5.5

这样首次排障更简单，也更容易控费。

第 5 步：先设置临时环境变量

Codex 通过 provider 配置读取 OPENAI_API_KEY。先在当前终端设置：

Linux / macOS
Windows PowerShell

export OPENAI_API_KEY=sk-xxx
echo $OPENAI_API_KEY

$env:OPENAI_API_KEY = "sk-xxx"
echo $env:OPENAI_API_KEY

第 6 步：把 API Key 写入持久环境变量

日常使用建议写入 shell 配置文件或系统用户环境变量。

Linux Bash
macOS / Zsh
Windows PowerShell

echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.bashrc
source ~/.bashrc

echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx", "User")
$env:OPENAI_API_KEY = "sk-xxx"

第 7 步：写入 Codex 配置文件 ~/.codex/config.toml

Codex CLI 启动时会读取 ~/.codex/config.toml。

macOS
Windows PowerShell

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.crazyrouter]
model = "gpt-5.5"
model_provider = "crazyrouter"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
EOF

New-Item -ItemType Directory -Force "$HOME/.codex" | Out-Null
@'
model = "gpt-5.5"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.crazyrouter]
model = "gpt-5.5"
model_provider = "crazyrouter"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
'@ | Set-Content -Path "$HOME/.codex/config.toml"

配置完后可以检查：

macOS
Windows PowerShell

cat ~/.codex/config.toml

Get-Content $HOME/.codex/config.toml

第 8 步：准备 Git 仓库并做首个快照

如果目录还不是 Git 仓库：

git init
git add .
git commit -m "chore: initial snapshot before Codex"

如果已经是现有仓库，至少先看一下：

git status

第 9 步：启动 Codex 并完成第一次验证

进入仓库目录后，可以先做一次最小验证：

cd /path/to/your/project
codex --profile crazyrouter "Reply only OK"

成功后再进入交互模式：

codex --profile crazyrouter

第一次验证建议按下面顺序：

Reply only OK
Read the repository structure only. Do not edit files.
Find the highest-risk file in this repo and explain why, but do not change anything.

使用场景	推荐模型	原因
默认主力编码	`gpt-5.5`	2026 年 3 月 23 日已在生产环境实测成功，适合作为 Codex / Responses API 主基线

模型	当前结论	说明
`kimi-k2.5`	推荐	`/v1/responses` SSE 可完整返回 `response.completed`，Codex 简单回复和读文件均通过
`kimi-k2.6`	推荐	与 `kimi-k2.5` 同档，当前可作为国产模型主力候选
`MiniMax-M2.7`	暂不推荐	最小 Responses 探针已出现 `convert_request_failed`，读文件任务仍会断在 `response.completed` 前
`deepseek-v4-pro`	暂不推荐	Claude Code 可用，但 Codex 这条 Responses 路由仍会出现 500 / 高需求 / 重连失败
`glm-5.1`	暂不推荐	当前生产 Responses 原生路由落到不支持该模型的上游，Codex 会报 `stream closed before response.completed`

Token 设置最佳实践

设置	建议	说明
专用 token	必须	Codex 不要和 Cursor、Claude Code 共用 token
模型白名单	强烈建议	只开放 Codex 真正会调用的模型
IP 限制	固定出口环境建议开启	个人设备经常换网络时谨慎使用
配额上限	强烈建议	Codex 代理式执行容易快速消耗额度
环境隔离	建议	本机开发、远程服务器、CI 使用不同 token
泄露处理	立即轮换	shell 历史、配置备份或共享屏幕暴露 token 后应立即更换

验证清单

常见错误与修复

现象	常见原因	修复方式
`codex: command not found`	CLI 没装成功，或全局 npm 目录不在 PATH	重装 Codex，并确认 npm 全局 bin 已进入 PATH
401 unauthorized	`OPENAI_API_KEY` 错误、过期或复制带空格	重新生成 token 并重新设置环境变量
403 / model not allowed	token 没有放行当前模型	在 Crazyrouter token 设置里放行对应模型
404	`base_url` 写错，或漏了 `/v1`	改成 `https://api.crazyrouter.com/v1`
请求结构报错	`wire_api` 不是 `responses`	改成 `wire_api = "responses"`
CLI 能启动但请求不走 Crazyrouter	`model_provider` 没切到 `crazyrouter`	检查 `config.toml` 的 provider 配置
Git 改动难以审查	没先做仓库快照	先提交初始快照，再让 Codex 做真实修改
成本增长太快	长上下文、多轮工具调用或多个仓库共用一个 token	拆 token、限额，并缩小模型白名单

性能与成本建议

首次接入先用小仓库验证，不要一上来就在超大仓库跑全量任务
默认主力建议 gpt-5.5，先把 GPT / Responses 这条主路径跑通
把 Codex 与 IDE 工具拆开记账，便于定位高消耗来源
对高风险仓库或 CI 场景设置更严格的 token 配额
每次遇到异常高消耗，先回看 Crazyrouter 日志确认是不是多轮代理行为导致

FAQ

Codex CLI 应该写哪个 Base URL？

写成 https://api.crazyrouter.com/v1。

Windows 上推荐用 PowerShell 还是 Git Bash？

首次配置时优先按文档里的 PowerShell 路线走，最容易和用户级环境变量、$HOME/.codex/config.toml 保持一致。

为什么这里要配置 `wire_api = "responses"`？

因为 Codex CLI 当前的自定义 provider 推荐通过 Responses API 工作，而 Crazyrouter 支持 /v1/responses。

为什么这里不再推荐 Claude？

因为 Claude 当前仅支持 POST /v1/messages 和 POST /v1/chat/completions，不支持 POST /v1/responses。Codex 这条接法固定走 wire_api = "responses"，因此不应该把 Claude 当成这条线路的推荐模型。

第一次为什么建议先做 Git 快照？

因为 Codex 是会改文件、会运行命令的代理。先做快照，review 和回滚都会轻松很多。需要。对接 Crazyrouter 时，仍然应使用 OPENAI_API_KEY 和自定义 provider 配置。

第一个推荐模型是什么？

先用 gpt-5.5。

如果你想优先获得 OpenAI / Responses API 路线下最顺手的终端代理体验，Codex 应该按 GPT / Responses 路线配置；如果你想优先使用 Claude，请改看 Claude Code 或 Claude 原生接口文档。

查看 crazyrouter-codex-cli 仓库

查看一键配置脚本、README 和最新使用说明。

API Key & 控制台管理

SDK & 代码示例

第三方集成

OpenAI Codex CLI 配置教程

概览

查看 Codex 一键配置仓库

适合谁用

使用协议

系统要求与前置条件

按操作系统的完整安装路径

Windows 推荐路径

macOS 推荐路径

Codex CLI 安装备选路径

从零开始完整安装

推荐模型配置

国产模型原生支持情况

切到国产模型的方式

Token 设置最佳实践

验证清单

常见错误与修复

性能与成本建议

FAQ

Codex CLI 应该写哪个 Base URL？

Windows 上推荐用 PowerShell 还是 Git Bash？

为什么这里要配置 `wire_api = "responses"`？

为什么这里不再推荐 Claude？

第一次为什么建议先做 Git 快照？

第一个推荐模型是什么？

查看 crazyrouter-codex-cli 仓库

​概览

查看 Codex 一键配置仓库

​适合谁用

​使用协议

​系统要求与前置条件

​按操作系统的完整安装路径

​Windows 推荐路径

​macOS 推荐路径

​Codex CLI 安装备选路径

​从零开始完整安装

​推荐模型配置

​国产模型原生支持情况

​切到国产模型的方式

​Token 设置最佳实践

​验证清单

​常见错误与修复

​性能与成本建议

​FAQ

​Codex CLI 应该写哪个 Base URL？

​Windows 上推荐用 PowerShell 还是 Git Bash？

​为什么这里要配置 wire_api = "responses"？

​为什么这里不再推荐 Claude？

​第一次为什么建议先做 Git 快照？

​如果我已经 codex login 过，还需要配 API Key 吗？

​第一个推荐模型是什么？

查看 crazyrouter-codex-cli 仓库

概览

适合谁用

使用协议

系统要求与前置条件

按操作系统的完整安装路径

Windows 推荐路径

macOS 推荐路径

Codex CLI 安装备选路径

从零开始完整安装

推荐模型配置

国产模型原生支持情况

切到国产模型的方式

Token 设置最佳实践

验证清单

常见错误与修复

性能与成本建议

FAQ

Codex CLI 应该写哪个 Base URL？

Windows 上推荐用 PowerShell 还是 Git Bash？

为什么这里要配置 `wire_api = "responses"`？

为什么这里不再推荐 Claude？

第一次为什么建议先做 Git 快照？

如果我已经 `codex login` 过，还需要配 API Key 吗？

第一个推荐模型是什么？