Инструменты вызывают 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-запрос поступал от настроенного доверенного источника прокси; для 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, если он присутствует, а иначе используют обычный набор операторских областей доступа по умолчанию.
• Оставляйте эту конечную точку доступной только через 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: {
      // Дополнительные инструменты, блокируемые через HTTP /tools/invoke
      deny: ["browser"],
      // Удаление инструментов из списка запретов по умолчанию для вызывающих сторон с правами владельца или администратора
      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
• Инструменты и плагины