OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

管理用 HTTP RPC Plugin

バンドルされている admin-http-rpc Plugin は、Gateway WebSocket 接続を開いたままにできない信頼されたホスト自動化向けに、許可リストに登録された Gateway コントロールプレーンメソッドを HTTP 経由で公開します。

これは OpenClaw に同梱されていますが、デフォルトでは無効です。無効な場合、ルートは登録されません。有効にすると、Gateway と同じリスナー（http://<gateway-host>:<port>/api/v1/admin/rpc）に POST /api/v1/admin/rpc が追加されます。

プライベートなホストツール、tailnet 自動化、または信頼された内部 ingress にのみ有効化してください。このルートを公開インターネットに直接公開しないでください。

有効化する前に

管理 HTTP RPC は、完全なオペレーターコントロールプレーンのサーフェスです。Gateway HTTP 認証を通過した呼び出し元は、以下の許可リストに登録されたメソッドを呼び出せます。次のすべての条件を満たす場合にのみ有効化してください。

  • 呼び出し元が Gateway の操作を任せられる信頼された主体である。
  • 呼び出し元が WebSocket RPC クライアントを使用できない。
  • ルートには、loopback、tailnet、または認証済みのプライベート ingress からのみ到達できる。
  • 許可されたメソッドを確認済みであり、実行予定の自動化に適合している。

Gateway WebSocket 接続を開いたままにできる OpenClaw クライアントや対話型ツールでは、代わりに WebSocket RPC を使用してください。

有効化

バンドルされた Plugin を有効化します。

CLI

bash
openclaw plugins enable admin-http-rpcopenclaw gateway restart

設定

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

ルートは Plugin の起動時に登録されるため、Plugin 設定を変更した後は Gateway を再起動してください。

HTTP サーフェスが不要になったら無効化します。

bash
openclaw plugins disable admin-http-rpcopenclaw gateway restart

ルートの確認

最小限で安全なリクエストとして health を使用します。

bash
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
{  "id": "generated-request-id",  "ok": true,  "payload": {    "status": "ok"  }}

Plugin が無効な場合、ルートが登録されていないため 404 が返されます。

認証

Plugin のルートは Gateway HTTP 認証を使用します。

一般的な認証経路：

  • 共有シークレット認証（gateway.auth.mode="token" または "password"）：Authorization: Bearer <token-or-password>
  • 信頼された ID 付き HTTP 認証（gateway.auth.mode="trusted-proxy"）：設定済みの ID 対応プロキシを経由させ、必要な ID ヘッダーを挿入させます
  • プライベート ingress のオープン認証（gateway.auth.mode="none"）：認証ヘッダーは不要です

セキュリティモデル

この Plugin は、完全な Gateway オペレーターサーフェスとして扱ってください。

  • Plugin を有効化すると、/api/v1/admin/rpc で許可リストに登録された管理 RPC メソッドへのアクセスが意図的に提供されます。
  • Plugin は予約済みの contracts.gatewayMethodDispatch: ["authenticated-request"] マニフェスト契約を宣言します。これにより、Gateway 認証済みの HTTP ルートからコントロールプレーンメソッドをプロセス内でディスパッチできます。これはサンドボックスではありません。この契約は予約済み SDK ヘルパーの誤使用を防ぎますが、信頼された Plugin は引き続き Gateway プロセス内で実行されます。
  • 共有シークレットの Bearer 認証（token/password モード）は、Gateway オペレーターシークレットを保持していることを証明します。この経路では、より限定的な x-openclaw-scopes ヘッダーは無視され、通常の完全なオペレーターのデフォルト設定が復元されます。
  • 信頼された ID 付き HTTP 認証（trusted-proxy モード）では、x-openclaw-scopes が存在する場合、それが適用されます。
  • gateway.auth.mode="none" は、Plugin が有効な場合にこのルートが未認証になることを意味します。完全に信頼できるプライベート ingress の背後でのみ使用してください。
  • リクエストは、Plugin ルートの認証を通過した後、WebSocket RPC と同じ Gateway メソッドハンドラーおよびスコープチェックを通じてディスパッチされます。
  • このルートは、準備済みの一時停止リース中も到達可能な状態を維持します。制限付きのリクエスト検証とローカルの commands.list 検出レスポンスは引き続き利用できます。Gateway にディスパッチされるメソッドのうち、受け入れが閉じられている間に実行できるのは gateway.suspend.prepare、gateway.suspend.status、gateway.suspend.resume のみです。その他の許可リスト登録済みメソッドは、通常の再試行可能な Gateway UNAVAILABLE レスポンスを返します。
  • このルートは loopback、tailnet、または信頼されたプライベート ingress 上に置いてください。公開インターネットに直接公開しないでください。呼び出し元が信頼境界をまたぐ場合は、別々の Gateway を使用してください。

リクエスト

http
POST /api/v1/admin/rpcAuthorization: Bearer <gateway-token>Content-Type: application/json
json
{  "id": "optional-request-id",  "method": "health",  "params": {}}

フィールド：

  • id（文字列、省略可能）：レスポンスにコピーされます。省略した場合は UUID が生成されます。
  • method（文字列、必須）：許可された Gateway メソッド名。
  • params（任意、省略可能）：メソッド固有のパラメーター。

デフォルトの最大リクエストボディサイズは 1 MB です。

レスポンス

成功レスポンスは Gateway RPC 形式を使用します。

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 この Plugin で許可されている 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：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：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 経路は、OpenClaw クライアント向けの推奨コントロールプレーン API です。管理 HTTP RPC は、リクエスト／レスポンス型の HTTP サーフェスを必要とするホストツールにのみ使用してください。

信頼されたデバイス ID を持たない共有トークンの WebSocket クライアントは、接続時に管理スコープを自己申告できません。管理 HTTP RPC は、既存の信頼された HTTP オペレーターモデルに意図的に従います。Plugin が有効な場合、共有シークレットの Bearer 認証は、この管理サーフェスに対する完全なオペレーターアクセスとして扱われます。

トラブルシューティング

404 Not Found

: Plugin が無効になっている、Plugin を有効化してから Gateway が再起動されていない、またはリクエストが別の Gateway プロセスに送信されています。

401 Unauthorized

: リクエストが Gateway HTTP 認証を満たしていません。Bearer トークンまたは信頼されたプロキシの ID ヘッダーを確認してください。

405 Method Not Allowed

: リクエストで POST 以外が使用されました。

413 Payload Too Large

: リクエストボディが 1 MB の制限を超えました。

400 INVALID_REQUEST

: リクエストボディが有効な JSON ではない、method フィールドがない、メソッドが Plugin の許可リストに含まれていない、または一時停止の再開 ID がアクティブなリースと一致していません。

503 UNAVAILABLE

: Gateway メソッドが起動中、レート制限中、一時停止中、または競合する一時停止／再開操作を待機中です。error.details が存在する場合は確認し、再試行する前に error.retryAfterMs に従ってください。

関連項目

Was this useful?
On this page

On this page