管理用 HTTP RPC Plugin

​

有効化する前に

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

​

有効化

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

​

セキュリティモデル

• 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 を使用してください。

​

リクエスト

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 この 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

​

WebSocket との比較

​

トラブルシューティング

​

関連項目

• オペレータースコープ
• Gateway のセキュリティ
• リモートアクセス
• Plugin マニフェスト
• SDK サブパス