Modele lokalne

​

Minimalne wymagania sprzętowe

​

Wybór zaplecza

​

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
• Pobierz największą dostępną kompilację modelu (unikaj wariantów „małych” lub silnie skwantyzowanych), uruchom serwer i potwierdź, że model znajduje się na liście pod adresem http://127.0.0.1:1234/v1/models.
• Zastąp my-local-model rzeczywistym identyfikatorem modelu wyświetlanym w LM Studio.
• Pozostaw model załadowany; ładowanie od zera zwiększa opóźnienie uruchamiania.
• Dostosuj contextWindow/maxTokens, jeśli Twoja kompilacja LM Studio ma inne wartości.
• W przypadku WhatsApp pozostań przy Responses API, aby wysyłany był tylko tekst końcowy.
• Zachowaj models.mode: "merge", aby modele hostowane pozostały dostępne jako opcje rezerwowe.

​

Konfiguracja hybrydowa: hostowany model podstawowy, lokalny model rezerwowy

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

​

Hosting regionalny / trasowanie 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 proxy zgodne z OpenAI, a nie natywne punkty końcowe OpenAI.
• Kształtowanie żądań przeznaczone wyłącznie dla natywnego OpenAI nie ma zastosowania: bez service_tier, bez store interfejsu Responses, bez kształtowania ładunku zgodności rozumowania OpenAI i bez wskazówek dotyczących pamięci podręcznej poleceń.
• Ukryte nagłówki atrybucji OpenClaw (originator, version, User-Agent) nie są wstrzykiwane do niestandardowych adresów URL proxy.

• Treść wyłącznie jako ciąg znaków: niektóre serwery akceptują tylko ciąg znaków w messages[].content, a nie ustrukturyzowane tablice części treści. Ustaw models.providers.<provider>.models[].compat.requiresStringContent: true.
• Ścisłe klucze wiadomości: jeśli serwer odrzuca wpisy wiadomości zawierające więcej niż role/content, ustaw compat.strictMessageKeys: true.
• Tekst narzędzia w nawiasach kwadratowych: niektóre modele lokalne emitują jako tekst samodzielne żądania narzędzi w nawiasach kwadratowych, takie jak [tool_name], po których następuje kod JSON i [END_TOOL_REQUEST]. OpenClaw przekształca je w rzeczywiste wywołania narzędzi tylko wtedy, gdy nazwa dokładnie odpowiada narzędziu zarejestrowanemu dla danej tury; w przeciwnym razie pozostają ukrytym, nieobsługiwanym tekstem.
• Nieustrukturyzowany tekst przypominający wywołanie narzędzia: jeśli model emituje tekst w stylu JSON/XML/ReAct, który wygląda jak wywołanie narzędzia, ale nie był ustrukturyzowanym wywołaniem, OpenClaw pozostawia go jako tekst i rejestruje ostrzeżenie z identyfikatorem uruchomienia, dostawcą/modelem, wykrytym wzorcem oraz nazwą narzędzia, jeśli jest dostępna. Jest to niezgodność dostawcy/modelu, a nie ukończone uruchomienie narzędzia.
• Wymuszanie użycia narzędzia: jeśli narzędzia pojawiają się jako tekst asystenta (surowy JSON/XML/ReAct albo pusta tablica tool_calls), najpierw potwierdź, że szablon/parser czatu serwera obsługuje wywołania narzędzi. Jeśli parser działa tylko przy wymuszonym użyciu narzędzi, nadpisz dla danego modelu domyślną wartość proxy tool_choice: "auto":
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Używaj tego tylko wtedy, gdy każda zwykła tura powinna wywoływać narzędzie. Zastąp local/my-local-model dokładnym odwołaniem z openclaw models list albo ustaw je za pomocą CLI:
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Dodatkowe poziomy intensywności rozumowania: jeśli niestandardowy model zgodny z OpenAI akceptuje poziomy intensywności rozumowania OpenAI wykraczające poza wbudowany profil, zadeklaruj je w bloku zgodności modelu. Dodanie "xhigh" udostępnia je dla tego odwołania do modelu w /think xhigh, selektorach sesji, walidacji Gateway oraz walidacji llm-task:
  {
    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 bardziej rygorystyczne zaplecza

1. Potwierdź, że model lokalny odpowiada — bez narzędzi i bez kontekstu agenta:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Potwierdź routing Gateway — wysyła wyłącznie prompt, pomijając transkrypcję, inicjalizację AGENTS, składanie silnika kontekstu, narzędzia i dołączone serwery MCP, ale nadal sprawdza routing Gateway, uwierzytelnianie i wybór dostawcy:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Wypróbuj tryb odchudzony, jeśli oba testy kończą się powodzeniem, ale rzeczywiste tury agenta zawodzą z powodu nieprawidłowych wywołań narzędzi lub zbyt dużych promptów: ustaw agents.defaults.experimental.localModelLean: true. Tryb ten usuwa rozbudowane narzędzia przeglądarki, cron, wiadomości, generowania multimediów, obsługi głosu i plików PDF, chyba że są jawnie wymagane, a większe katalogi narzędzi domyślnie udostępnia za pośrednictwem ustrukturyzowanych mechanizmów wyszukiwania narzędzi, pozostawiając exec bezpośrednio widoczne. Szczegóły i sposób sprawdzenia, czy tryb jest włączony, znajdziesz w sekcji Funkcje eksperymentalne -> Tryb odchudzony modelu lokalnego.
4. W ostateczności całkowicie wyłącz narzędzia, ustawiając dla tego modelu models.providers.<provider>.models[].compat.supportsTools: false — agent będzie wtedy działać bez wywołań narzędzi.
5. Po wyczerpaniu tych możliwości wąskie gardło znajduje się po stronie systemu nadrzędnego. Jeśli po włączeniu trybu odchudzonego i ustawieniu supportsTools: false backend nadal zawodzi tylko przy większych uruchomieniach OpenClaw, pozostały problem zwykle dotyczy samego modelu lub serwera — okna kontekstu, pamięci GPU, usuwania wpisów z pamięci podręcznej KV albo błędu backendu — a nie warstwy transportowej OpenClaw.

​

Rozwiązywanie problemów

• Gateway nie może połączyć się z serwerem proxy? curl http://127.0.0.1:1234/v1/models.
• Model został wyładowany z LM Studio? Załaduj go ponownie; zimny start jest częstą przyczyną „zawieszania się”.
• Serwer lokalny zgłasza terminated, ECONNRESET lub zamyka strumień w trakcie tury? OpenClaw zapisuje w diagnostyce wartość model.call.error.failureKind o niewielkiej liczbie możliwych wariantów oraz migawkę RSS/sterty procesu OpenClaw. W przypadku presji na pamięć w LM Studio/Ollama porównaj ten znacznik czasu z dziennikiem serwera albo dziennikiem awarii/jetsam systemu macOS, aby potwierdzić, czy serwer modelu został zakończony.
• Błędy kontekstu? OpenClaw wyznacza progi kontroli wstępnej okna kontekstu na podstawie wykrytego okna modelu (lub ograniczonego okna, gdy agents.defaults.contextTokens je zmniejsza), wyświetlając ostrzeżenie poniżej 20% przy dolnej granicy 8k i bezwzględnie blokując działanie poniżej 10% przy dolnej granicy 4k (wartości są ograniczone do efektywnego okna kontekstu, aby zawyżone metadane modelu nie mogły spowodować odrzucenia prawidłowego limitu użytkownika). Zmniejsz contextWindow albo zwiększ limit kontekstu serwera/modelu.
• messages[].content ... expected a string? Dodaj compat.requiresStringContent: true do wpisu tego modelu.
• validation.keys lub „message entries only allow role and content”? Dodaj compat.strictMessageKeys: true do wpisu tego modelu.
• Bezpośrednie wywołania /v1/chat/completions działają, ale openclaw infer model run --local nie działa z modelem Gemma lub innym modelem lokalnym? Najpierw sprawdź adres URL dostawcy, odwołanie do modelu, znacznik uwierzytelniania i dzienniki serwera — model run całkowicie pomija narzędzia agenta. Jeśli model run działa, ale większe tury agenta zawodzą, ogranicz zestaw narzędzi za pomocą localModelLean lub compat.supportsTools: false.
• Wywołania narzędzi pojawiają się jako nieprzetworzony tekst JSON/XML/ReAct albo dostawca zwraca pustą tablicę tool_calls? Nie dodawaj serwera proxy, który bezwarunkowo przekształca tekst asystenta w wykonanie narzędzia — najpierw napraw szablon/parser czatu serwera. Jeśli model działa tylko przy wymuszonym użyciu narzędzi, dodaj opisane wyżej nadpisanie params.extra_body.tool_choice: "required" i używaj tego wpisu modelu wyłącznie w sesjach, w których w każdej turze oczekiwane jest wywołanie narzędzia.
• Bezpieczeństwo: modele lokalne pomijają filtry po stronie dostawcy. Ogranicz zakres działania agentów i pozostaw włączoną funkcję Compaction, aby zmniejszyć zasięg skutków wstrzykiwania promptów.

​

Powiązane materiały

• Dokumentacja konfiguracji
• Przełączanie awaryjne modeli