> ## 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. # Плагин административного HTTP RPC Встроенный плагин `admin-http-rpc` предоставляет разрешённый список методов плоскости управления Gateway через HTTP для доверенной автоматизации на хосте, которая не может поддерживать открытое WebSocket-соединение с Gateway. Он поставляется с OpenClaw, но по умолчанию отключён; когда он отключён, маршрут не регистрируется. Когда он включён, добавляется `POST /api/v1/admin/rpc` на том же прослушивателе, что и Gateway (`http://:/api/v1/admin/rpc`). Включайте его только для частных инструментов хоста, автоматизации в tailnet или доверенной внутренней точки входа. Никогда не открывайте этот маршрут напрямую в публичный интернет. ## Перед включением Административный HTTP RPC предоставляет полный операторский интерфейс плоскости управления: любой вызывающий субъект, прошедший HTTP-аутентификацию Gateway, может вызывать перечисленные ниже разрешённые методы. Включайте его, только если выполняются все следующие условия: * Вызывающему субъекту доверено управление Gateway. * Вызывающий субъект не может использовать RPC-клиент WebSocket. * Маршрут доступен только через loopback, tailnet или частную аутентифицированную точку входа. * Вы проверили разрешённые методы, и они соответствуют автоматизации, которую вы планируете запускать. Для клиентов OpenClaw и интерактивных инструментов, способных поддерживать открытое WebSocket-соединение с Gateway, используйте RPC через WebSocket. ## Включение Включите встроенный плагин: > [tab] CLI > > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} > openclaw plugins enable admin-http-rpc > openclaw gateway restart > ``` > [tab] Конфигурация > > ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} > { > plugins: { > entries: { > "admin-http-rpc": { enabled: true }, > }, > }, > } > ``` Маршрут регистрируется при запуске плагина, поэтому после изменения конфигурации плагина перезапустите Gateway. Отключите его, когда HTTP-интерфейс больше не нужен: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins disable admin-http-rpc openclaw gateway restart ``` ## Проверка маршрута Используйте `health` как минимальный безопасный запрос: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -sS http://:/api/v1/admin/rpc \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"method":"health","params":{}}' ``` Успешный ответ содержит `ok: true`: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "id": "generated-request-id", "ok": true, "payload": { "status": "ok" } } ``` Когда плагин отключён, маршрут возвращает `404`, поскольку он не зарегистрирован. ## Аутентификация Маршрут плагина использует HTTP-аутентификацию Gateway. Распространённые варианты аутентификации: * аутентификация с общим секретом (`gateway.auth.mode="token"` или `"password"`): `Authorization: Bearer ` * доверенная HTTP-аутентификация с идентификационными данными (`gateway.auth.mode="trusted-proxy"`): направьте запрос через настроенный прокси-сервер с поддержкой идентификации и позвольте ему добавить необходимые заголовки идентификации * открытая аутентификация для частной точки входа (`gateway.auth.mode="none"`): заголовок аутентификации не требуется ## Модель безопасности Считайте этот плагин полноценным операторским интерфейсом Gateway. * Включение плагина намеренно предоставляет доступ к административным RPC-методам из разрешённого списка по адресу `/api/v1/admin/rpc`. * Плагин объявляет зарезервированный контракт манифеста `contracts.gatewayMethodDispatch: ["authenticated-request"]`, который позволяет его HTTP-маршруту, аутентифицированному через Gateway, передавать методы плоскости управления для выполнения внутри процесса. Это не песочница: контракт предотвращает случайное использование зарезервированных вспомогательных функций SDK, но доверенные плагины всё равно выполняются в процессе Gateway. * Аутентификация Bearer с общим секретом (режимы `token`/`password`) подтверждает владение операторским секретом Gateway; более узкие заголовки `x-openclaw-scopes` в этом случае игнорируются, и восстанавливаются обычные полные операторские права по умолчанию. * Доверенная HTTP-аутентификация с идентификационными данными (режим `trusted-proxy`) учитывает `x-openclaw-scopes`, если он указан. * `gateway.auth.mode="none"` означает, что при включённом плагине этот маршрут не требует аутентификации. Используйте этот режим только за частной точкой входа, которой вы полностью доверяете. * После успешной аутентификации маршрута плагина запросы передаются тем же обработчикам методов Gateway и проходят те же проверки областей доступа, что и RPC через WebSocket. * Маршрут остаётся доступным во время подготовленной аренды приостановки. По-прежнему доступны ограниченная проверка запросов и локальный ответ обнаружения `commands.list`. Из методов, передаваемых в Gateway, при закрытом допуске могут выполняться только `gateway.suspend.prepare`, `gateway.suspend.status` и `gateway.suspend.resume`; остальные методы из разрешённого списка возвращают обычный допускающий повторную попытку ответ Gateway `UNAVAILABLE`. * Оставляйте этот маршрут доступным только через loopback, tailnet или частную доверенную точку входа. Не открывайте его напрямую в публичный интернет. Если вызывающие субъекты находятся по разные стороны границ доверия, используйте отдельные экземпляры Gateway. ## Запрос ```http theme={"theme":{"light":"min-light","dark":"min-dark"}} POST /api/v1/admin/rpc Authorization: Bearer Content-Type: application/json ``` ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "id": "optional-request-id", "method": "health", "params": {} } ``` Поля: * `id` (строка, необязательно): копируется в ответ. Если поле опущено, создаётся UUID. * `method` (строка, обязательно): имя разрешённого метода Gateway. * `params` (любое значение, необязательно): параметры конкретного метода. Максимальный размер тела запроса по умолчанию — 1 МБ. ## Ответ Успешные ответы используют формат RPC Gateway: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "id": "optional-request-id", "ok": true, "payload": {} } ``` Ошибки методов Gateway используют следующий формат: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "id": "optional-request-id", "ok": false, "error": { "code": "INVALID_REQUEST", "message": "bad params" } } ``` Статус HTTP соответствует коду ошибки: | Код ошибки | Статус HTTP | | - | - | | `INVALID_REQUEST` | 400 | | `APPROVAL_NOT_FOUND` | 404 | | `NOT_LINKED`, `NOT_PAIRED` | 409 | | `UNAVAILABLE` | 503 | | `AGENT_TIMEOUT` | 504 | | любой другой код | 500 | ## Разрешённые методы * обнаружение: `commands.list` Возвращает имена методов HTTP RPC, разрешённых этим плагином. * Gateway: `health`, `status`, `logs.tail`, `usage.status`, `usage.cost`, `gateway.restart.request`, `gateway.suspend.prepare`, `gateway.suspend.status`, `gateway.suspend.resume` * конфигурация: `config.get`, `config.schema`, `config.schema.lookup`, `config.set`, `config.patch`, `config.apply` * каналы: `channels.status`, `channels.start`, `channels.stop`, `channels.logout` * веб: `web.login.start`, `web.login.wait` * модели: `models.list`, `models.authStatus` * агенты: `agents.list`, `agents.create`, `agents.update`, `agents.delete` * подтверждения: `exec.approvals.get`, `exec.approvals.set`, `exec.approvals.node.get`, `exec.approvals.node.set` * Cron: `cron.status`, `cron.list`, `cron.get`, `cron.runs`, `cron.add`, `cron.update`, `cron.remove`, `cron.run` * устройства: `device.pair.list`, `device.pair.approve`, `device.pair.reject`, `device.pair.remove` * узлы: `node.list`, `node.describe`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove`, `node.rename` * задачи: `tasks.list`, `tasks.get`, `tasks.cancel` * диагностика: `doctor.memory.status`, `update.status` Остальные методы Gateway блокируются, пока не будут добавлены намеренно. ## Сравнение с WebSocket Обычный путь RPC через WebSocket Gateway остаётся предпочтительным API плоскости управления для клиентов OpenClaw. Используйте административный HTTP RPC только для инструментов хоста, которым нужен HTTP-интерфейс запросов и ответов. Клиенты WebSocket с общим токеном без доверенной идентификации устройства не могут самостоятельно объявлять административные области доступа при подключении. Административный HTTP RPC намеренно следует существующей модели доверенного HTTP-оператора: когда плагин включён, Bearer-аутентификация с общим секретом считается полным операторским доступом к этому административному интерфейсу. ## Устранение неполадок `404 Not Found` : Плагин отключён, Gateway не был перезапущен после его включения либо запрос направляется другому процессу Gateway. `401 Unauthorized` : Запрос не прошёл HTTP-аутентификацию Gateway. Проверьте Bearer-токен или заголовки идентификации доверенного прокси-сервера. `405 Method Not Allowed` : В запросе использовалось что-то отличное от `POST`. `413 Payload Too Large` : Размер тела запроса превысил ограничение в 1 МБ. `400 INVALID_REQUEST` : Тело запроса не является допустимым JSON, поле `method` отсутствует, метод не входит в разрешённый список плагина либо идентификатор возобновления приостановки не соответствует активной аренде. `503 UNAVAILABLE` : Метод Gateway запускается, ограничен по частоте запросов, приостановлен или ожидает завершения конкурирующей операции приостановки или возобновления. Проверьте `error.details`, если он присутствует, и соблюдайте `error.retryAfterMs` перед повторной попыткой. ## Связанные материалы * [Операторские области доступа](https://docs2.openclaw.ai/ru/gateway/operator-scopes.md) * [Безопасность Gateway](https://docs2.openclaw.ai/ru/gateway/security.md) * [Удалённый доступ](https://docs2.openclaw.ai/ru/gateway/remote.md) * [Манифест плагина](https://docs2.openclaw.ai/ru/plugins/manifest.md#contracts-reference) * [Подпути SDK](https://docs2.openclaw.ai/ru/plugins/sdk-subpaths.md)