Codex 接入教程
把 peroai 接入 Codex,桌面版、命令行和官方 IDE 扩展都能用。
2026-11-15 用 Codex CLI 0.169.0 实测:下面两种配置方式都能正常对话,请求出现在本站使用日志里。
| 你用的客户端 | 从哪里开始 |
|---|---|
| Codex 桌面版 / 包含 Codex 的 ChatGPT 桌面版 | 先做通用配置,再看桌面客户端 |
| VS Code、Cursor、Windsurf 的官方 Codex 扩展 | 先做通用配置,再看 IDE 扩展 |
| Codex CLI | 先做通用配置,再看 Codex CLI;只在终端用也可以选环境变量方式 |
| 网页版 ChatGPT、Codex 云端任务 | 本教程不适用 |
准备连接信息
| 字段 | 填写 |
|---|---|
| Base URL | https://api.peroai.cc/v1 |
| 协议(wire_api) | responses |
| API Key | 本站密钥(sk- 开头) |
| Model | 该分组里的完整模型 ID |
Base URL 填到 /v1 为止。 不要填控制台地址,也不要填完整的 /v1/responses,Codex 会自己追加 /responses。
Codex 只走 Responses 协议,所以只能用 GPT 分组。Claude、Grok、Gemini 分组不支持 Responses。
通用配置
这种方式用 config.toml 保存服务商信息,用 auth.json 保存密钥。桌面版、CLI 和 IDE 扩展共用同一份配置,启动前不用设置环境变量。
1. 找到配置目录
| 运行环境 | 默认目录 |
|---|---|
| macOS / Linux | ~/.codex/ |
| Windows | %USERPROFILE%\.codex\,例如 C:\Users\Alice\.codex\ |
| 在 WSL 里运行的 Codex | WSL 用户自己的 ~/.codex/ |
自己设置过 CODEX_HOME 的,以它指向的目录为准。
2. 先备份
完全退出 Codex 相关客户端。目录里已有 config.toml 和 auth.json 的,各复制一份,例如 config.before-peroai.toml、auth.before-peroai.json。
这种方式会把 Codex 的本地登录换成本站密钥,同一目录下的 CLI 和扩展都会受影响。想保留原来的 ChatGPT 登录,只在 CLI 里用本站的话,改用后面的环境变量方式。
3. 编辑 config.toml
没有这个文件就新建一个纯文本文件。已有配置的,把下面的字段合并进去,删掉同名字段的旧值,不要整段重复追加。
model = "gpt-6-astra"
model_provider = "peroai"
cli_auth_credentials_store = "file"
web_search = "disabled"
[model_providers.peroai]
name = "peroai"
base_url = "https://api.peroai.cc/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
- 前四行是顶层配置,必须放在第一个
[...]段之前。 requires_openai_auth = true表示从auth.json读取密钥。请求发到哪里由base_url决定,不会发给 OpenAI。- 第一次接入先关掉联网搜索和 WebSocket,排查问题时少一些变量。
4. 编辑 auth.json
在同一目录新建或修改 auth.json:
{
"OPENAI_API_KEY": "sk-你的密钥"
}
字段名必须是 OPENAI_API_KEY,字段值才是本站密钥。用英文双引号,不要加注释,最后一项后面不要加逗号。
这两个文件都含有密钥,不要提交到 Git 或发给别人。macOS / Linux 可以收紧权限:
chmod 700 ~/.codex
chmod 600 ~/.codex/config.toml ~/.codex/auth.json
桌面客户端
macOS
- 按 ⌘Q 完全退出客户端,只关窗口不够。
- 在 Finder 按 ⌘⇧G,输入
~/.codex/。目录不存在就在终端运行mkdir -p ~/.codex && open ~/.codex。 - 按通用配置保存两个文件。用文本编辑时选纯文本格式,确认文件名不是
config.toml.txt。 - 重新打开客户端,进入 Codex,选择本机文件夹,新建一个本地任务。
- 按验证是否接入成功发一条测试消息。切换服务商后请新建任务,旧任务可能沿用原来的设置。
Windows
- 完全退出应用(包括托盘图标)。
- 按 Win+R,输入
%USERPROFILE%,在用户目录里创建或打开.codex文件夹。 - 在资源管理器打开「文件扩展名」显示,用记事本或代码编辑器保存两个文件:保存类型选「所有文件」,编码选 UTF-8,确认文件名恰好是
config.toml和auth.json。 - 重新打开客户端,新建本地任务,再到本站使用日志确认请求。
Windows 桌面程序和 WSL 里的 CLI 用的是两个不同的目录,改了 WSL 的 ~/.codex/ 不会影响 Windows 的 %USERPROFILE%\.codex\。
仍然停在登录页
先检查客户端版本、配置目录和文件格式。新版桌面客户端的登录页有「Sign in another way」之类的 API Key 入口。只在登录框里填密钥不会改 Base URL,必须先按上面配好服务商。
IDE 扩展
这里指 OpenAI 官方发布的 Codex 扩展(扩展 ID openai.chatgpt),不是 Cursor 或 Windsurf 自带的聊天面板。
- 在 VS Code、Cursor 或 Windsurf 的扩展市场安装 OpenAI 发布的 Codex。
- 打开项目,点 Codex 图标;找不到就在命令面板执行
Codex: Open Codex Sidebar。 - 点侧栏齿轮 → Codex Settings → Open config.toml,确认编辑的是用户配置。
- 按通用配置合并设置,并在同一目录放好
auth.json。同一台电脑已经配过桌面版的,一般不用重复配置。 - 完全退出并重新打开编辑器,新建一个 Codex 对话。
不要把 TOML 内容粘进 VS Code 的 settings.json。
WSL、SSH 和远程开发:配置要放在 Codex 实际运行的那台机器或那个环境的用户目录里。扩展在 WSL、SSH 主机或容器里运行时,本机的配置不会自动带过去。
Codex CLI
1. 安装
npm install -g @openai/codex
codex --version
macOS 也可以用 brew install --cask codex。全局 CLI、桌面版、IDE 扩展各自带的 Codex 版本可能不同,升级其中一个不会更新另外两个。
2. 启动
按通用配置保存两个文件后,进入项目目录运行:
codex
进入后用 /status 检查服务商和模型,然后发一条测试消息。用文件认证就不需要再运行 codex login。
只想跑一次非交互命令可以用 codex exec "你的问题"。当前目录不是 Git 仓库时,加上 --skip-git-repo-check。
仅 CLI:环境变量方式
只在命令行使用、想保留原有登录的,可以用这种方式代替文件认证。两种方式选一种,不要混用。
备份 config.toml,把相关字段改成:
model = "gpt-6-astra"
model_provider = "peroai"
web_search = "disabled"
[model_providers.peroai]
name = "peroai"
base_url = "https://api.peroai.cc/v1"
wire_api = "responses"
env_key = "PEROAI_API_KEY"
requires_openai_auth = false
supports_websockets = false
env_key 填的是环境变量名,不是密钥本身。然后在同一个终端设置密钥并启动:
macOS / Linux:
export PEROAI_API_KEY='sk-你的密钥'
codex
Windows PowerShell:
$env:PEROAI_API_KEY = 'sk-你的密钥'
codex
临时变量只对当前终端有效,从开始菜单或 Dock 打开的桌面客户端读不到它。带真实密钥的命令会留在 shell 历史里,不要分享终端记录。
验证是否接入成功
- 完全重启要用的客户端,新建一个本地任务。CLI 可以用
/status确认服务商是peroai。 - 发一条短消息,例如:
只回复 peroai-ok,不调用工具,不修改文件。 - 打开本站「使用日志」,按密钥和时间找到这次请求,核对模型和扣费。
- 再追问一句,确认多轮对话正常。需要写代码的话,让它读一个测试文件并概括内容,确认工具调用也能完成。
模型能回复只是第一步,本站使用日志里出现记录才说明请求真的走了本站。 不要靠问模型「你是谁」来判断。
Codex 每次请求都会带上很长的系统提示和工具说明,实测一句话的请求也有约 1.5 万输入 token,在
gpt-pro分组约 $0.06。这是正常的基础消耗。
常见问题
| 现象 | 先检查 |
|---|---|
| 一直要求登录,或仍显示原来的服务商 | 改的是不是正确的用户目录;顶层字段是否放在了 [...] 段后面;是否完全退出并新建了任务 |
Missing environment variable |
你用的是环境变量方式,但启动 Codex 的进程里没有这个变量。桌面端请改用通用配置 |
| 401 / 无效的令牌 | 密钥是否完整、有无多余空格、是否被禁用或过期;auth.json 字段名是否是 OPENAI_API_KEY |
| 404 | Base URL 应为 https://api.peroai.cc/v1,不能出现 /v1/v1、/responses/responses 或 peroai.cc/v1 |
| 「分组 xxx 下模型 yyy 无可用渠道」 | 模型不在这把密钥的分组里。用 GPT 分组的密钥,并从模型广场复制模型 ID |
| 文字能回复,工具调用或追问失败 | 记下时间和报错,按故障排查反馈 |
| 一直转圈、连接中断、WebSocket 报错 | 先确认 supports_websockets = false;检查本机代理和网络 |
| TOML / JSON 解析错误 | 重复字段、中文引号、JSON 注释、末尾逗号;Windows 是否存成了 .txt |
| 改完配置旧会话没变化 | 完全退出客户端,重新打开后新建任务 |
新版 CLI 可以用 codex doctor 检查本地配置。分享排查信息前请先遮住密钥,尤其不要公开 auth.json。
恢复原来的配置
退出桌面版、编辑器和 CLI,把备份的 config.toml、auth.json 放回原位,再启动客户端。如果只是把 peroai 字段合并进了旧文件,删掉 [model_providers.peroai] 段,把 model、model_provider 等字段改回原值即可。不要删除整个 .codex 目录,里面还有会话记录和其它设置。