Configuratie — tools en aangepaste providers

Providervermelding (type: "provider" of weggelaten):

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

CLI-vermelding (type: "cli"):

• command: uit te voeren programma
• args: argumentsjablonen (ondersteunt {{MediaPath}}, {{Prompt}}, {{MaxChars}}, enzovoort; openclaw doctor --fix migreert verouderde tijdelijke aanduidingen {input} naar {{MediaPath}})

Gemeenschappelijke velden:

• capabilities: optionele lijst (image, audio, video). Elke provider-Plugin declareert zijn eigen standaardset van capaciteiten; de meegeleverde provider openai gebruikt bijvoorbeeld standaard afbeelding+audio, anthropic/minimax afbeelding, google afbeelding+audio+video en groq audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: overschrijvingen per vermelding.
• tools.media.image.timeoutSeconds en overeenkomende vermeldingen voor het afbeeldingsmodel met timeoutSeconds zijn ook van toepassing wanneer de agent de expliciete tool image aanroept. Voor het interpreteren van afbeeldingen geldt deze time-out voor de aanvraag zelf en wordt deze niet verkort door eerder voorbereidingswerk.
• Bij fouten wordt teruggevallen op de volgende vermelding.

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

Velden voor asynchrone voltooiing:

• asyncCompletion.directSend: verouderde compatibiliteitsvlag. Voltooide asynchrone mediataken blijven via de sessie van de aanvrager verlopen, zodat de agent het resultaat ontvangt, bepaalt hoe dit aan de gebruiker wordt gemeld en de berichtentool gebruikt wanneer levering via de bron dit vereist.

• self: alleen de huidige sessiesleutel.
• tree: de huidige sessie plus sessies die door de huidige sessie zijn gestart (subagents).
• agent: elke sessie die bij de huidige agent-id hoort (kan andere gebruikers omvatten als u sessies per afzender uitvoert onder dezelfde agent-id).
• all: elke sessie. Voor het richten op andere agents is nog steeds tools.agentToAgent vereist.
• Sandboxbegrenzing: wanneer de huidige sessie in een sandbox wordt uitgevoerd en agents.defaults.sandbox.sessionToolsVisibility="spawned" (de standaardwaarde), wordt de zichtbaarheid gedwongen ingesteld op tree, zelfs als tools.sessions.visibility="all".
• Wanneer de waarde niet all is, bevat sessions_list een compact veld visibility dat de effectieve modus beschrijft en waarschuwt dat sommige sessies buiten het huidige bereik mogelijk zijn weggelaten.

• Voor bijlagen is enabled: true vereist.
• Bijlagen van subagents worden in de onderliggende werkruimte aangemaakt in .openclaw/attachments/<uuid>/, met een .manifest.json.
• ACP-bijlagen mogen alleen afbeeldingen bevatten en worden inline doorgestuurd naar de ACP-runtime nadat aan dezelfde limieten voor het aantal bestanden, het aantal bytes per bestand en het totale aantal bytes is voldaan.
• De inhoud van bijlagen 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 opruimen van subagentbijlagen volgt het beleid cleanup: delete verwijdert bijlagen altijd; keep behoudt ze alleen wanneer retainOnSessionKeep: true.

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

• models.mode: gedrag van de providercatalogus (merge of replace).
• models.providers: aangepaste providertoewijzing, 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 aanvullende updates. config set weigert destructieve vervangingen tenzij u --replace doorgeeft.

• models.providers.*.api: aanvraagadapter (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 lokale OpenAI-compatibele 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 ingebouwd contextvenster voor modellen onder deze provider wanneer het modelitem geen contextWindow instelt.
• models.providers.*.contextTokens: standaard effectieve runtimecontextlimiet voor modellen onder deze provider wanneer het modelitem geen contextTokens instelt.
• models.providers.*.maxTokens: standaardlimiet voor uitvoertokens voor modellen onder deze provider wanneer het modelitem geen maxTokens instelt.
• models.providers.*.timeoutSeconds: optionele time-out per provider voor HTTP-modelaanvragen in seconden, inclusief verbinding, headers, hoofdtekst en verwerking voor het afbreken van de volledige aanvraag.
• models.providers.*.injectNumCtxForOpenAICompat: voeg voor Ollama + openai-completions options.num_ctx toe aan aanvragen (standaard: true).
• models.providers.*.authHeader: dwing indien vereist het verzenden van referenties in de Authorization-header af.
• models.providers.*.baseUrl: basis-URL van de bovenliggende API.
• models.providers.*.headers: aanvullende statische headers voor proxy-/tenantroutering.

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

• request.headers: aanvullende headers (samengevoegd met de standaardwaarden van de provider). Waarden ondersteunen 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 ondersteunen een optioneel tls-subobject.
• request.tls: TLS-overschrijving voor rechtstreekse verbindingen. Velden: ca, cert, key, passphrase (ondersteunen allemaal SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: sta bij true toe dat HTTP-aanvragen aan modelproviders via de HTTP-ophaalbeveiliging van de provider naar privé-, CGNAT- of vergelijkbare bereiken gaan. Aangepaste/lokale basis-URL's van providers vertrouwen de exact geconfigureerde oorsprong al, behalve metadata-/link-local-oorsprongen, die zonder expliciete aanmelding geblokkeerd blijven. Stel dit in op false om het vertrouwen van de exacte oorsprong uit te schakelen. WebSocket gebruikt dezelfde request voor headers/TLS, maar niet die SSRF-beveiliging voor ophalen. Standaard false.

• models.providers.*.models: expliciete modelcatalogusitems van de provider.
• models.providers.*.models.*.input: modelinvoermodaliteiten. Gebruik ["text"] voor modellen die alleen tekst ondersteunen en ["text", "image"] voor modellen met ingebouwde ondersteuning voor afbeeldingen/visuele invoer. Afbeeldingsbijlagen worden alleen aan agentbeurten toegevoegd wanneer het geselecteerde model als afbeeldingsgeschikt is gemarkeerd.
• models.providers.*.models.*.contextWindow: metagegevens van het ingebouwde 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 u een kleiner effectief contextbudget wilt dan de ingebouwde contextWindow van het model; openclaw models list toont beide waarden wanneer ze verschillen.
• models.providers.*.models.*.compat.supportsDeveloperRole: optionele compatibiliteitsaanwijzing. Voor api: "openai-completions" met een niet-lege, niet-ingebouwde baseUrl (host is niet api.openai.com) dwingt OpenClaw dit tijdens runtime af op false. Een lege/weggelaten baseUrl behoudt het standaardgedrag van OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: optionele compatibiliteitsaanwijzing voor OpenAI-compatibele chateindpunten die alleen tekenreeksen ondersteunen. Wanneer dit true is, zet OpenClaw messages[].content-arrays die uitsluitend tekst bevatten om in gewone tekenreeksen voordat de aanvraag wordt verzonden.
• models.providers.*.models.*.compat.strictMessageKeys: optionele compatibiliteitsaanwijzing voor strikte OpenAI-compatibele chateindpunten. Wanneer dit true is, beperkt OpenClaw uitgaande Chat Completions-berichtobjecten tot role en content voordat de aanvraag wordt verzonden.
• models.providers.*.models.*.compat.thinkingFormat: optionele aanwijzing voor de payload van het denkproces. Gebruik "together" voor reasoning.enabled in Together-stijl, "qwen" voor enable_thinking op hoofdniveau of "qwen-chat-template" voor chat_template_kwargs.enable_thinking op OpenAI-compatibele servers uit de Qwen-familie die chat-sjabloonargumenten op aanvraagniveau ondersteunen, zoals vLLM. Geconfigureerde vLLM Qwen-modellen bieden voor deze indelingen binaire /think-keuzes (off, on).
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: optionele compatibiliteitsaanwijzing voor Chat Completions-backends in DeepSeek-stijl die vereisen dat eerdere assistentberichten bij opnieuw afspelen reasoning_content behouden. Wanneer dit true is, behoudt OpenClaw dat veld in uitgaande assistentberichten. Gebruik dit bij het aansluiten van een aangepaste DeepSeek-compatibele proxy die aanvragen weigert nadat de redenering is verwijderd. Standaard false.

• plugins.entries.amazon-bedrock.config.discovery: hoofdinstelling 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: peilinterval voor het vernieuwen van detectie.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: terugvalcontextvenster voor gedetecteerde modellen.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: maximaal aantal uitvoertokens bij terugval voor gedetecteerde modellen.

De officiële externe cerebras-provider-Plugin kan dit configureren via openclaw onboard --auth-choice cerebras-api-key. Gebruik alleen een expliciete providerconfiguratie wanneer u 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 een rechtstreekse verbinding met Z.AI.

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

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

Zie Lokale modellen. Kort gezegd: voer via de LM Studio Responses API een groot lokaal model uit op krachtige hardware; 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 Anthropic-compatibele streamingpad schakelt OpenClaw het denkproces van MiniMax M2.x standaard uit, tenzij je thinking zelf expliciet instelt; MiniMax-M3 (en M3.x) blijft standaard op het weggelaten/adaptieve denkpad van de provider. /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.

Native Moonshot-eindpunten geven aan dat ze compatibel zijn met streamingverbruiksgegevens via het gedeelde openai-completions-transport. OpenClaw baseert dit op de mogelijkheden van het eindpunt en niet 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-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,          },        ],      },    },  },}

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
• Programmeereindpunt: 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 detectie geen uitsluitsel geeft, wordt teruggevallen op een vraag met Global als standaardwaarde). Er zijn ook afzonderlijke authenticatiekeuzes voor CN en Coding-Plan beschikbaar voor expliciete selectie.
• Definieer voor het algemene eindpunt een aangepaste provider met een overschrijving van de basis-URL.