For choosing a provider as a user, see Choose Your AI Provider. This page is the technical reference: what actually gets written where when you configure each provider, and how the system repairs common broken states.

​
Provider lanes at a glance

OpenAI has two distinct lanes. The API-key lane (openai/…) and the ChatGPT-subscription lane (codex/…) have different model catalogs and different credentials. gpt-5 exists only on the API lane; the subscription serves gpt-5.5 / gpt-5.4 / gpt-5.4-mini. Mixing them up is the root of most “Incorrect API key” tickets — see self-healing below.

​
Where credentials actually go

Configuring a provider writes up to four places:
  1. ~/.openclaw/agents/main/agent/auth-profiles.json — the real secret. API keys as {type:"api_key", provider, key}; subscriptions as {type:"oauth", provider, access, id, refresh, expires}.
  2. openclaw.json → auth.profiles.<provider>:default — metadata only ({provider, mode}). No secret lives here.
  3. openclaw.json → models.providers.<provider> — the provider definition (baseUrl, API dialect, model list) for lanes that need one (ClawBox AI, Anthropic, Google, OpenRouter, Ollama, llama.cpp).
  4. ~/.openclaw/agents/<agent>/agent/codex-home/auth.json (+ ~/.codex/auth.json) — the ChatGPT-subscription session, synthesized from the auth profile on every gateway start.
The active model is agents.defaults.model.primary (e.g. codex/gpt-5.4), with agents.defaults.model.fallbacks behind it (typically ClawBox AI or a local model).

​
Compatibility routing (why some lanes use “OpenAI-compat”)

Some native OpenClaw provider plugins expect auth stores ClawBox doesn’t populate. ClawBox therefore routes Anthropic via https://api.anthropic.com/v1 and Google via https://generativelanguage.googleapis.com/v1beta/openai — both OpenAI-compatible endpoints with the key inline in the provider definition. Behavior is identical for users; the win is call-time auth that always works. OpenRouter likewise requires an explicit provider definition (https://openrouter.ai/api/v1) — without one, chats silently return empty usage.

​
ClawBox AI specifics

  • Pairing uses a device-code flow against the portal (openclawhardware.dev) — the wizard shows a short code you confirm in your portal account; the resulting token is stored on-device.
  • Requests proxy through the portal’s AI endpoint; both models advertise reasoning support including X-High effort (mapped upstream to DeepSeek’s maximum reasoning mode).
  • Changing the linked portal account automatically unpairs ClawKeep (backups belong to the account).

​
Reasoning effort

The chat header’s reasoning-effort picker is uniform across every cloud provider — Off, Low, Medium, High — so the control behaves the same whichever model you select. The gateway accepts this ladder for all of them and normalizes it per provider. Two consequences worth knowing:
  • A model with only one level shows no control at all. The header renders the picker only when more than one level is available, which is why the on-device local model has no reasoning dial.
  • An unsupported level falls back to that provider’s default, not to the nearest neighbouring level. Switching provider mid-conversation therefore resets the effort to the new provider’s default if the current one is not in its list. The selection is remembered per provider.
Provider-specific extras that the gateway vocabulary also accepts (minimal, xhigh, max, adaptive) are deliberately not offered in the picker, to keep the control consistent across models.
Model reasoning capability is declared programmatically, not by hand-editing config. Separately from the picker above, each model entry carries gateway compatibility metadata describing which efforts it accepts. Editing that by hand in openclaw.json does not stick — two mechanisms overwrite it:
  1. The gateway re-applies its expected values on every start. ClawBox’s boot-time configuration step rewrites the reasoning metadata on the ClawBox AI models each time the gateway starts, so a manual edit survives only until the next restart.
  2. System updates replace the bundled model catalog. Updating OpenClaw overwrites the packaged catalog wholesale, so edits made there are lost on the next update. ClawBox re-applies its own values on each boot precisely because of this.
If a level is not declared as supported, the gateway rejects it. Changes must therefore be made in ClawBox’s setup and boot-time configuration code, which is the single source of truth.

​
Local models (Ollama / llama.cpp)

  • Local lanes authenticate with a per-install bearer token through a local proxy — nothing is exposed unauthenticated, even on localhost.
  • Only one local runtime is active at a time (8 GB Jetson RAM). Ollama gets tuned automatically (quantized KV cache, flash attention, single loaded model).
  • A local model can be the primary or the fallback; the wizard’s fallback chain prefers a configured local model, else ClawBox AI.

​
Self-healing on boot (beta channel)

gateway-pre-start.sh runs before every gateway start and repairs known-bad provider states. On the beta channel (and the next stable release) this includes: All heals are idempotent — a healthy config is left untouched.

​
Troubleshooting pointers

  • 401 Incorrect API key (sk-proj-…) after switching to the subscription → Troubleshooting → AI provider errors
  • Config validation failed: … Unrecognized key → stale OpenClaw core; sudo bash install.sh --step openclaw_install
  • Codex chats crash immediately (createDiagnosticTraceContext… is not a function) → @openclaw/codex plugin version skew vs core; re-run sudo bash install.sh --step openclaw_install (re-pins plugins)
  • Model picker rejects a model ID → each lane validates against its own catalog; remember the two OpenAI lanes have different catalogs.