Codex desktop with AIXHUB

The Codex desktop app can use the same Codex home as Codex CLI for the same operating-system user. This guide changes shared user files, so a provider or credential change can affect both surfaces. Fully close the app and other Codex processes before editing.

What you will accomplish

You will add a minimal AIXHUB Responses provider to the shared Codex user configuration, keep the real key in the separate authentication file, run one read-only desktop request, match it in AIXHUB Usage, and retain an exact restore path.

These Codex surfaces are related but not interchangeable:

Desktop and CLI can share config.toml and auth.json. Changing either file can change the next session on both surfaces. An official ChatGPT login is not an AIXHUB API key and must not be used in place of the custom provider credential.

Supported platforms

• Windows: Supported by the current Codex app. This guide configures the shared files under the Windows user profile.
• macOS: Supported by the Codex app. This guide uses the Codex home under the macOS user account.
• Linux: No native desktop flow is documented here. Use Codex CLI instead.

Desktop app support and a visible custom-provider selector in every app version are different claims. A supported app version may not expose provider controls in its interface. This guide configures AIXHUB through the shared user files and then verifies what the app actually uses.

Install or open the app

On Windows or macOS, install or update Codex through the official Codex app page. Download controls and interface labels can change, so this guide does not invent a package command or exact menu path.

Before editing:

1. Fully quit the Codex desktop app instead of only closing its window.
2. Stop Codex CLI sessions and IDE integrations that may read or write the same Codex home.
3. Choose a small disposable test directory for the first run.

Restart the desktop app only after the configuration and authentication files have been saved and checked. Linux users should continue with the CLI guide rather than trying to adapt desktop files to an unsupported native app.

Configuration values

Codex normally reads these user files:

If CODEX_HOME is already set, it replaces the default .codex directory; use config.toml and auth.json inside that exact directory. Also inspect the test project and trusted parent directories for .codex/config.toml because a project-level setting can override the user provider or model.

Use these AIXHUB values:

Property names and provider IDs are case-sensitive. The Base URL contains exactly one /v1. Do not copy optional review, context, plugin, or desktop preference values from another machine into this minimal connection setup.

Configure AIXHUB

Back up both shared files on Windows

Run this in PowerShell after fully closing Codex. It honors CODEX_HOME, creates unique backup names, prints a path only after a successful copy, removes files created by a failed backup attempt, and returns an error without closing PowerShell:

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
$backupCandidates = [System.Collections.Generic.List[string]]::new()

try {
  New-Item -ItemType Directory -Force -Path $codexHome -ErrorAction Stop | Out-Null
  foreach ($name in @("config.toml", "auth.json")) {
    $sourcePath = Join-Path $codexHome $name
    if (Test-Path -LiteralPath $sourcePath -PathType Leaf) {
      $stamp = Get-Date -Format "yyyyMMddHHmmssfff"
      $suffix = [guid]::NewGuid().ToString("N").Substring(0, 8)
      $backupPath = "$sourcePath.backup.$stamp.$suffix"
      $backupCandidates.Add($backupPath)
      Copy-Item -LiteralPath $sourcePath -Destination $backupPath -ErrorAction Stop
      Write-Output "Backup created: $backupPath"
    } else {
      Write-Output "No existing $name; no backup was needed."
    }
  }
} catch {
  foreach ($path in $backupCandidates) {
    Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue
  }
  throw "Backup failed. Stop before editing Codex configuration."
}

Back up both shared files on macOS

Run this in Bash or zsh after fully closing Codex:

codex_home="${CODEX_HOME:-$HOME/.codex}"
created_backups=()
backup_failed=0

if ! mkdir -p "$codex_home"; then
  printf 'Cannot prepare Codex home. Stop before editing Codex configuration.\n' >&2
  false
else
  for name in config.toml auth.json; do
    source_path="$codex_home/$name"
    if [ -f "$source_path" ]; then
      backup=""
      if backup="$(mktemp "$source_path.backup.$(date +%Y%m%d%H%M%S).XXXXXX")" && cp "$source_path" "$backup"; then
        created_backups+=("$backup")
        printf 'Backup created: %s\n' "$backup"
      else
        [ -z "$backup" ] || rm -f "$backup"
        backup_failed=1
        break
      fi
    else
      printf 'No existing %s; no backup was needed.\n' "$name"
    fi
  done

  if [ "$backup_failed" -ne 0 ]; then
    for path in "${created_backups[@]}"; do
      rm -f "$path"
    done
    printf 'Backup failed. Stop before editing Codex configuration.\n' >&2
    false
  fi
fi

Continue only after every existing file prints Backup created: and every missing file prints No existing ...; no backup was needed.. Record each exact backup path for this operation. If either block reports a failure, stop and do not edit either file. Backups can contain credentials and must remain private.

Record the original state

Before merging, keep a protected record of:

If an AIXHUB provider or OPENAI_API_KEY already exists, decide explicitly whether replacing it is intended. Do not assume either value was created by this guide or can later be deleted.

Merge the minimal provider

Merge this complete minimal shape into the user config.toml:

model_provider = "AIXHUB"
model = "panel-model-id"

[model_providers.AIXHUB]
name = "AIXHUB"
base_url = "https://api.aixhub.org/v1"
wire_api = "responses"
requires_openai_auth = true

Place the two top-level keys before any TOML table. If the file already contains other providers or unrelated settings, preserve them and merge this table instead of replacing the file. Keep valid TOML and only one [model_providers.AIXHUB] table.

Merge the authentication field

The complete minimal auth.json shape for a new file is:

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-your-key"
}

Replace sk-your-key locally with the dedicated AIXHUB API key. The real key belongs only in auth.json, never in config.toml. If auth.json already exists, merge both fields: set auth_mode to apikey for this AIXHUB custom-provider test and add or update OPENAI_API_KEY, while preserving every unrelated token, official sign-in property, and other field. Official ChatGPT credentials may remain stored but are not the active authentication choice while auth_mode is apikey.

This changes the authentication selection shared by desktop and CLI; adding the key alone is not the complete setup. Record the exact original auth_mode before changing it so restore can put back that precise value or remove the property when its recorded original state was absent.

On macOS, restrict the authentication file after saving:

chmod 600 "${CODEX_HOME:-$HOME/.codex}/auth.json"

On Windows, keep auth.json under the current user's Codex home and use Windows file security settings to ensure unrelated accounts cannot read it. Apply the same protection to every backup.

First run

Open the Codex desktop app and choose the small disposable test directory. Trust the directory only after you understand its contents and scope. Fully restart the app if it was open while either shared file changed.

If the app displays the active provider or model, confirm AIXHUB and panel-model-id. Keep approval and sandbox permissions at the minimum needed for observation. Send this request:

Inspect the current folder without changing any file or running a state-changing command. Reply with OK only.

Do not approve file writes, shell commands that change state, or access outside the test directory for this first request.

Verification

The app should return:

OK

If the app displays provider or model information, confirm AIXHUB and panel-model-id there. Then open AIXHUB Usage and match the request time, panel-model-id, and successful status. Only compare an API mode when Usage actually displays it; this guide does not assume a protocol field is always present.

Troubleshooting

Official login appears or the custom configuration is not loaded

An official ChatGPT login is not the AIXHUB credential. Fully quit the app and other Codex processes, confirm the effective CODEX_HOME, keep model_provider and model before the provider table, and confirm that the shared auth.json has auth_mode set to apikey for this custom-provider test. Restart the app, then check whether the project or a trusted parent directory contains .codex/config.toml.

401 or authentication failed

Confirm that the effective Codex home contains auth.json with auth_mode set to apikey and the exact OPENAI_API_KEY property holding a current dedicated AIXHUB key. Preserve unrelated official sign-in and token properties, but do not use them in place of the active custom-provider key. Never print the key while checking.

404 or a doubled API version

Keep base_url exactly https://api.aixhub.org/v1. A missing version, a full /v1/responses endpoint in the Base URL field, or /v1/v1 can route requests incorrectly.

model not found

Copy the exact compatible ID again from Model routes, then keep the top-level model = "panel-model-id" synchronized. Do not use a display name or guess a version suffix.

A project overrides the user provider

Inspect .codex/config.toml in the test project and trusted parent directories. Record and resolve conflicting provider or model values rather than deleting an unknown project file. Restart the app after changes.

The request succeeds but Usage has no matching record

The app may be using an official account, another provider, or a project override. Check any provider/model indicator the app exposes, confirm the shared user files, fully restart, and repeat the small request. Match time, model, and status in Usage rather than assuming the visible response proves the route.

Desktop and CLI affect each other

Close both surfaces before editing. If a CLI session changes config.toml or auth.json, the next desktop session may load those values, and the reverse is also true. Keep one recorded shared state and verify both surfaces separately after an intentional change.

For 403, 429, 502, or 503 responses, continue with the error code reference.

Upgrade and restore

Upgrade the app through the official Codex app page or the update channel provided by the installed app. Do not replace the shared configuration merely to update the application. After upgrading, fully restart and repeat the read-only request before granting broader permissions.

To restore, close Codex desktop, CLI, and IDE integrations first, then reread the current files and compare them with the protected original-state record. An entire file may be replaced from this operation's exact timestamped backup only during a controlled verification window when you have confirmed that no unrelated state was added after configuration. If a later official login, desktop preference, provider, token, or other property must be kept, do not overwrite the whole file; merge the AIXHUB-related restoration into the current file instead.

If config.toml was originally absent, delete the current file only when it still exactly matches this guide's minimal TOML. If any later setting exists, keep the file and revert or remove only model_provider, model, and model_providers.AIXHUB when those values still match what this guide added and the original record says they were absent. When an original value or provider table existed, restore that exact value or table and preserve all later unrelated settings.

If auth.json was originally absent, delete the current file only when it still contains exactly auth_mode: "apikey" and the dedicated OPENAI_API_KEY introduced by this guide. Otherwise keep the file, restore auth_mode to its exact recorded original value or remove that property only when the record says absent and it still belongs to this change, and restore or remove OPENAI_API_KEY only after confirming it is still this operation's dedicated AIXHUB key. Preserve every later unrelated sign-in, token, desktop, or other property.

If no usable backup exists, apply the same field-level rules from the protected record. If ownership of any field, provider table, authentication mode, or key is unknown, stop and do not guess, delete, or overwrite it.

Restoring the shared user configuration also affects Codex CLI. Validate the restored TOML and JSON, then verify desktop and CLI separately before resuming normal work.

Security

• Create a dedicated AIXHUB key for Codex so it can be rotated without affecting unrelated clients or application code.
• Keep auth.json and every timestamped backup readable only by the current user. Clean up backups that are no longer needed after the recovery window and successful verification.
• Keep official ChatGPT sign-in data separate; never paste an AIXHUB key into an official login flow.
• Review project trust, approval, and sandbox scope before allowing tools or writes.
• Never commit the key, paste it into a prompt, or include it in screenshots, diagnostics, support logs, or configuration examples.
• Rotate the key immediately after exposure, then update the protected shared authentication file and reverify both desktop and CLI.

Official sources

• Codex app
• Codex configuration reference

Last verified: 2026-07-14