ChatGPT Codex with UniKey on macOS and Linux

Codex is now part of the ChatGPT product experience. For daily work, install the ChatGPT desktop app on macOS if your device supports it, and install the Codex CLI for terminal-based coding tasks. Linux users usually work through the Codex CLI.

This guide configures Codex CLI to use UniKey through the OpenAI-compatible API.

Base URL: https://www.getunikey.ai/v1
API key:  your UniKey API key
Model:    gpt-5.4, gpt-5.4-mini, or another model available in UniKey

1. Install ChatGPT and Codex

ChatGPT desktop app

On macOS, install the official ChatGPT desktop app from the ChatGPT download page. The desktop app is useful for project views, local files, longer tasks, and switching between ChatGPT and Codex work.

Linux does not currently have the same desktop-app path. Use the Codex CLI below.

Codex CLI

Open Terminal and run:

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

Close and reopen Terminal, then verify:

codex --version

If codex is not found, restart the terminal once. If it still fails, make sure the installer directory is in your PATH.

2. Create a UniKey API key

1. Open https://www.getunikey.ai/.
2. Log in.
3. Open the API key or token page.
4. Create a new API key.
5. Store it privately.

Never commit or share the key. In the examples below, replace sk-... with your own key.

3. Recommended setup: terminal plus config.toml

This is the clearest setup for most users: the secret stays in your shell environment, and Codex reads provider settings from ~/.codex/config.toml.

Set the API key

macOS normally uses zsh:

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

Add:

export UNIKEY_API_KEY="sk-..."

Reload:

source ~/.zshrc

Linux commonly uses bash:

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

Add:

export UNIKEY_API_KEY="sk-..."

Reload:

source ~/.bashrc

Confirm the variable exists:

printenv UNIKEY_API_KEY

Edit config.toml

Open the Codex config file:

nano ~/.codex/config.toml

Add or update this block:

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"

Save the file, then start Codex:

codex

Ask:

Reply with one sentence confirming Codex is using UniKey.

4. Optional file method: config.toml and auth.json

Codex keeps user configuration in ~/.codex/config.toml. When file-based credential storage is enabled, login credentials can also live in ~/.codex/auth.json.

For UniKey, prefer the config.toml + UNIKEY_API_KEY environment variable method above. It avoids putting the UniKey secret directly in config.toml and avoids manually editing auth.json.

Only touch auth.json if you are intentionally managing Codex login credentials and have made a backup first:

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

If auth.json becomes invalid, restore the backup or run:

codex logout

Then sign in again. Do not paste auth.json into support tickets, screenshots, or public chats.

5. Verify UniKey before debugging Codex

Run:

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

If this returns a model list, your UniKey key and base URL are working.

Common issues

Problem	Fix
codex command not found	Restart Terminal. Confirm the installer path is in PATH.
UNIKEY_API_KEY is empty	Check whether you edited the correct shell file: ~/.zshrc on macOS, usually ~/.bashrc on Linux.
401 unauthorized	The key is missing, expired, copied incorrectly, or has extra spaces.
404 model not found	Change model in config.toml to a model your UniKey account can use.
Config changes do not apply	Confirm the file is ~/.codex/config.toml, then restart Codex.
Desktop app and CLI behave differently	The ChatGPT desktop app and Codex CLI can ship different Codex versions. Check codex --version and restart the desktop app after config changes.
Network or TLS errors	Try the /v1/models curl test first. If curl fails too, check network, proxy, VPN, and certificate settings before changing Codex.