--- read_when: - Вызов инструментов без выполнения полного хода агента - Создание автоматизаций, которым требуется принудительное применение политик инструментов summary: Вызов одного инструмента напрямую через HTTP-эндпоинт Gateway title: Инструменты вызывают API x-i18n: generated_at: "2026-06-28T23:01:38Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 2023505f5a705b62e2fd685d64d3f9bd7788d09adfe89ac99604e6660c78ad8a source_path: gateway/tools-invoke-http-api.md workflow: 16 --- Gateway в OpenClaw предоставляет простой HTTP-эндпоинт для прямого вызова одного инструмента. Он всегда включен и использует аутентификацию Gateway вместе с политикой инструментов. Как и в OpenAI-совместимой поверхности `/v1/*`, bearer-аутентификация с общим секретом считается доверенным операторским доступом ко всему gateway. - `POST /tools/invoke` - Тот же порт, что и у Gateway (мультиплексирование WS + HTTP): `http://:/tools/invoke` Максимальный размер полезной нагрузки по умолчанию — 2 МБ. ## Аутентификация Использует конфигурацию аутентификации Gateway. Распространенные пути HTTP-аутентификации: - аутентификация с общим секретом (`gateway.auth.mode="token"` или `"password"`): `Authorization: Bearer ` - доверенная HTTP-аутентификация с идентификацией (`gateway.auth.mode="trusted-proxy"`): направьте запрос через настроенный прокси, учитывающий идентичность, и позвольте ему добавить требуемые заголовки идентичности - открытая аутентификация для приватного входа (`gateway.auth.mode="none"`): заголовок аутентификации не требуется Примечания: - Когда `gateway.auth.mode="token"`, используйте `gateway.auth.token` (или `OPENCLAW_GATEWAY_TOKEN`). - Когда `gateway.auth.mode="password"`, используйте `gateway.auth.password` (или `OPENCLAW_GATEWAY_PASSWORD`). - Когда `gateway.auth.mode="trusted-proxy"`, HTTP-запрос должен поступать из настроенного доверенного источника прокси; same-host loopback-прокси требуют явного `gateway.auth.trustedProxy.allowLoopback = true`. - Внутренние вызывающие стороны на том же хосте, которые обходят прокси, могут использовать `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` как локальный прямой запасной вариант. Любые признаки в заголовках `Forwarded`, `X-Forwarded-*` или `X-Real-IP` вместо этого удерживают запрос на пути trusted-proxy. - Если `gateway.auth.rateLimit` настроен и происходит слишком много сбоев аутентификации, эндпоинт возвращает `429` с `Retry-After`. ## Граница безопасности (важно) Рассматривайте этот эндпоинт как поверхность **полного операторского доступа** для экземпляра gateway. - HTTP bearer-аутентификация здесь не является узкой моделью области действия для отдельного пользователя. - Действительный токен/пароль Gateway для этого эндпоинта следует рассматривать как учетные данные владельца/оператора. - Для режимов аутентификации с общим секретом (`token` и `password`) эндпоинт восстанавливает обычные полные операторские значения по умолчанию, даже если вызывающая сторона отправляет более узкий заголовок `x-openclaw-scopes`. - Аутентификация с общим секретом также рассматривает прямые вызовы инструментов на этом эндпоинте как обращения от отправителя-владельца. - Доверенные HTTP-режимы с идентификацией (например, аутентификация через доверенный прокси или `gateway.auth.mode="none"` на приватном входе) учитывают `x-openclaw-scopes`, если он присутствует, а иначе возвращаются к обычному набору операторских областей по умолчанию. - Держите этот эндпоинт только на loopback/tailnet/приватном входе; не открывайте его напрямую в публичный интернет. Матрица аутентификации: - `gateway.auth.mode="token"` или `"password"` + `Authorization: Bearer ...` - доказывает владение общим операторским секретом gateway - игнорирует более узкие `x-openclaw-scopes` - восстанавливает полный набор операторских областей по умолчанию: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write` - рассматривает прямые вызовы инструментов на этом эндпоинте как обращения от отправителя-владельца - доверенные HTTP-режимы с идентификацией (например, аутентификация через доверенный прокси или `gateway.auth.mode="none"` на приватном входе) - аутентифицируют некоторую внешнюю доверенную идентичность или границу развертывания - учитывают `x-openclaw-scopes`, когда заголовок присутствует - возвращаются к обычному набору операторских областей по умолчанию, когда заголовок отсутствует - теряют семантику владельца только тогда, когда вызывающая сторона явно сужает области и опускает `operator.admin` ## Тело запроса ```json { "tool": "sessions_list", "action": "json", "args": {}, "sessionKey": "main", "dryRun": false } ``` Поля: - `tool` (строка, обязательно): имя инструмента для вызова. - `action` (строка, необязательно): сопоставляется с аргументами, если схема инструмента поддерживает `action`, а полезная нагрузка args его опустила. - `args` (объект, необязательно): аргументы, специфичные для инструмента. - `sessionKey` (строка, необязательно): ключ целевой сессии. Если он опущен или равен `"main"`, Gateway использует настроенный ключ основной сессии (учитывает `session.mainKey` и агента по умолчанию либо `global` в глобальной области). - `dryRun` (логическое значение, необязательно): зарезервировано для будущего использования; сейчас игнорируется. ## Поведение политики и маршрутизации Доступность инструментов фильтруется через ту же цепочку политик, которую используют агенты Gateway: - `tools.profile` / `tools.byProvider.profile` - `tools.allow` / `tools.byProvider.allow` - `agents..tools.allow` / `agents..tools.byProvider.allow` - групповые политики (если ключ сессии сопоставляется с группой или каналом) - политика субагента (при вызове с ключом сессии субагента) Если инструмент не разрешен политикой, эндпоинт возвращает **404**. Важные примечания о границах: - Одобрения exec — это операторские защитные ограничения, а не отдельная граница авторизации для этого HTTP-эндпоинта. Если инструмент доступен здесь через аутентификацию Gateway + политику инструментов, `/tools/invoke` не добавляет дополнительный запрос одобрения для каждого вызова. - Если `exec` доступен здесь, рассматривайте его как изменяющую shell-поверхность. Запрет `write`, `edit`, `apply_patch` или HTTP-инструментов записи в файловую систему не делает выполнение shell доступным только для чтения. - Не передавайте bearer-учетные данные Gateway недоверенным вызывающим сторонам. Если вам нужно разделение между границами доверия, запускайте отдельные gateway (и в идеале отдельных пользователей/хосты ОС). HTTP Gateway также по умолчанию применяет жесткий список запрета (даже если политика сессии разрешает инструмент): - `exec` - прямое выполнение команд (поверхность RCE) - `spawn` - произвольное создание дочерних процессов (поверхность RCE) - `shell` - выполнение shell-команд (поверхность RCE) - `fs_write` - произвольное изменение файлов на хосте - `fs_delete` - произвольное удаление файлов на хосте - `fs_move` - произвольное перемещение/переименование файлов на хосте - `apply_patch` - применение патча может переписывать произвольные файлы - `sessions_spawn` - оркестрация сессий; удаленный запуск агентов является RCE - `sessions_send` - внедрение сообщений между сессиями - `cron` - плоскость управления постоянной автоматизацией - `gateway` - плоскость управления gateway; предотвращает перенастройку через HTTP - `nodes` - ретрансляция команд узла может достигать system.run на сопряженных хостах - `whatsapp_login` - интерактивная настройка, требующая сканирования QR-кода в терминале; зависает при HTTP Вы можете настроить этот список запрета через `gateway.tools`: ```json5 { gateway: { tools: { // Additional tools to block over HTTP /tools/invoke deny: ["browser"], // Remove tools from the default deny list for owner/admin callers allow: ["gateway"], }, }, } ``` `gateway.tools.allow` — это переопределение экспозиции, а не повышение области действия. В HTTP-режимах с идентификацией `cron`, `gateway` и `nodes` остаются недоступными для вызывающих сторон без идентичности владельца/администратора (`operator.admin`), даже когда они перечислены в `gateway.tools.allow`. Bearer-аутентификация с общим секретом по-прежнему следует правилу полного доверенного оператора выше. Чтобы помочь групповым политикам определить контекст, можно необязательно задать: - `x-openclaw-message-channel: ` (пример: `slack`, `telegram`) - `x-openclaw-account-id: ` (когда существует несколько учетных записей) ## Ответы - `200` → `{ ok: true, result }` - `400` → `{ ok: false, error: { type, message } }` (недопустимый запрос или ошибка ввода инструмента) - `401` → не авторизовано - `429` → аутентификация ограничена по частоте (`Retry-After` задан) - `404` → инструмент недоступен (не найден или не включен в список разрешенных) - `405` → метод не разрешен - `500` → `{ ok: false, error: { type, message } }` (неожиданная ошибка выполнения инструмента; сообщение очищено) ## Пример ```bash curl -sS http://127.0.0.1:18789/tools/invoke \ -H 'Authorization: Bearer secret' \ -H 'Content-Type: application/json' \ -d '{ "tool": "sessions_list", "action": "json", "args": {} }' ``` ## Связанные материалы - [Протокол Gateway](/ru/gateway/protocol) - [Инструменты и plugins](/ru/tools)