Modele lokalne

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.

​

Minimalny sprzęt

​

Wybierz backend

​

Zalecane: LM Studio + duży model lokalny (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,
          },
        ],
      },
    },
  },
}

• Zainstaluj LM Studio: https://lmstudio.ai
• W LM Studio pobierz największą dostępną kompilację modelu (unikaj wariantów „small”/mocno kwantyzowanych), uruchom serwer, potwierdź, że http://127.0.0.1:1234/v1/models ją wyświetla.
• Zastąp my-local-model rzeczywistym identyfikatorem modelu pokazanym w LM Studio.
• Utrzymuj model załadowany; zimne ładowanie zwiększa opóźnienie startu.
• Dostosuj contextWindow/maxTokens, jeśli twoja kompilacja LM Studio się różni.
• W przypadku WhatsApp trzymaj się Responses API, aby wysyłany był tylko tekst końcowy.

​

Konfiguracja hybrydowa: hostowany podstawowy, lokalny awaryjny

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

​

Najpierw lokalnie, z hostowaną siatką bezpieczeństwa

​

Hosting regionalny / routing danych

• Hostowane warianty MiniMax/Kimi/GLM istnieją także w OpenRouter z punktami końcowymi przypiętymi do regionu (np. hostowane w USA). Wybierz tam wariant regionalny, aby utrzymać ruch w wybranej jurysdykcji, nadal używając models.mode: "merge" dla opcji awaryjnych Anthropic/OpenAI.
• Wyłącznie lokalne działanie pozostaje najsilniejszą ścieżką prywatności; hostowany routing regionalny to rozwiązanie pośrednie, gdy potrzebujesz funkcji dostawcy, ale chcesz kontrolować przepływ danych.

​

Inne lokalne proxy zgodne z OpenAI

{
  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 traktuje je jako trasy zgodne z OpenAI w stylu proxy, a nie natywne punkty końcowe OpenAI
• nie stosuje się tu kształtowanie żądań wyłącznie dla natywnego OpenAI: brak service_tier, brak Responses store, brak kształtowania payloadu zgodnego z rozumowaniem OpenAI i brak podpowiedzi pamięci podręcznej promptów
• ukryte nagłówki atrybucji OpenClaw (originator, version, User-Agent) nie są wstrzykiwane pod tymi niestandardowymi URL-ami proxy

• Niektóre serwery akceptują w Chat Completions tylko tekstowe messages[].content, a nie ustrukturyzowane tablice części treści. Ustaw models.providers.<provider>.models[].compat.requiresStringContent: true dla tych punktów końcowych.
• Niektóre modele lokalne emitują samodzielne narzędziowe żądania w nawiasach jako tekst, takie jak [tool_name], po którym następuje JSON i [END_TOOL_REQUEST]. OpenClaw promuje je do prawdziwych wywołań narzędzi tylko wtedy, gdy nazwa dokładnie pasuje do zarejestrowanego narzędzia dla danej tury; w przeciwnym razie blok jest traktowany jako nieobsługiwany tekst i ukrywany przed odpowiedziami widocznymi dla użytkownika.
• Jeśli model emituje JSON, XML lub tekst w stylu ReAct, który wygląda jak wywołanie narzędzia, ale provider nie wyemitował ustrukturyzowanego wywołania, OpenClaw pozostawia go jako tekst i rejestruje ostrzeżenie z identyfikatorem uruchomienia, providerem/modelem, wykrytym wzorcem oraz nazwą narzędzia, gdy jest dostępna. Traktuj to jako niekompatybilność wywołań narzędzi providera/modelu, a nie ukończone uruchomienie narzędzia.
• Jeśli narzędzia pojawiają się jako tekst asystenta zamiast się uruchamiać, na przykład surowy JSON, XML, składnia ReAct lub pusta tablica tool_calls w odpowiedzi providera, najpierw sprawdź, czy serwer używa szablonu/parsera czatu obsługującego wywołania narzędzi. W przypadku backendów Chat Completions zgodnych z OpenAI, których parser działa tylko wtedy, gdy użycie narzędzi jest wymuszone, ustaw nadpisanie żądania dla konkretnego modelu zamiast polegać na parsowaniu tekstu:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Używaj tego tylko dla modeli/sesji, w których każda normalna tura powinna wywoływać narzędzie. Nadpisuje to domyślną wartość proxy OpenClaw tool_choice: "auto". Zastąp local/my-local-model dokładnym odwołaniem provider/model pokazanym przez openclaw models list.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Jeśli niestandardowy model zgodny z OpenAI akceptuje wysiłki rozumowania OpenAI wykraczające poza wbudowany profil, zadeklaruj je w bloku kompatybilności modelu. Dodanie tutaj "xhigh" sprawia, że /think xhigh, selektory sesji, walidacja Gateway i walidacja llm-task udostępniają ten poziom dla skonfigurowanego odwołania provider/model:
  {
    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" },
              },
            },
          ],
        },
      },
    },
  }
  

​

Mniejsze lub ściślejsze backendy

1. Potwierdź, że sam model lokalny odpowiada. Bez narzędzi, bez kontekstu agenta:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Potwierdź trasowanie Gateway. Wysyła tylko podany prompt — pomija transkrypcję, bootstrap AGENTS, składanie przez silnik kontekstu, narzędzia i dołączone serwery MCP, ale nadal sprawdza trasowanie Gateway, uwierzytelnianie i wybór providera:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Wypróbuj tryb odchudzony. Jeśli oba sprawdzenia przechodzą, ale rzeczywiste tury agenta kończą się niepoprawnie sformatowanymi wywołaniami narzędzi lub zbyt dużymi promptami, włącz agents.defaults.experimental.localModelLean: true. Usuwa to trzy najcięższe domyślne narzędzia (browser, cron, message), dzięki czemu kształt promptu jest mniejszy i mniej kruchy. Zobacz Funkcje eksperymentalne → tryb odchudzonego modelu lokalnego, aby poznać pełne wyjaśnienie, kiedy go używać i jak potwierdzić, że jest włączony.
4. Całkowicie wyłącz narzędzia w ostateczności. Jeśli tryb odchudzony nie wystarczy, ustaw models.providers.<provider>.models[].compat.supportsTools: false dla tego wpisu modelu. Agent będzie wtedy działać na tym modelu bez wywołań narzędzi.
5. Poza tym wąskie gardło jest upstream. Jeśli backend nadal zawodzi tylko przy większych uruchomieniach OpenClaw po włączeniu trybu odchudzonego i supportsTools: false, pozostały problem zwykle dotyczy upstreamowego modelu lub pojemności serwera — okna kontekstu, pamięci GPU, eksmisji kv-cache albo błędu backendu. Na tym etapie nie jest to warstwa transportu OpenClaw.

​

Rozwiązywanie problemów

• Gateway może dosięgnąć proxy? curl http://127.0.0.1:1234/v1/models.
• Model LM Studio jest rozładowany? Załaduj go ponownie; zimny start to częsta przyczyna „zawieszania się”.
• Serwer lokalny zgłasza terminated, ECONNRESET albo zamyka strumień w połowie tury? OpenClaw zapisuje niskokardynalny model.call.error.failureKind oraz migawkę RSS/sterty procesu OpenClaw w diagnostyce. Przy presji pamięciowej LM Studio/Ollama dopasuj ten znacznik czasu do logu serwera albo logu awarii macOS / jetsam, aby potwierdzić, czy serwer modelu został zabity.
• OpenClaw wyprowadza progi kontroli wstępnej okna kontekstu z wykrytego okna modelu albo z nieograniczonego okna modelu, gdy agents.defaults.contextTokens obniża efektywne okno. Ostrzega poniżej 20% z dolnym limitem 8k. Twarde blokady używają progu 10% z dolnym limitem 4k, ograniczonego do efektywnego okna kontekstu, aby zawyżone metadane modelu nie mogły odrzucić skądinąd poprawnego limitu użytkownika. Jeśli trafisz na tę kontrolę wstępną, zwiększ limit kontekstu serwera/modelu albo wybierz większy model.
• Błędy kontekstu? Obniż contextWindow albo zwiększ limit serwera.
• Serwer zgodny z OpenAI zwraca messages[].content ... expected a string? Dodaj compat.requiresStringContent: true do tego wpisu modelu.
• Serwer zgodny z OpenAI zwraca validation.keys albo mówi, że wpisy wiadomości dopuszczają tylko role i content? Dodaj compat.strictMessageKeys: true do tego wpisu modelu.
• Bezpośrednie małe wywołania /v1/chat/completions działają, ale openclaw infer model run --local zawodzi na Gemmie albo innym modelu lokalnym? Najpierw sprawdź URL providera, referencję modelu, marker uwierzytelniania i logi serwera; lokalne model run nie zawiera narzędzi agenta. Jeśli lokalne model run działa, ale większe tury agenta zawodzą, ogranicz powierzchnię narzędzi agenta przez localModelLean albo compat.supportsTools: false.
• Wywołania narzędzi pojawiają się jako surowy tekst JSON/XML/ReAct albo provider zwraca pustą tablicę tool_calls? Nie dodawaj proxy, które ślepo konwertuje tekst asystenta na wykonanie narzędzia. Najpierw napraw szablon/parser czatu serwera. Jeśli model działa tylko wtedy, gdy użycie narzędzi jest wymuszone, dodaj powyższe nadpisanie params.extra_body.tool_choice: "required" dla danego modelu i używaj tego wpisu modelu tylko w sesjach, w których wywołanie narzędzia jest oczekiwane w każdej turze.
• Bezpieczeństwo: modele lokalne pomijają filtry po stronie providera; utrzymuj agentów wąsko ukierunkowanych i włącz Compaction, aby ograniczyć zasięg prompt injection.

​

Powiązane

• Dokumentacja konfiguracji
• Przełączanie awaryjne modeli