codex-openrouter

This is my personal reference implementation for running the Codex CLI against models routed through OpenRouter. I use it on my Mac; it is published so other people can fork it, inspect the approach, and adapt it to their own setup.

It is not a supported product or a general-purpose installer. It may break when Codex's model-catalog format or OpenRouter's beta Responses API changes.

What it does

codex-openrouter maintains an isolated Codex profile and a generated model catalog. The catalog comes from OpenRouter's public models endpoint and refreshes every 24 hours or when the installed Codex version changes.

The generated /model list includes text-output models that advertise tool calling and at least 100K tokens of context. Free, online, preview, beta, experimental, and expired model IDs are excluded. Kimi Latest is pinned into the catalog and selected by default with high reasoning effort.

Authentication uses Codex's command-backed custom-provider authentication. The helper tries 1Password first, then falls back to OPENROUTER_API_KEY.

Intended environment

• macOS with zsh
• Node.js 22 or newer
• Codex CLI (tested with codex-cli 0.146.1)
• An OpenRouter account and funded API key
• 1Password CLI with desktop integration, unless using OPENROUTER_API_KEY

The runtime has no third-party Node dependencies.

Fork and configure

Fork this repository on GitHub, then clone your fork. This repository is designed to be edited rather than consumed as a package.

Create the ignored authentication file:

cp .env.example .env

Set OPENROUTER_OP_REF to your 1Password secret reference and optionally set OPENROUTER_OP_ACCOUNT. You may instead leave those blank and set OPENROUTER_API_KEY in .env or your shell environment. If both methods are configured, 1Password is tried first and the API key is the fallback.

The .env file is copied to the installed runtime with mode 0600. It is never committed. Storing OPENROUTER_API_KEY there stores the key as plaintext; the 1Password reference is the preferred setup.

Fork-specific model filtering, refresh behavior, defaults, and bootstrap metadata are ordinary constants in runtime/config.mjs.

Install

npm test
./install.sh

Make sure $HOME/.local/bin is on PATH, then refresh the catalog:

codex-openrouter catalog refresh

The installer writes:

• $HOME/.local/bin/codex-openrouter
• $HOME/.local/libexec/codex-openrouter
• ${CODEX_HOME:-$HOME/.codex}/openrouter.config.toml
• ${XDG_CACHE_HOME:-$HOME/.cache}/codex-openrouter

An existing Codex profile is preserved. To regenerate it after changing the source defaults or authentication implementation, run:

./install.sh --force-profile

All other arguments are forwarded to codex --profile openrouter, and the current directory remains the Codex workspace.

Commands

codex-openrouter
codex-openrouter catalog status
codex-openrouter catalog refresh

Catalog status and refresh use OpenRouter's public endpoint and do not retrieve the API key. If a refresh fails, an existing valid catalog is retained; a first run falls back to a Kimi bootstrap entry.

Update or uninstall

To update a fork, pull or edit the source, run the tests, and run ./install.sh. The existing profile remains untouched unless --force-profile is supplied. Changes to .env require reinstalling so the private runtime copy is updated.

To uninstall:

rm "$HOME/.local/bin/codex-openrouter"
rm -r "$HOME/.local/libexec/codex-openrouter"
rm "${CODEX_HOME:-$HOME/.codex}/openrouter.config.toml"
rm -r "${XDG_CACHE_HOME:-$HOME/.cache}/codex-openrouter"

Review those paths before running the commands if you customized the installer.

Development

npm test
npm run check

Tests use Node's built-in test runner. The catalog is validated with codex debug models before replacing a working cache.

Costs, data, and compatibility

OpenRouter model prices are variable. Review the current model catalog and pricing before use. Requests can incur charges immediately, including tool-heavy or long-context Codex sessions.

Prompts, source code, tool results, and other request data pass through OpenRouter and the selected downstream model provider. Review their privacy, retention, and provider-routing terms before using this with sensitive code.

OpenRouter describes its Responses API as beta, with possible breaking changes. The generated catalog also depends on Codex developer commands and catalog fields that can change between CLI versions.

This project is unofficial and is not affiliated with or endorsed by OpenAI or OpenRouter. Codex, OpenRouter, Kimi, and other product names belong to their respective owners.

License

MIT. See LICENSE.