Codex（ChatGPT）Desktop 接入 UniKeyX

1

准备账号

在 www.unikeyx.com 注册并创建 API Key

创建 Key 时，分组请选择：

CODEX写代码专用

普通分组可能没有写代码模型的访问权限，导致模型不可用或路由失败。

浏览器访问 www.unikeyx.com。新用户先点击“注册”创建账号，已有账号的用户直接登录。
登录后进入控制台的“令牌管理”页面，点击“添加令牌”。
新建一个 API Key，名称可填写“Codex（ChatGPT）专用”，并选择上述专用分组。
创建成功后复制 Key，后续安装脚本会要求输入这个 Key。

2

推荐方式

下载完整配置模板

codex-unikeyx-template.zip

包含合并式安装脚本、Codex（ChatGPT）配置片段、模型目录 JSON，以及可选 profile 文件生成逻辑。

下载 ZIP

也可以单独下载： config.toml 模板 · 已安装用户下载模型更新文件

已安装 UniKeyX 配置的用户，可用这个 JSON 覆盖 ~/.codex/model-catalogs/unikeyx-codex-models.json，然后完全退出并重启 Codex（ChatGPT）Desktop。

3

自动安装

替换脚本并自动安装

Windows：解压后直接双击安装

下载 codex-unikeyx-template.zip，右键选择“全部解压”。
打开解压后的文件夹，双击 install-windows.cmd。
按提示粘贴 UniKeyX API Key 并回车。输入内容不会显示，安装完成后关闭窗口即可。

Windows：无需输入目录和命令

双击：install-windows.cmd

启动器会自动找到同一文件夹内的安装脚本和模型文件，不受用户解压目录影响。

macOS：自动保存 Key 并启动 Codex

下载 codex-unikeyx-template.zip，在 Finder 中双击 ZIP 完成解压。
打开终端，输入 cd （cd 后留一个空格），把解压后的文件夹拖入终端，然后按回车。
执行下面这一条安装命令：

sh ./install-macos-linux.sh

脚本会隐藏输入 API Key，将 Key 保存到登录钥匙串，并安装登录启动项。电脑重启或重新登录后会自动恢复环境变量。

已安装 UniKeyX 配置的苹果电脑

不需要重新安装整套配置。下载并运行 Key 更新脚本一次，即可更新钥匙串和登录启动项：

macOS：修复或更换已保存的 Key

cd ~/Downloads
sh ./update-macos-key.sh

单独下载 update-macos-key.sh。脚本会隐藏输入新 Key，完成后自动打开 Codex。

不要手工把 JSON 粘进 config.toml

config.toml 是 Codex（ChatGPT）配置文件；unikeyx-codex-models.json 只是模型目录文件。 Windows 用户只需双击 install-windows.cmd；启动器会自动调用普通 PowerShell，不需要管理员权限。脚本会先备份旧 config.toml，再合并 UniKeyX provider 和模型目录路径。默认不会生成多个 profile 文件。

4

配置说明

模板会写入什么

model默认模型：gpt-5.6-sol

model_provider使用 UniKeyX provider

base_url指向 https://www.unikeyx.com/v1

env_key从 OPENAI_API_KEY 读取密钥

wire_api使用 responses

model_catalog_json加载 Codex（ChatGPT）模型目录

查看 config.toml 核心配置

~/.codex/config.toml

model = "gpt-5.6-sol"
model_provider = "unikeyx"
model_catalog_json = "PATH_TO_UNIKEYX_CODEX_MODELS_JSON"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "danger-full-access"

[model_providers.unikeyx]
name = "UniKeyX"
base_url = "https://www.unikeyx.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

可选：查看独立 profile 文件

~/.codex/sol.config.toml

model = "gpt-5.6-sol"
model_provider = "unikeyx"
model_reasoning_effort = "xhigh"

当前 Codex（ChatGPT）支持通过 ~/.codex/sol.config.toml、terra.config.toml、 luna.config.toml、astra.config.toml 这样的独立 profile 文件切换配置。普通客户不需要这些文件；只有在运行 Windows 脚本时加 -InstallProfiles，或在 macOS/Linux 设置 UNIKEYX_INSTALL_PROFILES=1 时才会生成。

通常不需要手工修改 model catalog

模板已包含 gpt-5.6-sol、gpt-5.6-terra、 gpt-5.6-luna 和 gpt-6-astra。如需维护，模型 slug 必须与 UniKeyX 中的模型名完全一致， use_responses_lite 保持为 false。

5

完成接入

重启 Codex（ChatGPT）并验证

1

完全退出 Codex（ChatGPT）Desktop，然后重新打开。

2

新建任务，确认模型列表中显示 gpt-5.6-sol 或你用 -DefaultModel 指定的模型。

3

发送一句测试指令，例如“检查当前项目并概括技术栈”。

可选：命令行检查

codex doctor --summary --no-color --ascii
codex debug models | Select-String "gpt-5.6-sol"

能够正常返回内容，即表示接入成功。

此后可以在 Codex（ChatGPT）的模型配置中切换已授权的 Sol、Terra、Luna 或 Astra。

Troubleshooting

常见问题

返回 401，提示没有读取到 API Key

Windows 请重新双击 install-windows.cmd，按提示输入正确 Key。

macOS 请下载并运行 update-macos-key.sh：

cd ~/Downloads
sh ./update-macos-key.sh

脚本会把 Key 安全保存到登录钥匙串，并在每次登录时恢复 OPENAI_API_KEY。完成后请完全退出并重新打开 Codex（ChatGPT）Desktop。

模型不显示或提示 model not found

先确认 Key 属于 CODEX写代码专用分组，再检查 model catalog 路径及模型 slug。

Codex（ChatGPT）分组掉线或不稳定怎么办

建议在 UniKeyX 的密钥管理里确认该 API Key 的分组为 CODEX写代码专用。确认后完全退出并重启 Codex（ChatGPT）Desktop，再新建一个 Codex（ChatGPT）对话测试。

status_code=400，提示 encrypted content could not be verified

如果报错包含 The encrypted content gAAA...-MI= could not be verified、 Encrypted content could not be decrypted or parsed，请先检查 API Key 分组是否为 CODEX写代码专用。确认分组后，完全退出 Codex（ChatGPT）Desktop，并重新起一个 Codex（ChatGPT）对话。

出现 Responses Lite 或工具参数错误

确认 provider 使用 wire_api = "responses"，并且 model catalog 中的 use_responses_lite 为 false。

运行脚本后仍然没有切到 UniKeyX

检查 ~/.codex/config.toml 顶部是否是 model_provider = "unikeyx"，并确认 [model_providers.unikeyx] 里的 base_url 是 https://www.unikeyx.com/v1。如果仍然显示旧 provider，通常是没有完全退出并重启 Codex（ChatGPT）Desktop。

5 分钟接入 UniKeyX