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

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

​

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

• автентифікація через спільний секрет (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.

​

Межа безпеки (важливо)

• 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

​

Тіло запиту

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

• tool (рядок, обов’язково): назва інструмента для виклику.
• action (рядок, необов’язково): зіставляється з аргументами, якщо схема інструмента підтримує action, а корисне навантаження аргументів його не містить.
• args (об’єкт, необов’язково): аргументи, специфічні для інструмента.
• sessionKey (рядок, необов’язково): цільовий ключ сеансу. Якщо пропущено або "main", Gateway використовує налаштований головний ключ сеансу (враховує session.mainKey і типового агента або global у глобальній області).
• dryRun (булеве значення, необов’язково): зарезервовано для майбутнього використання; зараз ігнорується.

​

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

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• групові політики (якщо ключ сеансу зіставляється з групою або каналом)
• політика субагента (під час виклику з ключем сеансу субагента)

• Схвалення Exec — це операторські запобіжники, а не окрема межа авторизації для цієї HTTP-кінцевої точки. Якщо інструмент доступний тут через автентифікацію Gateway + політику інструментів, /tools/invoke не додає додаткового запиту схвалення для кожного виклику.
• Якщо exec доступний тут, вважайте його мутаційною поверхнею shell. Заборона write, edit, apply_patch або HTTP-інструментів запису у файлову систему не робить виконання shell доступним лише для читання.
• Не передавайте bearer-облікові дані Gateway недовіреним викликачам. Якщо потрібне розділення між межами довіри, запускайте окремі 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: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      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 → інструмент недоступний (не знайдено або не внесено до списку дозволених)
• 405 → метод не дозволено
• 500 → { ok: false, error: { type, message } } (неочікувана помилка виконання інструмента; повідомлення очищено)

​

Приклад

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
• Інструменти та plugins