Configuratie — hulpmiddelen en aangepaste providers

Providervermelding (type: "provider" of weggelaten):

• provider: API-provider-id (openai, anthropic, google/gemini, groq, enz.)
• model: model-id-overschrijving
• profile / preferredProfile: profielselectie voor auth-profiles.json

CLI-vermelding (type: "cli"):

• command: uitvoerbaar bestand om uit te voeren
• args: getemplate argumenten (ondersteunt {{MediaPath}}, {{Prompt}}, {{MaxChars}}, enz.; openclaw doctor --fix migreert verouderde {input}-placeholders naar {{MediaPath}})

Algemene velden:

• capabilities: optionele lijst (image, audio, video). Standaardwaarden: openai/anthropic/minimax → afbeelding, google → afbeelding+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: overschrijvingen per vermelding.
• tools.media.image.timeoutSeconds en overeenkomende timeoutSeconds-vermeldingen voor afbeeldingsmodellen zijn ook van toepassing wanneer de agent de expliciete image-tool aanroept.
• Fouten vallen terug op de volgende vermelding.

Provider-authenticatie volgt de standaardvolgorde: auth-profiles.json → env-vars → models.providers.*.apiKey.

Velden voor asynchrone voltooiing:

• asyncCompletion.directSend: verouderde compatibiliteitsvlag. Voltooide asynchrone mediataken blijven bemiddeld via de requester-sessie, zodat de agent het resultaat ontvangt, beslist hoe de gebruiker wordt geïnformeerd en de berichttool gebruikt wanneer bronlevering dit vereist.

• self: alleen de huidige sessiesleutel.
• tree: huidige sessie + sessies die door de huidige sessie zijn gestart (subagents).
• agent: elke sessie die bij de huidige agent-id hoort (kan andere gebruikers omvatten als je sessies per afzender onder dezelfde agent-id uitvoert).
• all: elke sessie. Cross-agent-targeting vereist nog steeds tools.agentToAgent.
• Sandbox-beperking: wanneer de huidige sessie in een sandbox draait en agents.defaults.sandbox.sessionToolsVisibility="spawned", wordt zichtbaarheid geforceerd naar tree, zelfs als tools.sessions.visibility="all".

• Bijlagen worden alleen ondersteund voor runtime: "subagent". ACP runtime weigert ze.
• Bestanden worden gematerialiseerd in de onderliggende werkruimte op .openclaw/attachments/<uuid>/ met een .manifest.json.
• Bijlage-inhoud wordt automatisch geredigeerd uit transcriptpersistentie.
• Base64-invoer wordt gevalideerd met strikte controles op alfabet/opvulling en een groottecontrole vóór decodering.
• Bestandsrechten zijn 0700 voor mappen en 0600 voor bestanden.
• Opschonen volgt het cleanup-beleid: delete verwijdert bijlagen altijd; keep bewaart ze alleen wanneer retainOnSessionKeep: true.

• Gebruik authHeader: true + headers voor aangepaste auth-behoeften.
• Override de agentconfiguratieroot met OPENCLAW_AGENT_DIR (of PI_CODING_AGENT_DIR, een alias voor een verouderde omgevingsvariabele).
• Samenvoegingsprioriteit voor overeenkomende provider-ID's:
  • Niet-lege agentwaarden voor models.json baseUrl winnen.
  • Niet-lege agentwaarden voor apiKey winnen alleen wanneer die provider niet door SecretRef wordt beheerd in de huidige configuratie-/auth-profielcontext.
  • Door SecretRef beheerde providerwaarden voor apiKey worden vernieuwd vanuit bronmarkers (ENV_VAR_NAME voor env-verwijzingen, secretref-managed voor bestands-/exec-verwijzingen) in plaats van opgeloste geheimen persistent op te slaan.
  • Door SecretRef beheerde providerheaderwaarden worden vernieuwd vanuit bronmarkers (secretref-env:ENV_VAR_NAME voor env-verwijzingen, secretref-managed voor bestands-/exec-verwijzingen).
  • Lege of ontbrekende agentwaarden voor apiKey/baseUrl vallen terug op models.providers in de configuratie.
  • Overeenkomende modelwaarden voor contextWindow/maxTokens gebruiken de hogere waarde van expliciete configuratie en impliciete cataloguswaarden.
  • Overeenkomende modelwaarden voor contextTokens behouden een expliciete runtimelimiet wanneer aanwezig; gebruik dit om de effectieve context te beperken zonder native modelmetadata te wijzigen.
  • Gebruik models.mode: "replace" wanneer je wilt dat de configuratie models.json volledig herschrijft.
  • Markerpersistentie is bronauthoritatief: markers worden geschreven vanuit de actieve bronconfiguratiesnapshot (vóór oplossing), niet vanuit opgeloste runtimegeheimwaarden.

• models.mode: gedrag van de providercatalogus (merge of replace).
• models.providers: aangepaste providermap met provider-id als sleutel.
  • Veilige bewerkingen: gebruik openclaw config set models.providers.<id> '<json>' --strict-json --merge of openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge voor additieve updates. config set weigert destructieve vervangingen tenzij je --replace doorgeeft.

• models.providers.*.api: requestadapter (openai-completions, openai-responses, anthropic-messages, google-generative-ai, enz.). Gebruik voor zelfgehoste /v1/chat/completions-backends zoals MLX, vLLM, SGLang en de meeste OpenAI-compatibele lokale servers openai-completions. Een aangepaste provider met baseUrl maar zonder api gebruikt standaard openai-completions; stel openai-responses alleen in wanneer de backend /v1/responses ondersteunt.
• models.providers.*.apiKey: providerreferentie (geef de voorkeur aan SecretRef-/env-substitutie).
• models.providers.*.auth: auth-strategie (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: standaard native contextvenster voor modellen onder deze provider wanneer de modelvermelding contextWindow niet instelt.
• models.providers.*.contextTokens: standaard effectieve runtimecontextlimiet voor modellen onder deze provider wanneer de modelvermelding contextTokens niet instelt.
• models.providers.*.maxTokens: standaardlimiet voor uitvoertokens voor modellen onder deze provider wanneer de modelvermelding maxTokens niet instelt.
• models.providers.*.timeoutSeconds: optionele HTTP-requesttimeout per provider voor modellen in seconden, inclusief afhandeling van verbinding, headers, body en totale requestafbreking.
• models.providers.*.injectNumCtxForOpenAICompat: injecteer voor Ollama + openai-completions options.num_ctx in requests (standaard: true).
• models.providers.*.authHeader: forceer transport van referenties in de Authorization-header wanneer vereist.
• models.providers.*.baseUrl: basis-URL van de upstream-API.
• models.providers.*.headers: extra statische headers voor proxy-/tenantroutering.

models.providers.*.request: transportoverrides voor HTTP-requests van modelproviders.

• request.headers: extra headers (samengevoegd met providerstandaarden). Waarden accepteren SecretRef.
• request.auth: override voor auth-strategie. Modi: "provider-default" (gebruik de ingebouwde auth van de provider), "authorization-bearer" (met token), "header" (met headerName, value, optioneel prefix).
• request.proxy: HTTP-proxy-override. Modi: "env-proxy" (gebruik de env-vars HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (met url). Beide modi accepteren een optioneel tls-subobject.
• request.tls: TLS-override voor directe verbindingen. Velden: ca, cert, key, passphrase (allemaal accepteren SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: sta, wanneer true, HTTPS naar baseUrl toe wanneer DNS wordt opgelost naar private, CGNAT- of vergelijkbare bereiken, via de HTTP-fetchguard van de provider (operator-opt-in voor vertrouwde zelfgehoste OpenAI-compatibele endpoints). Stream-URL's van modelproviders via local loopback, zoals localhost, 127.0.0.1 en [::1], worden automatisch toegestaan tenzij dit expliciet op false is ingesteld; LAN-, tailnet- en private DNS-hosts vereisen nog steeds opt-in. WebSocket gebruikt dezelfde request voor headers/TLS, maar niet die fetch-SSRF-gate. Standaard false.

• models.providers.*.models: expliciete modelcatalogusvermeldingen van de provider.
• models.providers.*.models.*.input: invoermodaliteiten van het model. Gebruik ["text"] voor modellen met alleen tekst en ["text", "image"] voor native image-/vision-modellen. Afbeeldingsbijlagen worden alleen in agentbeurten geïnjecteerd wanneer het geselecteerde model als image-capable is gemarkeerd.
• models.providers.*.models.*.contextWindow: native metadata voor het contextvenster van het model. Dit overschrijft contextWindow op providerniveau voor dat model.
• models.providers.*.models.*.contextTokens: optionele runtimecontextlimiet. Dit overschrijft contextTokens op providerniveau; gebruik dit wanneer je een kleiner effectief contextbudget wilt dan het native contextWindow van het model; openclaw models list toont beide waarden wanneer ze verschillen.
• models.providers.*.models.*.compat.supportsDeveloperRole: optionele compatibiliteitshint. Voor api: "openai-completions" met een niet-lege niet-native baseUrl (host niet api.openai.com) forceert OpenClaw dit tijdens runtime naar false. Een lege/weggelaten baseUrl behoudt het standaardgedrag van OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: optionele compatibiliteitshint voor OpenAI-compatibele chatendpoints met alleen strings. Wanneer true, maakt OpenClaw pure tekst-messages[].content-arrays plat naar gewone strings voordat het request wordt verzonden.

• plugins.entries.amazon-bedrock.config.discovery: root voor instellingen voor automatische Bedrock-detectie.
• plugins.entries.amazon-bedrock.config.discovery.enabled: schakel impliciete detectie in/uit.
• plugins.entries.amazon-bedrock.config.discovery.region: AWS-regio voor detectie.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: optioneel provider-id-filter voor gerichte detectie.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: pollinginterval voor detectievernieuwing.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: fallback-contextvenster voor gedetecteerde modellen.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: fallback voor maximaal aantal uitvoertokens voor gedetecteerde modellen.

De gebundelde provider-Plugin cerebras kan dit configureren via openclaw onboard --auth-choice cerebras-api-key. Gebruik expliciete providerconfiguratie alleen wanneer je standaardwaarden overschrijft.

{
  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)" },
        ],
      },
    },
  },
}

Gebruik cerebras/zai-glm-4.7 voor Cerebras; zai/glm-4.7 voor directe Z.AI.

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

Anthropic-compatibele, ingebouwde provider. Snelkoppeling: openclaw onboard --auth-choice kimi-code-api-key.

Zie Lokale modellen. TL;DR: voer een groot lokaal model uit via de LM Studio Responses API op krachtige hardware; houd gehoste modellen samengevoegd als fallback.

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

Stel MINIMAX_API_KEY in. Snelkoppelingen: openclaw onboard --auth-choice minimax-global-api of openclaw onboard --auth-choice minimax-cn-api. De modelcatalogus gebruikt standaard alleen M2.7. Op het Anthropic-compatibele streamingpad schakelt OpenClaw MiniMax-denken standaard uit, tenzij je thinking expliciet zelf instelt. /fast on of params.fastMode: true herschrijft MiniMax-M2.7 naar 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,
          },
        ],
      },
    },
  },
}

Voor het China-eindpunt: baseUrl: "https://api.moonshot.cn/v1" of openclaw onboard --auth-choice moonshot-api-key-cn.

Native Moonshot-eindpunten adverteren compatibiliteit met streaminggebruik op het gedeelde openai-completions-transport, en OpenClaw baseert dat op eindpuntmogelijkheden in plaats van alleen op de ingebouwde provider-id.

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

Stel OPENCODE_API_KEY (of OPENCODE_ZEN_API_KEY) in. Gebruik opencode/...-refs voor de Zen-catalogus of opencode-go/...-refs voor de Go-catalogus. Snelkoppeling: openclaw onboard --auth-choice opencode-zen of 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,
          },
        ],
      },
    },
  },
}

Basis-URL moet /v1 weglaten (de Anthropic-client voegt dit toe). Snelkoppeling: openclaw onboard --auth-choice synthetic-api-key.

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

Stel ZAI_API_KEY in. z.ai/* en z-ai/* worden geaccepteerd als aliassen. Snelkoppeling: openclaw onboard --auth-choice zai-api-key.

• Algemeen eindpunt: https://api.z.ai/api/paas/v4
• Coding-eindpunt (standaard): https://api.z.ai/api/coding/paas/v4
• Definieer voor het algemene eindpunt een aangepaste provider met de basis-URL-override.