FAQ: Modelle und Authentifizierung

Das Standardmodell von OpenClaw ist das, was Sie als Folgendes festlegen:

agents.defaults.model.primary

Modelle werden als provider/model referenziert (Beispiel: openai/gpt-5.5 oder openai-codex/gpt-5.5). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige Übereinstimmung mit einem konfigurierten Provider für genau diese Modell-ID und fällt erst danach als veralteten Kompatibilitätspfad auf den konfigurierten Standard-Provider zurück. Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw auf das erste konfigurierte Provider-/Modell-Paar zurück, statt einen veralteten Standard eines entfernten Providers anzuzeigen. Sie sollten provider/model dennoch explizit festlegen.

Empfohlener Standard: Verwenden Sie das stärkste Modell der neuesten Generation, das in Ihrem Provider-Stack verfügbar ist. Für Agents mit Tools oder nicht vertrauenswürdigen Eingaben: Priorisieren Sie Modellstärke vor Kosten. Für routinemäßigen Chat mit geringem Risiko: Verwenden Sie günstigere Fallback-Modelle und routen Sie nach Agent-Rolle.

MiniMax hat eigene Dokumentation: MiniMax und Lokale Modelle.

Faustregel: Verwenden Sie für kritische Arbeit das beste Modell, das Sie sich leisten können, und ein günstigeres Modell für routinemäßigen Chat oder Zusammenfassungen. Sie können Modelle pro Agent routen und Unteragenten verwenden, um lange Aufgaben zu parallelisieren (jeder Unteragent verbraucht Tokens). Siehe Modelle und Unteragenten.

Deutliche Warnung: Schwächere oder übermäßig quantisierte Modelle sind anfälliger für Prompt- Injection und unsicheres Verhalten. Siehe Sicherheit.

Mehr Kontext: Modelle.

Verwenden Sie Modellbefehle oder bearbeiten Sie nur die Modell-Felder. Vermeiden Sie vollständige Konfigurationsersetzungen.

Sichere Optionen:

• /model im Chat (schnell, pro Sitzung)
• openclaw models set ... (aktualisiert nur die Modellkonfiguration)
• openclaw configure --section model (interaktiv)
• agents.defaults.model in ~/.openclaw/openclaw.json bearbeiten

Vermeiden Sie config.apply mit einem Teilobjekt, sofern Sie nicht die gesamte Konfiguration ersetzen möchten. Für RPC-Bearbeitungen prüfen Sie zuerst mit config.schema.lookup und bevorzugen Sie config.patch. Die Lookup-Nutzlast gibt Ihnen den normalisierten Pfad, oberflächliche Schemadokumentation/-einschränkungen und unmittelbare Zusammenfassungen der untergeordneten Elemente für Teilaktualisierungen. Wenn Sie die Konfiguration überschrieben haben, stellen Sie sie aus einem Backup wieder her oder führen Sie openclaw doctor erneut aus, um sie zu reparieren.

Dokumentation: Modelle, Konfigurieren, Konfiguration, Doctor.

Ja. Ollama ist der einfachste Weg für lokale Modelle.

Schnellste Einrichtung:

1. Installieren Sie Ollama von https://ollama.com/download
2. Laden Sie ein lokales Modell, zum Beispiel ollama pull gemma4
3. Wenn Sie auch Cloud-Modelle möchten, führen Sie ollama signin aus
4. Führen Sie openclaw onboard aus und wählen Sie Ollama
5. Wählen Sie Local oder Cloud + Local

Hinweise:

• Cloud + Local gibt Ihnen Cloud-Modelle plus Ihre lokalen Ollama-Modelle
• Cloud-Modelle wie kimi-k2.5:cloud benötigen keinen lokalen Pull
• Für manuelles Wechseln verwenden Sie openclaw models list und openclaw models set ollama/<model>

Sicherheitshinweis: Kleinere oder stark quantisierte Modelle sind anfälliger für Prompt- Injection. Wir empfehlen dringend große Modelle für jeden Bot, der Tools verwenden kann. Wenn Sie dennoch kleine Modelle verwenden möchten, aktivieren Sie Sandboxing und strenge Tool-Allowlists.

Dokumentation: Ollama, Lokale Modelle, Modell-Provider, Sicherheit, Sandboxing.

• Diese Deployments können sich unterscheiden und sich im Laufe der Zeit ändern; es gibt keine feste Provider-Empfehlung.
• Prüfen Sie die aktuelle Laufzeiteinstellung auf jedem Gateway mit openclaw models status.
• Verwenden Sie für sicherheitssensible Agents oder Agents mit Tools das stärkste verfügbare Modell der neuesten Generation.

Verwenden Sie den Befehl /model als eigenständige Nachricht:

/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite

Dies sind die integrierten Aliasse. Benutzerdefinierte Aliasse können über agents.defaults.models hinzugefügt werden.

Sie können verfügbare Modelle mit /model, /model list oder /model status auflisten.

/model (und /model list) zeigt eine kompakte, nummerierte Auswahl. Wählen Sie per Nummer aus:

/model 3

Sie können auch ein bestimmtes Authentifizierungsprofil für den Provider erzwingen (pro Sitzung):

/model opus@anthropic:default
/model opus@anthropic:work

Tipp: /model status zeigt, welcher Agent aktiv ist, welche Datei auth-profiles.json verwendet wird und welches Authentifizierungsprofil als Nächstes versucht wird. Es zeigt außerdem den konfigurierten Provider-Endpunkt (baseUrl) und den API-Modus (api), sofern verfügbar.

Wie entferne ich die Anheftung eines Profils, das ich mit @profile gesetzt habe?

Führen Sie /model erneut ohne das Suffix @profile aus:

/model anthropic/claude-opus-4-6

Wenn Sie zum Standard zurückkehren möchten, wählen Sie ihn aus /model aus (oder senden Sie /model <default provider/model>). Verwenden Sie /model status, um zu bestätigen, welches Authentifizierungsprofil aktiv ist.

Ja. Behandeln Sie Modellwahl und Laufzeitwahl getrennt:

• Nativer Codex-Coding-Agent: Setzen Sie agents.defaults.model.primary auf openai/gpt-5.5 und agents.defaults.agentRuntime.id auf "codex". Melden Sie sich mit openclaw models auth login --provider openai-codex an, wenn Sie die ChatGPT-/Codex-Abonnementauthentifizierung verwenden möchten.
• Direkte OpenAI-API-Aufgaben über PI: Verwenden Sie /model openai/gpt-5.5 ohne Codex-Laufzeit-Override und konfigurieren Sie OPENAI_API_KEY.
• Codex OAuth über PI: Verwenden Sie /model openai-codex/gpt-5.5 nur, wenn Sie bewusst den normalen PI-Runner mit Codex OAuth verwenden möchten.
• Unteragenten: Routen Sie Coding-Aufgaben an einen reinen Codex-Agent mit eigenem Modell und eigenem agentRuntime-Standard.

Siehe Modelle und Slash-Befehle.

Verwenden Sie entweder einen Sitzungsumschalter oder einen Konfigurationsstandard:

• Pro Sitzung: Senden Sie /fast on, während die Sitzung openai/gpt-5.5 oder openai-codex/gpt-5.5 verwendet.
• Pro Modellstandard: Setzen Sie agents.defaults.models["openai/gpt-5.5"].params.fastMode oder agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode auf true.

Beispiel:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

Für OpenAI wird der Schnellmodus bei unterstützten nativen Responses-Anfragen auf service_tier = "priority" abgebildet. Sitzungs-Overrides mit /fast haben Vorrang vor Konfigurationsstandards.

Siehe Thinking und Schnellmodus und OpenAI-Schnellmodus.

Wenn agents.defaults.models gesetzt ist, wird es zur Allowlist für /model und alle Sitzungs-Overrides. Die Auswahl eines Modells, das nicht in dieser Liste enthalten ist, gibt Folgendes zurück:

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

Dieser Fehler wird anstelle einer normalen Antwort zurückgegeben. Lösung: Fügen Sie das Modell zu agents.defaults.models hinzu, entfernen Sie die Allowlist oder wählen Sie ein Modell aus /model list. Wenn der Befehl auch --runtime codex enthielt, fügen Sie zuerst das Modell hinzu und versuchen Sie dann denselben Befehl /model provider/model --runtime codex erneut.

Das bedeutet, dass der Provider nicht konfiguriert ist (es wurde keine MiniMax-Provider-Konfiguration oder kein Authentifizierungsprofil gefunden), sodass das Modell nicht aufgelöst werden kann.

Checkliste zur Behebung:

1. Aktualisieren Sie auf eine aktuelle OpenClaw-Version (oder führen Sie aus dem Quellcode main aus) und starten Sie dann das Gateway neu.

2. Stellen Sie sicher, dass MiniMax konfiguriert ist (Assistent oder JSON) oder dass MiniMax-Authentifizierung in Umgebungsvariablen/Authentifizierungsprofilen vorhanden ist, damit der passende Provider injiziert werden kann (MINIMAX_API_KEY für minimax, MINIMAX_OAUTH_TOKEN oder gespeichertes MiniMax- OAuth für minimax-portal).

3. Verwenden Sie die exakte Modell-ID (Groß-/Kleinschreibung beachten) für Ihren Authentifizierungspfad: minimax/MiniMax-M2.7 oder minimax/MiniMax-M2.7-highspeed für die Einrichtung mit API-Schlüssel oder minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed für die OAuth-Einrichtung.

4. Führen Sie Folgendes aus:

   openclaw models list
   

   und wählen Sie aus der Liste aus (oder /model list im Chat).

Siehe MiniMax und Modelle.

Ja. Verwenden Sie MiniMax als Standard und wechseln Sie Modelle pro Sitzung, wenn nötig. Fallbacks sind für Fehler gedacht, nicht für „schwere Aufgaben“, verwenden Sie daher /model oder einen separaten Agent.

Option A: pro Sitzung wechseln

{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}

Dann:

/model gpt

Option B: separate Agents

• Standard für Agent A: MiniMax
• Standard für Agent B: OpenAI
• Routen Sie nach Agent oder verwenden Sie /agent, um zu wechseln

Dokumentation: Modelle, Multi-Agent-Routing, MiniMax, OpenAI.

Ja. OpenClaw liefert einige Standard-Kurzformen mit (werden nur angewendet, wenn das Modell in agents.defaults.models vorhanden ist):

• opus → anthropic/claude-opus-4-6
• sonnet → anthropic/claude-sonnet-4-6
• gpt → openai/gpt-5.5 für Einrichtungen mit API-Schlüssel oder openai-codex/gpt-5.5, wenn für Codex OAuth konfiguriert
• gpt-mini → openai/gpt-5.4-mini
• gpt-nano → openai/gpt-5.4-nano
• gemini → google/gemini-3.1-pro-preview
• gemini-flash → google/gemini-3-flash-preview
• gemini-flash-lite → google/gemini-3.1-flash-lite-preview

Wenn Sie Ihren eigenen Alias mit demselben Namen festlegen, hat Ihr Wert Vorrang.

Aliasse stammen aus agents.defaults.models.<modelId>.alias. Beispiel:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}

Dann wird /model sonnet (oder /<alias>, sofern unterstützt) zu dieser Modell-ID aufgelöst.

OpenRouter (Bezahlung pro Token; viele Modelle):

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}

Z.AI (GLM-Modelle):

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}

Wenn Sie auf einen Provider/ein Modell verweisen, aber der erforderliche Provider-Schlüssel fehlt, erhalten Sie einen Authentifizierungsfehler zur Laufzeit (z. B. No API key found for provider "zai").

Kein API-Schlüssel für Provider gefunden, nachdem ein neuer Agent hinzugefügt wurde

Das bedeutet normalerweise, dass der neue Agent einen leeren Auth-Speicher hat. Authentifizierung ist agentbezogen und wird gespeichert in:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Behebungsoptionen:

• Führen Sie openclaw agents add <id> aus und konfigurieren Sie die Authentifizierung im Assistenten.
• Oder kopieren Sie nur portable statische api_key- / token-Profile aus dem Auth-Speicher des Haupt-Agenten in den Auth-Speicher des neuen Agenten.
• Melden Sie sich bei OAuth-Profilen über den neuen Agenten an, wenn dieser ein eigenes Konto benötigt; andernfalls kann OpenClaw auf den Standard-/Haupt-Agenten zugreifen, ohne Refresh-Tokens zu klonen.

Verwenden Sie agentDir nicht für mehrere Agenten wieder; dies verursacht Authentifizierungs-/Sitzungskollisionen.

Failover erfolgt in zwei Stufen:

1. Auth-Profil-Rotation innerhalb desselben Providers.
2. Modell-Fallback zum nächsten Modell in agents.defaults.model.fallbacks.

Cooldowns gelten für fehlschlagende Profile (exponentielles Backoff), sodass OpenClaw weiterhin antworten kann, auch wenn ein Provider rate-limitiert ist oder vorübergehend fehlschlägt.

Der Rate-Limit-Bucket umfasst mehr als reine 429-Antworten. OpenClaw behandelt auch Meldungen wie Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted und periodische Nutzungslimits (weekly/monthly limit reached) als Rate-Limits, die ein Failover rechtfertigen.

Einige nach Abrechnung aussehende Antworten sind keine 402, und einige HTTP-402- Antworten bleiben ebenfalls in diesem transienten Bucket. Wenn ein Provider expliziten Abrechnungstext bei 401 oder 403 zurückgibt, kann OpenClaw dies weiterhin in der Abrechnungsspur behalten, aber providerspezifische Text-Matcher bleiben auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter Key limit exceeded). Wenn eine 402- Meldung stattdessen wie ein wiederholbares Nutzungsfenster oder Ausgabenlimit für Organisation/Workspace aussieht (daily limit reached, resets tomorrow, organization spending limit exceeded), behandelt OpenClaw sie als rate_limit, nicht als langfristige Abrechnungsdeaktivierung.

Kontextüberlauf-Fehler sind anders: Signaturen wie request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model oder ollama error: context length exceeded bleiben auf dem Compaction-/Wiederholpfad, statt den Modell- Fallback fortzusetzen.

Generischer Serverfehlertext ist absichtlich enger gefasst als „alles mit unknown/error darin“. OpenClaw behandelt providerbezogene transiente Formen wie Anthropics reines An unknown error occurred, OpenRouters reines Provider returned error, Stop-Reason-Fehler wie Unhandled stop reason: error, JSON-api_error-Payloads mit transientem Servertext (internal server error, unknown error, 520, upstream error, backend error) und Provider-Busy-Fehler wie ModelNotReadyException als timeout-/überlastungsbezogene Signale, die ein Failover rechtfertigen, wenn der Provider-Kontext passt. Generischer interner Fallback-Text wie LLM request failed with an unknown error. bleibt konservativ und löst für sich genommen keinen Modell-Fallback aus.

Das bedeutet, dass das System versucht hat, die Auth-Profil-ID anthropic:default zu verwenden, aber im erwarteten Auth-Speicher keine Anmeldedaten dafür finden konnte.

Checkliste zur Behebung:

• Bestätigen Sie, wo Auth-Profile liegen (neue vs. Legacy-Pfade)
  • Aktuell: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Legacy: ~/.openclaw/agent/* (migriert durch openclaw doctor)
• Bestätigen Sie, dass Ihre Umgebungsvariable vom Gateway geladen wird
  • Wenn Sie ANTHROPIC_API_KEY in Ihrer Shell setzen, das Gateway aber über systemd/launchd ausführen, erbt es diese Variable möglicherweise nicht. Legen Sie sie in ~/.openclaw/.env ab oder aktivieren Sie env.shellEnv.
• Stellen Sie sicher, dass Sie den richtigen Agenten bearbeiten
  • Multi-Agent-Setups bedeuten, dass es mehrere auth-profiles.json-Dateien geben kann.
• Prüfen Sie Modell-/Auth-Status grob auf Plausibilität
  • Verwenden Sie openclaw models status, um konfigurierte Modelle anzuzeigen und zu sehen, ob Provider authentifiziert sind.

Checkliste zur Behebung von "No credentials found for profile anthropic"

Das bedeutet, dass der Lauf an ein Anthropic-Auth-Profil gebunden ist, das Gateway es aber nicht in seinem Auth-Speicher finden kann.

• Claude CLI verwenden

  • Führen Sie openclaw models auth login --provider anthropic --method cli --set-default auf dem Gateway-Host aus.

• Wenn Sie stattdessen einen API-Schlüssel verwenden möchten

  • Legen Sie ANTHROPIC_API_KEY in ~/.openclaw/.env auf dem Gateway-Host ab.

  • Entfernen Sie jede festgelegte Reihenfolge, die ein fehlendes Profil erzwingt:

    openclaw models auth order clear --provider anthropic
    

• Bestätigen Sie, dass Sie Befehle auf dem Gateway-Host ausführen

  • Im Remote-Modus liegen Auth-Profile auf der Gateway-Maschine, nicht auf Ihrem Laptop.

Wenn Ihre Modellkonfiguration Google Gemini als Fallback enthält (oder Sie zu einer Gemini-Kurzform gewechselt haben), versucht OpenClaw es während des Modell-Fallbacks. Wenn Sie keine Google-Anmeldedaten konfiguriert haben, sehen Sie No API key found for provider "google".

Behebung: Stellen Sie entweder Google-Authentifizierung bereit oder entfernen/vermeiden Sie Google-Modelle in agents.defaults.model.fallbacks / Aliasen, damit der Fallback nicht dorthin routet.

LLM-Anfrage abgelehnt: Thinking-Signatur erforderlich (Google Antigravity)

Ursache: Der Sitzungsverlauf enthält Thinking-Blöcke ohne Signaturen (häufig aus einem abgebrochenen/teilweisen Stream). Google Antigravity erfordert Signaturen für Thinking-Blöcke.

Behebung: OpenClaw entfernt jetzt unsignierte Thinking-Blöcke für Google Antigravity Claude. Wenn dies weiterhin auftritt, starten Sie eine neue Sitzung oder setzen Sie /thinking off für diesen Agenten.

Ein Auth-Profil ist ein benannter Anmeldedatensatz (OAuth oder API-Schlüssel), der an einen Provider gebunden ist. Profile liegen in:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Um gespeicherte Profile zu prüfen, ohne Geheimnisse auszugeben, führen Sie openclaw models auth list aus (optional mit --provider <id> oder --json). Details finden Sie unter Models CLI.

OpenClaw verwendet providerpräfigierte IDs wie:

• anthropic:default (üblich, wenn keine E-Mail-Identität vorhanden ist)
• anthropic:<email> für OAuth-Identitäten
• benutzerdefinierte IDs, die Sie wählen (z. B. anthropic:work)

Ja. Die Konfiguration unterstützt optionale Metadaten für Profile und eine Reihenfolge pro Provider (auth.order.<provider>). Dadurch werden keine Geheimnisse gespeichert; es ordnet IDs Provider/Modus zu und legt die Rotationsreihenfolge fest.

OpenClaw kann ein Profil vorübergehend überspringen, wenn es sich in einem kurzen Cooldown (Rate-Limits/Timeouts/Auth-Fehler) oder einem längeren deaktivierten Zustand (Abrechnung/unzureichendes Guthaben) befindet. Um dies zu prüfen, führen Sie openclaw models status --json aus und prüfen Sie auth.unusableProfiles. Feineinstellung: auth.cooldowns.billingBackoffHours*.

Rate-Limit-Cooldowns können modellbezogen sein. Ein Profil, das für ein Modell abkühlt, kann weiterhin für ein Geschwistermodell beim selben Provider nutzbar sein, während Abrechnungs-/Deaktivierungsfenster weiterhin das gesamte Profil blockieren.

Sie können auch eine agentbezogene Reihenfolge-Überschreibung festlegen (gespeichert in der auth-state.json dieses Agenten) über die CLI:

# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic

Um einen bestimmten Agenten anzusprechen:

openclaw models auth order set --provider anthropic --agent main anthropic:default

Um zu prüfen, was tatsächlich versucht wird, verwenden Sie:

openclaw models status --probe

Wenn ein gespeichertes Profil in der expliziten Reihenfolge ausgelassen wird, meldet Probe excluded_by_auth_order für dieses Profil, statt es stillschweigend zu versuchen.

OpenClaw unterstützt beides:

• OAuth nutzt häufig den Zugriff über ein Abonnement (sofern anwendbar).
• API-Schlüssel verwenden Pay-per-Token-Abrechnung.

Der Assistent unterstützt ausdrücklich Anthropic Claude CLI, OpenAI Codex OAuth und API-Schlüssel.