Codex Desktop

1. Prerequisites

This guide covers the Codex desktop interface on macOS and Windows. Install the client for your system and confirm that its Codex interface opens. Installation paths and UI labels may differ across distributions. For terminal usage, see the Codex CLI guide.

An installed application with a working Codex interface.
A GravitexAI account with sufficient balance.
An API key whose group supports your target GPT model and the Responses API.

For installations with the following bundled CLI path, you can optionally check the version:

ls /Applications/ChatGPT.app
/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex --version

If the path does not exist, check your actual installation location. On Windows, check the version in the application’s About or Settings page; the commands above are for macOS only.

2. Test your key and model

Replace the placeholder key below. gpt-6.1-sol is an example: use a model available to your key’s group in the model catalog.

macOS
Windows PowerShell

curl https://api.gravitex.ai/v1/responses \
  -H "Authorization: Bearer sk-your-gravitex-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6.1-sol","input":"say ok"}'

$headers = @{ Authorization = "Bearer sk-your-gravitex-key" }
$body = @{ model = "gpt-6.1-sol"; input = "say ok" } | ConvertTo-Json
Invoke-RestMethod -Uri "https://api.gravitex.ai/v1/responses" -Method Post -Headers $headers -ContentType "application/json" -Body $body

Response	Action
`"status": "completed"`	Basic request succeeded; continue with configuration
`503` / `No available channel`	Check model permissions and channel availability
`404` / `endpoint_not_found`	Check the endpoint and Responses API support for your group
`401` / `invalid api key`	Check key validity and remove extra whitespace

This test incurs a small amount of API usage. It verifies basic access; test desktop tool calls separately below.

3. Configure the provider

Both systems use the same TOML configuration:

System	Default user configuration
macOS	`~/.codex/config.toml`
Native Windows client	`%USERPROFILE%\.codex\config.toml` (usually `C:\Users\YourName\.codex\config.toml`)

If CODEX_HOME is set, edit config.toml in that directory. On Windows, press Win + R and enter %USERPROFILE%\.codex to open the default folder. These instructions target the native Windows client; the WSL ~/.codex directory is normally separate. Back up the existing file before editing:

macOS
Windows PowerShell

mkdir -p ~/.codex
if [ -f ~/.codex/config.toml ]; then
  cp ~/.codex/config.toml ~/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)
fi
nano ~/.codex/config.toml

$codexConfigDir = Join-Path $env:USERPROFILE ".codex"
if ($env:CODEX_HOME) { $codexConfigDir = $env:CODEX_HOME }
New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
$codexConfigPath = Join-Path $codexConfigDir "config.toml"
if (Test-Path $codexConfigPath) {
  Copy-Item $codexConfigPath "$codexConfigPath.backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
} else {
  New-Item -ItemType File -Path $codexConfigPath | Out-Null
}
notepad $codexConfigPath

Merge the following into your configuration and replace the key. Update existing fields and tables instead of defining them twice.

model = "gpt-6.1-sol"
model_provider = "gravitex"
model_reasoning_effort = "medium"

[model_providers.gravitex]
name = "GravitexAI"
base_url = "https://api.gravitex.ai/v1"
wire_api = "responses"

[model_providers.gravitex.http_headers]
Authorization = "Bearer sk-your-gravitex-key"
Content-Type = "application/json"

Field	Rule
`model`	Use the same GPT model ID that passed the API test
`model_provider`	Must match `gravitex` in the provider table name
`base_url`	Use `https://api.gravitex.ai/v1`; do not append `/responses`
`wire_api`	Use `responses`
`Authorization`	Keep one space after `Bearer` and the key on a single line

Keep top-level fields such as model before the first TOML table. Authorization belongs inside the http_headers table. This table does not have to be last: each new [table] header changes which table subsequent fields belong to.

Static headers store your key in plaintext on this device. The provider also supports env_key, but apps opened from Finder or Launchpad typically do not inherit temporary terminal exports. Verify that the application process can read the variable before using that approach. On Windows, $env:VARIABLE also affects only the current PowerShell session and its child processes; an application opened from Start does not automatically inherit those temporary values.

Save the file and fully quit the application hosting Codex:

macOS: use Command + Q.
Windows: use the application’s Quit or Exit command, including its system tray menu if it is still running there. If necessary, save your work and end the corresponding application and remaining Codex processes in Task Manager, then reopen from the Start menu.

Start a new local chat after reopening. Closing a window may leave background processes running.

4. Connect through CC Switch

On macOS or Windows, validate your API key and back up the Codex configuration first.

Follow the CC Switch guide, open the Codex page and add a GravitexAI provider.
Enter your key, Base URL https://api.gravitex.ai/v1 and a verified GPT model ID, such as gpt-6.1-sol. Select Responses if a protocol option is shown.
Save and switch to this provider. Confirm that CC Switch updates the same user configuration directory used by the desktop app, including any CODEX_HOME override.
Fully quit and reopen Codex Desktop, then verify chat and tools below.

This procedure uses provider switching. Local routing or aggregation may require CC Switch to remain running. Restart Codex after aggregated model lists change. To revert, switch back to the previous provider or restore your backup while Codex is closed.

5. Connect through Magpie

The request path is Codex Desktop → local Magpie → GravitexAI. Keep the gateway running on either operating system.

Follow the Magpie guide to install it and add provider gravitex with your GravitexAI key and Responses base URL https://api.gravitex.ai/v1. The screenshot uses provider ID gravitexai; the commands below use gravitex. If you use the screenshot’s ID, replace it in the commands, for example magpie codex gravitexai/gpt-6.1-sol.
Fully quit Codex Desktop and back up its configuration.
Run the commands below, replacing the provider and model IDs with your own available values.

macOS
Windows PowerShell

magpie ls
magpie provider set gravitex responses=https://api.gravitex.ai/v1
magpie codex gravitex/gpt-6.1-sol

magpie.exe ls
magpie.exe provider set gravitex responses=https://api.gravitex.ai/v1
magpie.exe codex gravitex/gpt-6.1-sol

If the program is not on PATH, use its actual path; invoke a quoted path with & "C:\actual path\magpie.exe".

Alternatively, enable Codex on Magpie’s Agent page and choose the GravitexAI model. Check that it manages the desktop app’s actual Codex directory.
Keep Magpie running, reopen Codex Desktop and verify chat and tools. For connection failures, check gateway port 3425 (default), localhost proxy handling and upstream permissions.

To return to a direct connection, disconnect Codex in Magpie, restore the previous configuration or select a provider through CC Switch, and fully restart Codex. Use one configuration manager at a time. Local gateway credentials and the upstream GravitexAI key serve different purposes.

6. Verify the desktop connection

Open a local project and create a chat. Check the model or provider selection. Some versions may show Custom; the label alone does not confirm routing.
Send hello and confirm a response.
Ask “List the files in the current directory.” Confirm that a file or terminal tool runs and its result is used in the reply. Grant local permissions when prompted.
Check the corresponding request, model and usage in the GravitexAI console.

7. Troubleshooting

Symptom	Checks
Official account login prompt	Check the active config directory, provider name and restart; some desktop features may still require official login
`401`	Check the key, space after `Bearer`, and TOML table placement
`404`	Check the base URL and your group’s Responses API support
Model unavailable	Check the exact model ID, group permissions and channel status; repeat the curl test
`400`	Inspect the reported parameter; remove `service_tier` if the error identifies it as unsupported
Changes have no effect	Fully restart and check project or profile overrides
Chat works but tools fail	Check local permissions, client version and model/channel tool compatibility
Windows command or parameter errors	Run the Windows tab’s commands in PowerShell; do not paste Bash backslash continuations
Windows config missing or ignored	Check that the file is named `config.toml`, not `config.toml.txt`; check `CODEX_HOME` and avoid editing the separate WSL config

8. Adjustments and key handling

To switch models, update top-level model, verify access and restart.
Set model_reasoning_effort to low, medium or high as supported by the model. Higher effort usually uses more time and tokens; it does not guarantee better results.
Restore your backup to undo changes. To use the official provider, set top-level model_provider = "openai", choose an available official model, restart and sign in as needed.
Keep keys out of repositories and shared screenshots. Revoke and replace exposed keys.
Cloud tasks, plugins and other account-dependent features vary by client, account and provider support.

Chat AI

Coding

AI Agent

Tech Engineering

Translation

1. Prerequisites

2. Test your key and model

3. Configure the provider

4. Connect through CC Switch

5. Connect through Magpie

6. Verify the desktop connection

7. Troubleshooting

8. Adjustments and key handling

9. References

​1. Prerequisites

​2. Test your key and model

​3. Configure the provider

​4. Connect through CC Switch

​5. Connect through Magpie

​6. Verify the desktop connection

​7. Troubleshooting

​8. Adjustments and key handling

​9. References

1. Prerequisites

2. Test your key and model

3. Configure the provider

4. Connect through CC Switch

5. Connect through Magpie

6. Verify the desktop connection

7. Troubleshooting

8. Adjustments and key handling

9. References