Инструменты (OpenClaw)

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

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

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

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

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

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

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

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

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

Используйте tools.byProvider для дополнительного ограничения инструментов для конкретных провайдеров (или одного provider/model) без изменения ваших глобальных настроек по умолчанию. Переопределение для каждого агента: agents.list[].tools.byProvider.

Это применяется после базового профиля инструментов и перед списками allow/deny, поэтому может только сузить набор инструментов. Ключи провайдера принимают либо provider (например, google-antigravity), либо provider/model (например, openai/gpt-5.2).

Пример (сохранить глобальный профиль кодирования, но минимальные инструменты для 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-команды) помимо основного набора. См. Плагины для установки + конфигурации, и Навыки для того, как руководство по использованию инструментов внедряется в промпты. Некоторые плагины поставляются со своими навыками вместе с инструментами (например, плагин голосовых вызовов).

Опциональные инструменты плагинов:

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

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

apply_patch

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

exec

Запустить shell-команды в рабочем пространстве.

Основные параметры:

command (обязательно)
yieldMs (автоматический переход в фон после тайм-аута, по умолчанию 10000)
background (немедленный переход в фон)
timeout (секунды; завершает процесс при превышении, по умолчанию 1800)
elevated (bool; запустить на хосте, если повышенный режим включён/разрешён; изменяет поведение только когда агент изолирован)
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 или безголовый хост узла (openclaw node run).
Одобрения и белые списки gateway/node: Одобрения Exec.

process

Управление фоновыми сессиями exec.

Основные действия:

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

Примечания:

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

web_search

Поиск в интернете с использованием Brave Search API.

Основные параметры:

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

Примечания:

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

web_fetch

Получить и извлечь читаемый контент из URL (HTML → markdown/text).

Основные параметры:

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

Примечания:

Включите через tools.web.fetch.enabled.
Ответы кэшируются (по умолчанию 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 также поддерживает опции снимка роли (interactive, compact, depth, selector), которые возвращают ссылки типа e12.
act требует ref из snapshot (числовой 12 из AI-снимков, или e12 из снимков роли); используйте 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

Примечания:

Использует gateway node.invoke под капотом.
Если node не предоставлен, инструмент выбирает по умолчанию (один подключённый узел или локальный узел mac).
A2UI это v0.8 только (без createSurface); CLI отклоняет v0.9 JSONL с ошибками строк.
Быстрая проверка: 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_snap, camera_clip, screen_record
location_get

Примечания:

Команды камеры/экрана требуют, чтобы приложение узла было на переднем плане.
Изображения возвращают блоки изображений + MEDIA:<path>.
Видео возвращают FILE:<path> (mp4).
Местоположение возвращает полезную нагрузку JSON (lat/lon/accuracy/timestamp).
Параметры run: массив argv command; опциональные 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 (основной или запасные), или когда неявная модель изображений может быть выведена из вашей модели по умолчанию + настроенной авторизации (сопряжение лучших усилий).
Использует модель изображений напрямую (независимо от основной модели чата).

message

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

Основные действия:

send (текст + опциональные медиа; MS Teams также поддерживает card для адаптивных карт)
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 через Gateway; другие каналы идут напрямую.
poll использует Gateway для WhatsApp и MS Teams; опросы Discord идут напрямую.
Когда вызов инструмента сообщения привязан к активной сессии чата, отправки ограничены целью этой сессии для избежания утечек между контекстами.

cron

Управление заданиями cron Gateway и пробуждениями.

Основные действия:

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

Примечания:

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

gateway

Перезапуск или применение обновлений к запущенному процессу Gateway (на месте).

Основные действия:

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

Примечания:

Используйте delayMs (по умолчанию 2000) для избежания прерывания активного ответа.
restart отключён по умолчанию; включите с помощью commands.restart: true.

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?, agentId?, model?, runTimeoutSeconds?, cleanup?
session_status: sessionKey? (по умолчанию текущая; принимает sessionId), model? (default очищает переопределение)

Примечания:

main — канонический ключ прямого чата; global/unknown скрыты.
messageLimit > 0 получает последние N сообщений для каждой сессии (сообщения инструментов отфильтрованы).
sessions_send ждёт окончательного завершения, когда timeoutSeconds > 0.
Доставка/объявление происходит после завершения и является лучшим усилием; status: "ok" подтверждает, что запуск агента завершён, а не что объявление было доставлено.
sessions_spawn запускает выполнение под-агента и отправляет ответ объявления обратно в чат запросившего.
sessions_spawn неблокирующий и немедленно возвращает status: "accepted".
sessions_send запускает пинг-понг ответа обратно (ответьте REPLY_SKIP для остановки; макс. ходы через session.agentToAgent.maxPingPongTurns, 0–5).
После пинг-понга целевой агент запускает шаг объявления; ответьте ANNOUNCE_SKIP для подавления объявления.

agents_list

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

Примечания:

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

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

Инструменты с поддержкой Gateway (canvas, nodes, cron):

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

Инструмент браузера:

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

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

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

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

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

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

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

Инструменты (OpenClaw)

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

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

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

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

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

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

apply_patch

exec

process

web_search

web_fetch

browser

canvas

nodes

image

message

cron

gateway

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

agents_list

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

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

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

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