--- read_when: - Виклик інструментів без виконання повного ходу агента - Створення автоматизацій, які потребують забезпечення дотримання політики інструментів summary: Викличте один інструмент безпосередньо через HTTP-ендпоінт Gateway title: API виклику інструментів x-i18n: generated_at: "2026-05-11T20:40:13Z" model: gpt-5.5 provider: openai source_hash: 531e77673fb9c06d0cc8f8145d874e22f7e590dc3e4c5dee1574874af5666886 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 MB. ## Автентифікація Використовує конфігурацію автентифікації Gateway. Поширені шляхи HTTP-автентифікації: - автентифікація зі спільним секретом (`gateway.auth.mode="token"` або `"password"`): `Authorization: Bearer ` - довірена HTTP-автентифікація з ідентичністю (`gateway.auth.mode="trusted-proxy"`): маршрутизуйте через налаштований identity-aware proxy і дозвольте йому вставити потрібні заголовки ідентичності - відкрита автентифікація для приватного ingress (`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-запит має надходити з налаштованого довіреного джерела proxy; same-host local loopback proxy потребують явного `gateway.auth.trustedProxy.allowLoopback = true`. - Якщо `gateway.auth.rateLimit` налаштовано і трапляється забагато невдалих спроб автентифікації, ендпоїнт повертає `429` з `Retry-After`. ## Межа безпеки (важливо) Вважайте цей ендпоїнт поверхнею **повного операторського доступу** для екземпляра gateway. - HTTP bearer auth тут не є вузькою моделлю per-user scope. - Чинний токен/пароль Gateway для цього ендпоїнта слід вважати обліковими даними власника/оператора. - Для режимів автентифікації зі спільним секретом (`token` і `password`) ендпоїнт відновлює звичайні повні операторські типові значення, навіть якщо викликач надсилає вужчий заголовок `x-openclaw-scopes`. - Автентифікація зі спільним секретом також розглядає прямі виклики інструментів на цьому ендпоїнті як ходи owner-sender. - Довірені HTTP-режими з ідентичністю (наприклад, автентифікація trusted proxy або `gateway.auth.mode="none"` на приватному ingress) враховують `x-openclaw-scopes`, коли він присутній, інакше повертаються до звичайного набору типових операторських scope. - Тримайте цей ендпоїнт лише на loopback/tailnet/private ingress; не виставляйте його напряму в публічний інтернет. Матриця автентифікації: - `gateway.auth.mode="token"` або `"password"` + `Authorization: Bearer ...` - доводить володіння спільним операторським секретом gateway - ігнорує вужчий `x-openclaw-scopes` - відновлює повний набір типових операторських scope: `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write` - розглядає прямі виклики інструментів на цьому ендпоїнті як ходи owner-sender - довірені HTTP-режими з ідентичністю (наприклад, автентифікація trusted proxy або `gateway.auth.mode="none"` на приватному ingress) - автентифікують певну зовнішню довірену ідентичність або межу розгортання - враховують `x-openclaw-scopes`, коли заголовок присутній - повертаються до звичайного набору типових операторських scope, коли заголовок відсутній - втрачають семантику власника лише тоді, коли викликач явно звужує scope і пропускає `operator.admin` ## Тіло запиту ```json { "tool": "sessions_list", "action": "json", "args": {}, "sessionKey": "main", "dryRun": false } ``` Поля: - `tool` (рядок, обов’язкове): назва інструмента для виклику. - `action` (рядок, необов’язкове): зіставляється з args, якщо схема інструмента підтримує `action`, а корисне навантаження args його пропустило. - `args` (об’єкт, необов’язкове): аргументи, специфічні для інструмента. - `sessionKey` (рядок, необов’язкове): ключ цільової сесії. Якщо пропущено або дорівнює `"main"`, Gateway використовує налаштований ключ основної сесії (враховує `session.mainKey` і default agent, або `global` у global scope). - `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` не додає додатковий prompt підтвердження для кожного виклику. - Якщо `exec` доступний тут, вважайте його мутаційною shell-поверхнею. Заборона `write`, `edit`, `apply_patch` або HTTP-інструментів запису у файлову систему не робить виконання shell доступним лише для читання. - Не передавайте bearer-облікові дані Gateway недовіреним викликачам. Якщо вам потрібне розділення між межами довіри, запускайте окремі gateways (і в ідеалі окремих користувачів/хости ОС). Gateway HTTP також типово застосовує жорсткий deny list (навіть якщо політика сесії дозволяє інструмент): - `exec` - пряме виконання команд (поверхня RCE) - `spawn` - довільне створення дочірніх процесів (поверхня RCE) - `shell` - виконання команд shell (поверхня RCE) - `fs_write` - довільна зміна файлів на хості - `fs_delete` - довільне видалення файлів на хості - `fs_move` - довільне переміщення/перейменування файлів на хості - `apply_patch` - застосування patch може переписувати довільні файли - `sessions_spawn` - оркестрація сесій; віддалене створення агентів є RCE - `sessions_send` - вставлення повідомлень між сесіями - `cron` - площина керування постійною автоматизацією - `gateway` - площина керування gateway; запобігає переналаштуванню через HTTP - `nodes` - ретрансляція команд вузла може досягати system.run на спарених хостах - `whatsapp_login` - інтерактивне налаштування, що потребує сканування QR у терміналі; зависає на HTTP Ви можете налаштувати цей deny list через `gateway.tools`: ```json5 { gateway: { tools: { // Additional tools to block over HTTP /tools/invoke deny: ["browser"], // Remove tools from the default deny list allow: ["gateway"], }, }, } ``` Щоб допомогти груповим політикам визначити контекст, ви можете необов’язково встановити: - `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` → інструмент недоступний (не знайдено або не додано до allowlist) - `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](/uk/gateway/protocol) - [Інструменти та plugins](/uk/tools)