---
read_when:
    - Виклик інструментів без запуску повного ходу агента
    - Створення автоматизацій, яким потрібне примусове застосування політик інструментів
summary: Викличте один інструмент безпосередньо через HTTP-кінцеву точку Gateway
title: API виклику інструментів
x-i18n:
    generated_at: "2026-06-27T17:37:33Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 2023505f5a705b62e2fd685d64d3f9bd7788d09adfe89ac99604e6660c78ad8a
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

OpenClaw's Gateway надає просту HTTP-кінцеву точку для прямого виклику одного інструмента. Вона завжди ввімкнена й використовує автентифікацію Gateway разом із політикою інструментів. Як і OpenAI-сумісна поверхня `/v1/*`, автентифікація bearer через спільний секрет вважається довіреним операторським доступом до всього gateway.

- `POST /tools/invoke`
- Той самий порт, що й Gateway (мультиплексування WS + HTTP): `http://<gateway-host>:<port>/tools/invoke`

Типовий максимальний розмір корисного навантаження — 2 МБ.

## Автентифікація

Використовує конфігурацію автентифікації Gateway.

Поширені шляхи HTTP-автентифікації:

- автентифікація через спільний секрет (`gateway.auth.mode="token"` або `"password"`):
  `Authorization: Bearer <token-or-password>`
- довірена 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`
  натомість залишають запит на шляху довіреного проксі.
- Якщо `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` (об’єкт, необов’язково): аргументи, специфічні для інструмента.
- `sessionKey` (рядок, необов’язково): цільовий ключ сеансу. Якщо пропущено або `"main"`, Gateway використовує налаштований головний ключ сеансу (враховує `session.mainKey` і типового агента або `global` у глобальній області).
- `dryRun` (булеве значення, необов’язково): зарезервовано для майбутнього використання; зараз ігнорується.

## Політика й поведінка маршрутизації

Доступність інструментів фільтрується через той самий ланцюг політик, який використовують агенти Gateway:

- `tools.profile` / `tools.byProvider.profile`
- `tools.allow` / `tools.byProvider.allow`
- `agents.<id>.tools.allow` / `agents.<id>.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` - застосування 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: <channel>` (приклад: `slack`, `telegram`)
- `x-openclaw-account-id: <accountId>` (коли існує кілька облікових записів)

## Відповіді

- `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](/uk/gateway/protocol)
- [Інструменти та plugins](/uk/tools)