Konfiguracja — narzędzia i niestandardowi dostawcy

​

Narzędzia

​

Profile narzędzi

​

Grupy narzędzi

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

​

tools.elevated

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

• Nadpisanie per agent (agents.list[].tools.elevated) może tylko dalej ograniczać.
• /elevated on|off|ask|full zapisuje stan per sesja; dyrektywy inline mają zastosowanie do pojedynczej wiadomości.
• Podwyższone exec omija sandboxing i używa skonfigurowanej ścieżki ucieczki (gateway domyślnie lub node, gdy celem exec jest node).

​

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.5"],
      },
    },
  },
}

​

tools.loopDetection

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: maksymalna historia wywołań narzędzi przechowywana do analizy pętli.
• warningThreshold: próg powtarzającego się wzorca bez postępu dla ostrzeżeń.
• criticalThreshold: wyższy próg powtarzania dla blokowania krytycznych pętli.
• globalCircuitBreakerThreshold: próg twardego zatrzymania dla dowolnego przebiegu bez postępu.
• detectors.genericRepeat: ostrzeganie przy powtarzanych wywołaniach tego samego narzędzia z tymi samymi argumentami.
• detectors.knownPollNoProgress: ostrzeganie/blokowanie przy znanych narzędziach odpytywania (process.poll, command_status itp.).
• detectors.pingPong: ostrzeganie/blokowanie przy naprzemiennych wzorcach par bez postępu.
• Jeśli warningThreshold >= criticalThreshold lub criticalThreshold >= globalCircuitBreakerThreshold, walidacja kończy się niepowodzeniem.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // lub zmienna env BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // opcjonalne; pomiń dla automatycznego wykrywania
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

​

tools.media

{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // opcjonalne: wysyłaj ukończoną asynchroniczną muzykę/wideo bezpośrednio do kanału
      },
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

​

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

​

tools.sessions

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

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

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opcjonalne: ustaw true, aby zezwolić na załączniki plikowe inline
        maxTotalBytes: 5242880, // 5 MB łącznie dla wszystkich plików
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB na plik
        retainOnSessionKeep: false, // zachowaj załączniki, gdy cleanup="keep"
      },
    },
  },
}

• Załączniki są obsługiwane tylko dla runtime: "subagent". Runtime ACP je odrzuca.
• Pliki są materializowane w przestrzeni roboczej dziecka w .openclaw/attachments/<uuid>/ z plikiem .manifest.json.
• Zawartość załączników jest automatycznie redagowana przy utrwalaniu transkryptu.
• Dane wejściowe Base64 są walidowane ścisłymi kontrolami alfabetu/dopełnienia oraz zabezpieczeniem rozmiaru przed dekodowaniem.
• Uprawnienia plików to 0700 dla katalogów i 0600 dla plików.
• Czyszczenie podąża za polityką cleanup: delete zawsze usuwa załączniki; keep zachowuje je tylko wtedy, gdy retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // włącz eksperymentalne update_plan
    },
  },
}

• planTool: włącza ustrukturyzowane narzędzie update_plan do śledzenia nietrywialnej pracy wieloetapowej.
• Domyślnie: false, chyba że agents.defaults.embeddedPi.executionContract (lub nadpisanie per agent) jest ustawione na "strict-agentic" dla uruchomienia rodziny GPT-5 OpenAI lub OpenAI Codex. Ustaw true, aby wymusić włączenie narzędzia poza tym zakresem, albo false, aby pozostawić je wyłączone nawet dla uruchomień strict-agentic GPT-5.
• Gdy jest włączone, prompt systemowy dodaje także wskazówki użycia, aby model używał go tylko do istotnej pracy i utrzymywał co najwyżej jeden krok in_progress.

​

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: domyślny model dla uruchamianych podagentów. Jeśli pominięto, podagenci dziedziczą model wywołującego.
• allowAgents: domyślna lista dozwolonych identyfikatorów agentów docelowych dla sessions_spawn, gdy agent żądający nie ustawia własnego subagents.allowAgents (["*"] = dowolny; domyślnie: tylko ten sam agent).
• runTimeoutSeconds: domyślny limit czasu (sekundy) dla sessions_spawn, gdy wywołanie narzędzia pomija runTimeoutSeconds. 0 oznacza brak limitu czasu.
• Polityka narzędzi per podagent: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Niestandardowi dostawcy i baseUrl

{
  models: {
    mode: "merge", // merge (domyślnie) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

• Użyj authHeader: true + headers dla niestandardowych potrzeb uwierzytelniania.
• Nadpisz katalog główny konfiguracji agenta przez OPENCLAW_AGENT_DIR (lub PI_CODING_AGENT_DIR, starszy alias zmiennej środowiskowej).
• Pierwszeństwo scalania dla pasujących identyfikatorów dostawców:
  • Niepuste wartości baseUrl w models.json agenta mają pierwszeństwo.
  • Niepuste wartości apiKey agenta mają pierwszeństwo tylko wtedy, gdy ten 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 z markerów źródła (ENV_VAR_NAME dla referencji env, secretref-managed dla referencji file/exec) zamiast utrwalania rozstrzygniętych sekretów.
  • Wartości nagłówków dostawców zarządzanych przez SecretRef są odświeżane z markerów źródła (secretref-env:ENV_VAR_NAME dla referencji env, secretref-managed dla referencji file/exec).
  • Puste lub brakujące apiKey/baseUrl agenta używają fallbacku do models.providers w konfiguracji.
  • Dla pasujących modeli contextWindow/maxTokens używają wyższej wartości z jawnej konfiguracji i niejawnych wartości katalogu.
  • Dla pasujących modeli contextTokens zachowuje jawny limit runtime, gdy istnieje; użyj tego, aby ograniczyć efektywny kontekst bez zmiany natywnych metadanych modelu.
  • Użyj models.mode: "replace", gdy chcesz, aby konfiguracja całkowicie przepisała models.json.
  • Utrwalanie markerów jest autorytatywne względem źródła: markery są zapisywane z migawki aktywnej konfiguracji źródłowej (przed rozstrzyganiem), a nie z rozstrzygniętych wartości sekretów w czasie działania.

​

Szczegóły pól dostawcy

• models.mode: zachowanie katalogu dostawców (merge lub replace).
• models.providers: mapa niestandardowych dostawców kluczowana identyfikatorem dostawcy.
  • Bezpieczne edycje: używaj openclaw config set models.providers.<id> '<json>' --strict-json --merge lub openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge do aktualizacji addytywnych. config set odmawia destrukcyjnych zastąpień, jeśli nie przekażesz --replace.
• models.providers.*.api: adapter żądań (openai-completions, openai-responses, anthropic-messages, google-generative-ai itd.).
• models.providers.*.apiKey: poświadczenie dostawcy (preferowane SecretRef/podstawienie env).
• models.providers.*.auth: strategia uwierzytelniania (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: dla Ollama + openai-completions wstrzykuje options.num_ctx do żądań (domyślnie: true).
• models.providers.*.authHeader: wymusza przesyłanie poświadczeń w nagłówku Authorization, gdy jest to wymagane.
• models.providers.*.baseUrl: bazowy URL nadrzędnego API.
• models.providers.*.headers: dodatkowe statyczne nagłówki do routingu proxy/dzierżawy.
• models.providers.*.request: nadpisania transportu dla żądań HTTP dostawcy modeli.
  • request.headers: dodatkowe nagłówki (scalane z domyślnymi nagłówkami 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 ma wartość true, zezwala na HTTPS do baseUrl, gdy DNS rozstrzyga do zakresów prywatnych, CGNAT lub podobnych, przez ochronę pobierania HTTP dostawcy (świadoma zgoda operatora dla zaufanych self-hosted punktów końcowych zgodnych z OpenAI). WebSocket używa tego samego request dla nagłówków/TLS, ale nie dla tej ochrony SSRF pobierania. Domyślnie false.
• models.providers.*.models: jawne wpisy katalogu modeli dostawcy.
• models.providers.*.models.*.contextWindow: natywne metadane okna kontekstu modelu.
• models.providers.*.models.*.contextTokens: opcjonalny limit kontekstu runtime. Użyj tego, gdy chcesz mniejszy efektywny budżet kontekstu niż natywne contextWindow modelu.
• 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 runtime wartość false. Puste/pominięte baseUrl zachowuje domyślne zachowanie OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: opcjonalna wskazówka zgodności dla punktów końcowych czatu zgodnych z OpenAI obsługujących tylko ciągi znaków. Gdy ma wartość true, OpenClaw spłaszcza czysto tekstowe tablice messages[].content do zwykłych ciągów przed wysłaniem żądania.
• plugins.entries.amazon-bedrock.config.discovery: główny poziom ustawień automatycznego wykrywania Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: włącza/wyłącza niejawne wykrywanie.
• 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 odświeżania wykrywania.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: zapasowe okno kontekstu dla wykrytych modeli.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: zapasowa maksymalna liczba tokenów wyjściowych dla wykrytych modeli.

​

Przykłady dostawców

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (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: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

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

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

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

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

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

{
  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", "image"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

​

Powiązane

• Odwołanie do konfiguracji — inne klucze najwyższego poziomu
• Konfiguracja — agenci
• Konfiguracja — kanały
• Narzędzia i Pluginy