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

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

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

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

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

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

• capabilities: необов’язковий список (image, audio, video). Стандартні значення: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: перевизначення для окремого запису.
• tools.media.image.timeoutSeconds і відповідні записи timeoutSeconds для моделі зображень також застосовуються, коли агент викликає явний інструмент image.
• У разі збоїв виконується перехід до наступного запису.

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

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

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

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

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

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

• 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, anthropic-messages, google-generative-ai тощо). Для самостійно розгорнутих бекендів /v1/chat/completions, таких як MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйте openai-completions. Власний провайдер із baseUrl, але без api, за замовчуванням використовує openai-completions; задавайте openai-responses лише коли бекенд підтримує /v1/responses.
• models.providers.*.apiKey: облікові дані провайдера (надавайте перевагу SecretRef/підстановці env).
• 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 upstream.
• models.providers.*.headers: додаткові статичні заголовки для маршрутизації proxy/tenant.

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, дозволяє HTTPS до baseUrl, коли DNS розв’язується в приватні, CGNAT або подібні діапазони, через захисник HTTP fetch провайдера (opt-in оператора для довірених самостійно розгорнутих сумісних з OpenAI кінцевих точок). URL-адреси потоків провайдера моделей local loopback, такі як localhost, 127.0.0.1 і [::1], дозволяються автоматично, якщо це явно не встановлено в false; хости LAN, tailnet і приватні DNS-хости все одно потребують opt-in. WebSocket використовує той самий request для заголовків/TLS, але не цей fetch SSRF gate. За замовчуванням 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 у звичайні рядки.

• 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: необов’язковий фільтр provider-id для цільового виявлення.
• 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-code" },
      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
    },
  },
}

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

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

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

Задайте MINIMAX_API_KEY. Скорочення: openclaw onboard --auth-choice minimax-global-api або openclaw onboard --auth-choice minimax-cn-api. Каталог моделей за замовчуванням містить лише M2.7. На сумісному з Anthropic потоковому шляху OpenClaw вимикає thinking MiniMax за замовчуванням, якщо ви явно не задасте thinking самостійно. /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. z.ai/* і z-ai/* приймаються як псевдоніми. Скорочення: openclaw onboard --auth-choice zai-api-key.

• Загальний endpoint: https://api.z.ai/api/paas/v4
• Coding endpoint (типовий): https://api.z.ai/api/coding/paas/v4
• Для загального endpoint визначте власного провайдера з перевизначенням базового URL.