Плагин административного HTTP RPC

Встроенный плагин admin-http-rpc предоставляет разрешённый список методов плоскости управления Gateway через HTTP для доверенной автоматизации на хосте, которая не может поддерживать открытое WebSocket-соединение с Gateway.

Он поставляется с OpenClaw, но по умолчанию отключён; когда он отключён, маршрут не регистрируется. Когда он включён, добавляется POST /api/v1/admin/rpc на том же прослушивателе, что и Gateway (http://<gateway-host>:<port>/api/v1/admin/rpc).

Включайте его только для частных инструментов хоста, автоматизации в tailnet или доверенной внутренней точки входа. Никогда не открывайте этот маршрут напрямую в публичный интернет.

Перед включением

Административный HTTP RPC предоставляет полный операторский интерфейс плоскости управления: любой вызывающий субъект, прошедший HTTP-аутентификацию Gateway, может вызывать перечисленные ниже разрешённые методы. Включайте его, только если выполняются все следующие условия:

• Вызывающему субъекту доверено управление Gateway.
• Вызывающий субъект не может использовать RPC-клиент WebSocket.
• Маршрут доступен только через loopback, tailnet или частную аутентифицированную точку входа.
• Вы проверили разрешённые методы, и они соответствуют автоматизации, которую вы планируете запускать.

Для клиентов OpenClaw и интерактивных инструментов, способных поддерживать открытое WebSocket-соединение с Gateway, используйте RPC через WebSocket.

Включение

Включите встроенный плагин:

openclaw plugins enable admin-http-rpcopenclaw gateway restart

{  plugins: {    entries: {      "admin-http-rpc": { enabled: true },    },  },}

Маршрут регистрируется при запуске плагина, поэтому после изменения конфигурации плагина перезапустите Gateway.

Отключите его, когда HTTP-интерфейс больше не нужен:

openclaw plugins disable admin-http-rpcopenclaw gateway restart

Проверка маршрута

Используйте health как минимальный безопасный запрос:

curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \  -H 'Authorization: Bearer <gateway-token>' \  -H 'Content-Type: application/json' \  -d '{"method":"health","params":{}}'

Успешный ответ содержит ok: true:

{  "id": "generated-request-id",  "ok": true,  "payload": {    "status": "ok"  }}

Когда плагин отключён, маршрут возвращает 404, поскольку он не зарегистрирован.

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

Маршрут плагина использует HTTP-аутентификацию Gateway.

Распространённые варианты аутентификации:

• аутентификация с общим секретом (gateway.auth.mode="token" или "password"): Authorization: Bearer <token-or-password>
• доверенная 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.

Запрос

POST /api/v1/admin/rpcAuthorization: Bearer <gateway-token>Content-Type: application/json

{  "id": "optional-request-id",  "method": "health",  "params": {}}

Поля:

• id (строка, необязательно): копируется в ответ. Если поле опущено, создаётся UUID.
• method (строка, обязательно): имя разрешённого метода Gateway.
• params (любое значение, необязательно): параметры конкретного метода.

Максимальный размер тела запроса по умолчанию — 1 МБ.

Ответ

Успешные ответы используют формат RPC Gateway:

{  "id": "optional-request-id",  "ok": true,  "payload": {}}

Ошибки методов Gateway используют следующий формат:

{  "id": "optional-request-id",  "ok": false,  "error": {    "code": "INVALID_REQUEST",    "message": "bad params"  }}

Статус HTTP соответствует коду ошибки:

Разрешённые методы

• обнаружение: 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 перед повторной попыткой.

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

• Операторские области доступа
• Безопасность Gateway
• Удалённый доступ
• Манифест плагина
• Подпути SDK