Lokale modellen

​

Hardwareminimum

​

Kies een backend

​

Aanbevolen: LM Studio + groot lokaal model (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,
          },
        ],
      },
    },
  },
}

• Installeer LM Studio: https://lmstudio.ai
• Download in LM Studio de grootste beschikbare modelbuild (vermijd “small”/zwaar gekwantiseerde varianten), start de server en bevestig dat http://127.0.0.1:1234/v1/models deze vermeldt.
• Vervang my-local-model door de werkelijke model-ID die in LM Studio wordt getoond.
• Houd het model geladen; koud laden voegt opstartlatency toe.
• Pas contextWindow/maxTokens aan als je LM Studio-build afwijkt.
• Blijf voor WhatsApp bij Responses API, zodat alleen de uiteindelijke tekst wordt verzonden.

​

Hybride configuratie: gehost primair, lokaal als 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,
          },
        ],
      },
    },
  },
}

​

Lokaal eerst met gehost vangnet

​

Regionale hosting / dataroutering

• Gehoste MiniMax/Kimi/GLM-varianten bestaan ook op OpenRouter met regio-gebonden endpoints (bijv. gehost in de VS). Kies daar de regionale variant om verkeer binnen je gekozen jurisdictie te houden terwijl je nog steeds models.mode: "merge" gebruikt voor Anthropic/OpenAI-fallbacks.
• Alleen lokaal blijft het sterkste privacypad; gehoste regionale routering is de middenweg wanneer je providerfuncties nodig hebt maar controle wilt over de datastroom.

​

Andere OpenAI-compatibele lokale proxy’s

{
  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 deze als proxy-achtige OpenAI-compatibele routes, niet als native OpenAI-endpoints
• native OpenAI-only request shaping geldt hier niet: geen service_tier, geen Responses store, geen OpenAI reasoning-compat payload shaping en geen prompt-cache hints
• verborgen OpenClaw-attributieheaders (originator, version, User-Agent) worden niet geïnjecteerd op deze aangepaste proxy-URL’s

• Sommige servers accepteren op Chat Completions alleen string messages[].content, geen gestructureerde arrays met contentonderdelen. Stel models.providers.<provider>.models[].compat.requiresStringContent: true in voor die endpoints.
• Sommige lokale modellen geven zelfstandige bracketed toolverzoeken als tekst uit, zoals [tool_name] gevolgd door JSON en [END_TOOL_REQUEST]. OpenClaw promoveert die alleen tot echte toolcalls wanneer de naam exact overeenkomt met een geregistreerde tool voor de beurt; anders wordt het blok behandeld als niet-ondersteunde tekst en verborgen in gebruikerszichtbare antwoorden.
• Als een model JSON, XML of ReAct-achtige tekst uitgeeft die op een toolcall lijkt, maar de provider geen gestructureerde aanroep heeft uitgegeven, laat OpenClaw dit als tekst staan en logt het een waarschuwing met de run-ID, provider/model, gedetecteerd patroon en toolnaam wanneer beschikbaar. Behandel dat als incompatibiliteit van provider/model met toolcalls, niet als een voltooide toolrun.
• Als tools als assistenttekst verschijnen in plaats van te draaien, bijvoorbeeld ruwe JSON, XML, ReAct-syntaxis of een lege tool_calls-array in de providerrespons, controleer dan eerst of de server een chattemplate/parser gebruikt die toolcalls ondersteunt. Voor OpenAI-compatibele Chat Completions-backends waarvan de parser alleen werkt wanneer toolgebruik wordt afgedwongen, stel je een requestoverride per model in in plaats van te vertrouwen op tekst parsing:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Gebruik dit alleen voor modellen/sessies waarbij elke normale beurt een tool moet aanroepen. Het overschrijft de standaard proxywaarde van OpenClaw van tool_choice: "auto". Vervang local/my-local-model door de exacte provider/model-referentie die wordt getoond door openclaw models list.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Als een aangepast OpenAI-compatibel model OpenAI-redeneerinspanningen accepteert buiten het ingebouwde profiel, declareer die dan op het modelcompatblok. Door hier "xhigh" toe te voegen, worden /think xhigh, sessiekiezers, Gateway-validatie en llm-task- validatie het niveau laten tonen voor die geconfigureerde provider/model-referentie:
  {
    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 of striktere backends

1. Bevestig dat het lokale model zelf reageert. Geen tools, geen agentcontext:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Bevestig Gateway-routering. Verstuurt alleen de opgegeven prompt: slaat transcript, AGENTS-bootstrap, context-engine-assembly, tools en gebundelde MCP-servers over, maar oefent nog steeds Gateway-routering, auth en providerselectie uit:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Probeer lean mode. Als beide controles slagen maar echte agentbeurten mislukken met misvormde toolaanroepen of te grote prompts, schakel dan agents.defaults.experimental.localModelLean: true in. Dit verwijdert de drie zwaarste standaardtools (browser, cron, message) en plaatst grotere toolcatalogi standaard achter gestructureerde Tool Search-bedieningselementen, behalve voor runs die directe semantiek voor message-bezorging moeten behouden. Zie Experimentele functies → Lean mode voor lokaal model voor de volledige uitleg, wanneer je dit moet gebruiken en hoe je bevestigt dat het is ingeschakeld.
4. Schakel tools als laatste redmiddel volledig uit. Als lean mode niet genoeg is, stel dan models.providers.<provider>.models[].compat.supportsTools: false in voor die modelvermelding. De agent werkt dan zonder toolaanroepen op dat model.
5. Daarna ligt de bottleneck upstream. Als de backend na lean mode en supportsTools: false nog steeds alleen faalt bij grotere OpenClaw-runs, is het resterende probleem meestal upstream model- of servercapaciteit: contextvenster, GPU-geheugen, kv-cacheverwijdering of een backendbug. Op dat punt is het niet de transportlaag van OpenClaw.

​

Probleemoplossing

• Kan Gateway de proxy bereiken? curl http://127.0.0.1:1234/v1/models.
• LM Studio-model niet geladen? Laad het opnieuw; een koude start is een veelvoorkomende oorzaak van “hangen”.
• Lokale server meldt terminated, ECONNRESET, of sluit de stream halverwege een beurt? OpenClaw registreert een low-cardinality model.call.error.failureKind plus de RSS/heap-snapshot van het OpenClaw-proces in diagnostiek. Voor geheugendruk bij LM Studio/Ollama vergelijk je dat tijdstip met het serverlog of het macOS-crash-/ jetsam-log om te bevestigen of de modelserver is beëindigd.
• OpenClaw leidt preflight-drempels voor contextvensters af uit het gedetecteerde modelvenster, of uit het onbeperkte modelvenster wanneer agents.defaults.contextTokens het effectieve venster verlaagt. Het waarschuwt onder 20% met een ondergrens van 8k. Harde blokkades gebruiken de drempel van 10% met een ondergrens van 4k, afgetopt op het effectieve contextvenster zodat te grote modelmetadata geen verder geldige gebruikerslimiet kunnen weigeren. Als je die preflight raakt, verhoog dan de contextlimiet van de server/het model of kies een groter model.
• Contextfouten? Verlaag contextWindow of verhoog je serverlimiet.
• OpenAI-compatibele server retourneert messages[].content ... expected a string? Voeg compat.requiresStringContent: true toe aan die modelvermelding.
• OpenAI-compatibele server retourneert validation.keys of zegt dat berichtvermeldingen alleen role en content toestaan? Voeg compat.strictMessageKeys: true toe aan die modelvermelding.
• Directe kleine /v1/chat/completions-aanroepen werken, maar openclaw infer model run --local faalt op Gemma of een ander lokaal model? Controleer eerst de provider-URL, modelverwijzing, auth- marker en serverlogs; lokale model run bevat geen agenttools. Als lokale model run slaagt maar grotere agentbeurten falen, verklein dan het tooloppervlak van de agent met localModelLean of compat.supportsTools: false.
• Toolaanroepen verschijnen als ruwe JSON/XML/ReAct-tekst, of de provider retourneert een lege tool_calls-array? Voeg geen proxy toe die assistenttekst blind omzet in tooluitvoering. Herstel eerst de chattemplate/parser van de server. Als het model alleen werkt wanneer toolgebruik wordt afgedwongen, voeg dan de per-model override params.extra_body.tool_choice: "required" hierboven toe en gebruik die modelvermelding alleen voor sessies waarin bij elke beurt een toolaanroep wordt verwacht.
• Veiligheid: lokale modellen slaan filters aan providerzijde over; houd agents smal en compaction ingeschakeld om de blast radius van promptinjectie te beperken.

​

Gerelateerd

• Configuratiereferentie
• Modelfailover