Plugin адміністративного HTTP RPC

​

Перед увімкненням

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

​

Увімкнення

openclaw plugins enable admin-http-rpc
openclaw gateway restart

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

openclaw plugins disable admin-http-rpc
openclaw gateway restart

​

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

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

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

​

Автентифікація

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

​

Модель безпеки

• Увімкнення plugin навмисно надає доступ до дозволених адміністративних методів RPC за адресою /api/v1/admin/rpc.
• Plugin оголошує зарезервований контракт маніфесту contracts.gatewayMethodDispatch: ["authenticated-request"], який дає змогу його HTTP-маршруту, автентифікованому через Gateway, передавати методи площини керування всередині процесу. Це не пісочниця: контракт запобігає випадковому використанню зарезервованих допоміжних засобів SDK, але довірені plugins усе одно виконуються в процесі Gateway.
• Автентифікація за спільним секретом у форматі Bearer (token/password) підтверджує володіння операторським секретом Gateway; вужчі заголовки x-openclaw-scopes у цьому режимі ігноруються, а звичайні повні операторські дозволи за замовчуванням відновлюються.
• Довірена HTTP-автентифікація з даними ідентичності (режим trusted-proxy) враховує x-openclaw-scopes, якщо його вказано.
• gateway.auth.mode="none" означає, що цей маршрут не потребує автентифікації, якщо plugin увімкнено. Використовуйте цей режим лише за приватною точкою входу, якій ви повністю довіряєте.
• Після успішної автентифікації маршруту plugin запити передаються через ті самі обробники методів Gateway і перевірки областей доступу, що й WebSocket RPC.
• Маршрут залишається доступним під час підготовленої оренди призупинення. Обмежена перевірка запитів і локальна відповідь виявлення commands.list залишаються доступними. Серед методів, що передаються до Gateway, лише gateway.suspend.prepare, gateway.suspend.status і gateway.suspend.resume можуть виконуватися, коли приймання запитів закрито; інші дозволені методи повертають звичайну повторювану відповідь Gateway UNAVAILABLE.
• Залишайте цей маршрут доступним лише через loopback, tailnet або приватну довірену точку входу. Не надавайте прямий доступ до нього з публічного Інтернету. Використовуйте окремі Gateway, коли клієнти належать до різних меж довіри.

​

Запит

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

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

• id (рядок, необов’язкове): копіюється у відповідь. Якщо його не вказано, генерується UUID.
• method (рядок, обов’язкове): ім’я дозволеного методу Gateway.
• params (будь-який тип, необов’язкове): параметри конкретного методу.

​

Відповідь

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

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

​

Дозволені методи

• виявлення: commands.list Повертає імена методів HTTP RPC, дозволених цим plugin.
• 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

​

Порівняння з WebSocket

​

Усунення несправностей

​

Пов’язані матеріали

• Області доступу оператора
• Безпека Gateway
• Віддалений доступ
• Маніфест plugin
• Підшляхи SDK