Configuratie — tools en aangepaste providers

Providervermelding (type: "provider" of weggelaten):

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

CLI-vermelding (type: "cli"):

• command: uit te voeren programma
• args: argumenten met sjablonen (ondersteunt {{AttachmentPath}}, {{AttachmentUrl}}, {{AttachmentContentType}}, {{AttachmentDir}}, {{AttachmentIndex}}, {{Prompt}}, {{MaxChars}}, enz.; openclaw doctor --fix migreert verouderde {input}-plaatsaanduidingen naar {{AttachmentPath}}). De oudere aliassen {{MediaPath}}, {{MediaUrl}}, {{MediaType}} en {{MediaDir}} blijven tijdens hun compatibiliteitsperiode beschikbaar, maar zijn verouderd.

Gemeenschappelijke velden:

• capabilities: lijst met een of meer van image, audio en video.
• prompt, maxChars, maxBytes, timeoutSeconds, language: overschrijvingen per vermelding.
• Overeenkomende timeoutSeconds-vermeldingen voor afbeeldingsmodellen zijn ook van toepassing wanneer de agent de expliciete image-tool aanroept. Voor het begrijpen van afbeeldingen geldt deze time-out voor de aanvraag zelf en wordt deze niet verminderd door eerder voorbereidingswerk.
• Bij fouten wordt teruggevallen op de volgende vermelding.

Providerverificatie volgt de standaardvolgorde: auth-profiles.json → omgevingsvariabelen → models.providers.*.apiKey.

• self: uitsluitend de sleutel van de huidige sessie.
• tree: huidige sessie + sessies die door de huidige sessie zijn gestart (subagents). Voor leesbewerkingen omvat dit ook groepssessies van dezelfde agent die de huidige sessie volgt via groepsbewustzijn op de achtergrond.
• 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. Voor doelen bij andere agents is nog steeds tools.agentToAgent vereist.
• Sandboxbegrenzing: wanneer de huidige sessie in een sandbox draait en agents.defaults.sandbox.sessionToolsVisibility="spawned" (de standaardwaarde) is ingesteld, wordt de zichtbaarheid gedwongen op tree, zelfs als tools.sessions.visibility="all".
• Wanneer dit niet all is, bevat sessions_list een compact visibility-veld dat de effectieve modus beschrijft en waarschuwt dat sommige sessies buiten het huidige bereik mogelijk worden weggelaten.

• Voor bijlagen is enabled: true vereist.
• Bijlagen van subagents worden in de onderliggende werkruimte opgeslagen op .openclaw/attachments/<uuid>/ met een .manifest.json.
• ACP-bijlagen zijn uitsluitend afbeeldingen en worden inline doorgestuurd naar de ACP-runtime nadat dezelfde limieten voor het aantal bestanden, het aantal bytes per bestand en het totale aantal bytes zijn doorstaan.
• Bijlage-inhoud wordt automatisch geredigeerd bij het permanent opslaan van transcripten.
• Base64-invoer wordt gevalideerd met strikte controles op alfabet en opvulling, plus een groottecontrole vóór het decoderen.
• Bestandsmachtigingen voor bijlagen van subagents zijn 0700 voor mappen en 0600 voor bestanden.
• Het opschonen van subagents volgt het cleanup-beleid: delete verwijdert bijlagen altijd; keep behoudt ze uitsluitend wanneer retainOnSessionKeep: true.

• Gebruik authHeader: true + headers voor aangepaste authenticatiebehoeften.
• Overschrijf de hoofdmap van de agentconfiguratie met OPENCLAW_AGENT_DIR.
• Samenvoegingsprioriteit voor overeenkomende provider-id's:
  • Niet-lege models.json-baseUrl-waarden van de agent hebben voorrang.
  • Niet-lege apiKey-waarden van de agent hebben alleen voorrang wanneer die provider in de huidige configuratie-/authenticatieprofielcontext niet door SecretRef wordt beheerd.
  • Door SecretRef beheerde apiKey-waarden van de provider worden vernieuwd vanuit bronmarkeringen (ENV_VAR_NAME voor omgevingsverwijzingen, secretref-managed voor bestands-/uitvoeringsverwijzingen) in plaats van opgeloste geheimen permanent op te slaan.
  • Door SecretRef beheerde headerwaarden van de provider worden vernieuwd vanuit bronmarkeringen (secretref-env:ENV_VAR_NAME voor omgevingsverwijzingen, secretref-managed voor bestands-/uitvoeringsverwijzingen).
  • Lege of ontbrekende apiKey/baseUrl van de agent vallen terug op models.providers in de configuratie.
  • Voor overeenkomende model-contextWindow/maxTokens heeft de expliciete configuratiewaarde voorrang wanneer deze aanwezig en geldig is (een positief eindig getal); anders wordt de impliciete/gegenereerde cataloguswaarde gebruikt.
  • Overeenkomende model-contextTokens volgt dezelfde regel waarbij expliciet voorrang heeft en anders impliciet wordt gebruikt; gebruik dit om de effectieve context te beperken zonder de oorspronkelijke modelmetadata te wijzigen.
  • Catalogi van providerplugins worden als gegenereerde, door de Plugin beheerde catalogusfragmenten opgeslagen onder de Pluginstatus van de agent.
  • Gebruik models.mode: "replace" wanneer de configuratie models.json volledig moet herschrijven en het samenvoegen van door de Plugin beheerde catalogusfragmenten moet overslaan.
  • Het permanent opslaan van markeringen is bronauthoritatief: markeringen worden geschreven vanuit de actieve momentopname van de bronconfiguratie (vóór oplossing), niet vanuit opgeloste geheime runtimewaarden.

• models.mode: gedrag van de providercatalogus (merge of replace).
• models.providers: kaart met aangepaste providers, geïndexeerd op provider-id.
  • 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: verzoekadapter (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). 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-/omgevingssubstitutie).
• models.providers.*.auth: authenticatiestrategie (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: standaard oorspronkelijke 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 time-out per provider voor HTTP-modelverzoeken in seconden, inclusief verbinding, headers, hoofdtekst en afhandeling van het afbreken van het volledige verzoek.
• models.providers.*.injectNumCtxForOpenAICompat: injecteer voor Ollama + openai-completions options.num_ctx in verzoeken (standaard: true).
• models.providers.*.authHeader: dwing indien vereist het transport van referenties af in de Authorization-header.
• models.providers.*.baseUrl: basis-URL van de upstream-API.
• models.providers.*.headers: extra statische headers voor proxy-/tenantroutering.

models.providers.*.request: transportoverschrijvingen voor HTTP-verzoeken aan modelproviders.

• request.headers: extra headers (samengevoegd met de standaardwaarden van de provider). Waarden accepteren SecretRef.
• request.auth: overschrijving van de authenticatiestrategie. Modi: "provider-default" (gebruik de ingebouwde authenticatie van de provider), "authorization-bearer" (met token), "header" (met headerName, value, optioneel prefix).
• request.proxy: overschrijving van de HTTP-proxy. Modi: "env-proxy" (gebruik de omgevingsvariabelen HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (met url). Beide modi accepteren een optioneel tls-subobject.
• request.tls: TLS-overschrijving voor directe verbindingen. Velden: ca, cert, key, passphrase (alle accepteren SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: sta wanneer true HTTP-verzoeken van modelproviders naar privé-, CGNAT- of vergelijkbare bereiken toe via de HTTP-fetchbeveiliging van de provider. Basis-URL's van aangepaste/lokale providers vertrouwen de exact geconfigureerde oorsprong al, met uitzondering van metadata-/link-local-oorsprongen, die zonder expliciete opt-in geblokkeerd blijven. Stel dit in op false om exact-oorsprongvertrouwen uit te schakelen. WebSocket gebruikt dezelfde request voor headers/TLS, maar niet die SSRF-fetchpoort. Standaard false.

• models.providers.*.models: expliciete vermeldingen in de providermodelcatalogus.
• models.providers.*.models.*.input: modelinvoermodaliteiten. Gebruik ["text"] voor modellen die alleen tekst ondersteunen en ["text", "image"] voor modellen met ingebouwde beeld-/zichtondersteuning. Afbeeldingsbijlagen worden alleen in agentbeurten ingevoegd wanneer het geselecteerde model als beeldgeschikt is gemarkeerd.
• models.providers.*.models.*.contextWindow: metadata van het oorspronkelijke 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 de oorspronkelijke contextWindow van het model; openclaw models list toont beide waarden wanneer ze verschillen.

Aangepaste declaraties van providermogelijkheden

Providercatalogi beheren compat voor gebundelde en in de catalogus bekende modelroutes. Kopieer die vlaggen niet naar de configuratie: OpenClaw gebruikt de catalogusrij wanneer de geconfigureerde api en baseUrl die route nog steeds identificeren. openclaw doctor --fix verwijdert overeenkomende verouderde overschrijvingen en meldt afwijkende waarden ter beoordeling.

Een compat-blok blijft ondersteund voor een werkelijk aangepaste provider, een aangepast model of een catalogusmodel dat naar een ander eindpunt wordt gerouteerd. Stel alleen mogelijkheden in die voor dat eindpunt zijn geverifieerd:

• plugins.entries.amazon-bedrock.config.discovery: hoofdinstelling voor automatische Bedrock-detectie.
• plugins.entries.amazon-bedrock.config.discovery.enabled: impliciete detectie in-/uitschakelen.
• 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 het vernieuwen van de detectie.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: standaardcontextvenster voor gedetecteerde modellen.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: standaardmaximumaantal uitvoertokens voor gedetecteerde modellen.

De officiële externe provider-Plugin cerebras kan dit configureren via openclaw onboard --auth-choice cerebras-api-key. Gebruik alleen een expliciete providerconfiguratie om de standaardwaarden te overschrijven.

{  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 rechtstreeks gebruik van Z.AI.

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

Ingebouwde provider die compatibel is met Anthropic. Snelkoppeling: openclaw onboard --auth-choice kimi-code-api-key.

Zie Lokale modellen. Kort gezegd: voer op krachtige hardware een groot lokaal model uit via de LM Studio Responses API; behoud samengevoegde gehoste modellen als terugvaloptie.

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

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 M3 en bevat ook de M2.7-varianten. Op het streamingpad dat compatibel is met Anthropic schakelt OpenClaw het denkproces van MiniMax M2.x standaard uit, tenzij je zelf expliciet thinking instelt; MiniMax-M3 (en M3.x) blijft standaard het pad voor weggelaten/adaptief denken van de provider gebruiken. /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 Chinese eindpunt: baseUrl: "https://api.moonshot.cn/v1" of openclaw onboard --auth-choice moonshot-api-key-cn.

Eigen Moonshot-eindpunten geven aan dat ze compatibel zijn met streamingverbruik via het gedeelde transport openai-completions, en OpenClaw baseert dit op de mogelijkheden van het eindpunt in plaats van uitsluitend 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/...-verwijzingen voor de Zen-catalogus of opencode-go/...-verwijzingen 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-M3" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M3": { alias: "MiniMax M3" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 65536,          },        ],      },    },  },}

De 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. Modelverwijzingen gebruiken de canonieke provider-id zai/*. Snelkoppeling: openclaw onboard --auth-choice zai-api-key.

• Algemeen eindpunt: https://api.z.ai/api/paas/v4
• Eindpunt voor programmeren: https://api.z.ai/api/coding/paas/v4
• De standaardauthenticatiekeuze zai-api-key test je sleutel en detecteert automatisch bij welk eindpunt deze hoort (als de detectie geen uitsluitsel geeft, wordt teruggevallen op een vraag met Global als standaardwaarde). Voor expliciete selectie zijn ook afzonderlijke authenticatiekeuzes voor CN en Coding-Plan beschikbaar.
• Definieer voor het algemene eindpunt een aangepaste provider met een overschrijving van de basis-URL.