Codex CLI setup
Configure Codex CLI with Weave Router
Run npx @weave-os/router --codex to configure Codex CLI. The installer adds a managed Weave provider to config.toml while preserving the active ChatGPT OAuth login. Check status and start a new run to use the changed configuration.
Source review
Codex CLI · user scope
Configure the provider, keep the login
Add the managed Weave provider
npx @weave-os/router --codexInspect connection and account
npx @weave-os/router status --codex- Managed file: ~/.codex/config.toml
- Existing ChatGPT OAuth login preserved
- Start a new Codex run
A preserved login does not include every model in a subscription. Model access depends on configured credentials.
Provider configuration belowAt a glance
Keep provider configuration and login distinct
- Evidence type
Codex configuration
A managed Weave provider block selects the Router endpoint in config.toml.
- Evidence type
Authentication context
The installer preserves the active ChatGPT OAuth login. Model access depends on the configured credentials.
- Evidence type
Request routing
Automatic routing or an explicit model selection determines how each request is served.
How do you configure Codex CLI?
This guide covers the Router’s Codex CLI installer target. Meet the quickstart requirements, then run:
npx @weave-os/router --codex
npx @weave-os/router status --codex
Follow the installer’s setup prompts and resolve any connectivity, configuration, or account-health errors. Start a new Codex run after changing the connection. These steps do not establish support for every application that embeds or connects to Codex.
What does the installer manage in config.toml?
The user installation patches ~/.codex/config.toml with a managed [model_providers.weave] block and sets model_provider = "weave". Fresh installations select weave-auto; reinstalling preserves an existing model choice.
The installer preserves the active ChatGPT OAuth login. That is distinct from the Router endpoint’s own configuration and credential requirements. Available models can use different configured credentials; preserving a subscription login does not include every selected model in that subscription.
For a project installation, run from the repository:
npx @weave-os/router --codex --scope project
npx @weave-os/router status --codex --scope project
This uses the repository’s .codex/config.toml. Follow the installer’s credential handling, inspect changes before committing, and keep keys out of Git. Re-running the installer refreshes its managed provider configuration.
How do automatic routing and model selection interact?
In automatic mode, Weave selects a model per upstream request. Codex’s native /model picker can force a named model and its selected reasoning effort when changed during a session. Selecting Weave Router resumes automatic routing.
An existing $fm session pin still applies in automatic mode until $ufm clears it. If you are investigating unexpected model choices, check both the picker and any active session pin before assuming the connection is wrong. The reviewed installer source describes this behavior and the credentials used for particular model families.
Use the current roster instead of relying on a model list copied into a guide:
npx @weave-os/router models --codex
Which commands work inside Codex?
The installer provides native Codex skills:
Scroll horizontally if needed →
| Task | Skill or control | What to check |
|---|---|---|
| Inspect the connection | $router-status | Endpoint, account health, and active configuration |
| Inspect the model roster | $router-models | Current models and credential availability |
| Switch routing off or on | $router-off / $router-on | The next run uses the changed connection |
| Pin or clear a session model | $force-model ($fm) / $unforce-model ($ufm) | A session pin can still apply in automatic mode |
These are native skills with a $ prefix. Codex does not load the third-party slash-command files used by Claude Code. Use the terminal status command if a skill is missing from an older installation, then consult the installer’s update instructions.
How do you switch back or uninstall?
For a user-scope installation, switch to the default provider without removing the Router configuration:
npx @weave-os/router off --codex
# Restore the saved Router connection:
npx @weave-os/router on --codex
Start the next Codex run after switching. The installed $disable-routing skill also returns the next session to the default provider without logging out or deleting Router configuration.
To remove the managed provider:
npx @weave-os/router --uninstall --codex
The installer removes its managed configuration while preserving other settings. Match project installations with --scope project from the same repository. Recheck the configuration and status after removal.
What should a useful troubleshooting report include?
Record the client version, installer version, selected scope, redacted endpoint, and status result. Note whether the native picker or a session pin was active. Do not share Router keys, OAuth tokens, or a raw configuration containing secrets.
For self-hosted endpoints or Windows shell limitations, follow the quickstart and the current installer documentation. Credential availability and client configuration should be checked separately.
Check the evidence
Sources
Use these sources to check the definitions, configuration, and scope described above.
Weave Router
Review the Codex configuration
Check the managed provider, credentials, and active model selection.