跳到正文
EN

将 ChatGPT 桌面端和 Codex 接入 XiuAI

按 macOS、Windows 或 Linux 配置 ChatGPT 本地 Codex;为 CLI 和 IDE 添加 XiuAI Responses provider,并检查实际请求。

更新于 复核于
查看 Markdown

本教程用于本地 Codex 任务。ChatGPT 登录页的“OpenAI API 密钥”用于官方服务,没有 XiuAI Base URL 输入框。先在应用外配置,再打开 ChatGPT;无需把 XiuAI 密钥填入官方登录框。

开始之前

  1. 在 XiuAI 控制台的“Agent 集成”选择可用密钥和完整模型 ID。控制台复制密钥命令会填入所选密钥;文档中的 YOUR_XIUROUTER_API_KEY、YOUR_MODEL_ID 需要你替换。
  2. 选择下面的操作系统。桌面端只需安装 ChatGPT;IDE 只需安装 OpenAI 发布的 Codex 扩展;只有 CLI 路径需要 codex --version 能输出版本。
  3. 已有配置要备份,保留其它 provider;密钥不写入 config.toml、项目仓库或 Agent 对话。

macOS 桌面端

已经安装就跳过这一项。还没安装时,打开下面的官方说明,下载和安装对应系统的桌面端。安装后先不要在登录框里填 XiuAI 密钥,继续下面的配置步骤。

下载 ChatGPT

按 Command + 空格,输入“终端”,按 Return 打开。下面的命令都粘贴到这个窗口,按 Return 执行。

1. 完全退出 ChatGPT(macOS)

点击屏幕左上角 ChatGPT → 退出 ChatGPT,或按 Command + Q。只关窗口不算退出。

2. 备份并打开配置文件(macOS)

回到命令窗口,复制下面整段并执行。它会创建所需文件夹和配置文件,给现有配置做一份带时间的备份,再用文本编辑器打开文件。不会覆盖原有配置。

mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"
open -e "$HOME/.codex/config.toml"

打开的文件是 ~/.codex/config.toml。备份也在同一文件夹,文件名以 config.toml.backup- 开头。

3. 设置模型和服务(macOS)

在刚打开的文件中,把下面三行放到文件最上面,位于任何以 [ 开头的配置段之前。已有 model、model_provider 或 web_search 时,只改原来的值,不要再粘贴一份;其它设置保留。

model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"

YOUR_MODEL_ID 要换成完整模型 ID;在 XiuAI 控制台选择模型后,控制台中的配置会自动填好。web_search 关闭 OpenAI 托管检索,避免首次测试调用不支持的工具。

4. 添加 XiuAI 配置并保存(macOS)

把下面整段放到文件末尾。若已有 [model_providers.xiurouter],替换这一段及它的 xiurouter.auth 子段(如有),不要重复添加。其它 provider 保留。

[model_providers.xiurouter]
name = "XiuAI"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"

在 TextEdit 中按 Command + S 保存,然后关闭文件。若看到富文本格式,先选择“格式 → 制作纯文本”;文件名保持 config.toml。

5. 保存 XiuAI 密钥(macOS)

回到刚才的命令窗口,复制下面整段并执行。在 XiuAI 控制台点复制会自动填入所选密钥;本文的 YOUR_XIUROUTER_API_KEY 要换成自己的密钥。

launchctl setenv XIUROUTER_API_KEY "YOUR_XIUROUTER_API_KEY"

没有输出、回到命令提示符就是执行完成。这条命令在当前登录期间有效;注销或重启电脑后,需重新执行本步再打开 ChatGPT。

6. 重新打开 ChatGPT(macOS)

从“应用程序”或 Dock 重新打开 ChatGPT。首次使用会进入新手引导;完成引导后切到 Codex。已有任务保持原连接,要新建本地任务。

7. 新建本地任务并验证(macOS)

在 Codex 中打开一个本地文件夹,新建任务,把下面的测试消息粘贴到输入框并发送。收到回复后,回到 XiuAI 控制台 → Agent 集成 → 检查实际请求,点击“刷新记录”。模型要与你在控制台所选一致,接口要是 /v1/responses,状态要是成功。

告诉我当前文件夹的名称,不要修改文件。

只看到 ChatGPT 打开不代表接入成功,以 XiuAI 实际请求记录为准。

Windows 桌面端

已经安装就跳过这一项。还没安装时,打开下面的官方说明,下载和安装对应系统的桌面端。安装后先不要在登录框里填 XiuAI 密钥,继续下面的配置步骤。

Windows 官方安装说明

按 Windows 键,搜索 PowerShell,打开 Windows PowerShell。用普通用户打开即可,不需要管理员权限。下面的命令都粘贴到这个窗口,按 Enter 执行;不要用命令提示符、Git Bash 或 WSL。

1. 完全退出 ChatGPT(Windows)

在 ChatGPT 菜单中选择“退出”。如果系统托盘里还有 ChatGPT 图标,右键它并退出;只关窗口不算退出。

2. 备份并打开配置文件(Windows)

回到命令窗口,复制下面整段并执行。它会创建所需文件夹和配置文件,给现有配置做一份带时间的备份,再用文本编辑器打开文件。不会覆盖原有配置。

$xiuConfigDir = Join-Path $env:USERPROFILE ".codex"
New-Item -ItemType Directory -Force $xiuConfigDir | Out-Null
$xiuConfigFile = Join-Path $xiuConfigDir "config.toml"
if (-not (Test-Path $xiuConfigFile)) { New-Item -ItemType File $xiuConfigFile | Out-Null }
Copy-Item $xiuConfigFile "$xiuConfigFile.backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
notepad $xiuConfigFile

打开的文件是 %USERPROFILE%.codex\config.toml。备份也在同一文件夹,文件名以 config.toml.backup- 开头。

3. 设置模型和服务(Windows)

在刚打开的文件中,把下面三行放到文件最上面,位于任何以 [ 开头的配置段之前。已有 model、model_provider 或 web_search 时,只改原来的值,不要再粘贴一份;其它设置保留。

model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"

YOUR_MODEL_ID 要换成完整模型 ID;在 XiuAI 控制台选择模型后,控制台中的配置会自动填好。web_search 关闭 OpenAI 托管检索,避免首次测试调用不支持的工具。

4. 添加 XiuAI 配置并保存(Windows)

把下面整段放到文件末尾。若已有 [model_providers.xiurouter],替换这一段及它的 xiurouter.auth 子段(如有),不要重复添加。其它 provider 保留。

[model_providers.xiurouter]
name = "XiuAI"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"

在记事本中按 Ctrl + S 保存,然后关闭记事本。文件名必须是 config.toml,不要另存成 config.toml.txt。

5. 保存 XiuAI 密钥(Windows)

回到刚才的命令窗口,复制下面整段并执行。在 XiuAI 控制台点复制会自动填入所选密钥;本文的 YOUR_XIUROUTER_API_KEY 要换成自己的密钥。

$env:XIUROUTER_API_KEY = "YOUR_XIUROUTER_API_KEY"
[Environment]::SetEnvironmentVariable("XIUROUTER_API_KEY", $env:XIUROUTER_API_KEY, "User")

没有输出、回到命令提示符就是执行完成。密钥同时保存在当前 PowerShell 窗口和 Windows 用户环境中。下一步继续使用这个窗口启动 ChatGPT,让应用立即读到密钥。

6. 从同一个 PowerShell 打开 ChatGPT(Windows)

回到刚才保存密钥的 PowerShell 窗口,复制下面整段并执行。它会找到 Microsoft Store 安装的 ChatGPT 并打开应用。确认已按上面的步骤完全退出 ChatGPT,否则旧进程仍会使用旧的环境。

$xiuChatGptPackage = Get-AppxPackage -Name OpenAI.Codex | Select-Object -First 1
if (-not $xiuChatGptPackage) { throw "没有找到 Microsoft Store 版 ChatGPT,请先按上面的官方下载说明安装。" }
$xiuChatGptExe = Join-Path $xiuChatGptPackage.InstallLocation "app\ChatGPT.exe"
Start-Process -FilePath $xiuChatGptExe

这次配置不需要重启电脑。首次使用会进入新手引导;完成后切到 Codex 并新建本地任务。以后可以从开始菜单打开;如果应用读不到新密钥,重新执行本教程的密钥和启动步骤,或保存其它工作后重启电脑。

7. 新建本地任务并验证(Windows)

在 Codex 中打开一个本地文件夹,新建任务,把下面的测试消息粘贴到输入框并发送。收到回复后,回到 XiuAI 控制台 → Agent 集成 → 检查实际请求,点击“刷新记录”。模型要与你在控制台所选一致,接口要是 /v1/responses,状态要是成功。

告诉我当前文件夹的名称,不要修改文件。

只看到 ChatGPT 打开不代表接入成功,以 XiuAI 实际请求记录为准。

Linux 桌面端

已经安装就跳过这一项。还没安装时,打开下面的官方说明,下载和安装对应系统的桌面端。安装后先不要在登录框里填 XiuAI 密钥,继续下面的配置步骤。

Linux 官方安装说明

在应用菜单中打开“终端”。下面的命令都粘贴到这个窗口,按 Enter 执行。Linux 桌面端目前是预览版,按 OpenAI 官方 Linux 安装说明安装对应发行版的软件包。

1. 完全退出 ChatGPT(Linux)

在 ChatGPT 菜单中选择“退出”,并退出托盘中的 ChatGPT(如有)。只关窗口不算退出。

2. 备份并打开配置文件(Linux)

回到命令窗口,复制下面整段并执行。它会创建所需文件夹和配置文件,给现有配置做一份带时间的备份,再用文本编辑器打开文件。不会覆盖原有配置。

mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"
nano "$HOME/.codex/config.toml"

打开的文件是 ~/.codex/config.toml。备份也在同一文件夹,文件名以 config.toml.backup- 开头。

3. 设置模型和服务(Linux)

在刚打开的文件中,把下面三行放到文件最上面,位于任何以 [ 开头的配置段之前。已有 model、model_provider 或 web_search 时,只改原来的值,不要再粘贴一份;其它设置保留。

model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"

YOUR_MODEL_ID 要换成完整模型 ID;在 XiuAI 控制台选择模型后,控制台中的配置会自动填好。web_search 关闭 OpenAI 托管检索,避免首次测试调用不支持的工具。

4. 添加 XiuAI 配置并保存(Linux)

把下面整段放到文件末尾。若已有 [model_providers.xiurouter],替换这一段及它的 xiurouter.auth 子段(如有),不要重复添加。其它 provider 保留。

[model_providers.xiurouter]
name = "XiuAI"
base_url = "https://router-api.xiu.ai/v1"
wire_api = "responses"

[model_providers.xiurouter.auth]
command = "/bin/sh"
args = ['-c', 'cat "$HOME/.codex/xiurouter-api-key"']

在 nano 中按 Ctrl + O,按 Enter 确认文件名,再按 Ctrl + X 退出。

5. 保存 XiuAI 密钥(Linux)

回到刚才的命令窗口,复制下面整段并执行。在 XiuAI 控制台点复制会自动填入所选密钥;本文的 YOUR_XIUROUTER_API_KEY 要换成自己的密钥。

(
  set -e
  umask 077
  mkdir -p "$HOME/.codex"
  if [ -f "$HOME/.codex/xiurouter-api-key" ]; then
    cp "$HOME/.codex/xiurouter-api-key" "$HOME/.codex/xiurouter-api-key.backup-$(date +%Y%m%d-%H%M%S)"
  fi
  touch "$HOME/.codex/xiurouter-api-key"
  chmod 600 "$HOME/.codex/xiurouter-api-key"
  printf '%s' "YOUR_XIUROUTER_API_KEY" > "$HOME/.codex/xiurouter-api-key"
)

没有输出、回到命令提示符就是执行完成。密钥保存在你自己的 .codex 文件夹,只有当前用户能读写;已有密钥会先备份到同一文件夹的 xiurouter-api-key.backup- 文件。无需把密钥写进 config.toml,也不用每次从终端启动应用。

6. 重新打开 ChatGPT(Linux)

从应用菜单重新打开 ChatGPT。首次使用会进入新手引导;完成引导后切到 Codex。已有任务保持原连接,要新建本地任务。

7. 新建本地任务并验证(Linux)

在 Codex 中打开一个本地文件夹,新建任务,把下面的测试消息粘贴到输入框并发送。收到回复后,回到 XiuAI 控制台 → Agent 集成 → 检查实际请求,点击“刷新记录”。模型要与你在控制台所选一致,接口要是 /v1/responses,状态要是成功。

告诉我当前文件夹的名称,不要修改文件。

只看到 ChatGPT 打开不代表接入成功,以 XiuAI 实际请求记录为准。

Codex CLI 或 IDE 扩展

macOS/Linux 的配置文件是 ~/.codex/config.toml;Windows 原生客户端是 %USERPROFILE%\.codex\config.toml。Windows 桌面端与 WSL 的用户目录不自动共享。

完全退出 IDE 的所有窗口,再在终端设置密钥:

export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"

Windows PowerShell:

$env:XIUROUTER_API_KEY = "YOUR_XIUROUTER_API_KEY"

将下面前三行放在第一个 TOML 表之前,provider 段放在末尾。已有同名字段或 provider 时修改原值,不重复添加。若之前使用 Linux 桌面端的 xiurouter.auth 子段,切换环境变量方案时移除该子段。

model = "YOUR_MODEL_ID"
model_provider = "xiurouter"
web_search = "disabled"

[model_providers.xiurouter]
name = "XiuAI"
base_url = "https://router-api.xiu.ai/v1"
env_key = "XIUROUTER_API_KEY"
wire_api = "responses"

CLI:在设置密钥的同一个终端执行:

codex exec --model YOUR_MODEL_ID --sandbox read-only "Run pwd without changing files, then tell me the directory."

IDE:从设置密钥的终端启动编辑器(VS Code 用 code .),在 Codex 面板中新建本地任务,发送“运行 pwd,不要修改文件,然后告诉我当前目录。”。只重载窗口可能保留旧环境,不需要另外安装 CLI 来验证 IDE。

确认接入成功

客户端回复后,在 XiuAI 控制台“检查实际请求”刷新记录。密钥、模型、/v1/responses 接口和成功状态必须匹配。打开应用、修改文件或通过密钥检查都不能代替真实请求。基础连接通过后,再测试项目需要的工具;文本回复不能证明编辑、文件、托管检索或长上下文能力。

常见失败与客服信息

现象 处理
仍停在官方登录页 完全退出后重开;确认顶层 model_provider = "xiurouter" 位于第一个 [配置段] 之前;Windows 文件不能叫 config.toml.txt
duplicate key 或配置解析失败 保留一份顶层设置与一个 XiuAI provider;macOS 用纯文本保存,Linux 不要同时配置 auth 与 env_key
401 按所选系统重新保存密钥并启动客户端,核对密钥状态与 env_key 名称;macOS 注销或重启后需重新设置
模型不在选择器中 在 config.toml 填完整 ID,再新建本地任务
Linux 提示 nano: command not found 文件管理器显示隐藏文件,用已有文本编辑器打开 .codex/config.toml

仍失败时,通过 XiuAI 页面内客服提供:操作系统、ChatGPT/Codex 版本、使用端、模型 ID、发生时间与时区、完整错误提示、请求 ID(如有)和已尝试步骤。截图隐藏密钥、Token、Cookie、邮箱及无关对话;不要发送完整 config.toml 或 auth.json。

回滚

用修改前的 config.toml.backup- 文件替换 config.toml,然后完全退出客户端并重开。Linux 更换过密钥时,也从 xiurouter-api-key.backup- 恢复旧文件。新密钥不用时撤销;删除本机配置前确认没有其它客户端使用它。

来源与核对日期

核对日期为 2026-10-09。macOS 已验证未登录实例读取 provider 后进入引导;Windows ChatGPT 26.1002.6548.0 已验证本地回复与 XiuAI 实际请求匹配。Linux 配置与密钥文件读取已执行验证,原生桌面界面尚未实测。

导航

输入关键词开始搜索

↑↓ 移动↵ 打开Esc 关闭