> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Инструменты вызывают 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/ru/gateway/protocol)
* [Инструменты и plugins](/ru/tools)