--- read_when: - Виклик інструментів без виконання повного циклу агента - Створення автоматизацій, що потребують примусового застосування політики інструментів summary: Виклик одного інструмента безпосередньо через HTTP-кінцеву точку Gateway title: Інструменти викликають API x-i18n: generated_at: "2026-07-12T13:16:25Z" model: gpt-5.6 postprocess_version: locale-links-v1 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-запит надходив із налаштованого джерела довіреного проксі; проксі local 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`, якщо він наявний, а інакше використовують звичайний набір операторських областей доступу за замовчуванням. - Залишайте цю кінцеву точку доступною лише через local 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 (бажано від імені окремих користувачів ОС або на окремих хостах). HTTP-інтерфейс Gateway також за замовчуванням застосовує жорсткий список заборон (навіть якщо політика сеансу дозволяє інструмент): | Інструмент | Причина | | ---------------- | --------------------------------------------------------------------------- | | `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: { // 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: ` (якщо існує кілька облікових записів) - `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](/uk/gateway/protocol) - [Інструменти та плагіни](/uk/tools)