Конфігурація — Tools і власні providers

​

Tools

​

Профілі інструментів

​

Групи інструментів

​

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

• Перевизначення для окремого агента (agents.list[].tools.elevated) може лише додатково обмежувати.
• /elevated on|off|ask|full зберігає стан для кожної сесії; inline-директиви застосовуються лише до одного повідомлення.
• Elevated exec обходить sandbox і використовує налаштований шлях виходу (gateway типово, або node, коли ціллю exec є 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: максимальна історія викликів інструментів, що зберігається для аналізу циклів.
• warningThreshold: поріг повторюваного шаблону без прогресу для попереджень.
• criticalThreshold: вищий поріг повторення для блокування критичних циклів.
• globalCircuitBreakerThreshold: жорсткий поріг зупинки для будь-якого запуску без прогресу.
• detectors.genericRepeat: попереджати про повторні виклики того самого інструмента з тими самими аргументами.
• detectors.knownPollNoProgress: попереджати/блокувати відомі poll-інструменти (process.poll, command_status тощо).
• detectors.pingPong: попереджати/блокувати шаблони чергування пар без прогресу.
• Якщо warningThreshold >= criticalThreshold або criticalThreshold >= globalCircuitBreakerThreshold, перевірка не проходить.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
        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, // opt-in: send finished async music/video directly to the channel
      },
      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: лише ключ поточної сесії.
• tree: поточна сесія + сесії, створені поточною сесією (субагенти).
• agent: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте окремі сесії для відправників під тим самим id агента).
• all: будь-яка сесія. Націлення між агентами все одно потребує tools.agentToAgent.
• Обмеження sandbox: коли поточна сесія працює в sandbox і agents.defaults.sandbox.sessionToolsVisibility="spawned", видимість примусово встановлюється на tree, навіть якщо tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

• Вкладення підтримуються лише для runtime: "subagent". Runtime ACP їх відхиляє.
• Файли матеріалізуються в дочірньому робочому просторі в .openclaw/attachments/<uuid>/ разом із .manifest.json.
• Вміст вкладень автоматично редагується під час збереження транскрипту.
• Входи Base64 перевіряються за допомогою суворої перевірки алфавіту/вирівнювання та захисту розміру до декодування.
• Права доступу до файлів: 0700 для каталогів і 0600 для файлів.
• Очищення виконується згідно з політикою cleanup: delete завжди видаляє вкладення; keep зберігає їх лише коли retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // enable experimental update_plan
    },
  },
}

• planTool: вмикає структурований інструмент update_plan для відстеження нетривіальної багатокрокової роботи.
• Типове значення: false, якщо тільки agents.defaults.embeddedPi.executionContract (або перевизначення для окремого агента) не встановлено в "strict-agentic" для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть true, щоб примусово ввімкнути інструмент поза цією областю, або false, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5.
• Коли інструмент увімкнено, system prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й підтримувала не більше одного кроку in_progress.

​

agents.defaults.subagents

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

• model: типова модель для створених субагентів. Якщо не вказано, субагенти успадковують модель викликувача.
• allowAgents: типовий allowlist цільових id агентів для sessions_spawn, коли агент-запитувач не задає власний subagents.allowAgents (["*"] = будь-який; типово: лише той самий агент).
• runTimeoutSeconds: типовий тайм-аут (у секундах) для sessions_spawn, коли виклик інструмента не вказує runTimeoutSeconds. 0 означає відсутність тайм-ауту.
• Політика інструментів для субагентів: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Власні providers і base URL

{
  models: {
    mode: "merge", // merge (default) | 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,
          },
        ],
      },
    },
  },
}

• Використовуйте authHeader: true + headers для власних потреб автентифікації.
• Перевизначайте корінь конфігурації агента через OPENCLAW_AGENT_DIR (або PI_CODING_AGENT_DIR, застарілий псевдонім змінної середовища).
• Пріоритет злиття для provider ID, що збігаються:
  • Непорожні значення baseUrl з агентського models.json мають пріоритет.
  • Непорожні значення apiKey з агента мають пріоритет лише тоді, коли цей provider не керується через SecretRef у поточному контексті config/auth-profile.
  • Значення apiKey для provider, керованих через SecretRef, оновлюються з маркерів джерела (ENV_VAR_NAME для env-посилань, secretref-managed для file/exec-посилань) замість збереження розв’язаних секретів.
  • Значення заголовків для provider, керованих через SecretRef, оновлюються з маркерів джерела (secretref-env:ENV_VAR_NAME для env-посилань, secretref-managed для file/exec-посилань).
  • Порожні або відсутні агентські apiKey/baseUrl беруться з models.providers у конфігурації.
  • Для моделей, що збігаються, contextWindow/maxTokens використовують більше значення між явною конфігурацією та неявними значеннями каталогу.
  • Для моделей, що збігаються, contextTokens зберігає явне обмеження runtime, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни рідних метаданих моделі.
  • Використовуйте models.mode: "replace", коли хочете, щоб конфігурація повністю переписала models.json.
  • Збереження маркерів є джерельно-авторитетним: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів runtime.

​

Докладніше про поля provider

• models.mode: поведінка каталогу provider (merge або replace).
• models.providers: мапа власних providers із ключем за id provider.
  • Безпечні редагування: використовуйте openclaw config set models.providers.<id> '<json>' --strict-json --merge або openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge для додаткових оновлень. config set відмовляється від руйнівних замін, якщо ви не передасте --replace.
• models.providers.*.api: адаптер запитів (openai-completions, openai-responses, anthropic-messages, google-generative-ai тощо).
• models.providers.*.apiKey: облікові дані provider (краще через SecretRef/env-підстановку).
• models.providers.*.auth: стратегія автентифікації (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: для Ollama + openai-completions вставляє options.num_ctx у запити (типово: true).
• models.providers.*.authHeader: примусово передає облікові дані в заголовку Authorization, коли це потрібно.
• models.providers.*.baseUrl: базовий URL висхідного API.
• models.providers.*.headers: додаткові статичні заголовки для маршрутизації через proxy/tenant.
• models.providers.*.request: перевизначення транспорту для HTTP-запитів model-provider.
  • request.headers: додаткові заголовки (зливаються з типовими для provider). Значення приймають SecretRef.
  • request.auth: перевизначення стратегії автентифікації. Режими: "provider-default" (використовувати вбудовану автентифікацію provider), "authorization-bearer" (з token), "header" (з headerName, value, необов’язковим prefix).
  • request.proxy: перевизначення HTTP proxy. Режими: "env-proxy" (використовувати змінні середовища HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (з url). Обидва режими приймають необов’язковий підоб’єкт tls.
  • request.tls: перевизначення TLS для прямих з’єднань. Поля: ca, cert, key, passphrase (усі приймають SecretRef), serverName, insecureSkipVerify.
  • request.allowPrivateNetwork: коли true, дозволяє HTTPS до baseUrl, якщо DNS розв’язується в private, CGNAT або подібні діапазони, через захист HTTP fetch provider від SSRF (явне ввімкнення оператором для довірених самостійно розміщених endpoint, сумісних з OpenAI). WebSocket використовує той самий request для заголовків/TLS, але не цей SSRF-захист fetch. Типове значення false.
• models.providers.*.models: явні записи каталогу моделей provider.
• models.providers.*.models.*.contextWindow: метадані рідного вікна контексту моделі.
• models.providers.*.models.*.contextTokens: необов’язкове обмеження контексту runtime. Використовуйте це, якщо хочете менший ефективний бюджет контексту, ніж рідний contextWindow моделі.
• models.providers.*.models.*.compat.supportsDeveloperRole: необов’язкова підказка сумісності. Для api: "openai-completions" з непорожнім нерідним baseUrl (хост не api.openai.com) OpenClaw примусово встановлює це в false під час runtime. Порожній/відсутній baseUrl зберігає типову поведінку OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: необов’язкова підказка сумісності для OpenAI-сумісних chat endpoint, які приймають лише рядки. Коли true, OpenClaw перетворює масиви messages[].content, що містять лише текст, у звичайні рядки перед надсиланням запиту.
• plugins.entries.amazon-bedrock.config.discovery: корінь налаштувань авто-виявлення Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: увімкнути/вимкнути неявне виявлення.
• plugins.entries.amazon-bedrock.config.discovery.region: регіон AWS для виявлення.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: необов’язковий фільтр id provider для цільового виявлення.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: інтервал опитування для оновлення виявлення.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: резервне вікно контексту для виявлених моделей.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: резервна максимальна кількість вихідних токенів для виявлених моделей.

​

Приклади provider

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

​

Пов’язане

• Довідник конфігурації — інші ключі верхнього рівня
• Конфігурація — агенти
• Конфігурація — канали
• Tools і plugins