Modellen-CLI

Modelrefs kiezen een provider en model. Ze kiezen meestal niet de low-level agentruntime. OpenAI-agentrefs zijn de belangrijkste uitzondering: openai/gpt-5.5 draait standaard via de Codex app-server-runtime op de officiële OpenAI-provider. Subscription Copilot-refs (github-copilot/*) kunnen daarnaast expliciet worden ingeschakeld voor de externe GitHub Copilot-agentruntime-Plugin; dat pad blijft expliciet (geen auto-fallback). Expliciete runtime-overschrijvingen horen thuis in provider/modelbeleid, niet op de hele agent of sessie. In Codex-runtimemodus impliceert de openai/gpt-*-ref geen facturering via API-sleutel; auth kan afkomstig zijn van een Codex-account of openai OAuth-profiel. Zie Agentruntimes en GitHub Copilot-agentruntime.

Hoe modelselectie werkt

OpenClaw selecteert modellen in deze volgorde:

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 elke keer een bekend slecht primair model te peilen; OpenClaw peilt periodiek het oorspronkelijke primaire model opnieuw, wist de automatische selectie wanneer dit herstelt en kondigt fallback-/herstelovergangen eenmaal per statuswijziging aan.
• 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.
• Het wijzigen van agents.defaults.model.primary herschrijft bestaande sessieselecties niet. Als de status zegt This session is pinned to X; config primary Y will apply to new/unpinned sessions., wis dan de huidige sessieselectie met /model default zodat deze de geconfigureerde primaire instelling weer erft.
• Cron --model / payload model is een primair model per taak. Het gebruikt nog steeds geconfigureerde fallbacks, tenzij de taak expliciete payload fallbacks aanlevert (gebruik fallbacks: [] voor een strikte Cron-run).
• CLI-standaardmodel- en allowlist-kiezers respecteren models.mode: "replace" door expliciete models.providers.*.models te tonen in plaats van de volledige ingebouwde catalogus te laden.
• De modelkiezer van de Control-UI vraagt de Gateway om de geconfigureerde modelweergave: agents.defaults.models wanneer aanwezig, inclusief providerbrede provider/*-items, 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.

Snel modelbeleid

• Stel je primaire model in op het sterkste nieuwste-generatiemodel dat voor jou beschikbaar is.
• Gebruik fallbacks voor kosten-/latentiegevoelige taken en chat met lagere inzet.
• Vermijd oudere/zwakkere modeltiers voor agents met tools ingeschakeld of niet-vertrouwde invoer.

Onboarding (aanbevolen)

Als je de configuratie niet met de hand wilt bewerken, voer onboarding uit:

openclaw onboard

Dit kan model + auth instellen voor veelgebruikte providers, waaronder OpenAI Code (Codex)-abonnement (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 + dynamische provideritems provider/*)
• models.providers (aangepaste providers die naar models.json worden geschreven)

Veilige allowlist-bewerkingen

Gebruik toevoegende schrijfbewerkingen wanneer je agents.defaults.models met de hand bijwerkt:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

"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

Wanneer de geweigerde opdracht een runtime-overschrijving bevatte, zoals /model openai/gpt-5.5 --runtime codex, los dan eerst de allowlist op 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 ref 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>. Kale lokale bestandsnamen of weergavenamen zijn niet genoeg wanneer de allowlist actief is.

Als je providers wilt beperken zonder elk model handmatig te vermelden, voeg dan provider/*-items toe aan agents.defaults.models:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Met dat beleid tonen /model, /models en modelkiezers de ontdekte catalogus alleen voor die providers. Nieuwe modellen van de geselecteerde providers kunnen verschijnen zonder de allowlist te bewerken. Exacte provider/model-items kunnen worden gemengd met provider/*-items wanneer je één specifiek model van een andere provider nodig hebt.

Voorbeeld van allowlist-configuratie:

{  agents: {    defaults: {      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 op te starten:

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Volledig opdrachtgedrag/configuratie: Slash-opdrachten.

CLI-opdrachten

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw 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:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filter op provider-ID, bijvoorbeeld moonshot. Weergavelabels uit interactieve pickers worden niet geaccepteerd.

models status

Toont het opgeloste primaire model, fallbacks, afbeeldingsmodel 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 print alleen het opgeloste primaire model.

Voorbeeld (Claude CLI):

claude auth loginopenclaw models status

Scannen (gratis OpenRouter-modellen)

openclaw models scan inspecteert de gratis modelcatalogus van OpenRouter en kan optioneel modellen proben op tool- en afbeeldingsondersteuning.

Scanresultaten worden gerangschikt op:

1. Afbeeldingsondersteuning
2. Toollatentie
3. Contextgrootte
4. Parameteraantal

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-/probecontroles: --timeout, --concurrency

Wanneer live probes in een TTY draaien, kun je fallbacks interactief selecteren. Geef in niet-interactieve modus --yes door om standaarden 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 naar models.json geschreven onder de agentmap (standaard ~/.openclaw/agents/<agentId>/agent/models.json). Provider-Plugin-catalogi worden opgeslagen als gegenereerde catalogusshards die eigendom zijn van de Plugin onder de pluginstatus van de agent en automatisch geladen. Dit bestand wordt standaard samengevoegd tenzij models.mode is ingesteld op replace.

Gerelateerd

• Agentruntimes — OpenClaw, Codex en andere agent-loop-runtimes
• Configuratiereferentie — modelconfiguratiesleutels
• Afbeeldingsgeneratie — configuratie van afbeeldingsmodel
• Model-failover — fallbackketens
• Modelproviders — providerroutering en auth
• Muziekgeneratie — configuratie van muziekmodel
• Videogeneratie — configuratie van videomodel