跳到主要内容

macOS / Linux 使用 UniKey 配置 ChatGPT Codex

Codex 现在已经并入 ChatGPT 的产品体验。日常使用时，macOS 用户建议安装 ChatGPT 桌面版，再安装 Codex CLI 用于终端里的代码任务；Linux 用户通常直接使用 Codex CLI。

本教程配置的是 Codex CLI，让它通过 UniKey 的 OpenAI 兼容 API 调用模型。

Base URL: https://www.getunikey.ai/v1
API Key:  你的 UniKey API Key
Model:    gpt-5.4、gpt-5.4-mini，或你的 UniKey 账号可用模型

1. 安装 ChatGPT 与 Codex​

ChatGPT 桌面版​

macOS 用户请从 ChatGPT 官方下载页面 安装 ChatGPT 桌面版。桌面版适合管理项目、本地文件、长任务，以及在 ChatGPT 与 Codex 工作流之间切换。

Linux 目前没有相同的桌面版安装路径，建议直接使用下面的 Codex CLI。

Codex CLI​

打开终端，运行：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

关闭终端再重新打开，然后验证：

codex --version

如果提示找不到 codex 命令，先重启终端。如果仍然不行，检查安装目录是否已经加入 PATH。

2. 创建 UniKey API Key​

  1. 打开 https://www.getunikey.ai/。
  2. 登录账号。
  3. 进入 API Key 或 Token 页面。
  4. 创建新的 API Key。
  5. 保存到密码管理器或其他私密位置。

不要把 Key 写进 Git、截图、公开聊天或前端代码。下面示例里的 sk-... 请替换成你自己的 Key。

3. 推荐配置：终端环境变量 + config.toml​

这是最清晰、最不容易出错的方式：API Key 放在系统环境变量里，Codex Provider 设置放在 ~/.codex/config.toml。

设置 API Key​

macOS 默认通常是 zsh：

mkdir -p ~/.codex
nano ~/.zshrc

添加：

export UNIKEY_API_KEY="sk-..."

重新加载：

source ~/.zshrc

Linux 常见是 bash：

mkdir -p ~/.codex
nano ~/.bashrc

添加：

export UNIKEY_API_KEY="sk-..."

重新加载：

source ~/.bashrc

确认变量存在：

printenv UNIKEY_API_KEY

编辑 config.toml​

打开 Codex 配置文件：

nano ~/.codex/config.toml

加入或更新下面配置：

model = "gpt-5.4"
model_provider = "unikey"

[model_providers.unikey]
name = "UniKey"
base_url = "https://www.getunikey.ai/v1"
env_key = "UNIKEY_API_KEY"
wire_api = "responses"

保存后启动 Codex：

codex

发送：

Reply with one sentence confirming Codex is using UniKey.

如果模型正常回复，说明配置已经生效。

4. 可选文件方式：config.toml 与 auth.json​

Codex 的用户配置文件是 ~/.codex/config.toml。当 Codex 使用文件方式保存登录凭据时，登录凭据可能保存在 ~/.codex/auth.json。

使用 UniKey 时，推荐使用上面的 config.toml + UNIKEY_API_KEY 环境变量方式。这样既不用把 UniKey Key 直接写进 config.toml，也不需要手动修改 auth.json。

只有在你明确知道自己要管理 Codex 登录凭据时，才考虑处理 auth.json。处理前先备份：

cp ~/.codex/auth.json ~/.codex/auth.json.bak

如果 auth.json 被改坏，可以恢复备份，或运行：

codex logout

然后重新登录。不要把 auth.json 发到工单、截图或公开聊天里。

5. 先验证 UniKey，再排查 Codex​

运行：

curl https://www.getunikey.ai/v1/models \
  -H "Authorization: Bearer $UNIKEY_API_KEY"

如果返回模型列表，说明 UniKey API Key 和 Base URL 正常。

常见问题​

现象处理方式
找不到 codex 命令重启终端，确认安装目录已经加入 PATH。
UNIKEY_API_KEY 为空检查是否改对了 Shell 文件：macOS 通常是 ~/.zshrc，Linux 常见是 ~/.bashrc。
401 unauthorizedKey 缺失、过期、复制错误，或前后多了空格。
404 model not found把 config.toml 里的 model 改成 UniKey 账号可用模型。
配置没有生效确认文件是 ~/.codex/config.toml，然后重启 Codex。
桌面版和 CLI 表现不同ChatGPT 桌面版和 Codex CLI 可能内置不同版本。用 codex --version 检查 CLI 版本，改完配置后重启桌面版。
网络或证书错误先跑 /v1/models 的 curl 验证。如果 curl 也失败，优先检查网络、代理、VPN 和证书设置。