Gateway

API виклику інструментів

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

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

Стандартний максимальний розмір корисного навантаження становить 2 MB.

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

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

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

автентифікація зі спільним секретом (gateway.auth.mode="token" або "password"): Authorization: Bearer <token-or-password>
довірена 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.<id>.tools.allow / agents.<id>.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: <channel> (приклад: slack, telegram)
x-openclaw-account-id: <accountId> (коли існує кілька облікових записів)

Відповіді

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": {}  }'

Пов’язане

Was this useful?