Konfiguracja — narzędzia i niestandardowi dostawcy

Wpis dostawcy (type: "provider" albo pominięte):

• provider: identyfikator dostawcy API (openai, anthropic, google/gemini, groq itd.)
• model: nadpisanie identyfikatora modelu
• profile / preferredProfile: wybór profilu auth-profiles.json

Wpis CLI (type: "cli"):

• command: plik wykonywalny do uruchomienia
• args: argumenty szablonowe (obsługuje {{MediaPath}}, {{Prompt}}, {{MaxChars}} itd.; openclaw doctor --fix migruje przestarzałe placeholdery {input} do {{MediaPath}})

Pola wspólne:

• capabilities: opcjonalna lista (image, audio, video). Domyślnie: openai/anthropic/minimax → obraz, google → obraz+audio+wideo, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: nadpisania dla pojedynczego wpisu.
• tools.media.image.timeoutSeconds oraz pasujące wpisy timeoutSeconds modelu obrazu mają też zastosowanie, gdy agent wywołuje jawne narzędzie image.
• Niepowodzenia powodują przejście do następnego wpisu.

Uwierzytelnianie dostawcy stosuje standardową kolejność: auth-profiles.json → zmienne środowiskowe → models.providers.*.apiKey.

Pola ukończenia asynchronicznego:

• asyncCompletion.directSend: przestarzała flaga zgodności. Ukończone asynchroniczne zadania multimedialne pozostają pośredniczone przez sesję żądającego, aby agent otrzymał wynik, zdecydował, jak przekazać go użytkownikowi, i użył narzędzia wiadomości, gdy wymaga tego dostarczenie ze źródła.

• self: tylko klucz bieżącej sesji.
• tree: bieżąca sesja + sesje utworzone przez bieżącą sesję (subagenci).
• agent: dowolna sesja należąca do bieżącego identyfikatora agenta (może obejmować innych użytkowników, jeśli uruchamiasz sesje dla poszczególnych nadawców pod tym samym identyfikatorem agenta).
• all: dowolna sesja. Kierowanie między agentami nadal wymaga tools.agentToAgent.
• Ograniczenie piaskownicy: gdy bieżąca sesja działa w piaskownicy i agents.defaults.sandbox.sessionToolsVisibility="spawned", widoczność jest wymuszana na tree, nawet jeśli tools.sessions.visibility="all".

• Załączniki są obsługiwane tylko dla runtime: "subagent". Środowisko uruchomieniowe ACP je odrzuca.
• Pliki są materializowane w podrzędnym obszarze roboczym w .openclaw/attachments/<uuid>/ z plikiem .manifest.json.
• Zawartość załączników jest automatycznie redagowana przy utrwalaniu transkrypcji.
• Dane wejściowe Base64 są weryfikowane za pomocą rygorystycznych kontroli alfabetu/dopełnienia oraz zabezpieczenia rozmiaru przed dekodowaniem.
• Uprawnienia plików to 0700 dla katalogów i 0600 dla plików.
• Czyszczenie jest zgodne z polityką cleanup: delete zawsze usuwa załączniki; keep zachowuje je tylko wtedy, gdy retainOnSessionKeep: true.

• Użyj authHeader: true + headers w przypadku niestandardowych potrzeb uwierzytelniania.
• Nadpisz katalog główny konfiguracji agenta za pomocą OPENCLAW_AGENT_DIR (albo PI_CODING_AGENT_DIR, starszego aliasu zmiennej środowiskowej).
• Pierwszeństwo scalania dla pasujących identyfikatorów dostawców:
  • Niepuste wartości baseUrl w models.json agenta wygrywają.
  • Niepuste wartości apiKey agenta wygrywają tylko wtedy, gdy ten dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście konfiguracji/profilu uwierzytelniania.
  • Wartości apiKey dostawcy zarządzane przez SecretRef są odświeżane ze znaczników źródłowych (ENV_VAR_NAME dla odwołań do zmiennych środowiskowych, secretref-managed dla odwołań do plików/wykonań), zamiast utrwalać rozwiązane sekrety.
  • Wartości nagłówków dostawcy zarządzane przez SecretRef są odświeżane ze znaczników źródłowych (secretref-env:ENV_VAR_NAME dla odwołań do zmiennych środowiskowych, secretref-managed dla odwołań do plików/wykonań).
  • Puste lub brakujące apiKey/baseUrl agenta korzystają z wartości zastępczych z models.providers w konfiguracji.
  • Pasujące contextWindow/maxTokens modelu używają wyższej wartości między jawną konfiguracją a niejawnymi wartościami katalogu.
  • Pasujące contextTokens modelu zachowuje jawny limit środowiska uruchomieniowego, gdy jest obecny; użyj go, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu.
  • Użyj models.mode: "replace", gdy chcesz, aby konfiguracja w pełni przepisała models.json.
  • Utrwalanie znaczników jest autorytatywne względem źródła: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (przed rozwiązaniem), a nie z rozwiązanych wartości sekretów środowiska uruchomieniowego.

• models.mode: zachowanie katalogu dostawców (merge albo replace).
• models.providers: mapa niestandardowych dostawców indeksowana identyfikatorem dostawcy.
  • Bezpieczne edycje: użyj openclaw config set models.providers.<id> '<json>' --strict-json --merge albo openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge do aktualizacji addytywnych. config set odmawia destrukcyjnych zastąpień, chyba że przekażesz --replace.

• models.providers.*.api: adapter żądań (openai-completions, openai-responses, anthropic-messages, google-generative-ai itd.). Dla samodzielnie hostowanych backendów /v1/chat/completions, takich jak MLX, vLLM, SGLang i większość lokalnych serwerów zgodnych z OpenAI, użyj openai-completions. Niestandardowy dostawca z baseUrl, ale bez api, domyślnie używa openai-completions; ustaw openai-responses tylko wtedy, gdy backend obsługuje /v1/responses.
• models.providers.*.apiKey: dane uwierzytelniające dostawcy (preferuj SecretRef/podstawienie ze zmiennych środowiskowych).
• models.providers.*.auth: strategia uwierzytelniania (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: domyślne natywne okno kontekstu dla modeli u tego dostawcy, gdy wpis modelu nie ustawia contextWindow.
• models.providers.*.contextTokens: domyślny efektywny limit kontekstu środowiska uruchomieniowego dla modeli u tego dostawcy, gdy wpis modelu nie ustawia contextTokens.
• models.providers.*.maxTokens: domyślny limit tokenów wyjściowych dla modeli u tego dostawcy, gdy wpis modelu nie ustawia maxTokens.
• models.providers.*.timeoutSeconds: opcjonalny limit czasu żądania HTTP modelu dla konkretnego dostawcy, w sekundach, obejmujący połączenie, nagłówki, treść i całkowitą obsługę przerwania żądania.
• models.providers.*.injectNumCtxForOpenAICompat: dla Ollama + openai-completions wstrzykuje options.num_ctx do żądań (domyślnie: true).
• models.providers.*.authHeader: wymusza transport danych uwierzytelniających w nagłówku Authorization, gdy jest wymagany.
• models.providers.*.baseUrl: bazowy adres URL upstream API.
• models.providers.*.headers: dodatkowe statyczne nagłówki do trasowania proxy/dzierżawcy.

models.providers.*.request: nadpisania transportu dla żądań HTTP dostawcy modeli.

• request.headers: dodatkowe nagłówki (scalane z wartościami domyślnymi dostawcy). Wartości akceptują SecretRef.
• request.auth: nadpisanie strategii uwierzytelniania. Tryby: "provider-default" (użyj wbudowanego uwierzytelniania dostawcy), "authorization-bearer" (z token), "header" (z headerName, value, opcjonalnym prefix).
• request.proxy: nadpisanie proxy HTTP. Tryby: "env-proxy" (użyj zmiennych środowiskowych HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (z url). Oba tryby akceptują opcjonalny podobiekt tls.
• request.tls: nadpisanie TLS dla połączeń bezpośrednich. Pola: ca, cert, key, passphrase (wszystkie akceptują SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: gdy true, zezwala na HTTPS do baseUrl, gdy DNS rozwiązuje się do zakresów prywatnych, CGNAT lub podobnych, przez zabezpieczenie fetch HTTP dostawcy (operatorska zgoda dla zaufanych, samodzielnie hostowanych endpointów zgodnych z OpenAI). Adresy URL strumieni dostawcy modeli w local loopback, takie jak localhost, 127.0.0.1 i [::1], są dozwolone automatycznie, chyba że jawnie ustawiono to na false; hosty LAN, tailnet i prywatne hosty DNS nadal wymagają zgody. WebSocket używa tego samego request dla nagłówków/TLS, ale nie tej bramki SSRF fetch. Domyślnie false.

• models.providers.*.models: jawne wpisy katalogu modeli dostawcy.
• models.providers.*.models.*.input: modalności wejściowe modelu. Użyj ["text"] dla modeli wyłącznie tekstowych i ["text", "image"] dla natywnych modeli obrazu/wizji. Załączniki obrazów są wstrzykiwane do tur agenta tylko wtedy, gdy wybrany model jest oznaczony jako obsługujący obrazy.
• models.providers.*.models.*.contextWindow: metadane natywnego okna kontekstu modelu. To nadpisuje contextWindow na poziomie dostawcy dla tego modelu.
• models.providers.*.models.*.contextTokens: opcjonalny limit kontekstu środowiska uruchomieniowego. To nadpisuje contextTokens na poziomie dostawcy; użyj tego, gdy chcesz mniejszego efektywnego budżetu kontekstu niż natywne contextWindow modelu; openclaw models list pokazuje obie wartości, gdy się różnią.
• models.providers.*.models.*.compat.supportsDeveloperRole: opcjonalna wskazówka zgodności. Dla api: "openai-completions" z niepustym nienatywnym baseUrl (host inny niż api.openai.com) OpenClaw wymusza w środowisku uruchomieniowym wartość false. Puste/pominięte baseUrl zachowuje domyślne zachowanie OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: opcjonalna wskazówka zgodności dla wyłącznie tekstowych endpointów czatu zgodnych z OpenAI. Gdy true, OpenClaw spłaszcza czysto tekstowe tablice messages[].content do zwykłych ciągów znaków przed wysłaniem żądania.

• plugins.entries.amazon-bedrock.config.discovery: katalog główny ustawień automatycznego wykrywania Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: włączanie/wyłączanie niejawnego wykrywania.
• plugins.entries.amazon-bedrock.config.discovery.region: region AWS do wykrywania.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: opcjonalny filtr identyfikatora dostawcy do ukierunkowanego wykrywania.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: interwał odpytywania do odświeżania wykrywania.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: zastępcze okno kontekstu dla wykrytych modeli.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: zastępczy maksymalny limit tokenów wyjściowych dla wykrytych modeli.

Dołączony Plugin dostawcy cerebras może skonfigurować to przez openclaw onboard --auth-choice cerebras-api-key. Używaj jawnej konfiguracji dostawcy tylko podczas nadpisywania wartości domyślnych.

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/gpt-oss-120b"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },
        ],
      },
    },
  },
}

Użyj cerebras/zai-glm-4.7 dla Cerebras; zai/glm-4.7 dla bezpośredniego Z.AI.

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi/kimi-code" },
      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
    },
  },
}

Wbudowany Provider zgodny z Anthropic. Skrót: openclaw onboard --auth-choice kimi-code-api-key.

Zobacz Modele lokalne. W skrócie: uruchom duży model lokalny przez LM Studio Responses API na wydajnym sprzęcie; zachowaj scalone modele hostowane jako fallback.

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

Ustaw MINIMAX_API_KEY. Skróty: openclaw onboard --auth-choice minimax-global-api lub openclaw onboard --auth-choice minimax-cn-api. Katalog modeli domyślnie zawiera tylko M2.7. Na ścieżce streamingu zgodnej z Anthropic OpenClaw domyślnie wyłącza myślenie MiniMax, chyba że jawnie ustawisz thinking samodzielnie. /fast on lub params.fastMode: true przepisuje MiniMax-M2.7 na MiniMax-M2.7-highspeed.

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.6" },
      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.6",
            name: "Kimi K2.6",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
        ],
      },
    },
  },
}

Dla punktu końcowego w Chinach: baseUrl: "https://api.moonshot.cn/v1" lub openclaw onboard --auth-choice moonshot-api-key-cn.

Natywne punkty końcowe Moonshot deklarują zgodność użycia streamingu na współdzielonym transporcie openai-completions, a OpenClaw opiera to na możliwościach punktu końcowego, nie tylko na identyfikatorze wbudowanego dostawcy.

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

Ustaw OPENCODE_API_KEY (lub OPENCODE_ZEN_API_KEY). Użyj odwołań opencode/... dla katalogu Zen albo odwołań opencode-go/... dla katalogu Go. Skrót: openclaw onboard --auth-choice opencode-zen lub openclaw onboard --auth-choice opencode-go.

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}

Bazowy URL powinien pomijać /v1 (klient Anthropic dodaje go). Skrót: openclaw onboard --auth-choice synthetic-api-key.

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}

Ustaw ZAI_API_KEY. z.ai/* i z-ai/* są akceptowanymi aliasami. Skrót: openclaw onboard --auth-choice zai-api-key.

• Ogólny punkt końcowy: https://api.z.ai/api/paas/v4
• Punkt końcowy do kodowania (domyślny): https://api.z.ai/api/coding/paas/v4
• Dla ogólnego punktu końcowego zdefiniuj niestandardowego providera z nadpisaniem bazowego URL.