Lokale Modelle

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.

​

Hardware-Mindestanforderungen

​

Backend auswählen

​

Empfohlen: LM Studio + großes lokales Modell (Responses API)

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• Installieren Sie LM Studio: https://lmstudio.ai
• Laden Sie in LM Studio den größten verfügbaren Modell-Build herunter (vermeiden Sie „small“/stark quantisierte Varianten), starten Sie den Server und bestätigen Sie, dass http://127.0.0.1:1234/v1/models ihn auflistet.
• Ersetzen Sie my-local-model durch die tatsächliche Modell-ID, die in LM Studio angezeigt wird.
• Halten Sie das Modell geladen; Kaltstarts erhöhen die Startlatenz.
• Passen Sie contextWindow/maxTokens an, falls Ihr LM-Studio-Build abweicht.
• Bleiben Sie für WhatsApp bei Responses API, damit nur finaler Text gesendet wird.

​

Hybridkonfiguration: gehostetes Primärmodell, lokaler Fallback

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​

Lokal zuerst mit gehostetem Sicherheitsnetz

​

Regionales Hosting / Datenrouting

• Gehostete MiniMax/Kimi/GLM-Varianten gibt es auch auf OpenRouter mit regional gebundenen Endpunkten (z. B. in den USA gehostet). Wählen Sie dort die regionale Variante, um Traffic in Ihrer gewählten Jurisdiktion zu halten und dennoch models.mode: "merge" für Anthropic/OpenAI-Fallbacks zu verwenden.
• Rein lokal bleibt der stärkste Datenschutzpfad; gehostetes regionales Routing ist der Mittelweg, wenn Sie Provider-Funktionen benötigen, aber Kontrolle über den Datenfluss wünschen.

​

Andere OpenAI-kompatible lokale Proxys

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

• OpenClaw behandelt diese als Proxy-artige OpenAI-kompatible Routen, nicht als native OpenAI-Endpunkte
• rein native OpenAI-Anfrageformung gilt hier nicht: kein service_tier, kein Responses store, keine OpenAI-Reasoning-Kompatibilitäts-Payload- Formung und keine Prompt-Cache-Hinweise
• versteckte OpenClaw-Attributionsheader (originator, version, User-Agent) werden bei diesen benutzerdefinierten Proxy-URLs nicht injiziert

• Manche Server akzeptieren bei Chat Completions nur String-messages[].content, keine strukturierten Content-Part-Arrays. Setzen Sie models.providers.<provider>.models[].compat.requiresStringContent: true für diese Endpunkte.
• Manche lokalen Modelle geben eigenständige eingeklammerte Tool-Anfragen als Text aus, zum Beispiel [tool_name], gefolgt von JSON und [END_TOOL_REQUEST]. OpenClaw hebt diese nur dann zu echten Tool-Aufrufen hoch, wenn der Name exakt einem für den Turn registrierten Tool entspricht; andernfalls wird der Block als nicht unterstützter Text behandelt und vor nutzersichtbaren Antworten verborgen.
• Wenn ein Modell JSON, XML oder ReAct-artigen Text ausgibt, der wie ein Tool-Aufruf aussieht, der Provider aber keinen strukturierten Aufruf ausgegeben hat, lässt OpenClaw ihn als Text stehen und protokolliert eine Warnung mit der Run-ID, Provider/Modell, erkanntem Muster und Tool-Namen, sofern verfügbar. Behandeln Sie dies als Tool-Call- Inkompatibilität von Provider/Modell, nicht als abgeschlossenen Tool-Lauf.
• Wenn Tools als Assistant-Text erscheinen, statt ausgeführt zu werden, zum Beispiel rohes JSON, XML, ReAct-Syntax oder ein leeres tool_calls-Array in der Provider-Antwort, prüfen Sie zuerst, ob der Server ein Tool-Call-fähiges Chat-Template bzw. einen entsprechenden Parser verwendet. Für OpenAI-kompatible Chat-Completions-Backends, deren Parser nur funktioniert, wenn Tool-Nutzung erzwungen wird, setzen Sie eine anfragebezogene Überschreibung pro Modell, statt sich auf Text- Parsing zu verlassen:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Verwenden Sie dies nur für Modelle/Sitzungen, bei denen jeder normale Turn ein Tool aufrufen soll. Es überschreibt den OpenClaw-Standard-Proxywert tool_choice: "auto". Ersetzen Sie local/my-local-model durch die exakte Provider/Modell-Referenz, die von openclaw models list angezeigt wird.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Wenn ein benutzerdefiniertes OpenAI-kompatibles Modell OpenAI-Reasoning-Efforts jenseits des eingebauten Profils akzeptiert, deklarieren Sie diese im Modell-Compat-Block. Wenn Sie hier "xhigh" hinzufügen, machen /think xhigh, Sitzungsauswahlen, Gateway-Validierung und llm-task- Validierung die Stufe für diese konfigurierte Provider/Modell-Referenz verfügbar:
  {
    models: {
      providers: {
        local: {
          baseUrl: "http://127.0.0.1:8000/v1",
          apiKey: "sk-local",
          api: "openai-responses",
          models: [
            {
              id: "gpt-5.4",
              name: "GPT 5.4 via local proxy",
              reasoning: true,
              input: ["text"],
              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
              contextWindow: 196608,
              maxTokens: 8192,
              compat: {
                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
                reasoningEffortMap: { xhigh: "xhigh" },
              },
            },
          ],
        },
      },
    },
  }
  

​

Kleinere oder strengere Backends

1. Bestätigen Sie, dass das lokale Modell selbst antwortet. Keine Tools, kein Agent-Kontext:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Bestätigen Sie das Gateway-Routing. Sendet nur den angegebenen Prompt – überspringt Transkript, AGENTS-Bootstrap, Zusammenbau der Kontext-Engine, Tools und mitgelieferte MCP-Server, prüft aber weiterhin Gateway-Routing, Authentifizierung und Provider-Auswahl:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Probieren Sie den Lean-Modus. Wenn beide Prüfungen bestehen, reale Agent-Durchläufe aber mit fehlerhaften Tool-Aufrufen oder übergroßen Prompts scheitern, aktivieren Sie agents.defaults.experimental.localModelLean: true. Dadurch werden die drei schwergewichtigsten Standard-Tools (browser, cron, message) entfernt, sodass die Prompt-Form kleiner und weniger brüchig ist. Siehe Experimentelle Funktionen → Lean-Modus für lokale Modelle für die vollständige Erklärung, wann Sie ihn verwenden sollten und wie Sie bestätigen, dass er aktiv ist.
4. Deaktivieren Sie Tools als letzten Ausweg vollständig. Wenn der Lean-Modus nicht ausreicht, setzen Sie models.providers.<provider>.models[].compat.supportsTools: false für diesen Modelleintrag. Der Agent arbeitet dann auf diesem Modell ohne Tool-Aufrufe.
5. Darüber hinaus liegt der Engpass upstream. Wenn das Backend nach Lean-Modus und supportsTools: false weiterhin nur bei größeren OpenClaw-Läufen scheitert, ist das verbleibende Problem normalerweise die Kapazität des upstream Modells oder Servers – Kontextfenster, GPU-Speicher, kv-cache-Verdrängung oder ein Backend-Fehler. An diesem Punkt ist es nicht mehr die Transportschicht von OpenClaw.

​

Fehlerbehebung

• Kann Gateway den Proxy erreichen? curl http://127.0.0.1:1234/v1/models.
• LM Studio-Modell entladen? Laden Sie es erneut; Kaltstart ist eine häufige Ursache für „Hängenbleiben“.
• Meldet der lokale Server terminated, ECONNRESET oder schließt er den Stream mitten im Durchlauf? OpenClaw zeichnet in der Diagnose ein niedrig-kardinales model.call.error.failureKind plus einen RSS-/Heap-Snapshot des OpenClaw-Prozesses auf. Bei Speicherdruck in LM Studio/Ollama gleichen Sie diesen Zeitstempel mit dem Serverlog oder macOS-Crash-/ Jetsam-Log ab, um zu bestätigen, ob der Modellserver beendet wurde.
• OpenClaw leitet die Preflight-Schwellenwerte für Kontextfenster aus dem erkannten Modellfenster ab oder aus dem nicht gedeckelten Modellfenster, wenn agents.defaults.contextTokens das effektive Fenster reduziert. Unter 20 % wird mit einer Untergrenze von 8k gewarnt. Harte Sperren verwenden den 10-%-Schwellenwert mit einer Untergrenze von 4k, begrenzt auf das effektive Kontextfenster, damit übergroße Modellmetadaten ein ansonsten gültiges Benutzerlimit nicht ablehnen können. Wenn Sie diese Preflight-Prüfung auslösen, erhöhen Sie das Kontextlimit des Servers/Modells oder wählen Sie ein größeres Modell.
• Kontextfehler? Senken Sie contextWindow oder erhöhen Sie Ihr Serverlimit.
• OpenAI-kompatibler Server gibt messages[].content ... expected a string zurück? Fügen Sie compat.requiresStringContent: true zu diesem Modelleintrag hinzu.
• OpenAI-kompatibler Server gibt validation.keys zurück oder sagt, dass Nachrichteneinträge nur role und content erlauben? Fügen Sie compat.strictMessageKeys: true zu diesem Modelleintrag hinzu.
• Direkte kleine /v1/chat/completions-Aufrufe funktionieren, aber openclaw infer model run --local scheitert bei Gemma oder einem anderen lokalen Modell? Prüfen Sie zuerst die Provider-URL, Modellreferenz, Authentifizierungsmarkierung und Serverlogs; lokales model run enthält keine Agent-Tools. Wenn lokales model run erfolgreich ist, größere Agent-Durchläufe aber scheitern, reduzieren Sie die Tool-Oberfläche des Agent mit localModelLean oder compat.supportsTools: false.
• Tool-Aufrufe erscheinen als roher JSON-/XML-/ReAct-Text, oder der Provider gibt ein leeres tool_calls-Array zurück? Fügen Sie keinen Proxy hinzu, der Assistant-Text blind in Tool-Ausführung umwandelt. Beheben Sie zuerst das Chat-Template/den Parser des Servers. Wenn das Modell nur funktioniert, wenn Tool-Nutzung erzwungen wird, fügen Sie die obige modellbezogene Überschreibung params.extra_body.tool_choice: "required" hinzu und verwenden Sie diesen Modelleintrag nur für Sitzungen, in denen in jedem Durchlauf ein Tool-Aufruf erwartet wird.
• Sicherheit: Lokale Modelle überspringen Provider-seitige Filter; halten Sie Agents eng begrenzt und Compaction aktiviert, um den Wirkungsradius von Prompt Injection zu begrenzen.

​

Verwandt

• Konfigurationsreferenz
• Modell-Failover