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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 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"): маршрутизуйте через налаштований 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.

​

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

• 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

​

Тіло запиту

{
  "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 (логічне значення, необов’язкове): зарезервовано для майбутнього використання; наразі ігнорується.

​

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

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

• Підтвердження exec є операторськими запобіжниками, а не окремою межею авторизації для цього HTTP-ендпоїнта. Якщо інструмент доступний тут через автентифікацію Gateway + політику інструментів, /tools/invoke не додає додатковий prompt підтвердження для кожного виклику.
• Якщо exec доступний тут, вважайте його мутаційною shell-поверхнею. Заборона write, edit, apply_patch або HTTP-інструментів запису у файлову систему не робить виконання shell доступним лише для читання.
• Не передавайте bearer-облікові дані Gateway недовіреним викликачам. Якщо вам потрібне розділення між межами довіри, запускайте окремі gateways (і в ідеалі окремих користувачів/хости ОС).

• 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
      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 } } (неочікувана помилка виконання інструмента; повідомлення очищено)

​

Приклад

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