Gateway

Инструменты вызывают API

Gateway в OpenClaw предоставляет простой 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"): заголовок аутентификации не требуется

Примечания:

Когда gateway.auth.mode="token", используйте gateway.auth.token (или OPENCLAW_GATEWAY_TOKEN).
Когда gateway.auth.mode="password", используйте gateway.auth.password (или OPENCLAW_GATEWAY_PASSWORD).
Когда gateway.auth.mode="trusted-proxy", HTTP-запрос должен поступать из настроенного доверенного источника прокси; same-host loopback-прокси требуют явного gateway.auth.trustedProxy.allowLoopback = true.
Внутренние вызывающие стороны на том же хосте, которые обходят прокси, могут использовать gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD как локальный прямой запасной вариант. Любые признаки в заголовках Forwarded, X-Forwarded-* или X-Real-IP вместо этого удерживают запрос на пути trusted-proxy.
Если 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/приватном входе; не открывайте его напрямую в публичный интернет.

Матрица аутентификации:

gateway.auth.mode="token" или "password" + Authorization: Bearer ...
- доказывает владение общим операторским секретом gateway
- игнорирует более узкие x-openclaw-scopes
- восстанавливает полный набор операторских областей по умолчанию: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- рассматривает прямые вызовы инструментов на этом эндпоинте как обращения от отправителя-владельца
доверенные HTTP-режимы с идентификацией (например, аутентификация через доверенный прокси или gateway.auth.mode="none" на приватном входе)
- аутентифицируют некоторую внешнюю доверенную идентичность или границу развертывания
- учитывают x-openclaw-scopes, когда заголовок присутствует
- возвращаются к обычному набору операторских областей по умолчанию, когда заголовок отсутствует
- теряют семантику владельца только тогда, когда вызывающая сторона явно сужает области и опускает operator.admin

Тело запроса

json

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

Поля:

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

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

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

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

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

Важные примечания о границах:

Одобрения exec — это операторские защитные ограничения, а не отдельная граница авторизации для этого HTTP-эндпоинта. Если инструмент доступен здесь через аутентификацию Gateway + политику инструментов, /tools/invoke не добавляет дополнительный запрос одобрения для каждого вызова.
Если exec доступен здесь, рассматривайте его как изменяющую shell-поверхность. Запрет write, edit, apply_patch или HTTP-инструментов записи в файловую систему не делает выполнение shell доступным только для чтения.
Не передавайте bearer-учетные данные Gateway недоверенным вызывающим сторонам. Если вам нужно разделение между границами доверия, запускайте отдельные gateway (и в идеале отдельных пользователей/хосты ОС).

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

exec - прямое выполнение команд (поверхность RCE)
spawn - произвольное создание дочерних процессов (поверхность RCE)
shell - выполнение shell-команд (поверхность RCE)
fs_write - произвольное изменение файлов на хосте
fs_delete - произвольное удаление файлов на хосте
fs_move - произвольное перемещение/переименование файлов на хосте
apply_patch - применение патча может переписывать произвольные файлы
sessions_spawn - оркестрация сессий; удаленный запуск агентов является RCE
sessions_send - внедрение сообщений между сессиями
cron - плоскость управления постоянной автоматизацией
gateway - плоскость управления gateway; предотвращает перенастройку через HTTP
nodes - ретрансляция команд узла может достигать system.run на сопряженных хостах
whatsapp_login - интерактивная настройка, требующая сканирования QR-кода в терминале; зависает при HTTP

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

json5

{  gateway: {    tools: {      // Additional tools to block over HTTP /tools/invoke      deny: ["browser"],      // Remove tools from the default deny list for owner/admin callers      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> (когда существует несколько учетных записей)

Ответы

200 → { ok: true, result }
400 → { ok: false, error: { type, message } } (недопустимый запрос или ошибка ввода инструмента)
401 → не авторизовано
429 → аутентификация ограничена по частоте (Retry-After задан)
404 → инструмент недоступен (не найден или не включен в список разрешенных)
405 → метод не разрешен
500 → { ok: false, error: { type, message } } (неожиданная ошибка выполнения инструмента; сообщение очищено)

Пример

bash

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

Связанные материалы

Was this useful?