> ## 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.

# Admin HTTP RPC Plugin

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

Plugin включен в OpenClaw, но по умолчанию отключен. Когда он отключен, маршрут не регистрируется. Когда он включен, он добавляет:

* `POST /api/v1/admin/rpc`
* тот же слушатель, что и Gateway: `http://<gateway-host>:<port>/api/v1/admin/rpc`

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

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

Admin HTTP RPC — это полноценная операторская поверхность плоскости управления. Любой вызывающий клиент, прошедший HTTP-аутентификацию Gateway, может вызывать разрешенные методы на этой странице.

Используйте его, когда выполняются все эти условия:

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

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

## Включение

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

<Tabs>
  <Tab title="CLI">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins enable admin-http-rpc
    openclaw gateway restart
    ```
  </Tab>

  <Tab title="Config">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      plugins: {
        entries: {
          "admin-http-rpc": { enabled: true },
        },
      },
    }
    ```
  </Tab>
</Tabs>

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

Отключите его, когда 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://<gateway-host>:<port>/api/v1/admin/rpc \
  -H 'Authorization: Bearer <gateway-token>' \
  -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"
  }
}
```

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

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

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

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

* аутентификация с общим секретом (`gateway.auth.mode="token"` или `"password"`): `Authorization: Bearer <token-or-password>`
* доверенная HTTP-аутентификация с удостоверением (`gateway.auth.mode="trusted-proxy"`): направляйте через настроенный прокси с учетом удостоверений и позвольте ему внедрить требуемые заголовки удостоверения
* открытая аутентификация через приватный вход (`gateway.auth.mode="none"`): заголовок аутентификации не требуется

## Модель безопасности

Относитесь к этому plugin как к полноценной операторской поверхности Gateway.

* Включение plugin намеренно предоставляет доступ к разрешенным admin RPC-методам по адресу `/api/v1/admin/rpc`.
* Plugin объявляет зарезервированный контракт манифеста `contracts.gatewayMethodDispatch: ["authenticated-request"]`, чтобы его HTTP-маршрут с аутентификацией Gateway мог диспетчеризовать методы плоскости управления внутри процесса.
* Bearer-аутентификация с общим секретом подтверждает владение операторским секретом gateway.
* Для аутентификации `token` и `password` более узкие заголовки `x-openclaw-scopes` игнорируются, а обычные полные операторские значения по умолчанию восстанавливаются.
* Доверенные HTTP-режимы с удостоверением учитывают `x-openclaw-scopes`, когда они присутствуют.
* `gateway.auth.mode="none"` означает, что этот маршрут не аутентифицирован, если plugin включен. Используйте это только за приватным входом, которому вы полностью доверяете.
* После прохождения аутентификации маршрута plugin запросы диспетчеризуются через те же обработчики методов Gateway и проверки областей доступа, что и WebSocket RPC.
* Держите этот маршрут на loopback, в tailnet или за приватным доверенным входом. Не открывайте его напрямую в публичный интернет.
* Контракты манифеста plugin не являются песочницей. Они предотвращают случайное использование зарезервированных вспомогательных средств SDK; доверенные plugins все равно выполняются в процессе Gateway.

Используйте отдельные gateway, когда вызывающие клиенты пересекают границы доверия.

## Запрос

```http theme={"theme":{"light":"min-light","dark":"min-dark"}}
POST /api/v1/admin/rpc
Authorization: Bearer <gateway-token>
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 МБ.

## Ответ

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

```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-статус по возможности следует ошибке Gateway. Например, `INVALID_REQUEST` возвращает `400`, а `UNAVAILABLE` возвращает `503`.

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

* обнаружение: `commands.list`
  Возвращает имена методов HTTP RPC, разрешенные этим plugin.
* gateway: `health`, `status`, `logs.tail`, `usage.status`, `usage.cost`, `gateway.restart.request`
* конфигурация: `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

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

WebSocket-клиенты с общим токеном без доверенного удостоверения устройства не могут самостоятельно объявлять admin-области при подключении. Admin HTTP RPC намеренно следует существующей доверенной HTTP-модели оператора: когда plugin включен, bearer-аутентификация с общим секретом рассматривается как полный операторский доступ для этой admin-поверхности.

## Устранение неполадок

`404 Not Found`

: Plugin отключен, Gateway не был перезапущен после его включения, или запрос идет в другой процесс Gateway.

`401 Unauthorized`

: Запрос не удовлетворил HTTP-аутентификацию Gateway. Проверьте bearer-токен или заголовки удостоверения trusted-proxy.

`400 INVALID_REQUEST`

: Тело запроса не является допустимым JSON, поле `method` отсутствует, или метод не находится в списке разрешений plugin.

`503 UNAVAILABLE`

: Обработчик метода Gateway недоступен. Проверьте журналы Gateway и повторите попытку после завершения запуска Gateway.

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

* [Операторские области](/ru/gateway/operator-scopes)
* [Безопасность Gateway](/ru/gateway/security)
* [Удаленный доступ](/ru/gateway/remote)
* [Манифест Plugin](/ru/plugins/manifest#contracts)
* [Подпути SDK](/ru/plugins/sdk-subpaths)