Инструменты вызывают 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-запрос поступал от настроенного доверенного источника прокси; для 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, если он присутствует, а иначе используют обычный набор операторских областей доступа по умолчанию.
• Оставляйте эту конечную точку доступной только через 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 (в идеале от имени разных пользователей ОС или на разных хостах).

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

cron, gateway и nodes также доступны только владельцу: даже вне этого списка запретов по умолчанию вызывающие стороны без прав владельца не могут вызывать их через этот интерфейс.

Настройте общий список запретов с помощью gateway.tools:

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