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

OpenClaw 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"): заголовок автентифікації не потрібен

Примітки:

• 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.

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

Розглядайте цю кінцеву точку як інтерфейс із повним операторським доступом до екземпляра Gateway.

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

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

Доступність інструментів фільтрується через той самий ланцюжок політик, який використовують агенти Gateway:

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

Якщо політика не дозволяє інструмент, кінцева точка повертає 404.

Важливі примітки щодо межі:

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

HTTP-інтерфейс Gateway також за замовчуванням застосовує жорсткий список заборон (навіть якщо політика сеансу дозволяє інструмент):

cron, gateway і nodes також доступні лише власнику: навіть поза цим стандартним списком заборон виклики не від власника не можуть запускати їх через цей інтерфейс.

Налаштуйте загальний список заборон через gateway.tools:

{  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> (якщо існує кілька облікових записів)
• 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
• Інструменти та плагіни