Вызов инструментов (HTTP)

Шлюз OpenClaw предоставляет простую конечную точку HTTP для прямого вызова одного инструмента. Она всегда включена, но контролируется аутентификацией шлюза и политикой инструментов.

  • POST /tools/invoke
  • Тот же порт, что и шлюз (мультиплексирование WS + HTTP): http://<gateway-host>:<port>/tools/invoke

Максимальный размер полезной нагрузки по умолчанию составляет 2 МБ.

Аутентификация

Использует конфигурацию аутентификации шлюза. Отправьте токен носителя:

  • Authorization: Bearer <token>

Примечания:

  • Когда gateway.auth.mode="token", используйте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN).
  • Когда gateway.auth.mode="password", используйте gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).

Тело запроса

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

Поля:

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

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

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

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

Если инструмент не разрешен политикой, конечная точка возвращает 404.

Чтобы помочь групповым политикам разрешить контекст, вы можете опционально установить:

  • x-openclaw-message-channel: <channel> (пример: slack, telegram)
  • x-openclaw-account-id: <accountId> (когда существует несколько аккаунтов)

Ответы

  • 200 → \{ ok: true, result \}
  • 400 → \{ ok: false, error: \{ type, message \} \} (неверный запрос или ошибка инструмента)
  • 401 → unauthorized
  • 404 → инструмент недоступен (не найден или не в списке разрешений)
  • 405 → метод не разрешен

Пример

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '\{
    "tool": "sessions_list",
    "action": "json",
    "args": \{\}
  \}'
← Назад к документации