文档 / 接入指南

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 云端任务 本教程不适用

准备连接信息

  1. 在「API 密钥」创建一把 Codex 专用的密钥,分组选 GPT 分组(推荐 gpt-pro),复制完整密钥。
  2. 在模型广场确认要用的模型 ID,例如 gpt-6-astra。
字段 填写
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

  1. 按 ⌘Q 完全退出客户端,只关窗口不够。
  2. 在 Finder 按 ⌘⇧G,输入 ~/.codex/。目录不存在就在终端运行 mkdir -p ~/.codex && open ~/.codex。
  3. 按通用配置保存两个文件。用文本编辑时选纯文本格式,确认文件名不是 config.toml.txt。
  4. 重新打开客户端,进入 Codex,选择本机文件夹,新建一个本地任务。
  5. 按验证是否接入成功发一条测试消息。切换服务商后请新建任务,旧任务可能沿用原来的设置。

Windows

  1. 完全退出应用(包括托盘图标)。
  2. 按 Win+R,输入 %USERPROFILE%,在用户目录里创建或打开 .codex 文件夹。
  3. 在资源管理器打开「文件扩展名」显示,用记事本或代码编辑器保存两个文件:保存类型选「所有文件」,编码选 UTF-8,确认文件名恰好是 config.toml 和 auth.json。
  4. 重新打开客户端,新建本地任务,再到本站使用日志确认请求。

Windows 桌面程序和 WSL 里的 CLI 用的是两个不同的目录,改了 WSL 的 ~/.codex/ 不会影响 Windows 的 %USERPROFILE%\.codex\。

仍然停在登录页

先检查客户端版本、配置目录和文件格式。新版桌面客户端的登录页有「Sign in another way」之类的 API Key 入口。只在登录框里填密钥不会改 Base URL,必须先按上面配好服务商。

IDE 扩展

这里指 OpenAI 官方发布的 Codex 扩展(扩展 ID openai.chatgpt),不是 Cursor 或 Windsurf 自带的聊天面板。

  1. 在 VS Code、Cursor 或 Windsurf 的扩展市场安装 OpenAI 发布的 Codex。
  2. 打开项目,点 Codex 图标;找不到就在命令面板执行 Codex: Open Codex Sidebar。
  3. 点侧栏齿轮 → Codex Settings → Open config.toml,确认编辑的是用户配置。
  4. 按通用配置合并设置,并在同一目录放好 auth.json。同一台电脑已经配过桌面版的,一般不用重复配置。
  5. 完全退出并重新打开编辑器,新建一个 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 历史里,不要分享终端记录。

验证是否接入成功

  1. 完全重启要用的客户端,新建一个本地任务。CLI 可以用 /status 确认服务商是 peroai。
  2. 发一条短消息,例如:只回复 peroai-ok,不调用工具,不修改文件。
  3. 打开本站「使用日志」,按密钥和时间找到这次请求,核对模型和扣费。
  4. 再追问一句,确认多轮对话正常。需要写代码的话,让它读一个测试文件并概括内容,确认工具调用也能完成。

模型能回复只是第一步,本站使用日志里出现记录才说明请求真的走了本站。 不要靠问模型「你是谁」来判断。

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 目录,里面还有会话记录和其它设置。

最后更新:2026-11-15。模型、价格和分组以控制台实时显示为准。