Конфігурація — інструменти та користувацькі провайдери

Запис провайдера (type: "provider" або не вказано):

• provider: ідентифікатор API-провайдера (openai, anthropic, google/gemini, groq тощо)
• model: перевизначення ідентифікатора моделі
• profile / preferredProfile: вибір профілю з auth-profiles.json

Запис CLI (type: "cli"):

• command: виконувана команда
• args: шаблонні аргументи (підтримує {{MediaPath}}, {{Prompt}}, {{MaxChars}} тощо; openclaw doctor --fix переносить застарілі заповнювачі {input} до {{MediaPath}})

Спільні поля:

• capabilities: необов’язковий список (image, audio, video). Кожен Plugin провайдера оголошує власний стандартний набір можливостей; наприклад, комплектний провайдер openai за замовчуванням підтримує зображення й аудіо, anthropic/minimax — зображення, google — зображення, аудіо й відео, а groq — аудіо.
• prompt, maxChars, maxBytes, timeoutSeconds, language: перевизначення для окремого запису.
• tools.media.image.timeoutSeconds і відповідні записи timeoutSeconds моделі зображень також застосовуються, коли агент викликає явний інструмент image. Для розпізнавання зображень цей тайм-аут застосовується до самого запиту й не скорочується через попередню підготовчу роботу.
• У разі помилки використовується наступний запис.

Автентифікація провайдера виконується у стандартному порядку: auth-profiles.json → змінні середовища → models.providers.*.apiKey.

Поля асинхронного завершення:

• asyncCompletion.directSend: застарілий прапорець сумісності. Завершені асинхронні завдання обробки медіафайлів і надалі опосередковуються сеансом запитувача, щоб агент отримав результат, вирішив, як повідомити його користувачеві, і скористався інструментом повідомлень, якщо цього вимагає доставка до джерела.

• self: лише ключ поточного сеансу.
• tree: поточний сеанс і сеанси, породжені поточним сеансом (субагенти).
• agent: будь-який сеанс, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо сеанси для кожного відправника виконуються з тим самим ідентифікатором агента).
• all: будь-який сеанс. Для вибору цілі серед інших агентів усе одно потрібен tools.agentToAgent.
• Обмеження пісочниці: коли поточний сеанс працює в пісочниці та agents.defaults.sandbox.sessionToolsVisibility="spawned" (стандартне значення), видимість примусово встановлюється на tree, навіть якщо tools.sessions.visibility="all".
• Якщо значення не дорівнює all, sessions_list містить компактне поле visibility, яке описує фактичний режим, і попередження про те, що деякі сеанси поза поточною областю можуть бути пропущені.

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

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

• models.mode: поведінка каталогу постачальників (merge або replace).
• models.providers: власна мапа постачальників із ключами за ідентифікатором постачальника.
  • Безпечне редагування: використовуйте 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, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Для самостійно розміщених серверних систем із /v1/chat/completions, як-от MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйте openai-completions. Власний постачальник із baseUrl, але без api, за замовчуванням використовує openai-completions; установлюйте openai-responses, лише якщо серверна система підтримує /v1/responses.
• models.providers.*.apiKey: облікові дані постачальника (надавайте перевагу SecretRef або підстановці змінної середовища).
• models.providers.*.auth: стратегія автентифікації (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: типове власне вікно контексту для моделей цього постачальника, якщо запис моделі не задає contextWindow.
• models.providers.*.contextTokens: типове ефективне обмеження контексту середовища виконання для моделей цього постачальника, якщо запис моделі не задає contextTokens.
• models.providers.*.maxTokens: типове обмеження кількості токенів виведення для моделей цього постачальника, якщо запис моделі не задає maxTokens.
• models.providers.*.timeoutSeconds: необов’язковий для кожного постачальника час очікування HTTP-запиту до моделі в секундах, включно з підключенням, заголовками, тілом і обробкою переривання всього запиту.
• models.providers.*.injectNumCtxForOpenAICompat: для Ollama + openai-completions додає options.num_ctx до запитів (типове значення: true).
• models.providers.*.authHeader: примусово передавати облікові дані в заголовку Authorization, коли це потрібно.
• models.providers.*.baseUrl: базова URL-адреса висхідного API.
• models.providers.*.headers: додаткові статичні заголовки для маршрутизації через проксі або орендаря.

models.providers.*.request: перевизначення транспорту для HTTP-запитів до постачальника моделі.

• request.headers: додаткові заголовки (об’єднуються з типовими значеннями постачальника). Значення підтримують SecretRef.
• request.auth: перевизначення стратегії автентифікації. Режими: "provider-default" (використовувати вбудовану автентифікацію постачальника), "authorization-bearer" (із token), "header" (із headerName, value і необов’язковим prefix).
• request.proxy: перевизначення HTTP-проксі. Режими: "env-proxy" (використовувати змінні середовища HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (із url). Обидва режими підтримують необов’язковий вкладений об’єкт tls.
• request.tls: перевизначення TLS для прямих з’єднань. Поля: ca, cert, key, passphrase (усі підтримують SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: якщо true, дозволяє HTTP-запити до постачальника моделі в приватні, CGNAT або подібні діапазони через захист HTTP-запитів постачальника. Базові URL-адреси власних або локальних постачальників уже довіряють точно налаштованому джерелу, крім джерел метаданих або локальної адресації каналу, які залишаються заблокованими без явної згоди. Установіть false, щоб відмовитися від довіри до точного джерела. WebSocket використовує той самий request для заголовків і TLS, але не цей захист запитів від SSRF. Типове значення — false.

• models.providers.*.models: явні записи каталогу моделей постачальника.
• models.providers.*.models.*.input: модальності вхідних даних моделі. Використовуйте ["text"] для моделей лише з текстовим введенням і ["text", "image"] для моделей із власною підтримкою зображень або комп’ютерного зору. Вкладені зображення додаються до ходів агента, лише якщо вибрану модель позначено як здатну обробляти зображення.
• models.providers.*.models.*.contextWindow: метадані власного вікна контексту моделі. Це перевизначає contextWindow рівня постачальника для цієї моделі.
• models.providers.*.models.*.contextTokens: необов’язкове обмеження контексту середовища виконання. Це перевизначає contextTokens рівня постачальника; використовуйте його, якщо потрібен менший ефективний бюджет контексту, ніж власне значення contextWindow моделі; openclaw models list показує обидва значення, якщо вони відрізняються.
• models.providers.*.models.*.compat.supportsDeveloperRole: необов’язкова підказка сумісності. Для api: "openai-completions" із непорожнім невласним baseUrl (вузол не api.openai.com) OpenClaw примусово встановлює false під час виконання. Порожній або пропущений baseUrl зберігає типову поведінку OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: необов’язкова підказка сумісності для сумісних з OpenAI кінцевих точок чату, які підтримують лише рядки. Якщо true, OpenClaw перетворює масиви messages[].content, що містять лише текст, на звичайні рядки перед надсиланням запиту.
• models.providers.*.models.*.compat.strictMessageKeys: необов’язкова підказка сумісності для суворих сумісних з OpenAI кінцевих точок чату. Якщо true, OpenClaw залишає у вихідних об’єктах повідомлень Chat Completions лише role і content перед надсиланням запиту.
• models.providers.*.models.*.compat.thinkingFormat: необов’язкова підказка щодо корисного навантаження міркування. Використовуйте "together" для reasoning.enabled у стилі Together, "qwen" для enable_thinking верхнього рівня або "qwen-chat-template" для chat_template_kwargs.enable_thinking на сумісних з OpenAI серверах сімейства Qwen, які підтримують аргументи шаблону чату на рівні запиту, як-от vLLM. Налаштовані моделі Qwen у vLLM надають двійковий вибір /think (off, on) для цих форматів.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: необов’язкова підказка сумісності для серверних систем Chat Completions у стилі DeepSeek, які вимагають зберігати reasoning_content у попередніх повідомленнях асистента під час повторного відтворення. Якщо true, OpenClaw зберігає це поле у вихідних повідомленнях асистента. Використовуйте це під час підключення власного сумісного з DeepSeek проксі, який відхиляє запити після видалення міркувань. Типове значення — false.

• 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: необов’язковий фільтр за ідентифікатором постачальника для цільового виявлення.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: інтервал опитування для оновлення виявлення.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: резервне вікно контексту для виявлених моделей.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: резервна максимальна кількість токенів виведення для виявлених моделей.

Офіційний зовнішній Plugin постачальника cerebras може налаштувати це за допомогою openclaw onboard --auth-choice cerebras-api-key. Використовуйте явну конфігурацію постачальника, лише коли потрібно перевизначити типові значення.

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

Використовуйте cerebras/zai-glm-4.7 для Cerebras; zai/glm-4.7 для прямого підключення до Z.AI.

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

Вбудований постачальник, сумісний з Anthropic. Скорочений спосіб: openclaw onboard --auth-choice kimi-code-api-key.

Див. Локальні моделі. Коротко: запускайте велику локальну модель через LM Studio Responses API на потужному обладнанні; залиште об’єднаними моделі у хмарі для резервного перемикання.

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

Установіть MINIMAX_API_KEY. Скорочені команди: openclaw onboard --auth-choice minimax-global-api або openclaw onboard --auth-choice minimax-cn-api. Каталог моделей за замовчуванням використовує M3, а також містить варіанти M2.7. У сумісному з Anthropic потоковому режимі OpenClaw за замовчуванням вимикає мислення MiniMax M2.x, якщо ви явно не задасте thinking самостійно; MiniMax-M3 (і M3.x) за замовчуванням залишається в режимі мислення постачальника з пропущеним або адаптивним параметром. /fast on або params.fastMode: true замінює MiniMax-M2.7 на 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,          },        ],      },    },  },}

Для китайської кінцевої точки: baseUrl: "https://api.moonshot.cn/v1" або openclaw onboard --auth-choice moonshot-api-key-cn.

Власні кінцеві точки Moonshot заявляють про сумісність потокового передавання даних про використання в спільному транспорті openai-completions, а OpenClaw визначає це за можливостями кінцевої точки, а не лише за вбудованим ідентифікатором постачальника.

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

Установіть OPENCODE_API_KEY (або OPENCODE_ZEN_API_KEY). Використовуйте посилання opencode/... для каталогу Zen або opencode-go/... для каталогу Go. Скорочена команда: openclaw onboard --auth-choice opencode-zen або 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,          },        ],      },    },  },}

Базова URL-адреса не повинна містити /v1 (клієнт Anthropic додає його сам). Скорочена команда: openclaw onboard --auth-choice synthetic-api-key.

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

Установіть ZAI_API_KEY. Посилання на моделі використовують канонічний ідентифікатор постачальника zai/*. Скорочена команда: openclaw onboard --auth-choice zai-api-key.

• Загальна кінцева точка: https://api.z.ai/api/paas/v4
• Кінцева точка для програмування: https://api.z.ai/api/coding/paas/v4
• Варіант автентифікації zai-api-key за замовчуванням перевіряє ваш ключ і автоматично визначає, до якої кінцевої точки він належить (якщо результат визначення неоднозначний, пропонує вибір із варіантом Global за замовчуванням). Для явного вибору також доступні окремі варіанти автентифікації CN і Coding-Plan.
• Для загальної кінцевої точки визначте власного постачальника з перевизначеною базовою URL-адресою.