tools.* ключи конфигурации и настройка пользовательского провайдера / базового URL. Для агентов, каналов и других ключей конфигурации верхнего уровня см. Справочник по конфигурации.
Инструменты
Профили инструментов
tools.profile задает базовый список разрешений перед tools.allow/tools.deny:
Локальный онбординг по умолчанию задает для новых локальных конфигураций
tools.profile: "coding", если значение не указано (существующие явно заданные профили сохраняются).| Профиль | Включает |
|---|---|
minimal | только session_status |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, skill_workshop, video_generate |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | Без ограничений (то же, что и без указания значения) |
Группы инструментов
| Группа | Инструменты |
|---|---|
group:runtime | exec, process, code_execution (bash принимается как псевдоним для exec) |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
group:memory | memory_search, memory_get |
group:web | web_search, x_search, web_fetch |
group:ui | browser, canvas |
group:automation | heartbeat_respond, cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:agents | agents_list, update_plan |
group:media | image, image_generate, music_generate, video_generate, tts |
group:openclaw | Все встроенные инструменты (исключая plugins провайдеров) |
group:plugins | Инструменты, принадлежащие загруженным plugins, включая настроенные MCP-серверы, открытые через bundle-mcp |
Инструменты MCP и plugins в политике инструментов песочницы
Настроенные MCP-серверы доступны как инструменты, принадлежащие plugin, под id pluginbundle-mcp. Обычные профили инструментов могут разрешать их, но tools.sandbox.tools является дополнительным шлюзом для сеансов в песочнице. Если режим песочницы равен "all" или "non-main", включите одну из этих записей в список разрешенных инструментов песочницы, когда инструменты MCP/plugin должны быть видимыми:
bundle-mcpдля MCP-серверов, управляемых OpenClaw, изmcp.servers- id plugin для конкретного нативного plugin
group:pluginsдля всех загруженных инструментов, принадлежащих plugins- точные имена инструментов MCP-сервера или glob-шаблоны серверов, например
outlook__send_mailилиoutlook__*, когда нужен только один сервер
mcp.servers. Символы, не входящие в [A-Za-z0-9_-], заменяются на -, имена, которые не начинаются с буквы, получают префикс mcp-, а длинные или повторяющиеся префиксы могут быть усечены или получить суффикс; например, mcp.servers["Outlook Graph"] использует glob-шаблон вида outlook-graph__*.
openclaw doctor, чтобы обнаружить такую форму для MCP-серверов, управляемых OpenClaw, в mcp.servers. MCP-серверы, загруженные из манифестов bundled plugins или Claude .mcp.json, используют тот же шлюз песочницы, но эта диагностика пока не перечисляет такие источники; используйте те же записи списка разрешений, если их инструменты исчезают в ходах в песочнице.
tools.codeMode
tools.codeMode включает универсальную поверхность режима кода OpenClaw. Когда он включен
для запуска с инструментами, модель видит только exec и wait; обычные инструменты OpenClaw
перемещаются за мост каталога tools.* внутри песочницы, а инструменты MCP
доступны через сгенерированное пространство имен MCP.
API.list("mcp") и
API.read("mcp/<server>.d.ts"), чтобы изучить сигнатуры в стиле TypeScript перед
вызовом MCP.<server>.<tool>(). См. Режим кода для
контракта среды выполнения, ограничений и шагов отладки.
tools.allow / tools.deny
Глобальная политика разрешения/запрета инструментов (запрет имеет приоритет). Без учета регистра, поддерживает wildcard *. Применяется даже при отключенной песочнице Docker.
write и apply_patch являются отдельными id инструментов. allow: ["write"] также включает apply_patch для совместимых моделей, но deny: ["write"] не запрещает apply_patch. Чтобы заблокировать все изменения файлов, запретите group:fs или явно перечислите каждый инструмент, изменяющий файлы:
tools.byProvider
Дополнительно ограничивает инструменты для конкретных провайдеров или моделей. Порядок: базовый профиль → профиль провайдера → разрешение/запрет.
tools.toolsBySender
Ограничивает инструменты для конкретной идентичности отправителя запроса. Это эшелонированная защита поверх контроля доступа канала; значения отправителя должны приходить из адаптера канала, а не из текста сообщения.
channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> или "*". Id каналов являются каноническими id OpenClaw; псевдонимы, такие как teams, нормализуются в msteams. Устаревшие ключи без префикса принимаются только как id:. Порядок сопоставления: channel+id, id, e164, username, name, затем wildcard.
Поагентное agents.list[].tools.toolsBySender переопределяет глобальное сопоставление отправителя, когда оно совпадает, даже с пустой политикой {}.
tools.elevated
Управляет повышенным доступом exec вне песочницы:
- Поагентное переопределение (
agents.list[].tools.elevated) может только дополнительно ограничивать. /elevated on|off|ask|fullсохраняет состояние для каждого сеанса; встроенные директивы применяются к одному сообщению.- Повышенный
execобходит песочницу и использует настроенный путь выхода (gatewayпо умолчанию илиnode, когда целью exec являетсяnode).
tools.exec
tools.loopDetection
Проверки безопасности циклов инструментов по умолчанию отключены. Задайте enabled: true, чтобы активировать обнаружение. Настройки можно определить глобально в tools.loopDetection и переопределить для каждого агента в agents.list[].tools.loopDetection.
Максимальная история вызовов инструментов, сохраняемая для анализа циклов.
Порог повторяющегося шаблона без прогресса для предупреждений.
Более высокий порог повторений для блокировки критических циклов.
Жесткий порог остановки для любого запуска без прогресса.
Предупреждать о повторных вызовах одного и того же инструмента с теми же аргументами.
Предупреждать/блокировать для известных инструментов опроса (
process.poll, command_status и т. д.).Предупреждать/блокировать для чередующихся парных шаблонов без прогресса.
tools.web
tools.media
Настраивает понимание входящих медиа (изображения/аудио/видео):
Поля записи модели медиа
Поля записи модели медиа
Запись провайдера (
type: "provider" или опущено):provider: идентификатор API-провайдера (openai,anthropic,google/gemini,groqи т. д.)model: переопределение идентификатора моделиprofile/preferredProfile: выбор профиляauth-profiles.json
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: устаревший флаг совместимости. Завершенные асинхронные задачи обработки медиа остаются опосредованными сеансом запрашивающего, чтобы агент получил результат, решил, как сообщить его пользователю, и использовал инструмент сообщений, когда этого требует доставка в исходный канал.
tools.agentToAgent
tools.sessions
Управляет тем, на какие сеансы могут быть нацелены инструменты сеансов (sessions_list, sessions_history, sessions_send).
По умолчанию: tree (текущий сеанс + сеансы, порожденные им, например подагенты).
Области видимости
Области видимости
self: только ключ текущего сеанса.tree: текущий сеанс + сеансы, порожденные текущим сеансом (подагенты).agent: любой сеанс, принадлежащий текущему идентификатору агента (может включать других пользователей, если вы запускаете сеансы для каждого отправителя под тем же идентификатором агента).all: любой сеанс. Нацеливание между агентами по-прежнему требуетtools.agentToAgent.- Ограничение песочницы: когда текущий сеанс находится в песочнице и
agents.defaults.sandbox.sessionToolsVisibility="spawned", видимость принудительно устанавливается вtree, даже еслиtools.sessions.visibility="all". - Когда режим не
all,sessions_listвключает компактное полеvisibility, описывающее эффективный режим, и предупреждение о том, что некоторые сеансы могут быть опущены за пределами текущей области.
tools.sessions_spawn
Управляет поддержкой встроенных вложений для sessions_spawn.
Примечания о вложениях
Примечания о вложениях
- Вложения требуют
enabled: true. - Вложения подагента материализуются в дочернем рабочем пространстве в
.openclaw/attachments/<uuid>/с.manifest.json. - Вложения ACP поддерживают только изображения и пересылаются встроенно в среду выполнения ACP после прохождения тех же лимитов на количество файлов, байты на файл и общий размер в байтах.
- Содержимое вложений автоматически редактируется при сохранении транскрипта.
- Входные данные Base64 проверяются строгими проверками алфавита/заполнения и защитой размера до декодирования.
- Права доступа к файлам вложений подагента:
0700для каталогов и0600для файлов. - Очистка подагента следует политике
cleanup:deleteвсегда удаляет вложения;keepсохраняет их только приretainOnSessionKeep: true.
tools.experimental
Экспериментальные флаги встроенных инструментов. По умолчанию отключены, если не применяется правило автоматического включения для строгого агентного GPT-5.
planTool: включает структурированный инструментupdate_planдля отслеживания нетривиальной многошаговой работы.- По умолчанию:
false, еслиagents.defaults.embeddedAgent.executionContract(или переопределение для отдельного агента) не задано как"strict-agentic"для запуска семейства GPT-5 через OpenAI или OpenAI Codex. Установитеtrue, чтобы принудительно включить инструмент вне этой области, илиfalse, чтобы оставить его отключенным даже для строгих агентных запусков GPT-5. - Когда он включен, системная подсказка также добавляет рекомендации по использованию, чтобы модель применяла его только для существенной работы и держала не более одного шага в состоянии
in_progress.
agents.defaults.subagents
model: модель по умолчанию для порождаемых подагентов. Если опущено, подагенты наследуют модель вызывающего.allowAgents: список разрешенных настроенных идентификаторов целевых агентов по умолчанию дляsessions_spawn, когда запрашивающий агент не задает собственныйsubagents.allowAgents(["*"]= любой настроенный целевой агент; по умолчанию: только тот же агент). Устаревшие записи, конфигурация агента для которых была удалена, отклоняютсяsessions_spawnи опускаются вagents_list; запуститеopenclaw doctor --fix, чтобы очистить их.runTimeoutSeconds: тайм-аут по умолчанию (в секундах) дляsessions_spawn.0означает отсутствие тайм-аута.announceTimeoutMs: тайм-аут отдельного вызова (в миллисекундах) для попыток доставки объявленияagentчерез Gateway. По умолчанию:120000. Временные повторные попытки могут сделать общее ожидание объявления длиннее одного настроенного тайм-аута.- Политика инструментов для отдельного подагента:
tools.subagents.tools.allow/tools.subagents.tools.deny.
Пользовательские провайдеры и базовые URL
Plugin провайдеров публикуют собственные строки каталога моделей. Добавляйте пользовательских провайдеров черезmodels.providers в конфигурации или ~/.openclaw/agents/<agentId>/agent/models.json.
Настройка baseUrl пользовательского/локального провайдера также является узким решением о доверии к сети для HTTP-запросов модели: OpenClaw разрешает именно этот источник scheme://host:port через защищенный путь fetch, без добавления отдельной опции конфигурации и без доверия другим частным источникам.
Аутентификация и приоритет слияния
Аутентификация и приоритет слияния
- Используйте
authHeader: true+headersдля пользовательских потребностей аутентификации. - Переопределите корень конфигурации агента с помощью
OPENCLAW_AGENT_DIR. - Приоритет слияния для совпадающих идентификаторов провайдеров:
- Непустые значения
baseUrlизmodels.jsonагента имеют приоритет. - Непустые значения
apiKeyагента имеют приоритет только тогда, когда этот провайдер не управляется SecretRef в текущем контексте конфигурации/профиля аутентификации. - Значения
apiKeyпровайдера, управляемого SecretRef, обновляются из исходных маркеров (ENV_VAR_NAMEдля ссылок на переменные окружения,secretref-managedдля ссылок на файл/exec) вместо сохранения разрешенных секретов. - Значения заголовков провайдера, управляемого SecretRef, обновляются из исходных маркеров (
secretref-env:ENV_VAR_NAMEдля ссылок на переменные окружения,secretref-managedдля ссылок на файл/exec). - Пустые или отсутствующие
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,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.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-защиту fetch провайдера. Базовые URL пользовательских/локальных провайдеров уже доверяют точно настроенному источнику, кроме источников metadata/link-local, которые остаются заблокированными без явного включения. Установитеfalse, чтобы отказаться от доверия точному источнику. WebSocket использует тот жеrequestдля заголовков/TLS, но не этот SSRF-шлюз fetch. По умолчанию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на серверах семейства Qwen, совместимых с OpenAI, которые поддерживают kwargs шаблона чата на уровне запроса, таких как vLLM. Настроенные модели vLLM Qwen предоставляют бинарные варианты/think(off,on) для этих форматов.models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: необязательная подсказка совместимости для бэкендов Chat Completions в стиле DeepSeek, которым требуется сохранятьreasoning_contentв предыдущих сообщениях ассистента при повторном воспроизведении. Когдаtrue, OpenClaw сохраняет это поле в исходящих сообщениях ассистента. Используйте это при подключении пользовательского прокси, совместимого с DeepSeek, который отклоняет запросы после удаления reasoning. По умолчаниюfalse.
Обнаружение Amazon Bedrock
Обнаружение Amazon Bedrock
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: резервный максимум выходных токенов для обнаруженных моделей.
--custom-image-input, чтобы принудительно задать метаданные с поддержкой изображений, или --custom-text-input, чтобы принудительно задать метаданные только для текста.
Примеры провайдеров
Cerebras (GLM 4.7 / GPT OSS)
Cerebras (GLM 4.7 / GPT OSS)
Официальный внешний Plugin провайдера Используйте
cerebras может настроить это через openclaw onboard --auth-choice cerebras-api-key. Используйте явную конфигурацию провайдера только при переопределении стандартных настроек.cerebras/zai-glm-4.7 для Cerebras; zai/glm-4.7 для прямого Z.AI.Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key.Локальные модели (LM Studio)
Локальные модели (LM Studio)
См. Локальные модели. Кратко: запускайте большую локальную модель через LM Studio Responses API на серьезном оборудовании; оставляйте размещенные модели объединенными для резервного варианта.
MiniMax M3 (напрямую)
MiniMax M3 (напрямую)
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.Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" или openclaw onboard --auth-choice moonshot-api-key-cn.Нативные конечные точки Moonshot объявляют совместимость использования потоковой передачи на общем транспорте openai-completions, и OpenClaw опирается на возможности конечной точки, а не только на встроенный ID провайдера.OpenCode
OpenCode
OPENCODE_API_KEY (или OPENCODE_ZEN_API_KEY). Используйте ссылки opencode/... для каталога Zen или ссылки opencode-go/... для каталога Go. Короткий путь: openclaw onboard --auth-choice opencode-zen или openclaw onboard --auth-choice opencode-go.Synthetic (Anthropic-совместимый)
Synthetic (Anthropic-совместимый)
/v1 (клиент Anthropic добавляет его). Сокращение: openclaw onboard --auth-choice synthetic-api-key.Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY. Ссылки на модели используют канонический ID провайдера zai/*. Сокращение: openclaw onboard --auth-choice zai-api-key.- Общая конечная точка:
https://api.z.ai/api/paas/v4 - Конечная точка для кодирования (по умолчанию):
https://api.z.ai/api/coding/paas/v4 - Для общей конечной точки определите пользовательского провайдера с переопределением базового URL.
Связанные материалы
- Конфигурация — агенты
- Конфигурация — каналы
- Справочник конфигурации — другие ключи верхнего уровня
- Инструменты и plugins