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

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

​

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

• аутентификация с общим секретом (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.

​

Граница безопасности (важно)

• 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

​

Тело запроса

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

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

​

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

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

• Одобрения exec — это операторские защитные ограничения, а не отдельная граница авторизации для этого HTTP-эндпоинта. Если инструмент доступен здесь через аутентификацию Gateway + политику инструментов, /tools/invoke не добавляет дополнительный запрос одобрения для каждого вызова.
• Если exec доступен здесь, рассматривайте его как изменяющую shell-поверхность. Запрет write, edit, apply_patch или HTTP-инструментов записи в файловую систему не делает выполнение shell доступным только для чтения.
• Не передавайте bearer-учетные данные Gateway недоверенным вызывающим сторонам. Если вам нужно разделение между границами доверия, запускайте отдельные 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: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      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 secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

​

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

• Протокол Gateway
• Инструменты и plugins