Codex with Lore

Codex is OpenAI’s terminal-based AI coding agent. Lore’s gateway is the recommended way to run Codex with persistent memory and gradient context management. For CLI users, lore run is the simplest path. For the Codex Desktop app — which can’t accept -c CLI overrides — see Setup command.

The Codex CLI is a Rust binary that does NOT read OPENAI_BASE_URL from the environment. Provider routing is done exclusively via ~/.codex/config.toml or -c CLI overrides. The gateway uses -c overrides when launched via lore run so you do not have to edit the config file by hand.

Install (CLI)

The hosted install script sets up Lore and Codex in one step:

curl -fsSL https://withlore.ai/install | bash

Then launch Codex through the gateway:

lore run

lore run starts the Lore gateway (if not already running) and launches Codex with the right -c overrides to route through it. The gateway auto-detects Codex on your PATH.

What lore run does for Codex

It launches Codex with per-invocation overrides equivalent to this configuration:

model_provider = "lore_http"
model_auto_compact_token_limit = 999999999

[model_providers.lore_http]
name = "Lore"
base_url = "http://127.0.0.1:3207/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

The named provider uses Codex’s existing OpenAI API-key or ChatGPT authentication and streams Responses over HTTP. Lore does not support WebSocket transport. Changing only openai_base_url leaves the built-in OpenAI provider’s WebSockets enabled, causing repeated upgrade attempts before HTTP fallback.

The compaction limit lets Lore’s gradient context manager and distillation pipeline manage context. The launcher also retains openai_base_url for compatibility and forwards OpenAI organization/project environment headers. All overrides apply only to the launched process.

Codex scopes session discovery by provider identity. When switching from openai to lore_http, older sessions may require codex resume --all. Setup undo restores your previous provider selection.

Manual setup (CLI)

If you’d rather start the gateway yourself and launch Codex directly — or if you’re setting up the Codex Desktop app, which doesn’t accept -c CLI overrides — run lore setup codex once. It writes the right ~/.codex/config.toml for both the CLI and the Desktop app, and supports -r <url> for remote gateways. See the Setup command page for the full command reference.

Custom upstream headers

The Codex plugin reads LORE_UPSTREAM_EXTRA_HEADERS from your environment and forwards its values through the Lore provider’s http_headers TOML map. This is the path for corporate proxies, LiteLLM team-routing tokens, and Cloudflare AI Gateway. See the custom upstreams guide for full examples.

The lore_http provider name is reserved for Lore’s HTTP configuration. If you already use that name with custom authentication, rename that provider before running setup or lore run. Setup refuses unsupported inline or non-contiguous definitions of that provider rather than rewriting unrelated config. A default profile that selects another provider must have its model_provider override removed or set to lore_http; explicitly selecting another profile or passing your own -c overrides can also override Lore’s configuration.

Per-harness notes

• Project identity is exposed as env vars. The gateway sets LORE_PROJECT and LORE_GIT_REMOTE (when a git remote exists) so Codex can map them to env_http_headers if your config.toml is configured to.
• Compaction is disabled. Codex’s model_auto_compact_token_limit=999999999 override prevents the built-in compaction from destroying Lore’s gradient context.

Next steps

• Setup command — lore setup codex for manual/Desktop configuration and remote gateways.
• Architecture — how temporal storage, distillation, and the gradient context manager fit together.
• Configuration — full reference for .lore.json.
• Custom upstreams — corporate proxies, LiteLLM, Cloudflare AI Gateway.