Протоколы и API

API вызова инструментов

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

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

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

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

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

• Authorization: Bearer

Примечания:

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

Тело запроса

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

Поля:

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

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

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

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

Если инструмент не разрешён политикой, конечная точка возвращает 404. HTTP шлюза также по умолчанию применяет жёсткий список запрета (даже если политика сессии разрешает инструмент):

• sessions_spawn
• sessions_send
• gateway
• whatsapp_login

Вы можете настроить этот список запрета через gateway.tools:

{
  gateway: {
    tools: {
      // Дополнительные инструменты для блокировки через HTTP /tools/invoke
      deny: ["browser"],
      // Удалить инструменты из списка запрета по умолчанию
      allow: ["gateway"],
    },
  },
}

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

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

Ответы

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

API OpenResponsesCLI Бэкенды

---