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

Запись провайдера (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). Каждый плагин провайдера объявляет собственный набор возможностей по умолчанию; например, встроенный провайдер 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 подчиняется тому же правилу «явное значение имеет приоритет, иначе используется неявное»; используйте его для ограничения эффективного контекста без изменения собственных метаданных модели.
  • Каталоги плагинов провайдеров хранятся в виде сгенерированных фрагментов каталога, принадлежащих плагинам, в состоянии плагинов агента.
  • Используйте 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, 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: резервное максимальное количество выходных токенов для обнаруженных моделей.

Официальный внешний плагин провайдера 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.