Configuration — tools and custom providers

Provider entry (type: "provider" or omitted):

• provider: API provider id (openai, anthropic, google/gemini, groq, etc.)
• model: model id override
• profile / preferredProfile: auth-profiles.json profile selection

CLI entry (type: "cli"):

• command: executable to run
• args: templated args (supports {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc.; openclaw doctor --fix migrates deprecated {input} placeholders to {{MediaPath}})

Common fields:

• capabilities: optional list (image, audio, video). Defaults: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: per-entry overrides.
• tools.media.image.timeoutSeconds and matching image model timeoutSeconds entries also apply when the agent calls the explicit image tool.
• Failures fall back to the next entry.

Provider auth follows standard order: auth-profiles.json → env vars → models.providers.*.apiKey.

Async completion fields:

• asyncCompletion.directSend: deprecated compatibility flag. Completed async media tasks stay requester-session mediated so the agent receives the result, decides how to tell the user, and uses the message tool when source delivery requires it.

• self: only the current session key.
• tree: current session + sessions spawned by the current session (subagents).
• agent: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
• all: any session. Cross-agent targeting still requires tools.agentToAgent.
• Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility="spawned", visibility is forced to tree even if tools.sessions.visibility="all".
• When not all, sessions_list includes a compact visibility field describing the effective mode and a warning that some sessions may be omitted outside the current scope.

• Attachments require enabled: true.
• Subagent attachments are materialized into the child workspace at .openclaw/attachments/<uuid>/ with a .manifest.json.
• ACP attachments are image-only and forwarded inline to the ACP runtime after the same file count, per-file byte, and total byte limits pass.
• Attachment content is automatically redacted from transcript persistence.
• Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
• Subagent attachment file permissions are 0700 for directories and 0600 for files.
• Subagent cleanup follows the cleanup policy: delete always removes attachments; keep retains them only when retainOnSessionKeep: true.

• Use authHeader: true + headers for custom auth needs.
• Override agent config root with OPENCLAW_AGENT_DIR.
• Merge precedence for matching provider IDs:
  • Non-empty agent models.json baseUrl values win.
  • Non-empty agent apiKey values win only when that provider is not SecretRef-managed in current config/auth-profile context.
  • SecretRef-managed provider apiKey values are refreshed from source markers (ENV_VAR_NAME for env refs, secretref-managed for file/exec refs) instead of persisting resolved secrets.
  • SecretRef-managed provider header values are refreshed from source markers (secretref-env:ENV_VAR_NAME for env refs, secretref-managed for file/exec refs).
  • Empty or missing agent apiKey/baseUrl fall back to models.providers in config.
  • Matching model contextWindow/maxTokens use the higher value between explicit config and implicit catalog values.
  • Matching model contextTokens preserves an explicit runtime cap when present; use it to limit effective context without changing native model metadata.
  • Provider-plugin catalogs are stored as generated plugin-owned catalog shards under the agent's plugin state.
  • Use models.mode: "replace" when you want config to fully rewrite models.json and active plugin catalog shards.
  • Marker persistence is source-authoritative: markers are written from the active source config snapshot (pre-resolution), not from resolved runtime secret values.

• models.mode: provider catalog behavior (merge or replace).
• models.providers: custom provider map keyed by provider id.
  • Safe edits: use openclaw config set models.providers.<id> '<json>' --strict-json --merge or openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge for additive updates. config set refuses destructive replacements unless you pass --replace.

• models.providers.*.api: request adapter (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc). For self-hosted /v1/chat/completions backends such as MLX, vLLM, SGLang, and most OpenAI-compatible local servers, use openai-completions. A custom provider with baseUrl but no api defaults to openai-completions; set openai-responses only when the backend supports /v1/responses.
• models.providers.*.apiKey: provider credential (prefer SecretRef/env substitution).
• models.providers.*.auth: auth strategy (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: default native context window for models under this provider when the model entry does not set contextWindow.
• models.providers.*.contextTokens: default effective runtime context cap for models under this provider when the model entry does not set contextTokens.
• models.providers.*.maxTokens: default output-token cap for models under this provider when the model entry does not set maxTokens.
• models.providers.*.timeoutSeconds: optional per-provider model HTTP request timeout in seconds, including connect, headers, body, and total request abort handling.
• models.providers.*.injectNumCtxForOpenAICompat: for Ollama + openai-completions, inject options.num_ctx into requests (default: true).
• models.providers.*.authHeader: force credential transport in the Authorization header when required.
• models.providers.*.baseUrl: upstream API base URL.
• models.providers.*.headers: extra static headers for proxy/tenant routing.

models.providers.*.request: transport overrides for model-provider HTTP requests.

• request.headers: extra headers (merged with provider defaults). Values accept SecretRef.
• request.auth: auth strategy override. Modes: "provider-default" (use provider's built-in auth), "authorization-bearer" (with token), "header" (with headerName, value, optional prefix).
• request.proxy: HTTP proxy override. Modes: "env-proxy" (use HTTP_PROXY/HTTPS_PROXY env vars), "explicit-proxy" (with url). Both modes accept an optional tls sub-object.
• request.tls: TLS override for direct connections. Fields: ca, cert, key, passphrase (all accept SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: when true, allow model-provider HTTP requests to private, CGNAT, or similar ranges through the provider HTTP fetch guard. Custom/local provider base URLs already trust the exact configured origin, except metadata/link-local origins, which remain blocked without explicit opt-in. Set this to false to opt out of exact-origin trust. WebSocket uses the same request for headers/TLS but not that fetch SSRF gate. Default false.

• models.providers.*.models: explicit provider model catalog entries.
• models.providers.*.models.*.input: model input modalities. Use ["text"] for text-only models and ["text", "image"] for native image/vision models. Image attachments are only injected into agent turns when the selected model is marked image-capable.
• models.providers.*.models.*.contextWindow: native model context window metadata. This overrides provider-level contextWindow for that model.
• models.providers.*.models.*.contextTokens: optional runtime context cap. This overrides provider-level contextTokens; use it when you want a smaller effective context budget than the model's native contextWindow; openclaw models list shows both values when they differ.
• models.providers.*.models.*.compat.supportsDeveloperRole: optional compatibility hint. For api: "openai-completions" with a non-empty non-native baseUrl (host not api.openai.com), OpenClaw forces this to false at runtime. Empty/omitted baseUrl keeps default OpenAI behavior.
• models.providers.*.models.*.compat.requiresStringContent: optional compatibility hint for string-only OpenAI-compatible chat endpoints. When true, OpenClaw flattens pure text messages[].content arrays into plain strings before sending the request.
• models.providers.*.models.*.compat.strictMessageKeys: optional compatibility hint for strict OpenAI-compatible chat endpoints. When true, OpenClaw strips outgoing Chat Completions message objects to role and content before sending the request.
• models.providers.*.models.*.compat.thinkingFormat: optional thinking payload hint. Use "together" for Together-style reasoning.enabled, "qwen" for top-level enable_thinking, or "qwen-chat-template" for chat_template_kwargs.enable_thinking on Qwen-family OpenAI-compatible servers that support request-level chat-template kwargs, such as vLLM. Configured vLLM Qwen models expose binary /think choices (off, on) for these formats.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: optional compatibility hint for DeepSeek-style Chat Completions backends that require prior assistant messages to keep reasoning_content on replay. When true, OpenClaw preserves that field on outgoing assistant messages. Use this when wiring a custom DeepSeek-compatible proxy that rejects requests after stripped reasoning. Default false.

• plugins.entries.amazon-bedrock.config.discovery: Bedrock auto-discovery settings root.
• plugins.entries.amazon-bedrock.config.discovery.enabled: turn implicit discovery on/off.
• plugins.entries.amazon-bedrock.config.discovery.region: AWS region for discovery.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: optional provider-id filter for targeted discovery.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: polling interval for discovery refresh.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: fallback context window for discovered models.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: fallback max output tokens for discovered models.

The bundled cerebras provider plugin can configure this via openclaw onboard --auth-choice cerebras-api-key. Use explicit provider config only when overriding defaults.

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Use cerebras/zai-glm-4.7 for Cerebras; zai/glm-4.7 for Z.AI direct.

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

Anthropic-compatible, built-in provider. Shortcut: openclaw onboard --auth-choice kimi-code-api-key.

See Local Models. TL;DR: run a large local model via LM Studio Responses API on serious hardware; keep hosted models merged for fallback.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

Set MINIMAX_API_KEY. Shortcuts: openclaw onboard --auth-choice minimax-global-api or openclaw onboard --auth-choice minimax-cn-api. The model catalog defaults to M3 and also includes the M2.7 variants. On the Anthropic-compatible streaming path, OpenClaw disables MiniMax M2.x thinking by default unless you explicitly set thinking yourself; MiniMax-M3 (and M3.x) stays on the provider's omitted/adaptive thinking path by default. /fast on or params.fastMode: true rewrites MiniMax-M2.7 to MiniMax-M2.7-highspeed.

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },    },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [          {            id: "kimi-k2.6",            name: "Kimi K2.6",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

For the China endpoint: baseUrl: "https://api.moonshot.cn/v1" or openclaw onboard --auth-choice moonshot-api-key-cn.

Native Moonshot endpoints advertise streaming usage compatibility on the shared openai-completions transport, and OpenClaw keys that off endpoint capabilities rather than the built-in provider id alone.

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

Set OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY). Use opencode/... refs for the Zen catalog or opencode-go/... refs for the Go catalog. Shortcut: openclaw onboard --auth-choice opencode-zen or openclaw onboard --auth-choice opencode-go.

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M2.5",            name: "MiniMax M2.5",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

Base URL should omit /v1 (Anthropic client appends it). Shortcut: openclaw onboard --auth-choice synthetic-api-key.

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

Set ZAI_API_KEY. Model refs use the canonical zai/* provider ID. Shortcut: openclaw onboard --auth-choice zai-api-key.

• General endpoint: https://api.z.ai/api/paas/v4
• Coding endpoint (default): https://api.z.ai/api/coding/paas/v4
• For the general endpoint, define a custom provider with the base URL override.