ノード

ノードは、Gateway の WebSocket（オペレーターと同じポート）に role: "node" で接続するコンパニオンデバイス（macOS/iOS/Android/ヘッドレス）です。node.invoke 経由でコマンドインターフェース（canvas.*、camera.*、device.*、notifications.*、system.* など）を公開します。プロトコルの詳細: Gateway プロトコル。

レガシートランスポート: Bridge プロトコル（TCP JSONL。現在のノードでは非推奨/削除済み）。

macOS はノードモードでも動作できます。メニューバーアプリが Gateway の WS サーバーに接続し、ローカルの canvas/camera コマンドをノードとして公開します（openclaw nodes … がこの Mac に対して動作します）。

補足:

  • ノードは周辺機器であり、Gateway ではありません。Gateway サービスは実行しません。
  • Telegram/WhatsApp 等のメッセージはゲートウェイに届き、ノードには届きません。
  • トラブルシューティング: /nodes/troubleshooting

ペアリングとステータス

WS ノードはデバイスペアリングを使用します。 ノードは connect 時にデバイス ID を提示し、Gateway が role: node のデバイスペアリングリクエストを作成します。デバイス CLI（または UI）で承認してください。

簡易 CLI:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

補足:

  • nodes status は、デバイスペアリングロールに node が含まれるノードをペアリング済みと表示します。
  • node.pair.*（CLI: openclaw nodes pending/approve/reject）は Gateway が所有する別のノードペアリングストアです。WS の connect ハンドシェイクのゲートにはなりません。

リモートノードホスト（system.run）

Gateway が一つのマシンで動作し、コマンドを別のマシンで実行したい場合はノードホストを使用します。モデルは引き続き Gateway と通信し、host=node が選択されると Gateway が exec 呼び出しをノードホストに転送します。

実行場所

  • Gateway ホスト: メッセージの受信、モデルの実行、ツールコールのルーティング。
  • ノードホスト: ノードマシン上で system.run/system.which を実行。
  • 承認: ~/.openclaw/exec-approvals.json 経由でノードホスト上で適用。

承認に関する補足:

  • 承認付きのノード実行は、正確なリクエストコンテキストにバインドされます。
  • 直接のシェル/ランタイムファイル実行では、OpenClaw はベストエフォートで具体的なローカルファイルオペランド 1 つにもバインドし、そのファイルが実行前に変更された場合は実行を拒否します。
  • インタプリタ/ランタイムコマンドで OpenClaw が具体的なローカルファイルを 1 つだけ特定できない場合、承認付き実行はランタイム全体をカバーするふりをせず拒否されます。より広範なインタプリタセマンティクスには、サンドボックス、別ホスト、または明示的な信頼済み許可リスト/完全なワークフローを使用してください。

ノードホストの起動（フォアグラウンド）

ノードマシン上で:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

SSH トンネル経由のリモート Gateway（ループバックバインド）

Gateway がループバックにバインドしている場合（gateway.bind=loopback、ローカルモードのデフォルト）、リモートノードホストは直接接続できません。SSH トンネルを作成し、ノードホストをトンネルのローカル側に向けてください。

例（ノードホスト -> Gateway ホスト）:

# ターミナル A（実行し続ける）: ローカル 18790 -> Gateway 127.0.0.1:18789 に転送
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# ターミナル B: Gateway トークンをエクスポートし、トンネル経由で接続
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

補足:

  • openclaw node run はトークンまたはパスワード認証をサポートします。
  • 環境変数が推奨: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
  • 設定のフォールバックは gateway.auth.token / gateway.auth.password。
  • ローカルモードでは、ノードホストは意図的に gateway.remote.token / gateway.remote.password を無視します。
  • リモートモードでは、gateway.remote.token / gateway.remote.password がリモート優先ルールに従い有効です。
  • アクティブなローカル gateway.auth.* SecretRef が設定されているが解決されていない場合、ノードホスト認証はクローズドで失敗します。
  • レガシーの CLAWDBOT_GATEWAY_* 環境変数は、ノードホスト認証解決では意図的に無視されます。

ノードホストの起動（サービス）

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

ペアリングと命名

Gateway ホスト上で:

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

命名オプション:

  • openclaw node run / openclaw node install の --display-name（ノード上の ~/.openclaw/node.json に保存）。
  • openclaw nodes rename --node <id|name|ip> --name "Build Node"（Gateway 側でのオーバーライド）。

コマンドの許可リスト

実行承認はノードホストごとです。Gateway から許可リストのエントリを追加します。

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

承認情報はノードホストの ~/.openclaw/exec-approvals.json に保存されます。

exec をノードに向ける

デフォルトの設定（Gateway 設定）:

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

またはセッションごとに:

/exec host=node security=allowlist node=<id-or-name>

設定後、host=node 付きのすべての exec 呼び出しがノードホスト上で実行されます（ノードの許可リスト/承認に従います）。

関連:

コマンドの実行

低レベル（生の RPC）:

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

一般的な「エージェントに MEDIA 添付ファイルを渡す」ワークフロー向けの高レベルヘルパーもあります。

スクリーンショット（canvas スナップショット）

ノードが Canvas（WebView）を表示している場合、canvas.snapshot は { format, base64 } を返します。

CLI ヘルパー（一時ファイルに書き込み、MEDIA:<path> を出力）:

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas 操作

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

補足:

  • canvas present は URL またはローカルファイルパス（--target）を受け付け、オプションで --x/--y/--width/--height による位置指定が可能です。
  • canvas eval はインライン JS（--js）または位置引数を受け付けます。

A2UI（Canvas）

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

補足:

  • A2UI v0.8 JSONL のみサポート（v0.9/createSurface は拒否されます）。

写真 + 動画（ノードカメラ）

写真（jpg）:

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # デフォルト: 両方の向き（MEDIA 行 2 つ）
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

ビデオクリップ（mp4）:

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

補足:

  • canvas.* と camera.* ではノードがフォアグラウンドである必要があります（バックグラウンド呼び出しは NODE_BACKGROUND_UNAVAILABLE を返します）。
  • クリップの長さは制限されています（現在 <= 60 秒）。base64 ペイロードの肥大化を防ぐためです。
  • Android では CAMERA/RECORD_AUDIO パーミッションのプロンプトが可能な場合に表示されます。拒否されたパーミッションは *_PERMISSION_REQUIRED で失敗します。

画面録画（ノード）

対応ノードは screen.record（mp4）を公開します。例:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

補足:

  • screen.record の利用可否はノードプラットフォームに依存します。
  • 画面録画は <= 60 秒 に制限されます。
  • --no-audio は対応プラットフォームでマイクキャプチャを無効にします。
  • 複数の画面がある場合、--screen <index> でディスプレイを選択できます。

位置情報（ノード）

設定で位置情報が有効な場合、ノードは location.get を公開します。

CLI ヘルパー:

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

補足:

  • 位置情報はデフォルトでオフです。
  • 「常に」を使用するにはシステムパーミッションが必要です。バックグラウンドフェッチはベストエフォートです。
  • レスポンスには緯度/経度、精度（メートル）、タイムスタンプが含まれます。

SMS（Android ノード）

Android ノードは、ユーザーが SMS パーミッションを許可し、デバイスが電話機能をサポートしている場合、sms.send を公開できます。

低レベル invoke:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

補足:

  • Android デバイスでパーミッションプロンプトを受け入れてから、機能がアドバタイズされます。
  • 電話機能のない Wi-Fi 専用デバイスは sms.send をアドバタイズしません。

Android デバイスと個人データコマンド

Android ノードは、対応する機能が有効な場合、追加のコマンドファミリーをアドバタイズできます。

利用可能なファミリー:

  • device.status、device.info、device.permissions、device.health
  • notifications.list、notifications.actions
  • photos.latest
  • contacts.search、contacts.add
  • calendar.events、calendar.add
  • motion.activity、motion.pedometer

invoke の例:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

補足:

  • モーションコマンドは利用可能なセンサーによるケーパビリティゲートがあります。

システムコマンド（ノードホスト / Mac ノード）

macOS ノードは system.run、system.notify、system.execApprovals.get/set を公開します。 ヘッドレスノードホストは system.run、system.which、system.execApprovals.get/set を公開します。

例:

openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

補足:

  • system.run はペイロードに stdout/stderr/終了コードを返します。
  • system.notify は macOS アプリの通知パーミッション状態を尊重します。
  • 認識できないノードの 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、nice、nohup、stdbuf、timeout）はラッパーパスではなく内部の実行可能ファイルパスを永続化します。アンラップが安全でない場合、許可リストエントリは自動永続化されません。
  • Windows ノードホストの許可リストモードでは、cmd.exe /c 経由のシェルラッパー実行は承認が必要です（許可リストエントリだけではラッパー形式を自動許可しません）。
  • system.notify は --priority <passive|active|timeSensitive> と --delivery <system|overlay|auto> をサポートします。
  • ノードホストは PATH のオーバーライドを無視し、危険なスタートアップ/シェルキー（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）を除去します。追加の PATH エントリが必要な場合は、--env 経由で PATH を渡す代わりに、ノードホストサービスの環境を設定するか、標準的な場所にツールをインストールしてください。
  • macOS ノードモードでは、system.run は macOS アプリの exec 承認（Settings → Exec approvals）によってゲートされます。 ask/allowlist/full はヘッドレスノードホストと同じ動作をします。拒否されたプロンプトは SYSTEM_RUN_DENIED を返します。
  • ヘッドレスノードホストでは、system.run は exec 承認（~/.openclaw/exec-approvals.json）によってゲートされます。

Exec のノードバインド

複数のノードが利用可能な場合、exec を特定のノードにバインドできます。 これにより exec host=node のデフォルトノードが設定されます（エージェントごとにオーバーライド可能）。

グローバルデフォルト:

openclaw config set tools.exec.node "node-id-or-name"

エージェントごとのオーバーライド:

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

設定解除（任意のノードを許可）:

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

パーミッションマップ

ノードは node.list / node.describe で permissions マップを含めることがあります。パーミッション名（screenRecording、accessibility など）をキー、boolean 値（true = 許可済み）を値とします。

ヘッドレスノードホスト（クロスプラットフォーム）

OpenClaw は Gateway WebSocket に接続して system.run / system.which を公開するヘッドレスノードホスト（UI なし）を実行できます。Linux/Windows や、サーバーの横で最小限のノードを実行する場合に便利です。

起動:

openclaw node run --host <gateway-host> --port 18789

補足:

  • ペアリングは引き続き必要です（Gateway がデバイスペアリングプロンプトを表示します）。
  • ノードホストはノード ID、トークン、表示名、Gateway 接続情報を ~/.openclaw/node.json に保存します。
  • exec 承認はローカルの ~/.openclaw/exec-approvals.json で適用されます （Exec 承認 を参照）。
  • macOS では、ヘッドレスノードホストはデフォルトで system.run をローカル実行します。 OPENCLAW_NODE_EXEC_HOST=app を設定すると、コンパニオンアプリの exec ホスト経由で system.run をルーティングします。 OPENCLAW_NODE_EXEC_FALLBACK=0 を追加すると、アプリホストを必須とし、利用できない場合はクローズドで失敗します。
  • Gateway WS が TLS を使用する場合は --tls / --tls-fingerprint を追加してください。

Mac ノードモード

  • macOS のメニューバーアプリは Gateway WS サーバーにノードとして接続します（openclaw nodes … がこの Mac に対して動作します）。
  • リモートモードでは、アプリが Gateway ポート用の SSH トンネルを開き、localhost に接続します。
arrow_back
前へ
Auth Monitoring
次へ
Troubleshooting
arrow_forward