Official provider plugins

Official provider plugins

Official provider plugins publish their own model catalog rows. These providers require no models.providers model entries; enable the provider plugin, set auth, and pick a model. Use models.providers only for explicit custom providers or narrow request settings such as timeouts.

OpenAI

• Provider: openai
• Auth: OPENAI_API_KEY
• Optional rotation: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, plus OPENCLAW_LIVE_OPENAI_KEY (single override)
• Fresh setup default: openai/gpt-5.6-sol.
• Example models: openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna, openai/gpt-5.5; the bare direct-API openai/gpt-5.6 alias remains supported.
• Verify account/model availability with openclaw models list --provider openai if a specific install or API key behaves differently.
• CLI: openclaw onboard --auth-choice openai-api-key
• Direct OpenAI API-key Responses requests default to "sse".
• Override per model via agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", "websocket-cached", or "auto"). Cached WebSockets reuse the session connection and send only new input with previous_response_id when history still matches.
• Set an explicit OpenAI API service tier with params.serviceTier or params.service_tier; Fast mode (formerly Priority processing) uses service_tier=priority.
• On native public OpenAI and ChatGPT/Codex Responses requests, precedence is payload/transport service_tier, then a valid explicit model param, then the fast-mode default.
• /fast and valid params.fastMode / params.fast_mode values are shared agent-runtime controls; on direct embedded openai/* Responses requests they supply service_tier=priority only when no higher-precedence tier exists.
• Hidden OpenClaw attribution headers (originator, version, User-Agent) apply only on native OpenAI traffic to api.openai.com, not generic OpenAI-compatible proxies
• Native OpenAI routes also keep Responses store, prompt-cache hints, and OpenAI reasoning-compat payload shaping; proxy routes do not
• openai/gpt-5.3-codex-spark is available only through ChatGPT/Codex OAuth; direct OpenAI API-key and Azure API-key routes reject it

{  agents: { defaults: { model: { primary: "openai/gpt-5.6-sol" } } },}

If the API organization does not expose GPT-5.6, set openai/gpt-5.5 explicitly. Normal onboarding and reauthentication preserve an existing explicit primary model; models auth login --set-default and models set are the intentional replacement paths.

Anthropic

• Provider: anthropic
• Auth: ANTHROPIC_API_KEY
• Optional rotation: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, plus OPENCLAW_LIVE_ANTHROPIC_KEY (single override)
• Example model: anthropic/claude-opus-5
• CLI: openclaw onboard --auth-choice apiKey
• Direct public Anthropic requests support the shared /fast toggle and params.fastMode, including API-key and OAuth-authenticated traffic sent to api.anthropic.com; OpenClaw maps that to Anthropic service_tier (auto vs standard_only)
• Preferred Claude CLI config keeps the model ref canonical and selects the CLI backend separately: anthropic/claude-opus-5 with model-scoped agentRuntime.id: "claude-cli". Legacy claude-cli/claude-opus-4-7 refs still work for compatibility.

{  agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } },}

OpenAI ChatGPT/Codex OAuth

• Provider: openai
• Auth: OAuth (ChatGPT)
• Fresh native Codex app-server harness ref: openai/gpt-5.6-sol
• Native Codex app-server harness docs: Codex harness
• Astra (openai/gpt-6-astra) defaults to low reasoning effort to limit routine budget use. The OpenAI provider default is shared by model controls and both runtimes; explicit thinking settings take precedence.
• Legacy model refs: codex/gpt-*, openai-codex/gpt-*
• Plugin boundary: openai/* loads the OpenAI plugin; explicit runtime policy or the provider-owned effective route decides whether the native Codex app-server plugin is selected.
• CLI: openclaw onboard --auth-choice openai or openclaw models auth login --provider openai
• OpenClaw's embedded ChatGPT Responses transport defaults to auto (WebSocket-first, SSE fallback).
• agents.defaults.models["openai/<model>"].params.transport and params.serviceTier are authored embedded-provider request settings. They keep implicit runtime selection on OpenClaw; native Codex owns its app-server transport and service tier.
• Valid model-scoped params.fastMode / params.fast_mode values and valid cutoff keys are portable typed agent-runtime controls. They do not count as authored provider request params and do not select a runtime. Pin agentRuntime.id: "openclaw" or agentRuntime.id: "codex" when a recipe depends on one runtime.
• Hidden OpenClaw attribution headers (originator, version, User-Agent) are only attached on native Codex traffic to chatgpt.com/backend-api, not generic OpenAI-compatible proxies
• The shared /fast toggle, configured defaults, and valid model-scoped Fast params resolve through one runtime-control policy. See Thinking levels for precedence.
• OpenAI API Fast mode is premium-priced and model-specific. GPT-5.6 Sol currently costs 2× Standard token pricing, and long-context multipliers stack. ChatGPT/Codex-credit Fast mode is separate: GPT-5.6 and GPT-5.5 currently consume 2.5× Standard credits, while API-key Codex runs use API token pricing. See Fast mode, API pricing, and Codex speed.
• The native Codex catalog can expose exact openai/gpt-5.6-sol, openai/gpt-5.6-terra, and openai/gpt-5.6-luna refs according to account access. It does not apply the direct API's bare gpt-5.6 alias client-side.
• openai/gpt-5.5 uses the Codex catalog native contextWindow = 400000 and default runtime contextTokens = 272000; override the runtime cap with models.providers.openai.models[].contextTokens
• Sign in with openai auth and use openai/gpt-5.6-sol for a fresh subscription-backed setup. Select openai/gpt-5.5 explicitly if that Codex workspace does not expose GPT-5.6.
• Use provider/model agentRuntime.id: "openclaw" to keep an otherwise eligible route on the built-in runtime. With runtime unset or auto, only an exact official HTTPS Responses/ChatGPT-compatible route with no authored provider request override may select Codex implicitly.
• Legacy Codex GPT refs are legacy state, not a live provider route. Use canonical openai/* refs for new agent config, and run openclaw doctor --fix to migrate codex/* and openai-codex/* refs while preserving their native Codex semantics with model-scoped agentRuntime.id: "codex". Existing explicit canonical openai/gpt-5.5 selections are not upgraded.

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },}

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Other subscription-style hosted options

OpenCode

• Auth: OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY)
• Zen runtime provider: opencode
• Go runtime provider: opencode-go
• Example models: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen or openclaw onboard --auth-choice opencode-go

{  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },}

Google Gemini (API key)

• Provider: google
• Auth: GEMINI_API_KEY
• Optional rotation: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, GOOGLE_API_KEY fallback, and OPENCLAW_LIVE_GEMINI_KEY (single override)
• Example models: google/gemini-3.1-pro-preview, google/gemini-3.5-flash
• Compatibility: legacy OpenClaw config using google/gemini-3.1-flash-preview is normalized to google/gemini-3-flash-preview
• Alias: google/gemini-3.1-pro is accepted and normalized to Google's live Gemini API id, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Thinking: /think adaptive uses Google dynamic thinking. Gemini 3/3.1 omit a fixed thinkingLevel; Gemini 2.5 sends thinkingBudget: -1.
• Direct Gemini runs also accept agents.defaults.models["google/<model>"].params.cachedContent (or legacy cached_content) to forward a provider-native cachedContents/... handle; Gemini cache hits surface as OpenClaw cacheRead

Google Vertex and Gemini CLI runtime

• google-vertex: managed Google Cloud access through gcloud Application Default Credentials.
• google-gemini-cli: optional local runtime for an explicitly configured canonical google/* model.

OpenClaw does not create Gemini CLI OAuth or Antigravity OAuth profiles. Connect Google through an AI Studio API key or Vertex AI. If you explicitly choose the Gemini CLI runtime, it can use the selected Google API-key profile. Existing valid Gemini CLI OAuth profiles remain runtime-compatible, but they are not a setup or recovery route.

Gemini CLI uses stream-json by default. OpenClaw reads assistant stream messages and normalizes stats.cached into cacheRead; legacy --output-format json overrides still read reply text from response.

Z.AI (GLM)

• Provider: zai
• Auth: ZAI_API_KEY
• Example model: zai/glm-5.2
• CLI: openclaw onboard --auth-choice zai-api-key
  • Model refs use the canonical zai/* provider ID.
  • zai-api-key auto-detects the matching Z.AI endpoint; zai-coding-global, zai-coding-cn, zai-global, and zai-cn force a specific surface

Vercel AI Gateway

• Provider: vercel-ai-gateway
• Auth: AI_GATEWAY_API_KEY
• Example models: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

Other bundled provider plugins

Quirks worth knowing