Codex Desktop Access to OpenAI Hub Tutorial

This guide will teach you how to redirect Codex Desktop’s requests to OpenAI Hub. You can get it running in 5 minutes without writing a single line of code.

Preparations

You will need two things:

Installed Codex Desktop (download from the official site: https://chatgpt.com/codex )
An OpenAI Hub API Key — register at https://openai-hub.com, then create it in the console. The format is sk-xxxx, it will only be shown once, so copy and save it immediately

Step 1: Locate the configuration directory

All Codex Desktop configurations are stored in the .codex folder inside your user directory.

Windows: C:\Users\YourUsername\.codex\
macOS: ~/.codex/ (that is, /Users/YourUsername/.codex/)

If you can’t see the .codex folder:

Windows: Open File Explorer → Top menu “View” → Check “Hidden items”
macOS: In Finder, press Command + Shift + . to show hidden files

Can’t find this folder? Just create it manually, name it .codex (note the dot at the beginning).

Step 2: Create two configuration files

In the .codex folder, create two empty files:

auth.json
config.toml

Windows users note: When creating files, if file extensions are hidden, you might accidentally save it as auth.json.txt, which will cause configuration loading to fail later. First check “File name extensions” in the View menu to ensure the suffix is correct.

macOS users can simply run in Terminal:

mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml

Step 3: Edit auth.json

Open auth.json with Notepad (Windows) or a text editor (macOS), and paste the following:

{
  "OPENAI_API_KEY": "sk-your-api-key"
}

Replace sk-your-api-key with the real key you obtained from OpenAI Hub.

Step 4: Edit config.toml

Open config.toml and paste the following content in its entirety:

model = "gpt-5-codex"
model_provider = "openaihub"
model_reasoning_effort = "medium"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.openaihub]
name = "openaihub"
base_url = "https://api.openai-hub.com/v1"
wire_api = "responses"
requires_openai_auth = true

Explanation of some fields (you can skip if you want):

model: The model name you want to use. You can change it to any model supported in the OpenAI Hub console.
model_reasoning_effort: Reasoning effort, options are minimal / low / medium / high
base_url: Must be exactly https://api.openai-hub.com/v1, do not omit the /v1 at the end
wire_api: Must be responses, not chat — this is the most common pitfall in Codex.

Step 5: Restart Codex Desktop

Fully quit Codex Desktop (macOS: Command + Q; Windows: right-click and exit from the system tray), then reopen it.

Once it’s open, ask something like “Hello” — if it responds normally, you’re connected.

Common Pitfalls

1. Prompts for Claude/OpenAI account login

This means the config file didn’t take effect. First check the directory path and file names (especially the .json.txt issue on Windows), then make sure the key format in auth.json has no extra spaces or quotation marks.

2. Error 404 or "Unknown endpoint"

Most likely base_url is missing /v1, or wire_api is set to chat. Codex uses the responses protocol, so both must be correct.

3. Model name error "model not found"

Go to the OpenAI Hub console’s model list and copy the exact model name. Pay attention to letter case and hyphens.

4. Windows sandbox permission issues

If running commands keeps showing permission errors, add this section to config.toml:

[windows]
sandbox = "elevated"

5. Config changes not taking effect

You must fully exit Codex Desktop and reopen it — closing the window is not enough; if it’s still running in the tray/Dock, changes won’t apply.

Once configured, all models available on OpenAI Hub can be directly selected in Codex Desktop, with a single key for everything.