Skip to main content

Prerequisites

Setup

1

Locate the Codex config folder

Codex Desktop stores its configuration under the user directory on each platform:
2

Write auth.json

Open auth.json in the .codex folder (create it if it does not exist) and paste the following:
⚠️ Important:replace the entire YOUR_A2AGENT_KEY placeholder with the real key from your a2agent dashboard.Codex Desktop reads this key from auth.json and uses it to authenticate with the A2Agent API.
3

Write config.toml

Open config.toml in the .codex folder (create it if it does not exist) and paste the following at the very top of the file:
The official docs also recommend disable_response_storage = true and supports_websockets = false. You may add both lines between model and the provider section; they are optional and do not change the setup flow.⚠️ Important: if config.toml already contains generated content such as [mcp_servers...], [plugins...], notify = ..., or [windows], do not delete it. Just add the model_provider and model lines at the very top (before any [section]), add the [model_providers.a2agent] block, and leave everything else untouched.
4

Restart Codex and test

  • Fully quit Codex Desktop, including the tray icon (closing the window is not enough).
  • Reopen Codex Desktop and start a new conversation.
  • Send “Hello”. If you receive a reply, setup is working.

Changing the Model

To change the default model, change one setting:
  1. Open config.toml and replace model = "qwen3.8-max" with the model you want, for example:
  2. Save the file, then fully quit and reopen Codex Desktop.

Optional: Show A2Agent Models in the Dropdown

By default, the model dropdown in Codex Desktop only shows the built-in OpenAI models, not the A2Agent models. To select them directly from the dropdown:
  • Copy the bundled a2agent-model-catalog.json file into the .codex folder.
a2agent-model-catalog.json
  • Add this line at the very top of config.toml:
  • Fully quit and reopen Codex Desktop. The dropdown will now list these models.