Перейти к основному содержанию

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

Gateway (шлюз) OpenClaw предоставляет простой HTTP‑эндпоинт для прямого вызова одного инструмента. Он всегда включён, но доступ к нему ограничен аутентификацией Gateway и политиками инструментов.
  • POST /tools/invoke
  • Тот же порт, что и у Gateway (мультиплексирование WS + HTTP): http://<gateway-host>:<port>/tools/invoke
Максимальный размер полезной нагрузки по умолчанию — 2 МБ.

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

Используется конфигурация аутентификации Gateway. Отправьте bearer‑токен:
  • Authorization: Bearer <token>
Примечания:
  • Когда gateway.auth.mode="token", используйте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN).
  • Когда gateway.auth.mode="password", используйте gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).
  • Если настроен gateway.auth.rateLimit и происходит слишком много неудачных попыток аутентификации, endpoint возвращает 429 с Retry-After.

​
Тело запроса

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
Поля:
  • tool (string, обязательно): имя инструмента для вызова.
  • action (string, необязательно): сопоставляется с args, если схема инструмента поддерживает action и полезная нагрузка args его не содержит.
  • args (object, необязательно): аргументы, специфичные для инструмента.
  • sessionKey (string, необязательно): целевой ключ сеанса. Если опущен или "main", Gateway использует настроенный основной ключ сеанса (с учётом session.mainKey и агента по умолчанию либо global в глобальной области).
  • dryRun (boolean, необязательно): зарезервировано для будущего использования; в настоящее время игнорируется.

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

Доступность инструментов фильтруется той же цепочкой политик, что используется агентами Gateway:
  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • групповые политики (если ключ сеанса сопоставляется с группой или каналом)
  • политика субагента (при вызове с ключом сеанса субагента)
Если инструмент запрещён политикой, эндпоинт возвращает 404. Gateway HTTP также по умолчанию применяет жёсткий deny list (даже если политика сессии разрешает инструмент):
  • sessions_spawn
  • sessions_send
  • gateway
  • whatsapp_login
Вы можете настроить этот deny list через gateway.tools: 
{
  gateway: {
    tools: {
      // Дополнительные инструменты для блокировки через HTTP /tools/invoke
      deny: ["browser"],
      // Удалить инструменты из 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 → инструмент недоступен (не найден или не в списке разрешённых)
  • 405 → метод не разрешён
  • 500 → { ok: false, error: { type, message } } (неожиданная ошибка выполнения инструмента; сообщение очищено)

​
Пример

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": {}
  }'