Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Model-failover

Rotatie van auth-profielen, cooldowns, en hoe dat samenwerkt met fallbacks.

Modelproviders

Kort provideroverzicht en voorbeelden.

Agentruntimes

PI, Codex en andere agent-loopruntimes.

Configuratiereferentie

Modelconfiguratiesleutels.
Modelreferenties kiezen een provider en model. Ze kiezen meestal niet de laag-niveau agentruntime. openai/gpt-5.5 kan bijvoorbeeld via het normale OpenAI-providerpad of via de Codex app-serverruntime draaien, afhankelijk van agents.defaults.agentRuntime.id. In Codex-runtimemodus impliceert de openai/gpt-*-referentie geen facturering via API-sleutels; auth kan afkomstig zijn van een Codex-account of openai-codex-auth-profiel. Zie Agentruntimes.

​
Hoe modelselectie werkt

OpenClaw selecteert modellen in deze volgorde:
1

Primair model

agents.defaults.model.primary (of agents.defaults.model).
2

Fallbacks

agents.defaults.model.fallbacks (op volgorde).
3

Provider-auth-failover

Auth-failover gebeurt binnen een provider voordat naar het volgende model wordt gegaan.
  • agents.defaults.models is de allowlist/catalogus van modellen die OpenClaw kan gebruiken (plus aliassen).
  • agents.defaults.imageModel wordt alleen gebruikt wanneer het primaire model geen afbeeldingen kan accepteren.
  • agents.defaults.pdfModel wordt gebruikt door de pdf-tool. Als dit is weggelaten, valt de tool terug op agents.defaults.imageModel, en daarna op het opgeloste sessie-/standaardmodel.
  • agents.defaults.imageGenerationModel wordt gebruikt door de gedeelde mogelijkheid voor afbeeldingsgeneratie. Als dit is weggelaten, kan image_generate nog steeds een auth-ondersteunde providerstandaard afleiden. Het probeert eerst de huidige standaardprovider, en daarna de resterende geregistreerde providers voor afbeeldingsgeneratie op volgorde van provider-id. Als je een specifieke provider/model instelt, configureer dan ook de auth/API-sleutel van die provider.
  • agents.defaults.musicGenerationModel wordt gebruikt door de gedeelde mogelijkheid voor muziekgeneratie. Als dit is weggelaten, kan music_generate nog steeds een auth-ondersteunde providerstandaard afleiden. Het probeert eerst de huidige standaardprovider, en daarna de resterende geregistreerde providers voor muziekgeneratie op volgorde van provider-id. Als je een specifieke provider/model instelt, configureer dan ook de auth/API-sleutel van die provider.
  • agents.defaults.videoGenerationModel wordt gebruikt door de gedeelde mogelijkheid voor videogeneratie. Als dit is weggelaten, kan video_generate nog steeds een auth-ondersteunde providerstandaard afleiden. Het probeert eerst de huidige standaardprovider, en daarna de resterende geregistreerde providers voor videogeneratie op volgorde van provider-id. Als je een specifieke provider/model instelt, configureer dan ook de auth/API-sleutel van die provider.
  • Standaarden per agent kunnen agents.defaults.model overschrijven via agents.list[].model plus bindingen (zie Multi-agentroutering).

​
Selectiebron en fallbackgedrag

Dezelfde provider/model kan verschillende dingen betekenen, afhankelijk van waar deze vandaan kwam:
  • Geconfigureerde standaarden (agents.defaults.model.primary en agentspecifieke primaire modellen) zijn het normale startpunt en gebruiken agents.defaults.model.fallbacks.
  • Automatische fallbackselecties zijn tijdelijke herstelstatus. Ze worden opgeslagen met modelOverrideSource: "auto" zodat latere beurten de fallbackketen kunnen blijven gebruiken zonder eerst een bekende slechte primary te proberen.
  • Gebruikerssessieselecties zijn exact. /model, de modelkiezer, session_status(model=...) en sessions.patch slaan modelOverrideSource: "user" op; als die geselecteerde provider/model niet bereikbaar is, faalt OpenClaw zichtbaar in plaats van door te vallen naar een ander geconfigureerd model.
  • Cron --model / payload model is een primaire instelling per taak. Deze gebruikt nog steeds geconfigureerde fallbacks tenzij de taak expliciete payload-fallbacks opgeeft (gebruik fallbacks: [] voor een strikte cron-run).
  • CLI-standaardmodel- en allowlistkiezers respecteren models.mode: "replace" door expliciete models.providers.*.models te tonen in plaats van de volledige ingebouwde catalogus te laden.
  • De modelkiezer in de Control UI vraagt de Gateway om de geconfigureerde modelweergave: agents.defaults.models wanneer aanwezig, anders expliciete models.providers.*.models plus providers met bruikbare auth. De volledige ingebouwde catalogus is gereserveerd voor expliciete bladerweergaven zoals models.list met view: "all" of openclaw models list --all.

​
Kort modelbeleid

  • Stel je primaire model in op het sterkste beschikbare model van de nieuwste generatie.
  • Gebruik fallbacks voor kosten-/latentiegevoelige taken en chat met lagere inzet.
  • Vermijd oudere/zwakkere modelniveaus voor agents met tools of niet-vertrouwde invoer.

​
Onboarding (aanbevolen)

Als je de configuratie niet handmatig wilt bewerken, voer onboarding uit: 
openclaw onboard
Dit kan model + auth instellen voor veelgebruikte providers, waaronder OpenAI Code (Codex) subscription (OAuth) en Anthropic (API-sleutel of Claude CLI).

​
Configuratiesleutels (overzicht)

  • agents.defaults.model.primary en agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary en agents.defaults.imageModel.fallbacks
  • agents.defaults.pdfModel.primary en agents.defaults.pdfModel.fallbacks
  • agents.defaults.imageGenerationModel.primary en agents.defaults.imageGenerationModel.fallbacks
  • agents.defaults.videoGenerationModel.primary en agents.defaults.videoGenerationModel.fallbacks
  • agents.defaults.models (allowlist + aliassen + providerparameters)
  • models.providers (aangepaste providers geschreven naar models.json)
Modelreferenties worden genormaliseerd naar kleine letters. Provideraliassen zoals z.ai/* normaliseren naar zai/*.Providerconfiguratievoorbeelden (inclusief OpenCode) staan in OpenCode.

​
Veilige allowlist-bewerkingen

Gebruik additieve schrijfacties wanneer je agents.defaults.models handmatig bijwerkt: 
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set beschermt model-/providermaps tegen onbedoeld overschrijven. Een gewone objecttoewijzing aan agents.defaults.models, models.providers of models.providers.<id>.models wordt geweigerd wanneer deze bestaande vermeldingen zou verwijderen. Gebruik --merge voor additieve wijzigingen; gebruik --replace alleen wanneer de opgegeven waarde de volledige doelwaarde moet worden.Interactieve providerinstelling en openclaw configure --section model voegen providergebonden selecties ook samen in de bestaande allowlist, zodat het toevoegen van Codex, Ollama of een andere provider geen niet-gerelateerde modelvermeldingen verwijdert. Configure behoudt een bestaande agents.defaults.model.primary wanneer provider-auth opnieuw wordt toegepast. Expliciete opdrachten voor standaardinstellingen, zoals openclaw models auth login --provider <id> --set-default en openclaw models set <model>, vervangen nog steeds agents.defaults.model.primary.

​
”Model is niet toegestaan” (en waarom antwoorden stoppen)

Als agents.defaults.models is ingesteld, wordt dit de allowlist voor /model en voor sessie-overschrijvingen. Wanneer een gebruiker een model selecteert dat niet in die allowlist staat, retourneert OpenClaw: 
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
Dit gebeurt voordat een normaal antwoord wordt gegenereerd, dus het bericht kan aanvoelen alsof er “niet is gereageerd”. De oplossing is een van de volgende:
  • Voeg het model toe aan agents.defaults.models, of
  • Wis de allowlist (verwijder agents.defaults.models), of
  • Kies een model uit /model list.
Wanneer de geweigerde opdracht een runtime-overschrijving bevatte, zoals /model openai/gpt-5.5 --runtime codex, repareer dan eerst de allowlist en probeer daarna dezelfde opdracht /model ... --runtime ... opnieuw. Voor native Codex-uitvoering is het geselecteerde model nog steeds openai/gpt-5.5; de codex-runtime selecteert de harness en gebruikt Codex-auth afzonderlijk. Sla voor lokale/GGUF-modellen de volledige providergeprefixte referentie op in de allowlist, bijvoorbeeld ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf, of de exacte provider/model die wordt getoond door openclaw models list --provider <provider>. Losse lokale bestandsnamen of weergavenamen zijn niet genoeg wanneer de allowlist actief is. Voorbeeld van allowlistconfiguratie: 
{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

​
Modellen wisselen in chat (/model)

Je kunt modellen voor de huidige sessie wisselen zonder opnieuw te starten: 
/model
/model list
/model 3
/model openai/gpt-5.4
/model status
  • /model (en /model list) is een compacte, genummerde kiezer (modelfamilie + beschikbare providers).
  • Op Discord openen /model en /models een interactieve kiezer met provider- en modelkeuzelijsten plus een verzendstap.
  • Op Telegram zijn /models-kiezerselecties sessiegebonden; ze wijzigen de permanente standaard van de agent in openclaw.json niet.
  • /models add is verouderd en retourneert nu een verouderingsbericht in plaats van modellen vanuit chat te registreren.
  • /model <#> selecteert uit die kiezer.
  • /model slaat de nieuwe sessieselectie onmiddellijk op.
  • Als de agent inactief is, gebruikt de volgende run meteen het nieuwe model.
  • Als er al een run actief is, markeert OpenClaw een livewisseling als in behandeling en herstart het pas met het nieuwe model op een schoon retrypunt.
  • Als toolactiviteit of antwoorduitvoer al is gestart, kan de in behandeling zijnde wisseling in de wachtrij blijven tot een latere retrymogelijkheid of de volgende gebruikersbeurt.
  • Een door de gebruiker geselecteerde /model-referentie is strikt voor die sessie: als de geselecteerde provider/model niet bereikbaar is, faalt het antwoord zichtbaar in plaats van stilzwijgend te antwoorden vanuit agents.defaults.model.fallbacks. Dit verschilt van geconfigureerde standaarden en primaire modellen voor cron-taken, die nog steeds fallbackketens kunnen gebruiken.
  • /model status is de gedetailleerde weergave (auth-kandidaten en, wanneer geconfigureerd, providerendpoint baseUrl + api-modus).
  • Modelreferenties worden geparseerd door te splitsen op de eerste /. Gebruik provider/model wanneer je /model <ref> typt.
  • Als de model-ID zelf / bevat (OpenRouter-stijl), moet je het providerprefix opnemen (voorbeeld: /model openrouter/moonshotai/kimi-k2).
  • Als je de provider weglaat, lost OpenClaw de invoer in deze volgorde op:
    1. aliasmatch
    2. unieke geconfigureerde-providermatch voor die exacte model-ID zonder prefix
    3. verouderde fallback naar de geconfigureerde standaardprovider — als die provider het geconfigureerde standaardmodel niet meer aanbiedt, valt OpenClaw in plaats daarvan terug op de eerste geconfigureerde provider/model om te voorkomen dat een verouderde verwijderde-providerstandaard zichtbaar wordt.
Volledig opdrachtgedrag/configuratie: Slash-opdrachten.

​
CLI-opdrachten

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear
openclaw models (zonder subopdracht) is een snelkoppeling voor models status.

​
models list

Toont standaard geconfigureerde/auth-beschikbare modellen. Handige vlaggen:
​
--all
boolean
Volledige catalogus. Bevat gebundelde statische catalogusrijen die eigendom zijn van providers voordat auth is geconfigureerd, zodat discovery-only-weergaven modellen kunnen tonen die niet beschikbaar zijn totdat je bijpassende providerreferenties toevoegt.
​
--local
boolean
Alleen lokale providers.
​
--provider <id>
string
Filter op provider-id, bijvoorbeeld moonshot. Weergavelabels uit interactieve pickers worden niet geaccepteerd.
​
--plain
boolean
Eén model per regel.
​
--json
boolean
Machineleesbare uitvoer.

​
models status

Toont het opgeloste primaire model, fallbacks, beeldmodel en een auth-overzicht van geconfigureerde providers. Het toont ook de OAuth-vervalstatus voor profielen die in de auth-store zijn gevonden (waarschuwt standaard binnen 24 uur). --plain drukt alleen het opgeloste primaire model af.
  • OAuth-status wordt altijd getoond (en opgenomen in --json-uitvoer). Als een geconfigureerde provider geen referenties heeft, drukt models status een sectie Ontbrekende auth af.
  • JSON bevat auth.oauth (waarschuwingsvenster + profielen) en auth.providers (effectieve auth per provider, inclusief door env ondersteunde referenties). auth.oauth is alleen de gezondheid van auth-storeprofielen; providers met alleen env verschijnen daar niet.
  • Gebruik --check voor automatisering (exit 1 wanneer ontbrekend/verlopen, 2 wanneer bijna verlopen).
  • Gebruik --probe voor live auth-controles; proberijen kunnen afkomstig zijn van auth-profielen, env-referenties of models.json.
  • Als expliciete auth.order.<provider> een opgeslagen profiel weglaat, rapporteert probe excluded_by_auth_order in plaats van het te proberen. Als auth bestaat maar er geen probeerbaar model voor die provider kan worden opgelost, rapporteert probe status: no_model.
Auth-keuze is afhankelijk van provider/account. Voor altijd actieve Gateway-hosts zijn API-sleutels meestal het meest voorspelbaar; hergebruik van Claude CLI en bestaande Anthropic OAuth-/tokenprofielen worden ook ondersteund.
Voorbeeld (Claude CLI): 
claude auth login
openclaw models status

​
Scannen (gratis OpenRouter-modellen)

openclaw models scan inspecteert OpenRouter’s gratis modellencatalogus en kan optioneel modellen proben op tool- en beeldondersteuning.
​
--no-probe
boolean
Sla live probes over (alleen metadata).
​
--min-params <b>
number
Minimale parametergrootte (miljarden).
​
--max-age-days <days>
number
Sla oudere modellen over.
​
--provider <name>
string
Filter op providerprefix.
​
--max-candidates <n>
number
Grootte van fallbacklijst.
​
--set-default
boolean
Stel agents.defaults.model.primary in op de eerste selectie.
​
--set-image
boolean
Stel agents.defaults.imageModel.primary in op de eerste beeldselectie.
De OpenRouter /models-catalogus is openbaar, dus scans met alleen metadata kunnen gratis kandidaten zonder sleutel weergeven. Probing en inferentie vereisen nog steeds een OpenRouter API-sleutel (uit auth-profielen of OPENROUTER_API_KEY). Als er geen sleutel beschikbaar is, valt openclaw models scan terug op uitvoer met alleen metadata en blijft de configuratie ongewijzigd. Gebruik --no-probe om expliciet de modus met alleen metadata aan te vragen.
Scanresultaten worden gerangschikt op:
  1. Beeldondersteuning
  2. Toollatentie
  3. Contextgrootte
  4. Aantal parameters
Invoer:
  • OpenRouter /models-lijst (filter :free)
  • Live probes vereisen een OpenRouter API-sleutel uit auth-profielen of OPENROUTER_API_KEY (zie Omgevingsvariabelen)
  • Optionele filters: --max-age-days, --min-params, --provider, --max-candidates
  • Aanvraag-/probebesturing: --timeout, --concurrency
Wanneer live probes in een TTY worden uitgevoerd, kun je fallbacks interactief selecteren. Geef in niet-interactieve modus --yes mee om de standaardwaarden te accepteren. Resultaten met alleen metadata zijn informatief; --set-default en --set-image vereisen live probes zodat OpenClaw geen onbruikbaar OpenRouter-model zonder sleutel configureert.

​
Modellenregister (models.json)

Aangepaste providers in models.providers worden weggeschreven naar models.json onder de agentmap (standaard ~/.openclaw/agents/<agentId>/agent/models.json). Dit bestand wordt standaard samengevoegd, tenzij models.mode is ingesteld op replace.
Voorrang in samenvoegmodus voor overeenkomende provider-ID’s:
  • Niet-lege baseUrl die al aanwezig is in de agent-models.json wint.
  • Niet-lege apiKey in de agent-models.json wint alleen wanneer die provider niet door SecretRef wordt beheerd in de huidige config-/auth-profielcontext.
  • Door SecretRef beheerde provider-apiKey-waarden worden vernieuwd vanuit bronmarkeringen (ENV_VAR_NAME voor env-refs, secretref-managed voor file/exec-refs) in plaats van opgeloste geheimen blijvend op te slaan.
  • Door SecretRef beheerde providerheaderwaarden worden vernieuwd vanuit bronmarkeringen (secretref-env:ENV_VAR_NAME voor env-refs, secretref-managed voor file/exec-refs).
  • Lege of ontbrekende agent-apiKey/baseUrl vallen terug op config models.providers.
  • Andere providervelden worden vernieuwd vanuit config en genormaliseerde catalogusgegevens.
Het bewaren van markeringen is bron-autoritatief: OpenClaw schrijft markeringen uit de actieve bronconfiguratiesnapshot (vóór oplossing), niet uit opgeloste runtimegeheimwaarden. Dit is van toepassing telkens wanneer OpenClaw models.json opnieuw genereert, inclusief door opdrachten aangestuurde paden zoals openclaw agent.

​
Gerelateerd