--- read_when: - Вызов инструментов без выполнения полного цикла агента - Создание автоматизаций, требующих принудительного применения политик использования инструментов summary: Вызовите отдельный инструмент напрямую через HTTP-эндпоинт Gateway title: Инструменты вызывают API x-i18n: generated_at: "2026-07-13T19:51:00Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda source_path: gateway/tools-invoke-http-api.md workflow: 16 --- OpenClaw Gateway предоставляет конечную точку 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"`): заголовок аутентификации не требуется Примечания: - `mode="token"` использует `gateway.auth.token` (или `OPENCLAW_GATEWAY_TOKEN`). - `mode="password"` использует `gateway.auth.password` (или `OPENCLAW_GATEWAY_PASSWORD`). - `mode="trusted-proxy"` требует, чтобы HTTP-запрос поступал от настроенного доверенного источника прокси; для loopback-прокси на том же хосте необходимо явно указать `gateway.auth.trustedProxy.allowLoopback = true`. - Внутренние вызывающие стороны на том же хосте, которые обходят прокси, могут использовать `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` как локальный прямой резервный вариант. Любые признаки в заголовках `Forwarded`, `X-Forwarded-*` или `X-Real-IP` вместо этого оставляют запрос на пути доверенного прокси. - Если настроен `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 или приватный входящий трафик; не предоставляйте к ней прямой доступ из общедоступного интернета. Матрица аутентификации: | Режим аутентификации | Поведение | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token` или `password` + `Authorization: Bearer ...` | Подтверждает владение общим операторским секретом Gateway. Игнорирует более узкий `x-openclaw-scopes`. Восстанавливает полный набор операторских областей доступа по умолчанию: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`. Считает прямые вызовы инструментов обращениями от владельца-отправителя. | | Доверенный HTTP с идентификационными данными (аутентификация через доверенный прокси или `mode="none"` для приватного входящего трафика) | Аутентифицирует внешнюю доверенную идентичность или границу развёртывания. Учитывает `x-openclaw-scopes`, если он присутствует. Если заголовок отсутствует, использует обычный набор операторских областей доступа по умолчанию. Семантика владельца утрачивается только в том случае, если вызывающая сторона явно сужает области доступа и не включает `operator.admin`. | ## Тело запроса ```json { "tool": "sessions_list", "action": "json", "args": {}, "sessionKey": "main", "dryRun": false } ``` Поля: - `tool` / `name` (строка, обязательно): имя вызываемого инструмента. Если отправлены оба поля, приоритет имеет `name`. - `action` (строка, необязательно): объединяется с `args.action`, если схема инструмента поддерживает свойство `action` и в `args` оно ещё не задано. - `args` (объект, необязательно): аргументы, специфичные для инструмента. - `sessionKey` (строка, необязательно): ключ целевого сеанса. Если он не указан или равен `"main"`, Gateway использует настроенный ключ основного сеанса (учитывая `session.mainKey` и агента по умолчанию либо `global` в глобальной области сеанса). - `agentId` (строка, необязательно): определяет ключ сеанса для указанного агента. Возвращает ошибку `400`, если значение конфликтует с явно заданным `sessionKey`, который уже сопоставлен другому агенту. - `idempotencyKey` (строка, необязательно): используется для формирования стабильного идентификатора вызова инструмента. - `dryRun` (логическое значение, необязательно): зарезервировано для будущего использования; в настоящее время игнорируется. ## Поведение политики и маршрутизации Доступность инструментов фильтруется через ту же цепочку политик, которую используют агенты Gateway: - `tools.profile` / `tools.byProvider.profile` - `tools.allow` / `tools.byProvider.allow` - `agents..tools.allow` / `agents..tools.byProvider.allow` - групповые политики (если ключ сеанса сопоставлен группе или каналу) - политика субагента (при вызове с ключом сеанса субагента) Если инструмент запрещён политикой, конечная точка возвращает **404**. Важные замечания о границах: - Подтверждения выполнения являются операторскими защитными мерами, а не отдельной границей авторизации для этой конечной точки HTTP. Если инструмент доступен здесь посредством аутентификации Gateway и политики инструментов, `/tools/invoke` не добавляет дополнительный запрос подтверждения для каждого вызова. - Если здесь доступен `exec`, считайте его изменяющим состояние интерфейсом оболочки. Запрет `write`, `edit`, `apply_patch` или HTTP-инструментов записи в файловую систему не делает выполнение команд оболочки доступным только для чтения. - Не передавайте учётные данные Bearer для Gateway недоверенным вызывающим сторонам. Если требуется разделение между границами доверия, запускайте отдельные экземпляры Gateway (в идеале от имени разных пользователей ОС или на разных хостах). Gateway HTTP также по умолчанию применяет жёсткий список запретов (даже если политика сеанса разрешает инструмент): | Инструмент | Причина | | ---------------- | --------------------------------------------------------- | | `exec` | Прямое выполнение команд (поверхность RCE) | | `spawn` | Создание произвольных дочерних процессов (поверхность RCE) | | `shell` | Выполнение команд оболочки (поверхность RCE) | | `fs_write` | Произвольное изменение файлов на хосте | | `fs_delete` | Произвольное удаление файлов на хосте | | `fs_move` | Произвольное перемещение или переименование файлов на хосте | | `apply_patch` | Применение исправлений может перезаписывать произвольные файлы | | `sessions_spawn` | Оркестрация сеансов; удалённый запуск агентов представляет собой RCE | | `sessions_send` | Внедрение сообщений между сеансами | | `cron` | Уровень управления постоянной автоматизацией | | `gateway` | Уровень управления Gateway; предотвращает изменение конфигурации через HTTP | | `nodes` | Ретрансляция команд Node может обращаться к `system.run` на сопряжённых хостах | `cron`, `gateway` и `nodes` также доступны только владельцу: даже вне этого списка запретов по умолчанию вызывающие стороны без прав владельца не могут вызывать их через этот интерфейс. Настройте общий список запретов с помощью `gateway.tools`: ```json5 { gateway: { tools: { // Дополнительные инструменты, блокируемые через HTTP /tools/invoke deny: ["browser"], // Удаление инструментов из списка запретов по умолчанию для вызывающих сторон с правами владельца или администратора 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: ` (если существует несколько учётных записей) - `x-openclaw-message-to: ` (цель доставки для политики инструмента сообщений) - `x-openclaw-thread-id: ` (контекст ветки для политики инструмента сообщений) ## Ответы | Статус | Значение | | ------ | ---------------------------------------------------------------------------------------------- | | `200` | `{ ok: true, result }` | | `400` | `{ ok: false, error: { type, message } }` (недопустимый запрос или ошибка входных данных инструмента) | | `401` | Не авторизовано | | `403` | `{ ok: false, error: { type, message, requiresApproval? } }` (вызов инструмента заблокирован политикой) | | `404` | Инструмент недоступен (не найден или отсутствует в списке разрешённых) | | `405` | Метод не разрешён | | `408` | Истекло время ожидания чтения тела запроса | | `413` | Размер тела запроса превысил максимальный размер полезной нагрузки | | `429` | Аутентификация ограничена по частоте запросов (задан `Retry-After`) | | `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) - [Инструменты и плагины](/ru/tools)