Обзор

Инструменты

OpenClaw предоставляет инструменты агента первого класса для браузера, canvas, узлов и cron. Они заменяют старые навыки openclaw-*: инструменты типизированы, не требуют вызова оболочки, и агент должен полагаться на них напрямую.

Отключение инструментов

Вы можете глобально разрешать/запрещать инструменты через tools.allow / tools.deny в openclaw.json (запрет имеет приоритет). Это предотвращает отправку неразрешенных инструментов провайдерам моделей.

{
  tools: { deny: ["browser"] },
}

Примечания:

  • Сопоставление регистронезависимое.
  • Поддерживаются подстановочные знаки * ("*" означает все инструменты).
  • Если tools.allow ссылается только на неизвестные или незагруженные имена инструментов плагинов, OpenClaw логирует предупреждение и игнорирует список разрешений, чтобы основные инструменты оставались доступными.

Профили инструментов (базовый список разрешений)

tools.profile устанавливает базовый список разрешений инструментов перед применением tools.allow/tools.deny. Переопределение для конкретного агента: agents.list[].tools.profile. Профили:

  • minimal: только session_status
  • coding: group:fs, group:runtime, group:sessions, group:memory, image
  • messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
  • full: без ограничений (аналогично отсутствию настройки)

Пример (только обмен сообщениями по умолчанию, разрешить также инструменты Slack + Discord):

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

Пример (профиль coding, но запретить exec/process везде):

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

Пример (глобальный профиль coding, агент поддержки только для обмена сообщениями):

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

Политика инструментов для конкретного провайдера

Используйте tools.byProvider, чтобы дополнительно ограничить инструменты для конкретных провайдеров (или одной пары provider/model), не меняя глобальные настройки по умолчанию. Переопределение для конкретного агента: agents.list[].tools.byProvider. Это применяется после базового профиля инструментов и перед списками разрешений/запретов, поэтому может только сужать набор инструментов. Ключи провайдера принимают либо provider (например, google-antigravity), либо provider/model (например, openai/gpt-5.2). Пример (сохранить глобальный профиль coding, но минимальные инструменты для Google Antigravity):

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Пример (специфичный для провайдера/модели список разрешений для ненадежной конечной точки):

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Пример (переопределение для конкретного агента для одного провайдера):

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

Группы инструментов (сокращения)

Политики инструментов (глобальные, для агента, песочницы) поддерживают записи group:*, которые раскрываются в несколько инструментов. Используйте их в tools.allow / tools.deny. Доступные группы:

  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:web: web_search, web_fetch
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: все встроенные инструменты OpenClaw (исключает плагины провайдеров)

Пример (разрешить только файловые инструменты + браузер):

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Плагины + инструменты

Плагины могут регистрировать дополнительные инструменты (и команды CLI) помимо основного набора. См. Плагины для установки и настройки, и Навыки о том, как рекомендации по использованию инструментов внедряются в промпты. Некоторые плагины поставляются со своими навыками вместе с инструментами (например, плагин voice-call). Дополнительные инструменты плагинов:

  • Lobster: типизированная среда выполнения рабочих процессов с возобновляемыми подтверждениями (требует CLI Lobster на хосте шлюза).
  • LLM Task: шаг LLM только для JSON для структурированного вывода рабочего процесса (опциональная валидация схемы).
  • Diffs: средство просмотра различий только для чтения и рендерер файлов PNG или PDF для текста до/после или унифицированных патчей.

Инвентарь инструментов

apply_patch

Применяет структурированные патчи к одному или нескольким файлам. Используйте для многострочных правок. Экспериментально: включите через tools.exec.applyPatch.enabled (только модели OpenAI). tools.exec.applyPatch.workspaceOnly по умолчанию true (ограничено рабочей областью). Установите в false только если вы намеренно хотите, чтобы apply_patch писал/удалял за пределами директории рабочей области.

exec

Запускает команды оболочки в рабочей области. Основные параметры:

  • command (обязательный)
  • yieldMs (авто-фон после таймаута, по умолчанию 10000)
  • background (немедленный фон)
  • timeout (секунды; убивает процесс при превышении, по умолчанию 1800)
  • elevated (bool; запуск на хосте, если режим elevated включен/разрешен; меняет поведение только когда агент в песочнице)
  • host (sandbox | gateway | node)
  • security (deny | allowlist | full)
  • ask (off | on-miss | always)
  • node (id/имя узла для host=node)
  • Нужен реальный TTY? Установите pty: true.

Примечания:

  • Возвращает status: "running" с sessionId при переходе в фон.
  • Используйте process для опроса/логирования/записи/убийства/очистки фоновых сессий.
  • Если process запрещен, exec выполняется синхронно и игнорирует yieldMs/background.
  • elevated контролируется tools.elevated плюс любое переопределение agents.list[].tools.elevated (оба должны разрешать) и является псевдонимом для host=gateway + security=full.
  • elevated меняет поведение только когда агент в песочнице (иначе это no-op).
  • host=node может нацеливаться на приложение-компаньон macOS или на хост узла без GUI (openclaw node run).
  • Подтверждения и списки разрешений шлюза/узла: Подтверждения Exec.

process

Управляет фоновыми сессиями exec. Основные действия:

  • list, poll, log, write, kill, clear, remove

Примечания:

  • poll возвращает новый вывод и статус завершения.
  • log поддерживает построчные offset/limit (опустите offset, чтобы получить последние N строк).
  • process ограничен для каждого агента; сессии от других агентов не видны.

loop-detection (ограничения для предотвращения циклов вызовов инструментов)

OpenClaw отслеживает историю недавних вызовов инструментов и блокирует или предупреждает при обнаружении повторяющихся циклов без прогресса. Включите с помощью tools.loopDetection.enabled: true (по умолчанию false).

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      historySize: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
  • genericRepeat: повторяющийся шаблон вызова одного и того же инструмента с одинаковыми параметрами.
  • knownPollNoProgress: повторение инструментов, похожих на poll, с идентичными выводами.
  • pingPong: чередующиеся шаблоны без прогресса A/B/A/B.
  • Переопределение для конкретного агента: agents.list[].tools.loopDetection.

Ищет в интернете с помощью Perplexity, Brave, Gemini, Grok или Kimi. Основные параметры:

  • query (обязательный)
  • count (1–10; по умолчанию из tools.web.search.maxResults)

Примечания:

  • Требуется API-ключ для выбранного провайдера (рекомендуется: openclaw configure --section web).
  • Включите через tools.web.search.enabled.
  • Ответы кэшируются (по умолчанию 15 мин).
  • См. Веб-инструменты для настройки.

web_fetch

Получает и извлекает читаемое содержимое из URL (HTML → markdown/текст). Основные параметры:

  • url (обязательный)
  • extractMode (markdown | text)
  • maxChars (обрезать длинные страницы)

Примечания:

  • Включите через tools.web.fetch.enabled.
  • maxChars ограничивается tools.web.fetch.maxCharsCap (по умолчанию 50000).
  • Ответы кэшируются (по умолчанию 15 мин).
  • Для сайтов с большим количеством JS предпочтительнее инструмент браузера.
  • См. Веб-инструменты для настройки.
  • См. Firecrawl для опционального резервного варианта против ботов.

browser

Управляет выделенным браузером под управлением OpenClaw. Основные действия:

  • status, start, stop, tabs, open, focus, close
  • snapshot (aria/ai)
  • screenshot (возвращает блок изображения + MEDIA:<path>)
  • act (действия UI: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
  • navigate, console, pdf, upload, dialog

Управление профилями:

  • profiles — список всех профилей браузера со статусом
  • create-profile — создать новый профиль с автоматически выделенным портом (или cdpUrl)
  • delete-profile — остановить браузер, удалить пользовательские данные, удалить из конфига (только локально)
  • reset-profile — убить зависший процесс на порту профиля (только локально)

Общие параметры:

  • profile (опционально; по умолчанию browser.defaultProfile)
  • target (sandbox | host | node)
  • node (опционально; выбирает конкретный id/имя узла) Примечания:
  • Требуется browser.enabled=true (по умолчанию true; установите false для отключения).
  • Все действия принимают опциональный параметр profile для поддержки нескольких экземпляров.
  • Когда profile опущен, используется browser.defaultProfile (по умолчанию “chrome”).
  • Имена профилей: только строчные буквы, цифры и дефисы (макс. 64 символа).
  • Диапазон портов: 18800-18899 (~100 профилей макс.).
  • Удаленные профили только для подключения (без start/stop/reset).
  • Если подключен узел с поддержкой браузера, инструмент может автоматически перенаправить на него (если вы не зафиксировали target).
  • snapshot по умолчанию ai, когда установлен Playwright; используйте aria для дерева доступности.
  • snapshot также поддерживает опции role-snapshot (interactive, compact, depth, selector), которые возвращают ссылки типа e12.
  • act требует ref из snapshot (числовой 12 из AI-снимков или e12 из role-снимков); используйте evaluate для редких случаев необходимости CSS-селектора.
  • Избегайте act → wait по умолчанию; используйте только в исключительных случаях (нет надежного состояния UI для ожидания).
  • upload может опционально передавать ref для автоматического клика после подготовки.
  • upload также поддерживает inputRef (aria ref) или element (CSS-селектор) для прямой установки <input type="file">.

canvas

Управляет Canvas узла (present, eval, snapshot, A2UI). Основные действия:

  • present, hide, navigate, eval
  • snapshot (возвращает блок изображения + MEDIA:<path>)
  • a2ui_push, a2ui_reset

Примечания:

  • Использует node.invoke шлюза под капотом.
  • Если node не указан, инструмент выбирает узел по умолчанию (единственный подключенный узел или локальный mac-узел).
  • A2UI только v0.8 (нет createSurface); CLI отклоняет JSONL v0.9 с ошибками строк.
  • Быстрая проверка: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

nodes

Обнаруживает и нацеливается на сопряженные узлы; отправляет уведомления; захватывает камеру/экран. Основные действия:

  • status, describe
  • pending, approve, reject (сопряжение)
  • notify (macOS system.notify)
  • run (macOS system.run)
  • camera_list, camera_snap, camera_clip, screen_record
  • location_get, notifications_list, notifications_action
  • device_status, device_info, device_permissions, device_health

Примечания:

  • Команды камеры/экрана требуют, чтобы приложение узла было на переднем плане.
  • Изображения возвращают блоки изображений + MEDIA:<path>.
  • Видео возвращают FILE:<path> (mp4).
  • Местоположение возвращает JSON-пакет (lat/lon/accuracy/timestamp).
  • run параметры: массив command argv; опционально cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

Пример (run):

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

image

Анализирует изображение с помощью настроенной модели изображений. Основные параметры:

  • image (обязательный путь или URL)
  • prompt (опционально; по умолчанию “Describe the image.”)
  • model (опциональное переопределение)
  • maxBytesMb (опциональное ограничение размера)

Примечания:

  • Доступно только когда настроен agents.defaults.imageModel (основная или резервные модели), или когда неявная модель изображений может быть выведена из вашей модели по умолчанию + настроенной аутентификации (сопоставление по возможности).
  • Использует модель изображений напрямую (независимо от основной чат-модели).

pdf

Анализирует один или несколько PDF-документов. Полное поведение, ограничения, конфигурация и примеры см. в Инструмент PDF.

message

Отправляет сообщения и действия каналов через Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams. Основные действия:

  • send (текст + опционально медиа; MS Teams также поддерживает card для Adaptive Cards)
  • poll (опросы WhatsApp/Discord/MS Teams)
  • react / reactions / read / edit / delete
  • pin / unpin / list-pins
  • permissions
  • thread-create / thread-list / thread-reply
  • search
  • sticker
  • member-info / role-info
  • emoji-list / emoji-upload / sticker-upload
  • role-add / role-remove
  • channel-info / channel-list
  • voice-status
  • event-list / event-create
  • timeout / kick / ban

Примечания:

  • send маршрутизирует WhatsApp через Шлюз; другие каналы идут напрямую.
  • poll использует Шлюз для WhatsApp и MS Teams; опросы Discord идут напрямую.
  • Когда вызов инструмента message привязан к активной чат-сессии, отправки ограничиваются целью этой сессии, чтобы избежать утечек между контекстами.

cron

Управляет заданиями cron и пробуждениями Шлюза. Основные действия:

  • status, list
  • add, update, remove, run, runs
  • wake (поставить системное событие в очередь + опциональное немедленное heartbeat)

Примечания:

  • add ожидает полный объект задания cron (та же схема, что и RPC cron.add).
  • update использует { jobId, patch } (id принимается для совместимости).

gateway

Перезапускает или применяет обновления к запущенному процессу Шлюза (на месте). Основные действия:

  • restart (авторизует + отправляет SIGUSR1 для внутрипроцессного перезапуска; openclaw gateway перезапускает на месте)
  • config.schema.lookup (проверить один путь конфигурации за раз без загрузки полной схемы в контекст промпта)
  • config.get
  • config.apply (валидация + запись конфига + перезапуск + пробуждение)
  • config.patch (частичное обновление слиянием + перезапуск + пробуждение)
  • update.run (запуск обновления + перезапуск + пробуждение)

Примечания:

  • config.schema.lookup ожидает целевой путь конфигурации, такой как gateway.auth или agents.list.*.heartbeat.
  • Пути могут включать разделенные слешем id плагинов при обращении к plugins.entries.<id>, например plugins.entries.pack/one.config.
  • Используйте delayMs (по умолчанию 2000), чтобы избежать прерывания ответа в процессе.
  • config.schema остается доступным для внутренних потоков UI управления и не раскрывается через инструмент агента gateway.
  • restart включен по умолчанию; установите commands.restart: false, чтобы отключить.

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

Список сессий, просмотр истории транскрипта или отправка в другую сессию. Основные параметры:

  • sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = нет)
  • sessions_history: sessionKey (или sessionId), limit?, includeTools?
  • sessions_send: sessionKey (или sessionId), message, timeoutSeconds? (0 = fire-and-forget)
  • sessions_spawn: task, label?, runtime?, agentId?, model?, thinking?, cwd?, runTimeoutSeconds?, thread?, mode?, cleanup?, sandbox?, streamTo?, attachments?, attachAs?
  • session_status: sessionKey? (по умолчанию текущая; принимает sessionId), model? (default снимает переопределение)

Примечания:

  • main — канонический ключ прямого чата; global/unknown скрыты.
  • messageLimit > 0 получает последние N сообщений для каждой сессии (сообщения инструментов отфильтрованы).
  • Нацеливание на сессии контролируется tools.sessions.visibility (по умолчанию tree: текущая сессия + порожденные сессии под-агентов). Если вы запускаете общего агента для нескольких пользователей, рассмотрите установку tools.sessions.visibility: "self", чтобы предотвратить просмотр между сессиями.
  • sessions_send ждет окончательного завершения, когда timeoutSeconds > 0.
  • Доставка/объявление происходит после завершения и является best-effort; status: "ok" подтверждает завершение запуска агента, а не доставку объявления.
  • sessions_spawn поддерживает runtime: "subagent" | "acp" (по умолчанию subagent). Для поведения среды выполнения ACP см. ACP Agents.
  • Для среды выполнения ACP streamTo: "parent" направляет сводки прогресса начального запуска обратно в сессию инициатора как системные события вместо прямой доставки дочернему элементу.
  • sessions_spawn запускает выполнение под-агента и публикует ответ-объявление обратно в чат инициатора.
    • Поддерживает одноразовый режим (mode: "run") и постоянный режим, привязанный к ветке (mode: "session" с thread: true).
    • Если thread: true и mode опущен, режим по умолчанию session.
    • mode: "session" требует thread: true.
    • Если runTimeoutSeconds опущен, OpenClaw использует agents.defaults.subagents.runTimeoutSeconds, если установлено; иначе таймаут по умолчанию 0 (без таймаута).
    • Потоки, привязанные к веткам Discord, зависят от session.threadBindings.* и channels.discord.threadBindings.*.
    • Формат ответа включает Status, Result и компактную статистику.
    • Result — это текст завершения ассистента; если отсутствует, используется последний toolResult как запасной вариант.
  • Ручные spawn-ы в режиме завершения отправляют напрямую сначала, с резервной очередью и повторной попыткой при временных сбоях (status: "ok" означает завершение запуска, а не доставку объявления).
  • sessions_spawn поддерживает встроенные вложения файлов только для среды выполнения под-агента (ACP отклоняет их). Каждое вложение имеет name, content и опционально encoding (utf8 или base64) и mimeType. Файлы материализуются в рабочей области дочернего элемента в .openclaw/attachments/<uuid>/ с файлом метаданных .manifest.json. Инструмент возвращает квитанцию с count, totalBytes, sha256 для каждого файла и relDir. Содержимое вложений автоматически скрывается из постоянного хранения транскрипта.
    • Настройте ограничения через tools.sessions_spawn.attachments (enabled, maxTotalBytes, maxFiles, maxFileBytes, retainOnSessionKeep).
    • attachAs.mountPath — зарезервированная подсказка для будущих реализаций монтирования.
  • sessions_spawn неблокирующий и немедленно возвращает status: "accepted".
  • Ответы ACP streamTo: "parent" могут включать streamLogPath (ограниченный сессией *.acp-stream.jsonl) для отслеживания истории прогресса.
  • sessions_send запускает пинг-понг ответа (ответьте REPLY_SKIP, чтобы остановить; максимальное количество ходов через session.agentToAgent.maxPingPongTurns, 0–5).
  • После пинг-понга целевой агент выполняет шаг объявления; ответьте ANNOUNCE_SKIP, чтобы подавить объявление.
  • Ограничение песочницы: когда текущая сессия в песочнице и agents.defaults.sandbox.sessionToolsVisibility: "spawned", OpenClaw ограничивает tools.sessions.visibility до tree.

agents_list

Список id агентов, которые текущая сессия может нацелить с помощью sessions_spawn. Примечания:

  • Результат ограничен списками разрешений для каждого агента (agents.list[].subagents.allowAgents).
  • Когда настроено ["*"], инструмент включает всех настроенных агентов и помечает allowAny: true.

Параметры (общие)

Инструменты на основе Шлюза (canvas, nodes, cron):

  • gatewayUrl (по умолчанию ws://127.0.0.1:18789)
  • gatewayToken (если включена аутентификация)
  • timeoutMs

Примечание: когда установлен gatewayUrl, явно укажите gatewayToken. Инструменты не наследуют учетные данные конфигурации или окружения для переопределений, и отсутствие явных учетных данных является ошибкой. Инструмент браузера:

  • profile (опционально; по умолчанию browser.defaultProfile)
  • target (sandbox | host | node)
  • node (опционально; зафиксировать конкретный id/имя узла)

Рекомендуемые потоки агента

Автоматизация браузера:

  1. browser → status / start
  2. snapshot (ai или aria)
  3. act (click/type/press)
  4. screenshot если нужна визуальная проверка

Рендер Canvas:

  1. canvas → present
  2. a2ui_push (опционально)
  3. snapshot

Нацеливание на узел:

  1. nodes → status
  2. describe на выбранном узле
  3. notify / run / camera_snap / screen_record

Безопасность

  • Избегайте прямого system.run; используйте nodes → run только с явного согласия пользователя.
  • Уважайте согласие пользователя на захват камеры/экрана.
  • Используйте status/describe, чтобы убедиться в разрешениях перед вызовом медиа-команд.

Как инструменты представляются агенту

Инструменты раскрываются через два параллельных канала:

  1. Текст системного промпта: удобочитаемый список + рекомендации.
  2. Схема инструментов: структурированные определения функций, отправляемые в API модели.

Это означает, что агент видит и «какие инструменты существуют», и «как их вызывать». Если инструмент не появляется в системном промпте или схеме, модель не может его вызвать.

Инструмент apply_patch