Skip to main content
ValarCode routes the OpenAI Codex CLI through Valar by editing its 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 ~/.codex config directory (%USERPROFILE%\.codex on Windows). Run Codex once so the directory exists.
  • A Valar coding key (vlrcode_…) and the valar CLI (install).

Enable routing

Run once per machine:
The routing lives entirely in 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:
In detail, enabling:
  • Sets the root model_provider to valar so Codex uses the Valar provider block.
  • Writes base_url with the /v1 surface. Codex speaks the OpenAI Responses API (wire_api = "responses") and appends /responses, so requests land on https://api.valarhq.ai/v1/responses.
  • Puts the coding key on experimental_bearer_token, which Codex renders as Authorization: Bearer on the wire. It must not be an Authorization entry in http_headers, which Codex drops.
  • Adds the X-Valar-Client-Id, X-Valar-Harness and X-Valar-Cli-Version request headers. The client-id header is omitted entirely when there is no client id, rather than written blank.
Your comments, layout, and any other tables pass through byte-for-byte. The file is written user-only (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 after on or off, then start a new conversation.
  • A config.toml saved by a Windows editor keeps its line endings and byte-order mark.
  • The original config.toml is 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 0600 mode 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 run valar 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

This restores the pre-enable 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 a valar 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:
Finish or close a routed conversation before you turn routing off. Do not 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, and model_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.