Інструменти викликають API

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

​

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

• автентифікація зі спільним секретом (gateway.auth.mode="token" або "password"): Authorization: Bearer <token-or-password>
• довірена HTTP-автентифікація з ідентифікаційними даними (gateway.auth.mode="trusted-proxy"): спрямовуйте запит через налаштований проксі з підтримкою ідентифікації, щоб він додавав необхідні заголовки ідентифікації
• відкрита автентифікація через приватну точку входу (gateway.auth.mode="none"): заголовок автентифікації не потрібен

• mode="token" використовує gateway.auth.token (або OPENCLAW_GATEWAY_TOKEN).
• mode="password" використовує gateway.auth.password (або OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" вимагає, щоб HTTP-запит надходив із налаштованого джерела довіреного проксі; проксі local 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, якщо він наявний, а інакше використовують звичайний набір операторських областей доступу за замовчуванням.
• Залишайте цю кінцеву точку доступною лише через local loopback, tailnet або приватну точку входу; не відкривайте її безпосередньо для загальнодоступного інтернету.

​

Тіло запиту

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

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

​

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

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

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

{
  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> (якщо існує кілька облікових записів)
• x-openclaw-message-to: <target> (ціль доставлення для політики інструментів повідомлень)
• x-openclaw-thread-id: <threadId> (контекст гілки для політики інструментів повідомлень)

​

Відповіді

​

Приклад

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
• Інструменти та плагіни