role: "node" で接続し、node.invoke 経由でコマンドサーフェス（例: canvas.*、camera.*、device.*、notifications.*、system.*）を公開するコンパニオンデバイス（macOS/iOS/Android/headless）です。プロトコルの詳細: Gateway プロトコル。
レガシートランスポート: Bridge プロトコル（TCP JSONL。現在のノードでは歴史的な用途のみ）。
macOS は ノードモードでも実行できます。メニューバーアプリが Gateway の WS サーバーに接続し、ローカルの canvas/camera コマンドをノードとして公開します（そのため openclaw nodes … はこの Mac に対して動作します）。リモートゲートウェイモードでは、ブラウザー自動化はネイティブアプリのノードではなく、CLI ノードホスト（openclaw node run またはインストール済みノードサービス）によって処理されます。
ノードは Gateway ではなく周辺機器です。Gateway サービスは実行せず、チャネルメッセージ（Telegram、WhatsApp など）はノードではなく Gateway に届きます。
トラブルシューティング Runbook: /nodes/troubleshooting
ペアリング + ステータス
WS ノードはデバイスペアリングを使用します。ノードはconnect 時にデバイス ID を提示し、Gateway は role: node のデバイスペアリングリクエストを作成します。デバイス CLI（または UI）で承認します。
requestId）を維持します。リクエスト/承認/トークンの完全なライフサイクルについては、Gateway 所有のペアリングを参照してください。ノードが変更された認証詳細（ロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しい requestId が作成されます。クライアントは置き換えられたリクエストに対する device.pair.resolved イベントを受け取り、承認前に openclaw devices list を再実行する必要があります。
nodes statusは、デバイスペアリングロールにnodeが含まれている場合、ノードをペアリング済みとしてマークします。- デバイスペアリングレコードは、承認済みロールの永続的な契約です。トークンローテーションはその契約内にとどまり、ペアリング承認が付与していないロールへペアリング済みノードを昇格することはできません。
node.pair.*（CLI:openclaw nodes pending/approve/reject/remove/rename）は、再接続をまたいでノードの承認済みコマンド/機能サーフェスを追跡する、別個の Gateway 所有ノードペアリングストアです。これは WSconnectハンドシェイクをゲートしません。デバイスペアリングがそれを行います。openclaw nodes remove --node <id|name|ip>はノードペアリングを削除します。デバイスに裏付けられたノードの場合、devices/paired.json内のデバイスのnodeロールを取り消し、そのデバイスのノードロールセッションを切断します。混在ロールのデバイスは行を保持してnodeロールだけを失い、ノード専用デバイスの行は削除されます。また、別個のノードペアリングストアから一致するエントリも消去します。operator.pairingは他のデバイス上の非オペレーターノード行を削除できます。混在ロールデバイスで自分自身のノードロールを取り消すデバイストークン呼び出し元には、追加でoperator.adminが必要です。- 承認スコープは、保留中リクエストが宣言したコマンドに従います。
- コマンドなしリクエスト:
operator.pairing - 非 exec ノードコマンド:
operator.pairing+operator.write system.run/system.run.prepare/system.which:operator.pairing+operator.admin
- コマンドなしリクエスト:
バージョンスキューとアップグレード順序
Gateway は、N-1 プロトコルウィンドウ内で認証済みノードクライアントを受け入れます。 そのため現在の v4 Gateway は、接続がrole: "node" と client.mode: "node" の両方を宣言している場合に v3 ノードを受け入れます。オペレーターおよび UI セッションは引き続き現在のプロトコルを使用する必要があります。
段階的なフリートアップグレードでは、まず Gateway をアップグレードし、その後で各ノードをアップグレードします。
N-1 ノードはアップグレード中も表示および管理可能です。Gateway はアップグレード推奨とともに legacy node protocol accepted をログに記録します。ペアリング、デバイス認証、コマンド許可リスト、exec 承認は引き続き適用されます。
Plugin 所有の機能とコマンドは、ノードが現在のプロトコルにアップグレードされるまで非表示のままです。N-1 より古いノードは、再接続前に帯域外アップグレードが必要です。
リモートノードホスト（system.run）
Gateway をあるマシンで実行し、別のマシンでコマンドを実行したい場合は、ノードホストを使用します。モデルは引き続き Gateway と通信します。host=node が選択されている場合、Gateway は exec 呼び出しをノードホストへ転送します。
| ロール | 責任 |
|---|---|
| Gateway ホスト | メッセージを受信し、モデルを実行し、ツール呼び出しをルーティングします。 |
| ノードホスト | ノードマシン上で system.run/system.which を実行します。 |
| 承認 | ノードホスト上の ~/.openclaw/exec-approvals.json で強制されます。 |
- 承認に裏付けられたノード実行は、正確なリクエストコンテキストにバインドされます。exec パスは承認前に正規の
systemRunPlanを準備します。承認されると、Gateway は後から呼び出し元が編集した command/cwd/session フィールドではなく、その保存済みプランを転送し、実行前に作業ディレクトリを再検証します。 - 直接のシェル/ランタイムファイル実行では、OpenClaw はベストエフォートで 1 つの具体的なローカルファイルオペランドもバインドし、そのファイルが実行前に変更された場合は実行を拒否します。
- OpenClaw がインタープリター/ランタイムコマンドに対して、正確に 1 つの具体的なローカルファイルを識別できない場合、完全なランタイムカバレッジを装うのではなく、承認に裏付けられた実行は拒否されます。より広いインタープリターセマンティクスには、サンドボックス化、分離ホスト、または明示的な信頼済み許可リスト/完全ワークフローを使用してください。
ノードホストを開始する（フォアグラウンド）
ノードマシン上で:node run は --context-path（Gateway WS コンテキストパス）、--tls、--tls-fingerprint <sha256>、--node-id（上書きするとペアリングトークンが消去されます）も受け付けます。
SSH トンネル経由のリモート Gateway（loopback バインド）
Gateway が loopback にバインドしている場合（gateway.bind=loopback、ローカルモードのデフォルト）、リモートノードホストは直接接続できません。SSH トンネルを作成し、ノードホストをトンネルのローカル側に向けます。
例（ノードホスト -> Gateway ホスト）:
openclaw node runはトークンまたはパスワード認証をサポートします。- 環境変数が推奨されます:
OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD。 - config フォールバックは
gateway.auth.token/gateway.auth.passwordです。 - ローカルモードでは、ノードホストは意図的に
gateway.remote.token/gateway.remote.passwordを無視します。 - リモートモードでは、
gateway.remote.token/gateway.remote.passwordはリモート優先順位ルールに従って候補になります。 - アクティブなローカル
gateway.auth.*SecretRefs が設定されているが解決されていない場合、ノードホスト認証はフェイルクローズします。 - ノードホスト認証解決は
OPENCLAW_GATEWAY_*環境変数のみを尊重します。
ノードホストを開始する（サービス）
node install は --context-path、--tls、--tls-fingerprint、--node-id、--runtime <node|bun>（デフォルト: node）、再インストール用の --force も受け付けます。node status、node stop、node uninstall も利用できます。
ペアリング + 名前
Gateway ホスト上で:openclaw devices list を再実行し、現在の requestId を承認します。
命名オプション:
openclaw node run/openclaw node installの--display-name（ノード上の~/.openclaw/node.jsonに、ノード ID、トークン、Gateway 接続情報とともに永続化されます）。openclaw nodes rename --node <id|name|ip> --name "Build Node"（Gateway 側の上書き）。
コマンドを許可リストに追加する
Exec 承認はノードホストごとです。Gateway から許可リストエントリを追加します。~/.openclaw/exec-approvals.json にあります。
exec をノードに向ける
デフォルトを設定します（Gateway config）:host=node を指定した任意の exec 呼び出しはノードホスト上で実行されます（ノードの許可リスト/承認の対象）。
host=auto は単独では暗黙的にノードを選択しませんが、呼び出しごとの明示的な host=node リクエストは auto から許可されます。セッションでノード exec をデフォルトにしたい場合は、tools.exec.host=node または /exec host=node ... を明示的に設定してください。
関連:
ローカルモデル推論
デスクトップまたはサーバーノードは、そのノード上で実行されている Ollama サーバーからチャット対応モデルを公開できます。エージェントは Ollama Plugin のnode_inference ツールを使用して、インストール済みモデルを検出し、制限付きプロンプトをリモートで実行します。Gateway が Ollama に直接ネットワークアクセスできる必要はありません。セットアップ、モデルフィルタリング、直接検証コマンドについては、Ollama ノードローカル推論を参照してください。
コマンドの呼び出し
低レベル（raw RPC）:nodes invoke は system.run と system.run.prepare をブロックします。これらのコマンドは host=node を指定した exec ツール経由でのみ実行されます（上記参照）。一般的な「エージェントに MEDIA 添付を渡す」ワークフロー（canvas、camera、screen、location、下記）には、より高レベルなヘルパーがあります。
コマンドポリシー
ノードコマンドは、呼び出し可能になる前に 2 つのゲートを通過する必要があります。- ノードが WebSocket
connect.commandsリストでそのコマンドを宣言している必要があります。 - Gateway のプラットフォームおよび承認由来の許可リストに、宣言されたコマンドが含まれている必要があります。
allowCommands/denyCommands 上書きの前）:
| プラットフォーム | デフォルトで許可されるコマンド |
|---|---|
| iOS | camera.list, location.get, device.info, device.status, contacts.search, calendar.events, reminders.list, photos.latest, motion.activity, motion.pedometer, system.notify |
| Android | camera.list, location.get, notifications.list, notifications.actions, system.notify, device.info, device.status, device.permissions, device.health, device.apps, contacts.search, calendar.events, callLog.search, reminders.list, photos.latest, motion.activity, motion.pedometer |
| macOS | camera.list, location.get, device.info, device.status, contacts.search, calendar.events, reminders.list, photos.latest, motion.activity, motion.pedometer, system.notify |
| Windows | camera.list, location.get, device.info, device.status, system.notify |
| Linux | system.notify（system.run のようなノードホストコマンドは承認ゲート付き。下記参照） |
canvas.* コマンド（canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*）は、iOS、Android、macOS、Windows、および不明なプラットフォーム（Linux 以外）では Plugin のデフォルトです。iOS ではこれらすべてがフォアグラウンドに制限されます。
talk.ptt.start, talk.ptt.stop, talk.ptt.cancel, talk.ptt.once は、プラットフォームラベルに関係なく、talk ケイパビリティを公開している、または talk.* コマンドを宣言している任意のノードでデフォルトで許可されます。
デスクトップホストコマンド（macOS/Windows の system.run, system.run.prepare, system.which, browser.proxy, screen.snapshot）は、上記の静的なプラットフォームデフォルト表には含まれません。これらを宣言するペアリング要求をオペレーターが承認すると利用可能になり、その後はノードの承認済みコマンドセットが再接続時にもそれらを引き継ぎます。
危険なコマンドやプライバシーに大きく関わるコマンドは、ノードが宣言している場合でも、引き続き gateway.nodes.allowCommands による明示的なオプトインが必要です: camera.snap, camera.clip, screen.record, contacts.add, calendar.add, reminders.add, sms.send, sms.search。gateway.nodes.denyCommands は、デフォルトや追加の allowlist エントリより常に優先されます。
Plugin 所有のノードコマンドは、Gateway のノード呼び出しポリシーを追加できます。このポリシーは allowlist チェックの後、ノードへの転送前に実行されるため、生の node.invoke、CLI ヘルパー、専用エージェントツールは同じ Plugin 権限境界を共有します。危険な Plugin ノードコマンドには、引き続き明示的な gateway.nodes.allowCommands オプトインが必要です。
ノードが宣言済みコマンドリストを変更した後は、古いデバイスペアリングを拒否し、新しい要求を承認して、Gateway が更新済みコマンドスナップショットを保存するようにしてください。
設定 (openclaw.json)
ノード関連の設定は gateway.nodes と tools.exec の下にあります。
denyCommands は、プラットフォームデフォルトや allowCommands エントリが本来許可する場合でも、そのコマンドを削除します。Gateway ノードペアリングとコマンドポリシーフィールドの詳細は、Gateway 設定リファレンスを参照してください。
エージェント単位の exec ノードオーバーライド:
スクリーンショット（canvas スナップショット）
ノードが Canvas（WebView）を表示している場合、canvas.snapshot は { format, base64 } を返します。
CLI ヘルパー（一時ファイルに書き込み、保存先パスを出力）:
Canvas コントロール
canvas presentは URL またはローカルファイルパス（--target）を受け付け、配置用の任意の--x/--y/--width/--heightも受け付けます。canvas evalはインライン JS（--js）または位置引数を受け付けます。
A2UI（Canvas）
- モバイルノードは、アクション対応レンダリングのために、バンドルされたアプリ所有の A2UI ページを使用します。
- A2UI v0.8 JSONL のみがサポートされます（v0.9/createSurface は拒否されます）。
- iOS と Android はリモート Gateway Canvas ページをレンダリングしますが、A2UI ボタンアクションはバンドルされたアプリ所有の A2UI ページからのみディスパッチされます。Gateway がホストする HTTP/HTTPS A2UI ページは、これらのモバイルクライアントではレンダリング専用です。
写真 + 動画（ノードカメラ）
写真（jpg）:
mp4）:
canvas.*とcamera.*では、ノードがフォアグラウンドにある必要があります（バックグラウンド呼び出しはNODE_BACKGROUND_UNAVAILABLEを返します）。- ノードは base64 ペイロードを扱いやすく保つためにクリップ時間を制限します（プラットフォームごとの正確な制限はカメラキャプチャを参照）。
nodesエージェントツールはさらに、要求されたdurationMsを、呼び出しを転送する前に 300000（5 分）で上限設定します。ノード自体はより厳しい制限を適用します。 - Android は可能な場合、
CAMERA/RECORD_AUDIO権限を求めます。拒否された権限は*_PERMISSION_REQUIREDで失敗します。
画面録画（ノード）
サポート対象ノードはscreen.record（mp4）を公開します。例:
screen.recordの可用性はノードプラットフォームによって異なります。nodesエージェントツールは、要求されたdurationMsを 300000（5 分）で上限設定します。ノードは返されるペイロードを制限するため、より厳しい制限を適用する場合があります。--no-audioは、サポート対象プラットフォームでマイクキャプチャを無効にします。- 複数の画面が利用可能な場合は、
--screen <index>を使用してディスプレイを選択します（0 = プライマリ）。
位置情報（ノード）
設定で位置情報が有効になっている場合、ノードはlocation.get を公開します。
CLI ヘルパー:
- 位置情報はデフォルトでオフです。
- 「常に」にはシステム権限が必要です。バックグラウンド取得はベストエフォートです。
- レスポンスには緯度/経度、精度（メートル）、タイムスタンプが含まれます。
- パラメーター/レスポンスの完全な形状とエラーコード: 位置情報コマンド。
SMS（Android ノード）
Android ノードは、ユーザーが SMS 権限を付与し、デバイスが通話機能をサポートしている場合、sms.send と sms.search を公開できます。どちらのコマンドもデフォルトでは危険です。呼び出す前に、Gateway オペレーターがそれらを gateway.nodes.allowCommands に追加する必要もあります（コマンドポリシーを参照）。
読み取り専用の SMS 検索では、openclaw.json で明示的にオプトインします。
sms.send を別途追加してください。Android 権限と Gateway コマンド承認は独立しています。電話の権限を付与しても Gateway ポリシーは編集されません。
低レベル呼び出し:
- 呼び出しが権限診断を返せるよう、
READ_SMSが付与される前にsms.searchが宣言される場合があります。メッセージの読み取りには引き続きその Android 権限が必要です。 - 通話機能のない Wi-Fi 専用デバイスは
sms.sendを公開しません。 requires explicit gateway.nodes.allowCommands opt-inエラーは、電話がコマンドを宣言しているものの、Gateway オペレーターが承認していないことを意味します。
デバイスおよび個人データコマンド
iOS、Android、macOS ノードは、デフォルトで複数の読み取り専用データコマンドを公開します（コマンドポリシー表を参照）。Android はさらに、独自のアプリ内設定でゲートされるより大きなファミリーを公開します。 利用可能なファミリー:device.status,device.info— iOS、Android、macOS、Windows。device.permissions,device.health,device.apps— Android のみ。device.appsには Android 設定でインストール済みアプリの共有が有効になっている必要があり、デフォルトではランチャーに表示されるアプリを返します。notifications.list,notifications.actions— Android のみ。photos.latest— iOS、Android、macOS。contacts.search— iOS、Android、macOS（読み取り専用デフォルト）。contacts.addは危険であり、gateway.nodes.allowCommandsが必要です。calendar.events— iOS、Android、macOS（読み取り専用デフォルト）。calendar.addは危険であり、gateway.nodes.allowCommandsが必要です。reminders.list— iOS、Android、macOS（読み取り専用デフォルト）。reminders.addは危険であり、gateway.nodes.allowCommandsが必要です。callLog.search— Android のみ。motion.activity,motion.pedometer— iOS、Android、macOS。利用可能なセンサーによってケイパビリティゲートされます。
システムコマンド（ノードホスト / mac ノード）
macOS ノードはsystem.run、system.notify、system.execApprovals.get/set を公開します。ヘッドレスノードホストは system.run、system.which、system.execApprovals.get/set を公開します。
例:
system.runはペイロード内で stdout/stderr/終了コードを返します。- シェル実行は現在、
host=nodeのexecツールを通ります。nodesは明示的なノードコマンド用の直接 RPC サーフェスのままです。 nodes invokeはsystem.runやsystem.run.prepareを公開しません。これらは exec パス上にのみ残ります。- exec パスは承認前に正規の
systemRunPlanを準備します。承認が付与されると、gateway はその保存済みプランを転送し、後から呼び出し元が編集した command/cwd/session フィールドは転送しません。 system.notifyは macOS アプリの通知権限状態に従います。--priority <passive|active|timeSensitive>と--delivery <system|overlay|auto>をサポートします。- 認識されないノードの
platform/deviceFamilyメタデータには、system.runとsystem.whichを除外する保守的なデフォルト許可リストが使われます。不明なプラットフォームでこれらのコマンドが意図的に必要な場合は、gateway.nodes.allowCommandsで明示的に追加してください。 system.runは--cwd、--env KEY=VAL、--command-timeout、--needs-screen-recordingをサポートします。- シェルラッパー（
bash|sh|zsh ... -c/-lc）では、リクエストスコープの--env値は明示的な許可リスト（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）に削減されます。 - 許可リストモードの常時許可判定では、既知のディスパッチラッパー（
env、flock、nice、nohup、stdbuf、timeout）はラッパーパスではなく内側の実行可能ファイルパスを永続化します。安全にアンラップできない場合、許可リストエントリは自動的には永続化されません。 - Windows ノードホストの許可リストモードでは、
cmd.exe /c経由のシェルラッパー実行は承認が必要です（許可リストエントリだけではラッパー形式は自動許可されません）。 - ノードホストは
--env内のPATH上書きを無視し、コマンド実行前に、保守されている多数のインタープリター/シェル起動変数（例:NODE_OPTIONS、PYTHONPATH、BASH_ENV、DYLD_*、LD_*）を取り除きます。追加の PATH エントリが必要な場合は、--envでPATHを渡すのではなく、ノードホストサービス環境を設定する（または標準の場所にツールをインストールする）ようにしてください。 - macOS ノードモードでは、
system.runは macOS アプリ内の exec 承認（Settings → Exec approvals）で制御されます。ask/allowlist/full はヘッドレスノードホストと同じように動作します。拒否されたプロンプトはSYSTEM_RUN_DENIEDを返します。 - ヘッドレスノードホストでは、
system.runは exec 承認（~/.openclaw/exec-approvals.json）で制御されます。特に macOS については、下の ヘッドレスノードホスト にある exec-host ルーティング環境変数を参照してください。
Exec ノードバインディング
複数のノードが利用可能な場合、exec を特定のノードにバインドできます。これにより、exec host=node のデフォルトノードが設定されます（エージェントごとに上書きできます）。
グローバルデフォルト:
権限マップ
ノードはnode.list / node.describe 内に permissions マップを含めることがあります。これは権限名（例: screenRecording、accessibility、location）をキーとし、ブール値（true = 付与済み）を値にします。
ヘッドレスノードホスト（クロスプラットフォーム）
OpenClaw は、Gateway WebSocket に接続してsystem.run / system.which を公開する ヘッドレスノードホスト（UI なし）を実行できます。これは Linux/Windows 上、またはサーバーの横で最小構成のノードを実行する場合に便利です。
起動:
- ペアリングは引き続き必要です（Gateway がデバイスペアリングプロンプトを表示します）。
- ノードホストは、ノード ID、トークン、表示名、gateway 接続情報を
~/.openclaw/node.jsonに保存します。 - Exec 承認は
~/.openclaw/exec-approvals.json経由でローカルに適用されます（Exec 承認 を参照）。 - macOS では、ヘッドレスノードホストはデフォルトで
system.runをローカル実行します。system.runをコンパニオンアプリの exec ホスト経由にルーティングするにはOPENCLAW_NODE_EXEC_HOST=appを設定します。アプリホストを必須にし、利用できない場合にフェイルクローズするにはOPENCLAW_NODE_EXEC_FALLBACK=0を追加します。 - Gateway WS が TLS を使用する場合は
--tls/--tls-fingerprintを追加してください。
Mac ノードモード
- macOS メニューバーアプリはノードとして Gateway WS サーバーに接続します（そのため、この Mac に対して
openclaw nodes …が動作します）。 - リモートモードでは、アプリは Gateway ポート用の SSH トンネルを開き、
localhostに接続します。