Codex App desktop configuration

Connecting the desktop app

The Codex desktop app reads model gateway settings from local config.toml. On macOS it shares the default user configuration with the local CLI. Fully quit and restart the app after editing it. The Windows app uses the Windows user directory, not the WSL configuration.

For terminal usage, see Codex CLI configuration. The official gateway guide documents the macOS and Windows app configuration.

1. Prepare a key and model

Create a key in the AIMirrorX console. The model and channel must support Responses, streaming and tool calls.

Use an original model name recognized by your Codex version and routed to the matching model by the gateway. Custom aliases require matching Codex model metadata from your administrator. No particular model is guaranteed to be available on your account.

2. Edit config.toml

If the app launch environment sets CODEX_HOME, use config.toml there. Merge these fields into existing settings without duplicating keys or tables. Keep the first three top-level settings before TOML table headers.

model = "YOUR_RESPONSES_MODEL_ID"
model_provider = "aimirrorx"
web_search = "disabled"

[model_providers.aimirrorx]
name = "AIMirrorX"
base_url = "https://api.aimirrorx.com/v1"
env_key = "AIMIRRORX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Replace YOUR_RESPONSES_MODEL_ID with your actual model ID. End base_url with /v1, without /responses. env_key names the environment variable, not the secret itself. Built-in web search is disabled for the initial test; verify gateway support before enabling it.

This setup uses the AIMirrorX API key with requires_openai_auth = false. It does not require manually editing auth.json.

3. Make the key available to the app

An app launched from the desktop may not inherit a terminal's export. Supply AIMIRRORX_API_KEY to the process that actually launches the app.

macOS

Fully quit Codex, then set the variable for your current user login session in Terminal and reopen the app from the desktop:

launchctl setenv AIMIRRORX_API_KEY "YOUR_AIMIRRORX_API_KEY"

Replace the key placeholder. Set it again after logout or restart. If a managed launcher or secret delivery tool already supplies the variable, use that method. Keep real keys out of projects, screenshots and Git.

Windows

Fully quit Codex. In PowerShell, set a user environment variable:

[Environment]::SetEnvironmentVariable(
  "AIMIRRORX_API_KEY",
  "YOUR_AIMIRRORX_API_KEY",
  "User"
)

You can also create the same user variable in Windows Environment Variables settings. Replace the placeholder, sign out of Windows and sign back in, then open the app so the desktop launch process receives the variable. Closing a chat window alone does not fully quit the app. This user variable persists.

The Windows app uses Windows files and variables. A CLI running inside WSL uses the WSL environment instead.

4. Restart and verify

1. Fully quit and reopen the app.
2. Open a local project and start a new chat. Check the aimirrorx provider and the configured model ID.
3. Try a simple project summary request before development work.
4. If settings remain unchanged, check trusted project .codex/config.toml, profiles and managed settings for overrides.

This provider controls model requests. MCP, plugins, voice and other connected capabilities have separate network paths, authentication or permissions. An AIMirrorX key does not authorize those systems. These instructions do not change approval or sandbox settings.

Model catalogs

• For a built-in model name, ensure the bundled metadata matches the model actually routed by the gateway.
• A custom alias needs Codex-compatible model metadata. An ordinary GET /v1/models response listing IDs alone is insufficient.
• If your administrator provides a real catalog URL, add model_catalog_url inside the provider table. For a local file, use top-level model_catalog_json with its existing absolute path.
• Do not invent catalog URLs or file paths. An effective model_catalog_json takes precedence over a remote catalog.

Troubleshooting

Related documentation

• Codex CLI configuration
• AIMirrorX protocols and URLs
• Official gateway setup
• Configuration reference