Gateway

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

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

Пов’язане

Was this useful?