Modellen-CLI

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:

# 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)

# 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

# "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, 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

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:

--allboolean

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.

--localboolean

Alleen lokale providers.

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

--plainboolean

Eén model per regel.

--jsonboolean

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.

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-probeboolean

Sla live probes over (alleen metadata).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Stel agents.defaults.model.primary in op de eerste selectie.

--set-imageboolean

Stel agents.defaults.imageModel.primary in op de eerste beeldselectie.

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.

# Gerelateerd

• Agentruntimes — PI, Codex en andere agentloopruntimes
• Configuratiereferentie — modelconfiguratiesleutels
• Beeldgeneratie — beeldmodelconfiguratie
• Modelfailover — fallbackketens
• Modelproviders — providerrouting en auth
• Muziekgeneratie — muziekmodelconfiguratie
• Videogeneratie — videomodelconfiguratie