--- read_when: - Создание инструментов для хоста, которые не могут использовать RPC-клиент Gateway на основе WebSocket - Предоставление доступа к автоматизации администрирования Gateway через приватную доверенную точку входа - Аудит модели безопасности HTTP-доступа к методам Gateway summary: Предоставьте доступ к выбранным методам плоскости управления Gateway через встроенный подключаемый по желанию плагин admin-http-rpc title: Плагин административного HTTP RPC x-i18n: generated_at: "2026-07-13T18:26:12Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 0709081efd0ce65cef7edac54df9a71978cbad17e2b25df83ac9075de938376c source_path: plugins/admin-http-rpc.md workflow: 16 --- Встроенный плагин `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. ## Включение Включите встроенный плагин: ```bash openclaw plugins enable admin-http-rpc openclaw gateway restart ``` ```json5 { plugins: { entries: { "admin-http-rpc": { enabled: true }, }, }, } ``` Маршрут регистрируется при запуске плагина, поэтому после изменения конфигурации плагина перезапустите Gateway. Отключите его, когда HTTP-интерфейс больше не нужен: ```bash openclaw plugins disable admin-http-rpc openclaw gateway restart ``` ## Проверка маршрута Используйте `health` как минимальный безопасный запрос: ```bash curl -sS http://:/api/v1/admin/rpc \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"method":"health","params":{}}' ``` Успешный ответ содержит `ok: true`: ```json { "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 POST /api/v1/admin/rpc Authorization: Bearer Content-Type: application/json ``` ```json { "id": "optional-request-id", "method": "health", "params": {} } ``` Поля: - `id` (строка, необязательно): копируется в ответ. Если поле опущено, создаётся UUID. - `method` (строка, обязательно): имя разрешённого метода Gateway. - `params` (любое значение, необязательно): параметры конкретного метода. Максимальный размер тела запроса по умолчанию — 1 МБ. ## Ответ Успешные ответы используют формат RPC Gateway: ```json { "id": "optional-request-id", "ok": true, "payload": {} } ``` Ошибки методов Gateway используют следующий формат: ```json { "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` перед повторной попыткой. ## Связанные материалы - [Операторские области доступа](/ru/gateway/operator-scopes) - [Безопасность Gateway](/ru/gateway/security) - [Удалённый доступ](/ru/gateway/remote) - [Манифест плагина](/ru/plugins/manifest#contracts-reference) - [Подпути SDK](/ru/plugins/sdk-subpaths)