Codex CLI

OpenAI 的命令行编码 Agent。命令为 codex，配置目录为 ~/.codex，npm 包名为 @openai/codex。

2026-09-22 已使用稳定版 Codex CLI 0.155.1、下文环境变量配置及 gpt-5.5 完成最小真实调用。此结果不代表桌面端或 CC-Switch 已完成同样验证。

方式	适合
CC-Switch 图形配置	不想碰配置文件，想在多家服务商间快速切换
手写 config.toml	想精确控制模型和参数，或在 Linux/服务器上用

使用 Responses API

本页已验证配置使用 wire_api="responses"。所选模型须支持 /v1/responses；Chat Completions 成功不能证明 Responses 可用，失败也不一定返回 not implemented。参见厂商调用差异。

开始之前

需要一个 API Key 和账户可用额度，模型名从模型列表复制（大小写敏感）。

Windows 一键配置

不想手动安装 CLI、设置环境变量和编辑 config.toml？可使用 GSS Deploy（Windows 一键配置）自动完成。仅支持 Windows；macOS / Linux 请继续按下方步骤操作。

装 Codex CLI

系统	命令
Windows	`irm https://chatgpt.com/codex/install.ps1 \| iex`（PowerShell，无需管理员权限）
macOS	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`，或 `brew install --cask codex`
Linux	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`

装了 Node.js 的话，三个系统都可以用 npm install -g @openai/codex。

装完验证：

codex --version

方式一：CC-Switch（图形界面）

从 sourceforge.net/projects/cc-switch.mirror 下载安装并运行。

点顶部导航栏中间的 OpenAI
点右上角 + 添加
填写：

字段填什么
供应商名称 TokenRoute（可自定义）
官网链接 https://www.tokenroute.com/
API Key 你的 API Key
API 请求地址 https://api.smartwan.com/v1
点保存

字段	填什么
供应商名称	`TokenRoute`（可自定义）
官网链接	`https://www.tokenroute.com/`
API Key	你的 API Key
API 请求地址	`https://api.smartwan.com/v1`

然后运行 codex 发一条测试消息，能回复即成功。

方式二：手写 config.toml

配置层说明见官方配置文档。自定义 Provider 必须写在用户级 ~/.codex/config.toml。项目级的 .codex/config.toml 不支持定义 model_provider 和 model_providers。

1. 设环境变量

env_key 填的是环境变量名，不是密钥本身——密钥不要写进配置文件。

系统	命令
Windows (PowerShell)	`$env:TOKENROUTE_API_KEY = "sk-你的Token"`
macOS / Linux	`export TOKENROUTE_API_KEY="sk-你的Token"`

上面只对当前会话生效。长期使用：

Windows：setx TOKENROUTE_API_KEY "sk-你的Token"，或按 Win+R 输入 sysdm.cpl → 「高级 → 环境变量 → 用户变量」新建。setx 不会更新已运行的程序，请重新打开终端并启动 Codex CLI，确保新进程读取更新后的变量。
macOS / Linux：写进 ~/.zshrc 或 ~/.bashrc。

确认变量已被新进程读到（不回显密钥）：

if ($env:TOKENROUTE_API_KEY) { "已读取" } else { "未读取" }

别用 echo 查密钥

echo $env:TOKENROUTE_API_KEY 会把真实密钥显示在终端和截图里。用上面的判断式即可。

2. 写配置文件

mkdir -p ~/.codex

Windows CMD 可用 mkdir %USERPROFILE%\.codex；PowerShell 可用 New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"。

~/.codex/config.toml：

model_provider = "tokenroute"
model = "gpt-5.5"
model_reasoning_effort = "low"

[model_providers.tokenroute]
name = "TokenRoute"
base_url = "https://api.smartwan.com/v1"
env_key = "TOKENROUTE_API_KEY"
wire_api = "responses"

四个容易写错的地方

wire_api 必须是 "responses"
env_key 填环境变量名，不是密钥
model 和 model_reasoning_effort 必须在顶层，不能塞进 [model_providers.tokenroute] 里面
文件里若有重复的 notify = [...]，只留一行

Windows 上注意文件后缀必须是 .toml 不是 .txt——看不到后缀就在资源管理器「查看」里勾选「文件扩展名」。

3. 重启并验证

改完配置后重新启动 Codex CLI；修改持久环境变量后还应重新打开终端。

codex --version
codex

如果 Windows 上安装目录包含下述版本目录，可在 PowerShell 调用；替换 <版本号>，其他安装方式请使用实际路径。配置加载成功后仍需最小真实调用验证：

& "$env:LOCALAPPDATA\OpenAI\Codex\bin\<版本号>\codex.exe" doctor

另一种认证方式：auth.json

用 Codex 自带的 OpenAI 认证模式，去掉 env_key 改用 requires_openai_auth：

model_provider = "tokenroute"
model = "gpt-5.5"
model_reasoning_effort = "low"

[model_providers.tokenroute]
name = "TokenRoute"
base_url = "https://api.smartwan.com/v1"
wire_api = "responses"
requires_openai_auth = true

密钥存在 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "sk-你的Token"
}

新版 Codex 也可能改存到 Windows 凭据管理器。

两套方案二选一，不要混用

推荐：env_key + 系统环境变量
兼容：requires_openai_auth = true + Codex 认证存储

requires_openai_auth = true 会走 Codex 自己的认证存储而不读 Provider 的环境变量，同时设两个反而不生效。而且它占用通用 OpenAI 认证槽位，可能影响你原有的 ChatGPT 登录状态——新用户建议用环境变量方案。

深度验证

配置文件看着对、codex doctor 总状态绿，都不代表真能调通。按四层依次验证。

第一层：命令可用

codex --version

提示找不到 codex 就检查安装和 PATH。

第二层：认证与 Provider 被读到

codex doctor --json

检查项	成功标准
`config.load`	`ok`，模型和 Provider 与 `config.toml` 一致
`auth.credentials`	`ok`，环境变量方案显示变量存在
`network.provider_reachability`	`ok`，Base URL 指向 `https://api.smartwan.com/v1`
`network.websocket_reachability`	显示使用 `responses`；未启用 WebSocket 不影响普通调用

若 npm 安装目录与实际 Codex 目录不同，installation 或 updates.status 可能报失败——那只影响升级，不代表接入失败，以真实调用结果为准。

第三层：最小真实调用（最终判定）

codex exec `
  --ephemeral `
  --skip-git-repo-check `
  --sandbox read-only `
  --json `
  "只回复 OK，不要调用任何工具。"

成功时输出里会出现：

{"type":"item.completed","item":{"type":"agent_message","text":"OK"}}

末尾出现 turn.completed 且进程正常结束。这一条同时证明了配置已加载、密钥已读取、鉴权通过、/v1/responses 路由可用、所选模型能回复。

第四层：绕过 Codex 直连 API

前三层有问题时，直接打接口分清是 Codex 的问题还是网关的问题。

$headers = @{ Authorization = "Bearer sk-你的Token" }

Invoke-RestMethod `
  -Uri "https://api.smartwan.com/v1/models" `
  -Headers $headers `
  -Method Get

/v1/models 通了再验 Responses：

$headers = @{
  Authorization = "Bearer sk-你的Token"
  "Content-Type" = "application/json"
}

$body = @{
  model = "gpt-5.5"
  input = "只回复 OK"
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://api.smartwan.com/v1/responses" `
  -Headers $headers `
  -Method Post `
  -Body $body

直连命令含明文密钥

只在本机可信终端执行，不要把命令、截图或终端历史发给他人。已经公开过的 Key 应到控制台轮换。

结果对照

结果	说明
Codex 返回 `OK`	配置、认证、路由、模型调用全部通过
`/v1/models` 返回列表	Key 鉴权正常
`/v1/models` 返回 `Invalid token`	Key 内容、状态、有效期或额度有问题
模型列表成功但 Responses 失败	该模型可能不支持 Responses API，或路由异常
返回 `not implemented`	当前模型不支持 Responses API，换一个
Provider 未找到	`model_provider` 与 `[model_providers.<id>]` 不一致
配置无法加载	检查 TOML 重复键、换行，以及文件是否误存为 `config.toml.txt`

桌面端应用

ChatGPT 也有桌面客户端，微软商店下载。

切中文：File → Settings（Ctrl+,）→ General → Language 选「中文（中国）」。等中文包加载完，右下角托盘图标右键退出再重开生效。没生效就再重启一次。

首次发消息若弹 Unable to send message，点 OK，再点输入框旁的黑色 Set up 按钮完成沙箱配置。

模型在输入框下方的下拉里切换。

遇到问题

现象	处理
找不到 `.codex` 目录	按上文 CMD / PowerShell 示例创建目录
Provider 未找到	顶层 `model_provider` 的值要和 `[model_providers.xxx]` 的 ID 完全一致
认证失败	确认环境变量已设置且当前终端可见，Key 以 `sk-` 开头且未过期
404 或协议不兼容	`base_url` 要带 `/v1`；确认该模型支持 `/v1/responses`
返回 `not implemented`	该模型不支持 Responses API，换一个
桌面端突然不通	托盘图标右键退出，重新打开

换模型就改 ~/.codex/config.toml 顶层的 model 字段，或在 CC-Switch 里重选。模型名要取自模型列表且确认支持 Responses API。

装 Codex CLI​

方式一：CC-Switch（图形界面）​

方式二：手写 config.toml​

1. 设环境变量​

2. 写配置文件​

3. 重启并验证​

另一种认证方式：auth.json​

深度验证​

第一层：命令可用​

第二层：认证与 Provider 被读到​

第三层：最小真实调用（最终判定）​

第四层：绕过 Codex 直连 API​

结果对照​

桌面端应用​

遇到问题​