Konfiguracja — narzędzia i dostawcy niestandardowi

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

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

Wpis CLI (type: "cli"):

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

Pola wspólne:

• capabilities: opcjonalna lista (image, audio, video). Każdy Plugin dostawcy deklaruje własny domyślny zestaw możliwości; na przykład dołączony dostawca openai domyślnie obsługuje obraz i dźwięk, anthropic/minimax — obraz, google — obraz, dźwięk i wideo, a groq — dźwięk.
• prompt, maxChars, maxBytes, timeoutSeconds, language: nadpisania dla poszczególnych wpisów.
• tools.media.image.timeoutSeconds oraz odpowiadające mu wpisy timeoutSeconds modelu obrazu mają również zastosowanie, gdy agent wywołuje jawne narzędzie image. W przypadku rozpoznawania obrazów ten limit czasu dotyczy samego żądania i nie jest pomniejszany o wcześniejsze prace przygotowawcze.
• W przypadku niepowodzenia używany jest następny wpis.

Uwierzytelnianie dostawcy odbywa się w standardowej kolejności: 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ą obsługiwane za pośrednictwem sesji żądającego, dzięki czemu agent otrzymuje wynik, decyduje, jak przekazać go użytkownikowi, i używa narzędzia wiadomości, gdy wymaga tego dostarczenie do źródła.

• self: tylko klucz bieżącej sesji.
• tree: bieżąca sesja oraz sesje utworzone przez bieżącą sesję (podagenci).
• agent: dowolna sesja należąca do identyfikatora bieżącego agenta (może obejmować innych użytkowników, jeśli sesje poszczególnych nadawców są uruchamiane z tym samym identyfikatorem agenta).
• all: dowolna sesja. Wskazywanie między agentami nadal wymaga tools.agentToAgent.
• Ograniczenie piaskownicy: gdy bieżąca sesja działa w piaskownicy, a agents.defaults.sandbox.sessionToolsVisibility="spawned" (wartość domyślna), widoczność jest wymuszana na tree, nawet jeśli ustawiono tools.sessions.visibility="all".
• Gdy wartość nie wynosi all, sessions_list zawiera zwięzłe pole visibility opisujące obowiązujący tryb oraz ostrzeżenie, że niektóre sesje spoza bieżącego zakresu mogą zostać pominięte.

• Załączniki wymagają ustawienia enabled: true.
• Załączniki podagenta są zapisywane w obszarze roboczym procesu potomnego w .openclaw/attachments/<uuid>/ wraz z plikiem .manifest.json.
• Załączniki ACP mogą zawierać wyłącznie obrazy i są przekazywane bezpośrednio do środowiska wykonawczego ACP po spełnieniu tych samych limitów liczby plików, liczby bajtów na plik i łącznej liczby bajtów.
• Zawartość załączników jest automatycznie redagowana w utrwalanym zapisie transkrypcji.
• Dane wejściowe Base64 są sprawdzane pod kątem ścisłej zgodności alfabetu i dopełnienia, a przed dekodowaniem stosowane jest zabezpieczenie rozmiaru.
• Uprawnienia plików załączników podagenta wynoszą 0700 dla katalogów i 0600 dla plików.
• Czyszczenie podagenta jest zgodne z zasadą cleanup: delete zawsze usuwa załączniki; keep zachowuje je tylko wtedy, gdy ustawiono retainOnSessionKeep: true.

• Użyj authHeader: true wraz z headers, jeśli potrzebujesz niestandardowego uwierzytelniania.
• Zastąp katalog główny konfiguracji agenta za pomocą OPENCLAW_AGENT_DIR.
• Kolejność scalania dla zgodnych identyfikatorów dostawców:
  • Niepuste wartości baseUrl w pliku models.json agenta mają pierwszeństwo.
  • Niepuste wartości apiKey agenta mają pierwszeństwo tylko wtedy, gdy dany dostawca nie jest zarządzany przez SecretRef w bieżącym kontekście konfiguracji/profilu uwierzytelniania.
  • Wartości apiKey dostawców zarządzanych przez SecretRef są odświeżane na podstawie znaczników źródłowych (ENV_VAR_NAME dla odwołań do zmiennych środowiskowych, secretref-managed dla odwołań do plików/poleceń) zamiast utrwalania rozwiązanych sekretów.
  • Wartości nagłówków dostawców zarządzanych przez SecretRef są odświeżane na podstawie znaczników źródłowych (secretref-env:ENV_VAR_NAME dla odwołań do zmiennych środowiskowych, secretref-managed dla odwołań do plików/poleceń).
  • Puste lub brakujące wartości apiKey/baseUrl agenta korzystają z wartości zastępczych z models.providers w konfiguracji.
  • Dla zgodnych wartości contextWindow/maxTokens modelu pierwszeństwo ma jawna wartość konfiguracji, jeśli jest obecna i prawidłowa (dodatnia liczba skończona); w przeciwnym razie używana jest niejawna/wygenerowana wartość katalogowa.
  • Zgodna wartość contextTokens modelu podlega tej samej zasadzie pierwszeństwa wartości jawnej, a w przeciwnym razie niejawnej; użyj jej, aby ograniczyć efektywny kontekst bez zmieniania natywnych metadanych modelu.
  • Katalogi Pluginów dostawców są przechowywane jako wygenerowane fragmenty katalogu należące do Pluginu w stanie Pluginu agenta.
  • Użyj models.mode: "replace", jeśli konfiguracja ma całkowicie nadpisać plik models.json i pominąć scalanie fragmentów katalogu należących do Pluginów.
  • Utrwalanie znaczników jest podporządkowane źródłu: znaczniki są zapisywane z aktywnej migawki konfiguracji źródłowej (sprzed rozwiązania), a nie z rozwiązanych wartości sekretów środowiska wykonawczego.

• models.mode: sposób działania katalogu dostawców (merge lub replace).
• models.providers: niestandardowa mapa dostawców indeksowana według identyfikatora dostawcy.
  • Bezpieczne zmiany: do aktualizacji addytywnych użyj openclaw config set models.providers.<id> '<json>' --strict-json --merge lub openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge. Polecenie config set odrzuca destrukcyjne zastąpienia, chyba że przekażesz --replace.

• models.providers.*.api: adapter żądań (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). W przypadku 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 ustawieniem baseUrl, ale bez api, domyślnie korzysta z openai-completions; ustaw openai-responses tylko wtedy, gdy backend obsługuje /v1/responses.
• models.providers.*.apiKey: dane uwierzytelniające dostawcy (preferowane jest podstawianie SecretRef/zmiennej środowiskowej).
• models.providers.*.auth: strategia uwierzytelniania (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: domyślne natywne okno kontekstu dla modeli tego dostawcy, gdy wpis modelu nie ustawia contextWindow.
• models.providers.*.contextTokens: domyślny efektywny limit kontekstu środowiska wykonawczego dla modeli tego dostawcy, gdy wpis modelu nie ustawia contextTokens.
• models.providers.*.maxTokens: domyślny limit tokenów wyjściowych dla modeli tego dostawcy, gdy wpis modelu nie ustawia maxTokens.
• models.providers.*.timeoutSeconds: opcjonalny limit czasu żądania HTTP modelu dla danego dostawcy w sekundach, obejmujący nawiązanie połączenia, nagłówki, treść i obsługę przerwania całego żądania.
• models.providers.*.injectNumCtxForOpenAICompat: dla Ollama wraz z openai-completions wstawia options.num_ctx do żądań (domyślnie: true).
• models.providers.*.authHeader: wymusza przesyłanie danych uwierzytelniających w nagłówku Authorization, gdy jest to wymagane.
• models.providers.*.baseUrl: bazowy adres URL nadrzędnego API.
• models.providers.*.headers: dodatkowe statyczne nagłówki do trasowania przez serwer proxy lub dzierżawcę.

models.providers.*.request: nadpisania transportu żądań HTTP do dostawcy modelu.

• 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życie wbudowanego uwierzytelniania dostawcy), "authorization-bearer" (z token), "header" (z headerName, value i opcjonalnym prefix).
• request.proxy: nadpisanie serwera proxy HTTP. Tryby: "env-proxy" (użycie 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 ma wartość true, zezwala żądaniom HTTP do dostawcy modelu na dostęp do zakresów prywatnych, CGNAT lub podobnych poprzez zabezpieczenie pobierania HTTP dostawcy. Bazowe adresy URL niestandardowych/lokalnych dostawców już ufają dokładnie skonfigurowanemu źródłu, z wyjątkiem źródeł metadanych/link-local, które pozostają zablokowane bez jawnego włączenia. Ustaw tę opcję na false, aby wyłączyć zaufanie do dokładnego źródła. WebSocket używa tego samego ustawienia request dla nagłówków/TLS, ale nie korzysta z tej bramy SSRF pobierania. Wartość domyślna: false.

• models.providers.*.models: jawne wpisy katalogu modeli dostawcy.
• models.providers.*.models.*.input: modalności wejściowe modelu. Użyj ["text"] dla modeli obsługujących wyłącznie tekst oraz ["text", "image"] dla modeli z natywną obsługą obrazów/wizji. Załączniki obrazów są wstawiane do tur agenta tylko wtedy, gdy wybrany model jest oznaczony jako obsługujący obrazy.
• models.providers.*.models.*.contextWindow: metadane natywnego okna kontekstu modelu. Ta wartość zastępuje contextWindow na poziomie dostawcy dla tego modelu.
• models.providers.*.models.*.contextTokens: opcjonalny limit kontekstu środowiska wykonawczego. Ta wartość zastępuje contextTokens na poziomie dostawcy; użyj jej, jeśli potrzebujesz mniejszego efektywnego budżetu kontekstu niż natywne contextWindow modelu; polecenie openclaw models list wyświetla obie wartości, gdy się różnią.
• models.providers.*.models.*.compat.supportsDeveloperRole: opcjonalna wskazówka dotycząca zgodności. Dla api: "openai-completions" z niepustym, nienatywnym baseUrl (host innym niż api.openai.com) OpenClaw wymusza wartość false w środowisku wykonawczym. Puste/pominięte baseUrl zachowuje domyślne działanie OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: opcjonalna wskazówka dotycząca zgodności dla punktów końcowych czatu zgodnych z OpenAI, które obsługują wyłącznie ciągi znaków. Gdy ma wartość true, OpenClaw spłaszcza tablice messages[].content zawierające wyłącznie tekst do zwykłych ciągów znaków przed wysłaniem żądania.
• models.providers.*.models.*.compat.strictMessageKeys: opcjonalna wskazówka dotycząca zgodności dla rygorystycznych punktów końcowych czatu zgodnych z OpenAI. Gdy ma wartość true, OpenClaw ogranicza wychodzące obiekty wiadomości Chat Completions do pól role i content przed wysłaniem żądania.
• models.providers.*.models.*.compat.thinkingFormat: opcjonalna wskazówka dotycząca ładunku rozumowania. Użyj "together" dla reasoning.enabled w stylu Together, "qwen" dla ustawienia enable_thinking najwyższego poziomu lub "qwen-chat-template" dla chat_template_kwargs.enable_thinking na zgodnych z OpenAI serwerach rodziny Qwen, które obsługują argumenty słów kluczowych szablonu czatu na poziomie żądania, takich jak vLLM. Skonfigurowane modele Qwen w vLLM udostępniają dla tych formatów binarne opcje /think (off, on).
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: opcjonalna wskazówka dotycząca zgodności dla backendów Chat Completions w stylu DeepSeek, które wymagają zachowania reasoning_content w poprzednich wiadomościach asystenta podczas ponownego odtwarzania. Gdy ma wartość true, OpenClaw zachowuje to pole w wychodzących wiadomościach asystenta. Użyj tej opcji podczas podłączania niestandardowego serwera proxy zgodnego z DeepSeek, który odrzuca żądania po usunięciu rozumowania. Wartość domyślna: false.

• plugins.entries.amazon-bedrock.config.discovery: katalog główny ustawień automatycznego wykrywania Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: włącza lub wyłącza niejawne wykrywanie.
• plugins.entries.amazon-bedrock.config.discovery.region: region AWS używany 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 w celu odświeżania wyników 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.

Oficjalny zewnętrzny Plugin dostawcy cerebras może skonfigurować tę opcję za pomocą openclaw onboard --auth-choice cerebras-api-key. Jawnej konfiguracji dostawcy używaj tylko do zastępowania 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 do bezpośredniego połączenia z Z.AI.

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

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

Zobacz Modele lokalne. W skrócie: uruchom duży model lokalny za pośrednictwem interfejsu Responses API LM Studio na wydajnym sprzęcie; zachowaj scalone modele hostowane jako rozwiązanie awaryjne.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            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 wskazuje M3 i obejmuje również warianty M2.7. Na ścieżce strumieniowej zgodnej z Anthropic OpenClaw domyślnie wyłącza wnioskowanie MiniMax M2.x, chyba że jawnie ustawisz thinking; MiniMax-M3 (oraz M3.x) domyślnie pozostaje na ścieżce pominiętego/adaptacyjnego wnioskowania dostawcy. /fast on lub params.fastMode: true zamienia 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 chińskiego punktu końcowego: baseUrl: "https://api.moonshot.cn/v1" lub openclaw onboard --auth-choice moonshot-api-key-cn.

Natywne punkty końcowe Moonshot deklarują zgodność ze strumieniowym raportowaniem użycia we współdzielonym transporcie openai-completions, a OpenClaw uzależnia tę funkcję od możliwości punktu końcowego, a nie wyłącznie od wbudowanego identyfikatora 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żywaj odwołań opencode/... dla katalogu Zen albo 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 adres URL powinien pomijać /v1 (klient Anthropic dodaje go automatycznie). 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. Odwołania do modeli używają kanonicznego identyfikatora dostawcy zai/*. 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 programowania: https://api.z.ai/api/coding/paas/v4
• Domyślna opcja uwierzytelniania zai-api-key sprawdza klucz i automatycznie wykrywa, do którego punktu końcowego należy (jeśli wykrycie nie jest jednoznaczne, wyświetla monit z domyślnym wyborem Global). Dostępne są również osobne opcje uwierzytelniania CN i Coding-Plan umożliwiające jawny wybór.
• Dla ogólnego punktu końcowego zdefiniuj niestandardowego dostawcę z nadpisanym bazowym adresem URL.