Lokale modellen

​

Minimale hardwarevereisten

​

Kies een backend

​

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 de grootste beschikbare modelbuild (vermijd “small”/sterk gekwantiseerde varianten), start de server en controleer of http://127.0.0.1:1234/v1/models deze vermeldt.
• Vervang my-local-model door de daadwerkelijke model-ID die in LM Studio wordt weergegeven.
• Houd het model geladen; koud laden voegt opstartlatentie toe.
• Pas contextWindow/maxTokens aan als jouw LM Studio-build afwijkt.
• Blijf voor WhatsApp de Responses API gebruiken, zodat alleen de definitieve tekst wordt verzonden.
• Behoud models.mode: "merge", zodat gehoste modellen als terugvalopties beschikbaar blijven.

​

Hybride configuratie: gehost primair model, lokale terugvaloptie

{
  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,
          },
        ],
      },
    },
  },
}

​

Regionale hosting / gegevensroutering

​

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 OpenAI-compatibele proxyroutes, niet als systeemeigen OpenAI-eindpunten.
• Aanvraagvorming die uitsluitend voor systeemeigen OpenAI geldt, wordt niet toegepast: geen service_tier, geen Responses-store, geen vormgeving van OpenAI-compatibele payloads voor redeneringen, geen hints voor promptcaching.
• Verborgen OpenClaw-toeschrijvingsheaders (originator, version, User-Agent) worden niet ingevoegd bij aangepaste proxy-URL’s.

• Alleen tekenreeksinhoud: sommige servers accepteren alleen messages[].content als tekenreeks, geen gestructureerde arrays van inhoudsdelen. Stel models.providers.<provider>.models[].compat.requiresStringContent: true in.
• Strikte berichtsleutels: als de server berichtvermeldingen met meer dan role/content weigert, stel je compat.strictMessageKeys: true in.
• Tooltekst tussen blokhaken: sommige lokale modellen geven zelfstandige toolaanvragen als tekst tussen blokhaken weer, zoals [tool_name], gevolgd door JSON en [END_TOOL_REQUEST]. OpenClaw zet deze alleen om in echte toolaanroepen wanneer de naam exact overeenkomt met een voor de beurt geregistreerde tool; anders blijft deze als verborgen, niet-ondersteunde tekst staan.
• Ongestructureerde tekst die op een toolaanroep lijkt: als een model JSON/XML/ReAct-achtige tekst genereert die op een toolaanroep lijkt, maar geen gestructureerde aanroep was, laat OpenClaw deze als tekst staan en registreert het een waarschuwing met de run-ID, provider/het model, het gedetecteerde patroon en, indien beschikbaar, de toolnaam. Dit is incompatibiliteit van de provider/het model, geen voltooide toolrun.
• Toolgebruik afdwingen: als tools als assistenttekst verschijnen (onbewerkte JSON/XML/ReAct of een lege tool_calls-array), controleer dan eerst of de chatsjabloon/parser van de server toolaanroepen ondersteunt. Als de parser alleen werkt wanneer toolgebruik wordt afgedwongen, overschrijf je de standaardproxywaarde van tool_choice: "auto" per model:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Gebruik dit alleen wanneer elke normale beurt een tool moet aanroepen. Vervang local/my-local-model door de exacte verwijzing uit openclaw models list, of stel deze in via de CLI:
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Extra redeneerinspanningen: als een aangepast OpenAI-compatibel model OpenAI-redeneerinspanningen buiten het ingebouwde profiel accepteert, declareer je deze in het compat-blok van het model. Door "xhigh" toe te voegen, wordt deze voor die modelverwijzing beschikbaar in /think xhigh, sessiekiezers, Gateway-validatie en llm-task-validatie:
  {
    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 lokale 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 strengere backends

1. Controleer of het lokale model reageert - geen tools, geen agentcontext:
   openclaw infer model run --local --model <provider/model> --prompt "Antwoord exact met: pong" --json
   
2. Controleer Gateway-routering - verzendt alleen de prompt en slaat het transcript, de AGENTS-bootstrap, de samenstelling van de context-engine, tools en gebundelde MCP-servers over, maar test nog steeds Gateway-routering, authenticatie en providerselectie:
   openclaw infer model run --gateway --model <provider/model> --prompt "Antwoord exact met: pong" --json
   
3. Probeer de zuinige modus als beide tests slagen, maar echte agentbeurten mislukken door ongeldige toolaanroepen of te grote prompts: stel agents.defaults.experimental.localModelLean: true in. Hiermee worden zware browser-, cron-, bericht-, mediageneratie-, spraak- en PDF-tools weggelaten, tenzij ze expliciet vereist zijn, en worden grotere toolcatalogi standaard achter gestructureerde Tool Search-besturingselementen geplaatst, terwijl exec direct zichtbaar blijft. Zie Experimentele functies -> Zuinige modus voor lokale modellen voor details en hoe je controleert of deze actief is.
4. Schakel tools als laatste redmiddel volledig uit door models.providers.<provider>.models[].compat.supportsTools: false voor dat model in te stellen - de agent wordt dan zonder toolaanroepen uitgevoerd.
5. Daarna ligt de bottleneck upstream. Als de backend na de zuinige modus en supportsTools: false nog steeds alleen bij grotere OpenClaw-uitvoeringen mislukt, ligt het resterende probleem meestal bij het model of de server zelf - contextvenster, GPU-geheugen, verwijdering uit de kv-cache of een backendbug - en niet bij de transportlaag van OpenClaw.

​

Problemen oplossen

• Kan de Gateway de proxy niet bereiken? curl http://127.0.0.1:1234/v1/models.
• LM Studio-model niet meer geladen? Laad het opnieuw; een koude start is een veelvoorkomende oorzaak van ‘vastlopen’.
• Meldt de lokale server terminated, ECONNRESET, of sluit deze de stream halverwege een beurt? OpenClaw registreert in de diagnostiek een model.call.error.failureKind met lage cardinaliteit plus een momentopname van het RSS-/heapgebruik van het OpenClaw-proces. Vergelijk bij geheugendruk in LM Studio/Ollama die tijdstempel met het serverlogboek of een macOS-crash-/jetsamlogboek om te bevestigen of de modelserver is beëindigd.
• Contextfouten? OpenClaw leidt de drempelwaarden voor de preflightcontrole van het contextvenster af van het gedetecteerde modelvenster (of het begrensde venster wanneer agents.defaults.contextTokens dit verlaagt), met een waarschuwing onder 20% en een ondergrens van 8k, en een harde blokkering onder 10% met een ondergrens van 4k (begrensd tot het effectieve contextvenster, zodat te grote modelmetadata een geldige gebruikerslimiet niet kan afwijzen). Verlaag contextWindow of verhoog de contextlimiet van de server/het model.
• messages[].content ... expected a string? Voeg compat.requiresStringContent: true toe aan die modelvermelding.
• validation.keys, of ‘berichtvermeldingen staan alleen role en content toe’? Voeg compat.strictMessageKeys: true toe aan die modelvermelding.
• Werken directe /v1/chat/completions-aanroepen, maar mislukt openclaw infer model run --local bij Gemma of een ander lokaal model? Controleer eerst de provider-URL, de modelreferentie, de authenticatiemarkering en de serverlogboeken - model run slaat agenttools volledig over. Als model run slaagt, maar grotere agentbeurten mislukken, verklein dan het tooloppervlak met localModelLean of compat.supportsTools: false.
• Verschijnen toolaanroepen als onbewerkte JSON-/XML-/ReAct-tekst, of retourneert de provider een lege tool_calls-array? Voeg geen proxy toe die assistenttekst blindelings omzet in tooluitvoering - herstel eerst het chatsjabloon/de parser van de server. Als het model alleen werkt wanneer toolgebruik wordt afgedwongen, voeg dan de bovenstaande params.extra_body.tool_choice: "required"-override toe en gebruik die modelvermelding alleen voor sessies waarin bij elke beurt een toolaanroep wordt verwacht.
• Veiligheid: lokale modellen slaan filters aan de providerzijde over. Houd agents beperkt en laat Compaction ingeschakeld om het bereik van promptinjecties te beperken.

​

Gerelateerd

• Configuratiereferentie
• Model-failover