config.toml. Codex keeps speaking the OpenAI Responses API and you keep picking your model; the gateway maps whatever it sends to the target your routing resolves to. See Set up ValarCode for the shared setup and the client-id model.
Prerequisites
- The OpenAI Codex CLI or the ChatGPT app installed, with a
~/.codexconfig directory (%USERPROFILE%\.codexon Windows). Run Codex once so the directory exists. - A Valar coding key (
vlrcode_…) and thevalarCLI (install).
Enable routing
Run once per machine:config.toml, with no env var, shell-rc edit, or new-terminal step. Then restart Codex (or the ChatGPT app, if that is where you run Codex) and start a new conversation. Check the state any time:
What gets written
valar codex on edits ~/.codex/config.toml, or $CODEX_HOME/config.toml when you set CODEX_HOME, as Codex does. A config.toml that is a symlink, for example into a dotfiles repo, stays a symlink: Valar edits the file it points to. It sets the root provider to Valar and adds a provider block that points at the gateway and carries your credentials in request headers:
- Sets the root
model_providertovalarso Codex uses the Valar provider block. - Writes
base_urlwith the/v1surface. Codex speaks the OpenAI Responses API (wire_api = "responses") and appends/responses, so requests land onhttps://api.valarhq.ai/v1/responses. - Puts the coding key on
experimental_bearer_token, which Codex renders asAuthorization: Beareron the wire. It must not be anAuthorizationentry inhttp_headers, which Codex drops. - Adds the
X-Valar-Client-Id,X-Valar-HarnessandX-Valar-Cli-Versionrequest headers. The client-id header is omitted entirely when there is no client id, rather than written blank.
0600), since it now holds a bearer token, and the original config.toml is snapshotted under ~/.valar/codex/ before the first change so off restores it exactly. Settings Codex saves while routing is on, such as trusted folders and MCP servers, stay in the file after off.
The client id defaults to your OS username, so the header reads
X-Valar-Client-Id: jdoe. Use --user-id RANDOM for an opaque vc_… id instead. See per-engineer attribution.On Windows
valar codex on works on Windows 11 the same way, with valar 1.1.39 or newer (run valar upgrade first). Run it from PowerShell as yourself; it needs no administrator access.
- It edits
%USERPROFILE%\.codex\config.toml, which both the Codex CLI and the ChatGPT app read. Restart the ChatGPT app afteronoroff, then start a new conversation. - A
config.tomlsaved by a Windows editor keeps its line endings and byte-order mark. - The original
config.tomlis snapshotted under%USERPROFILE%\.valar\codex\. - The file can hold your key, so its access list allows only you and the system account, in place of the
0600mode used on macOS and Linux. - With the on-device proxy set up, Codex goes through it on the forwarder lane, so a new sign-in reaches a running Codex without a restart.
Claude models
When Claude on Codex is turned on for your organization, Codex’s model picker also lists eight Claude models: Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5 and Claude Haiku 4.5. Ask your Valar contact to turn it on. Without it, the picker shows no Claude models. To see them, update valar to the latest version, then runvalar models refresh (or valar codex on again) and restart Codex. Pick a Claude model like any other one. You can switch between Claude and the other models in the same conversation.
Codex’s hosted web search is offered on the GPT models only. On Claude, as on the open-weight models, Codex does not declare it.
Turn off routing
config.toml byte-for-byte. Restart Codex and start a new conversation.
Known limitations
Existing conversations require a fork between valar on and off
Moving a conversation across avalar codex on or off boundary is not supported. Start a new conversation, or /fork.
Conversations opened before valar codex on stay with OpenAI. Run /fork in one and the fork carries the context through Valar.
Running valar codex off under a conversation that is still open breaks that conversation. Routing reverts with the file, but the model stays the one you had selected, and OpenAI does not serve it:
codex resume a session across a valar codex on or off switch: it resumes on whatever the config says at that moment, which can be a different provider and model. Start a new conversation or /fork instead. Codex warns only about the model:
Voice is off while routing is on
Codex voice, realtime sessions and in-app dictation both, terminates at OpenAI. The audio leg runs against OpenAI’s Realtime API under your ChatGPT sign-in, andmodel_provider does not redirect it. Valar routing authenticates with your coding key instead, so the voice path is unavailable and Codex stays text-only. Turn routing off, or keep an unrouted Codex beside it, if you need voice.
Next steps
Model routing
How cohorts and the split decide which model serves each request.
Models
The open-weight targets and the frontier Claude tiers.