> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex Desktop

> Connect Codex Desktop to GravitexAI and verify model access and local tools

## 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](https://docs.gravitex.ai/en/integrations/codex.md).

* An installed application with a working Codex interface.
* A [GravitexAI account](https://maas.gravitex.ai) with sufficient balance.
* An [API key](https://maas.gravitex.ai/#/keys) 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:

```bash theme={null}
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](https://maas.gravitex.ai/#/models).

> [tab] macOS
>
> ```bash theme={null}
> 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"}'
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $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 |

> [!NOTE]
>
> 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:

> [tab] macOS
>
> ```bash theme={null}
> 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
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $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.

```toml theme={null}
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 |

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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.

1. Follow the [CC Switch guide](https://docs.gravitex.ai/en/integrations/cc-switch.md), open the **Codex** page and add a GravitexAI provider.

2. 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.

   ![CC Switch Codex provider settings showing the API URL and model list](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-cc-switch.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=d2d0ec20ceecb5c4c3c1bcfd0ad63e16)

3. 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.

4. Fully quit and reopen Codex Desktop, then verify chat and tools below.

> [!NOTE]
>
> 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.

1. Follow the [Magpie guide](https://docs.gravitex.ai/en/integrations/magpie.md) to install it and add provider `gravitex` with your GravitexAI key and Responses base URL `https://api.gravitex.ai/v1`.

   ![Magpie GravitexAI provider settings showing the OpenAI Responses URL](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-magpie.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=556bf6b7a49daa3cfbd4c5d7e92df96b)

   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`.

2. Fully quit Codex Desktop and back up its configuration.

3. Run the commands below, replacing the provider and model IDs with your own available values.

> [tab] macOS
>
> ```bash theme={null}
> magpie ls
> magpie provider set gravitex responses=https://api.gravitex.ai/v1
> magpie codex gravitex/gpt-6.1-sol
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> 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"`.

4. Alternatively, enable **Codex** on Magpie’s **Agent** page and choose the GravitexAI model. Check that it manages the desktop app’s actual Codex directory.
5. 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.

> [!TIP]
>
> 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

1. 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.
2. Send `hello` and confirm a response.
3. 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.
4. 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.

## 9. References

* [Codex CLI guide](https://docs.gravitex.ai/en/integrations/codex.md)

* [GravitexAI API keys](https://maas.gravitex.ai/#/keys)

* [GravitexAI model catalog](https://maas.gravitex.ai/#/models)

* [OpenAI configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)

* [Windows desktop configuration](https://learn.chatgpt.com/docs/windows/windows-app)

* [CC Switch documentation](https://github.com/farion1231/cc-switch)

* [Magpie reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.