Node群

ノードとは、role: "node" で Gateway に接続し、node.invoke を介してコマンドサーフェス（例: canvas.*、camera.*、device.*、notifications.*、system.*）を公開するコンパニオンデバイス（macOS/iOS/watchOS/Android/ヘッドレス）です。ほとんどのノードは、オペレーターポート上の Gateway WebSocket を使用します。オプションの直接接続 Apple Watch ノードは、watchOS が通常のアプリによる汎用的な低レベルネットワーク通信をブロックするため、同じポート上で署名付き HTTPS ポーリングを使用します。プロトコルの詳細: Gateway プロトコル。

レガシートランスポート: ブリッジプロトコル（TCP JSONL。現在のノードでは履歴参照専用）。

macOS は ノードモードでも実行できます。メニューバーアプリが 1 つのノードとして Gateway の WS サーバーに接続します（そのため、この Mac に対して openclaw nodes … が機能します）。アプリは、 openclaw node run が使用するものと同じノードホストのコマンドサーフェスに、ネイティブの Canvas、カメラ、画面、通知、コンピューター制御コマンドを 追加します。その Mac で 2 つ目の CLI ノードを起動しないでください。アプリは対応する CLI ノードホストランタイムを 内部ワーカーとして実行し、唯一の Gateway 接続およびノード ID であり続けます。

ノードは Gateway ではなく周辺デバイスです。ノードは Gateway サービスを実行せず、チャンネルメッセージ（Telegram、WhatsApp など）はノードではなく Gateway に届きます。

トラブルシューティングのランブック: /nodes/troubleshooting

ペアリングとステータス

ノードはデバイスペアリングを使用します。ノードは接続時に署名付きデバイス ID を提示し、Gateway は role: node に対するデバイスペアリングリクエストを作成します。デバイス CLI（または UI）で承認してください。Apple Watch の直接接続セットアップでは、管理者が発行した有効期間の短いノード専用セットアップコードを使用して、固定された低リスクのコマンドサーフェスを承認します。その後の機能拡張には、引き続き通常の承認が必要です。

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

保留中のペアリングリクエストは、デバイスの最後の再試行から 5 分後に期限切れになります。再接続を続けるデバイスでは、数分ごとに新しいプロンプトを発行するのではなく、保留中の 1 つのリクエスト（および requestId）が維持されます。リクエストから承認までの完全なライフサイクルについては、ノードのペアリングを参照してください。認証の詳細（ロール/スコープ/公開鍵）が変更された状態でノードが再試行すると、以前の保留中リクエストは置き換えられ、新しい requestId が作成されます。クライアントは置き換えられたリクエストについて device.pair.resolved イベントを受け取るため、承認前に openclaw devices list を再実行してください。

• nodes status は、デバイスペアリングのロールに node が含まれる場合、ノードをペアリング済みとして示します。
• 接続済みのネイティブ Mac では、 Settings -> Permissions -> Active computer detection から、統合された物理入力アクティビティの検出をオプトインできます。アクセシビリティ権限も 必要です。Gateway は、対象となる Mac のうちアクティビティが最も新しいものを active として示し、エージェントに安定したノード ID のヒントを提供して、遅延フォールバックの前にノード接続 アラートをその Mac にルーティングします。セットアップ、プライバシー、タイミング、トラブルシューティングについては、 アクティブなコンピューターのプレゼンスを参照してください。
• デバイスペアリングレコードは、承認済みロールを定める永続的な契約です。トークンのローテーションはその契約内に留まり、ペアリング承認で付与されていないロールへ、ペアリング済みノードを昇格させることはできません。
• node.pair.*（CLI: openclaw nodes pending/approve/reject/remove/rename）は、再接続をまたいでノードの承認済みコマンド/機能サーフェスを追跡する、Gateway が所有する独立したノードペアリングストアです。これはトランスポート認証を制御しません。トランスポート認証はデバイスペアリングが制御します。
• openclaw nodes remove --node <id|name|ip> はノードペアリングを削除します。デバイスに紐づくノードの場合、ペアリング済みデバイスストアでそのデバイスの 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 WebSocket は、N-1 プロトコル範囲内の認証済みノードクライアントを受け入れます。 したがって、現在の v4 Gateway は、接続で role: "node" と client.mode: "node" の両方が宣言されている場合、v3 ノードを受け入れます。オペレーターおよび UI セッションでは、 引き続き現在のプロトコルを使用する必要があります。

段階的なフリートアップグレードでは、最初に Gateway をアップグレードし、その後に各ノードをアップグレードします。 N-1 ノードはアップグレード中も表示および管理できます。Gateway は アップグレードの推奨事項とともに legacy node protocol accepted をログに記録します。ペアリング、 デバイス認証、コマンド許可リスト、および exec 承認は引き続き適用されます。 Plugin が所有する機能とコマンドは、ノードが現在のプロトコルへ アップグレードされるまで非表示のままです。N-1 より古いノードは、再接続する前に 帯域外でアップグレードする必要があります。

watchOS の直接 HTTPS トランスポートには現在のプロトコルバージョンが必要です。直接モードを有効にする前に、 Gateway とともに Watch アプリを更新してください。

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

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

承認に関する注意:

• 承認を伴うノード実行は、正確なリクエストコンテキストに紐づけられます。exec パスは承認前に正規化された systemRunPlan を準備します。承認後、Gateway は呼び出し元が後から編集したコマンド/cwd/セッションフィールドではなく、保存されたそのプランを転送し、実行前に作業ディレクトリを再検証します。
• シェル/ランタイムによるファイルの直接実行では、OpenClaw は具体的なローカルファイルオペランド 1 つにもベストエフォートで紐づけ、実行前にそのファイルが変更された場合は実行を拒否します。
• インタープリター/ランタイムコマンドに対して具体的なローカルファイルを正確に 1 つ特定できない場合、OpenClaw はランタイム全体を保護できるかのように扱わず、承認を伴う実行を拒否します。より広範なインタープリターセマンティクスには、サンドボックス、分離したホスト、または明示的に信頼された許可リスト/完全なワークフローを使用してください。

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

ノードマシン上で:

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

node run は、--context-path（Gateway WS コンテキストパス）、--tls、--tls-fingerprint <sha256>、および --node-id（レガシークライアントのインスタンス ID を上書きします。ペアリングはリセットされません）も受け入れます。macOS では、device.apps を通知するために --share-installed-apps を渡します。共有はデフォルトで無効です。以前保存したオプトインを無効にするには、--no-share-installed-apps を使用します。

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.* SecretRefs が設定されているものの解決できない場合、ノードホスト認証はフェイルクローズします。
• ノードホストの認証解決では、OPENCLAW_GATEWAY_* 環境変数のみが使用されます。

ノードホストを起動する（サービス）

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

node install は、--context-path、--tls、--tls-fingerprint、--node-id（レガシークライアントのインスタンス ID のみ）、--share-installed-apps / --no-share-installed-apps、--runtime <node>（デフォルト: node）、および再インストール用の --force も受け入れます。node status、node stop、node uninstall も使用できます。

ペアリングと名前付け

Gateway ホスト上で:

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

認証の詳細が変更された状態でノードが再試行した場合は、openclaw devices list を再実行し、現在の requestId を承認してください。

名前付けのオプション:

• openclaw node run / openclaw node install の --display-name（クライアントインスタンス ID および Gateway 接続メタデータとともに、共有 node_host_config SQLite 行に永続化されます）。
• openclaw nodes rename --node <id|name|ip> --name "Build Node"（Gateway による上書き）。

ノードでホストされる MCP サーバー

MCP サーバーは Gateway ではなく、ノードマシン上の openclaw.json に 設定します。

{  nodeHost: {    mcp: {      servers: {        localDocs: {          command: "npx",          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],          toolFilter: {            include: ["read_*", "search"],          },        },        internalApi: {          url: "https://mcp.internal.example/mcp",          transport: "streamable-http",          headers: {            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",          },        },      },    },  },}

ヘッドレスノードホストはこれらのサーバーを起動し、そのツールを一覧化して、接続後に 記述子を公開します。ツール呼び出しは mcp.tools.call.v1 を介してそのノードに戻ります。 Gateway に対応する MCP 設定や JS Plugin は必要ありません。 このノードホスト型 v1 パスでは、OAuth MCP サーバーはサポートされていません。

現在のノードホストは、MCP サーバーが設定されていない場合でも、最初のペアリング時に 組み込みの mcp.tools.call.v1 コマンドファミリーを宣言します。古いバージョンの OpenClaw でペアリングされたノードでは、ノードホストの更新後に 1 回限りのコマンドサーフェスのアップグレードを 要求することがあります。その後にサーバーを追加、削除、またはフィルタリングしても、 承認済みのコマンドファミリーは変わらないため、再ペアリングは必要ありません。ノードの MCP 設定変更を適用するには、 openclaw node run または openclaw node restart を再起動してください。 ノードホストはこの設定を監視しません。

Gateway オペレーターは、 gateway.nodes.pluginTools.enabled: false を使用して、ノードでホストされる MCP ツールを含む、ペアリング済みノードが公開するすべてのエージェント可視ツールを無視できます。 gateway.nodes.commands.deny: ["mcp.tools.call.v1"] のようなコマンド単位の明示的な拒否も 実行をブロックします。

ノードでホストされる Skills

Node マシンのアクティブな OpenClaw Skills ディレクトリ（デフォルトでは ~/.openclaw/skills）に Skills をインストールします。OPENCLAW_HOME、OPENCLAW_STATE_DIR、および OPENCLAW_CONFIG_PATH は、そのアクティブプロファイルを移動します。Skills については OPENCLAW_STATE_DIR が 優先されます。それ以外の場合、skills/ は openclaw config file が出力するパスの隣にあります。ヘッドレス Node ホストは接続後に有効な SKILL.md ファイルを 公開し、Gateway はその Node が接続されている間に限り、それらをエージェントの Skills スナップショットに追加します。 各 Skills ディレクトリ名は name frontmatter フィールドと一致する必要があります。これにより、 別のプロトコルフィールドを追加することなく、抽象 Node ロケーターが単一のエントリにマッピングされます。

最初の Node ロールのペアリングによって、Skills の公開が承認されます。Skills の追加、削除、または 変更に、再度のペアリングや Gateway 設定の変更は必要ありません。 Node の Skills ファイルを変更した後は、openclaw node run または openclaw node restart を 再起動してください。Node ホストは Skills ディレクトリを監視しません。

Node でホストされる Skills エントリは、その Node を識別し、実行場所を保持します。 Skills ファイル、相対パスで参照されるファイル、およびバイナリは、その Node 上に残ります。 エージェントは、通知された node://.../SKILL.md の場所を通常の read ツールで読み取ります。file_fetch は、オペレーターが承認した Node の絶対パスを受け入れますが、 Node Skills ロケーターは受け入れません。通常の読み取りツールを持たないランタイムでは、代わりに 通知された node://.../skills/<name> ディレクトリを workdir として使用し、 exec host=node node=<node-id> を介して cat SKILL.md を実行できます。参照されるファイルとバイナリは、 同じ実行ターゲットと作業ディレクトリを使用します。Node ホストは、そのロケーターを アクティブな OpenClaw 状態ディレクトリに対して解決するため、相対パスは Gateway マシンではなく Node 上で解決されます。公開する Node では system.run が承認済みである必要があり、 エージェントの実行ポリシーでは host=node が許可されている必要があります。そうでない場合、その Skills は エージェントのスナップショットに含まれません。

公開を停止するには、Node で nodeHost.skills.enabled: false を設定します。Gateway オペレーターは、gateway.nodes.allowSkills: false を使用して、ペアリングされたすべての Node の Skills を無視できます。

ヘッドレス ID の状態

ヘッドレス Node は、共有 SQLite に次の 3 つの独立した状態レコードを保持します。

• ~/.openclaw/state/openclaw.sqlite（node_host_config）：クライアントインスタンス ID、表示名、および Gateway 接続メタデータ。
• ~/.openclaw/state/openclaw.sqlite（device_identities、キー primary）：署名済みデバイスキーペアと、そこから導出された暗号学的デバイス ID。
• ~/.openclaw/state/openclaw.sqlite（device_auth_tokens）：暗号学的デバイス ID とロールをキーとする、ペアリング済みデバイス認証トークン。

署名済み Node の場合、Gateway は暗号学的デバイス ID をペアリングと Node ルーティングに使用します。クライアントインスタンス ID は接続メタデータにすぎません。 したがって、--node-id を変更したり、廃止された node.json を移行したりしても、ペアリングはリセットされません。 サポートされている取り消しと再ペアリングの流れ、およびアップグレードに関する注意事項については、 ID とペアリングの状態を参照してください。

廃止された identity/device.json および identity/device-auth.json ファイルは、 Doctor が管理する移行入力です。Node ホストを停止し、 openclaw doctor --fix を実行してください。Doctor は、古いファイルを削除する前に、 それらの行を SQLite にインポートして検証します。

コマンドを許可リストに追加する

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

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

承認は Node ホスト上の ~/.openclaw/exec-approvals.json に保存されます。

実行先を Node に設定する

デフォルトを設定します（Gateway 設定）。

openclaw config set tools.exec.host nodeopenclaw config set tools.exec.mode allowlistopenclaw config set tools.exec.node "<id-or-name>"

または、セッションごとに設定します。

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

設定後、host=node を指定したすべての exec 呼び出しは、Node ホスト上で実行されます（Node の許可リストおよび承認に従います）。

host=auto が暗黙的に Node を選択することはありませんが、auto からの明示的な呼び出し単位の host=node リクエストは許可されます。Node での実行をセッションのデフォルトにする場合は、tools.exec.host=node または /exec host=node ... を明示的に設定します。

関連項目：

• Node ホスト CLI
• 実行ツール
• 実行承認

ローカルモデル推論

デスクトップまたはサーバー Node は、その Node 上で稼働する Ollama サーバーからチャット対応モデルを公開できます。エージェントは Ollama Plugin の node_inference ツールを使用して、インストール済みモデルを検出し、制限付きプロンプトをリモートで実行します。Gateway から Ollama への直接的なネットワークアクセスは必要ありません。セットアップ、モデルのフィルタリング、および直接検証コマンドについては、Ollama の Node ローカル推論を参照してください。

Codex のセッションとトランスクリプト

公式の codex Plugin は、ヘッドレス Node ホストまたはネイティブ macOS Node 上の アーカイブされていない Codex セッションを公開できます。カタログ登録は supervision.enabled に依存しなくなりました。このオプションは、エージェント向けの監督ツールを制御します。 プロバイダーやハーネスを無効にせずにオペレーターカタログとペアリング済み Node のカタログコマンドを無効にするには、 Codex Plugin 設定で sessionCatalog.enabled: false を設定します。 両方のコンピューターで Plugin が引き続き有効である必要があり、Node の設定はローカルでの同意として機能します。 Gateway 側だけを有効にしても、別のコンピューターの Codex 状態は読み取れません。

Node は、バージョン管理された読み取り専用の codex.appServer.threads.list.v1 および codex.appServer.thread.turns.list.v1 コマンドを通知します。Codex CLI が利用可能なネイティブ Node ホストは、 codex.terminal.resume.v1 も通知します。これらのコマンドが初めて表示されたときに、Node のペアリングアップグレードを承認してください。 Gateway は通常の Plugin Node ポリシーを介してこれらを呼び出し、障害をホストごとに分離します。

ペアリング済み Node の行は、通常のセッションサイドバーに Codex グループとして表示されます。 各ホスト内では、デフォルトで行がプロジェクトフォルダー別にグループ化されます。.claude/worktrees/<name> 配下の作業ディレクトリは そのオリジンリポジトリにまとめられ、プロジェクトグループは他のサイドバーセクションと同様に折りたためます。 カタログヘッダーのフォルダーアイコンを使用して、プロジェクトグループをフラット化または復元します。同じグループ化は Claude セッションカタログにも適用されます。 デフォルトでは、行を選択すると通常のチャットペインが開き、完全な項目投影を使用した、制限付きのカーソルページネーション対応 thread/turns/list 呼び出しを通じて、永続化されたトランスクリプトが読み取られます。行メニュー、ビューアーヘッダー、または Open Codex/Claude sessions in 設定を使用して、セッションを所有するコンピューターのオペレーターターミナルで codex resume <thread-id> を起動します。ペアリング済み Node のターミナルパスは Codex Plugin が所有する許可リスト登録済み PTY リレーであり、任意の Node コマンド実行ではありません。

このリレーは、OpenClaw ハーネスの完全な継続およびアーカイブ所有権の契約を提供しません。そのため、リモートの行では Continue と Archive を使用できません。Gateway コンピューター上では、保存済みまたはアイドル状態の 行から、モデルが固定された別個のチャットブランチを開始できます。どちらも、他の Codex クライアントが使用していないことを オペレーターが確認した後にのみアーカイブできます。保存済みの行のライブアクティビティは不明なままです。アクティブな行は分岐もアーカイブもできません。

セットアップ、ページネーション、ローカルでの継続、およびメタデータのセキュリティ境界については、 Codex セッションを監督するを参照してください。

Claude のセッションとトランスクリプト

同梱の anthropic Plugin は、デフォルトで Gateway およびペアリング済み Node 上にある、 アーカイブされていない Claude CLI と Claude Desktop のセッションを検出します。Anthropic モデルや Claude CLI バックエンドを無効にせずにオペレーターカタログとペアリング済み Node のカタログコマンドを無効にするには、 plugins.entries.anthropic.config.sessionCatalog.enabled: false を設定します。 リモートの macOS アプリ Node は、Anthropic Plugin が有効で ~/.claude/projects/ が存在する場合に、 anthropic.claude.sessions.list.v1 および anthropic.claude.sessions.read.v1 を通知します。これらのコマンドが初めて表示されたときに、 Node のペアリングアップグレードを承認してください。

Claude CLI が利用可能なネイティブ Node ホストは、 anthropic.claude.terminal.resume.v1 も通知します。対象となる CLI および Desktop の行では、 それぞれを所有するホストのオペレーターターミナルで claude --resume <session-id> を開けます。 これはネイティブセッションの引き継ぎです。OpenClaw による採用とは異なり、最初に Claude セッションを フォークすることはありません。

カタログは、有効な Claude CLI プロジェクトインデックスレコードと、インデックス未登録の JSONL トランスクリプト向けの 制限付きメタデータフォールバックを組み合わせます。このフォールバックは、同時実行される非サイドチェーンの対話型 （cli）セッションおよびヘッドレス Agent SDK CLI（sdk-cli）セッションを認識します。 Claude Desktop のローカルメタデータは、Desktop のタイトルとアーカイブ状態を提供します。 両方のソースが同じ Claude Code セッション ID を参照する場合は Desktop メタデータが優先されます。 CLI にはアーカイブフラグがないため、CLI のみに存在するトランスクリプトは引き続き表示されます。 トランスクリプトの読み取りでは、不透明なバイトオフセットカーソルと制限付きのファイル逆方向読み取りを使用します。 そのため、大きなセッションを選択したり古いページを読み込んだりしても、JSONL 履歴全体が 1 つの Gateway レスポンスに読み込まれることはありません。

一覧および読み取りコマンドは読み取り専用です。これらは、operator.write を持つ認証済みオペレーター接続に対してのみ、 汎用の sessions.catalog.list および sessions.catalog.read メソッドを通じて、カタログメタデータとトランスクリプト内容を公開します。 Gateway ローカルの Claude CLI の行は、通常のチャットコンポーザーから採用できます。OpenClaw は表示可能な履歴を 制限付きでインポートし、最初のターンで --fork-session を使用して再開し、ソーストランスクリプトは変更しません。

ヘッドレス Node ホストは、同じ継続フローをオプトインできます。

{  nodeHost: {    agentRuns: {      claude: { enabled: true },    },  },}

Node は、この Node ローカル設定が有効であり、claude 実行可能ファイルがその Node 上で解決できる場合にのみ、 agent.cli.claude.run.v1 を通知します。Gateway からリモートで有効にすることはできません。 このコマンドには、Node の既存の実行承認ポリシーも適用されます。3 つの Claude コマンドがすべて通知され、 Gateway の Node コマンドポリシーで許可されている場合、その Node 上の Claude CLI の行を継続できるようになります。 OpenClaw は制限付き履歴をインポートし、採用したセッションを Node およびカタログから通知された作業ディレクトリに関連付け、 1 回限りの各 claude -p ターンをそこで実行します。最初のターンでは引き続き --fork-session を使用し、ソーストランスクリプトを保持します。

Node 上で実行されるターンは、Node の Claude デフォルトを使用します。v1 では、 Gateway loopback MCP 設定や Gateway Skills Plugin を受け取らず、Gateway トランスクリプトから再シードできず、 添付ファイルと画像を拒否します。Claude Desktop の行、および実行コマンドを通知しない Node は、引き続き表示専用です。 macOS アプリ Node はまだこのコマンドを通知しないため、その行は表示専用のままです。

Control UI の動作とストレージソースについては、Anthropic：コンピューター間の Claude セッション を参照してください。

OpenCode と Pi のセッション

同梱の OpenCode および ACPX Plugin も、Gateway とペアリング済み Node 上にある読み取り専用のネイティブセッション カタログを検出します。opencode CLI がインストールされている場合、Node は opencode.sessions.list.v1 / opencode.sessions.read.v1 を通知し、Pi のセッションディレクトリが存在する場合は acpx.pi.sessions.list.v1 / acpx.pi.sessions.read.v1 を通知します。新しいコマンドが初めて表示されたときに、 Node のペアリングアップグレードを承認してください。対応する CLI も利用可能な場合、Node は opencode.terminal.resume.v1 または acpx.pi.terminal.resume.v1 を追加します。その後、既存の行メニューとビューアーヘッダーから、 opencode --session <id> または pi --session <id> を使用して、選択したセッションを所有元のターミナルで再度開けます。

OpenCode は公式 CLI の JSON/エクスポートインターフェースを通じて読み取ります。Pi は、 プロジェクトおよびグローバルの settings.json セッションディレクトリに加え、 PI_CODING_AGENT_DIR および PI_CODING_AGENT_SESSION_DIR のオーバーライドを含む、文書化された JSONL セッションストアを読み取ります。 どちらのカタログもデフォルトで有効です。無効にするには、Web UI の Config > Plugins で設定します。

ターミナルでの再開には、保存されたセッションの作業ディレクトリと、Codex および Claude と同じ 許可リスト登録済みの双方向 PTY リレーが使用されます。任意の Node コマンド実行は公開されません。

ターミナルへのファイルアップロード

Control UI では、開いているペアリング済み Node のターミナルにファイルをドラッグできます。ネイティブ Node ホストは管理者専用の terminal.upload コマンドを公開します。最初に表示されたときに、ペアリングのアップグレードを承認してください。各ファイルは 16 MiB に制限され、その Node 上の非公開一時ディレクトリにステージングされ、実行されることなくシェル引用形式のパスとしてターミナルに返されます。

パスの挿入は PowerShell、cmd.exe、および認識された POSIX シェル（sh、Bash、Dash、Ash、Ksh、Zsh、Fish）に対応し、Windows 上の Git Bash も含まれます。その他のシェルのオーバーライドは、引用規則を安全に推測できないため拒否されます。ネイティブな WSL パスを使用するには、WSL 内で Node ホストを実行してください。% または ! を含む cmd.exe パスも、そのシェルでは二重引用符内でもこれらの文字が展開されるため拒否されます。

コマンドの呼び出し

低レベル（raw RPC）：

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

nodes invoke は system.run と system.run.prepare をブロックします。これらのコマンドは、host=node を指定した exec ツールを介してのみ実行されます（前述を参照）。一般的な「エージェントに MEDIA 添付ファイルを渡す」ワークフロー（Canvas、カメラ、画面、位置情報。後述）には、高レベルのヘルパーが用意されています。

長時間実行されるストリーミング Node コマンドは、追加の node.invoke.progress イベントを使用します。各イベントには、呼び出し ID、0 始まりのシーケンス番号、および サイズ制限付きの UTF-8 テキストチャンクが含まれます。Gateway はチャンクを並べ替えてから 呼び出し元に配信します。既存の node.invoke.result は、引き続き単一の最終 レスポンスです。ストリーミングの呼び出し元は、最初の進捗イベントから開始し、 後続の進捗ごとにリセットされる非アクティブ期限を設定できます。同時に、 承認および実行中には、呼び出しに個別に設定されたハードタイムアウトが維持されます。結果、ハード タイムアウト、非アクティブタイムアウト、Node の切断が発生すると、保留中のストリーム 状態はすべて破棄されます。呼び出し元によるキャンセルでは node.invoke.cancel が送出され、Node ホストは 該当するプロセスツリーを終了します。既存のリクエスト／レスポンス型コマンドに変更はありません。

コマンドポリシー

Node コマンドを呼び出すには、事前に 2 つのゲートを通過する必要があります。

1. Node は、認証済みの接続メタデータ（connect.commands）でコマンドを宣言する必要があります。
2. Gateway のプラットフォームと承認から導出された許可リストに、宣言されたコマンドが含まれている必要があります。

プラットフォーム別のデフォルト許可リスト（Plugin のデフォルトおよび commands.allow/commands.deny によるオーバーライドの適用前）：

これらの行は、各 Node アプリに実装されているコマンドではなく、Gateway ポリシーの上限を示します。コマンドを使用できるのは、接続済みの Node もそのコマンドを宣言している場合に限られます。特に、現在の macOS アプリは、macOS のポリシー行に記載されているデバイスおよび個人データ系のコマンド群を宣言しません。

canvas.* コマンド（canvas.present、canvas.hide、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.*）は、iOS、Android、macOS、Windows、Linux、および不明なプラットフォームにおける Plugin のデフォルトです。Linux Node は、デスクトップアプリのローカル Canvas ソケットが存在する場合にのみ、これらを宣言します。iOS では、すべての Canvas コマンドがフォアグラウンドでのみ実行できます。

talk.ptt.start、talk.ptt.stop、talk.ptt.cancel、talk.ptt.once は、プラットフォームラベルに関係なく、talk 機能を公開するか、talk.* コマンドを宣言するすべての Node でデフォルトで許可されます。

デスクトップホストコマンド（macOS／Windows／Linux 上の system.run、system.run.prepare、system.which、browser.proxy、mcp.tools.call.v1、screen.snapshot）は、前述の静的なプラットフォーム別デフォルト表には含まれません。これらを宣言するペアリングリクエストをオペレーターが承認すると使用可能になり、それ以降は Node の承認済みコマンドセットに保持され、再接続後も引き継がれます。

危険性が高いコマンドやプライバシーに大きく関わるコマンドは、Node が宣言している場合でも、引き続き gateway.nodes.commands.allow による明示的なオプトインが必要です：camera.snap、camera.clip、screen.record、computer.act、contacts.add、calendar.add、reminders.add、health.summary、sms.send、sms.search。gateway.nodes.commands.deny は常にデフォルトおよび追加の許可リストエントリより優先されます。iPhone の同意ゲートについては HealthKit の概要を、デスクトップ入力に関する追加の機能、ツールポリシー、アーム、有効化、およびプラットフォーム実装ゲートについては コンピューター操作を参照してください。

Plugin が所有する Node コマンドは、Gateway の Node 呼び出しポリシーを追加できます。このポリシーは、許可リストの確認後、Node への転送前に実行されます。そのため、raw node.invoke、CLI ヘルパー、専用のエージェントツールは、同じ Plugin 権限境界を共有します。危険な Plugin Node コマンドには、引き続き明示的な gateway.nodes.commands.allow オプトインが必要です。

Node が宣言済みコマンドリストを変更した後は、古いデバイスのペアリングを拒否し、新しいリクエストを承認して、Gateway に更新済みのコマンドスナップショットを保存させてください。

設定（openclaw.json）

Node 関連の設定は gateway.nodes と tools.exec の配下にあります：

{  gateway: {    nodes: {      // 信頼できるネットワーク（CIDR リスト）からの初回 Node ペアリングを自動承認します。      // 未設定の場合は無効です。要求スコープがない初回の role:node リクエストにのみ      // 適用され、アップグレードは自動承認しません。      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],        // SSH 検証済みの自動承認（デフォルト：有効）。SSH 経由で読み戻した        // デバイスキーが完全に一致する場合に、初回の Node ペアリングを承認します。        sshVerify: true,      },      // ペアリング済み Node が公開する、エージェントから参照可能な Plugin ツールを信頼します（デフォルト：true）。      pluginTools: {        enabled: true,      },      // 危険性が高い、またはプライバシーに大きく関わる Node コマンド（camera.snap など）をオプトインします。      commands: {        allow: ["camera.snap", "screen.record"],        // デフォルトまたは commands.allow に含まれていても、完全一致するコマンド名をブロックします。        deny: ["camera.clip"],      },    },  },  tools: {    exec: {      // デフォルトの exec ホスト："node" はすべての exec 呼び出しをペアリング済み Node にルーティングします。      host: "node",      // Node exec のセキュリティモード：承認済み／許可リスト登録済みのコマンドのみ許可します。      security: "allowlist",      // exec を特定の Node（ID または名前）に固定します。任意の Node を許可する場合は省略します。      node: "build-node",    },  },}

正確な Node コマンド名を使用してください。commands.deny は、プラットフォームのデフォルトまたは commands.allow エントリで許可される場合でも、そのコマンドを削除します。ペアリング済み Node は、エージェントから参照可能な Plugin ツール記述子をデフォルトで公開できますが、各記述子のコマンドは引き続き Node の承認済みコマンドサーフェスに含まれている必要があります。そのような記述子をすべて無視するには、gateway.nodes.pluginTools.enabled: false を設定します。Gateway の Node ペアリングおよびコマンドポリシーフィールドの詳細については、Gateway 設定リファレンスを参照してください。

エージェントごとの exec Node オーバーライド：

{  agents: {    list: [      {        id: "main",        tools: { exec: { node: "build-node" } },      },    ],  },}

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

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

CLI ヘルパー（一時ファイルに書き込み、保存先パスを出力します）：

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

Canvas の操作

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.comopenclaw 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 は、ローカルパスをサポートする Node 上で URL またはローカルファイルパス（--target）を受け付けるほか、配置用のオプション --x/--y/--width/--height も受け付けます。Linux Canvas は、HTTP(S) URL またはバンドル済みの A2UI レンダラーを受け付けます。
• canvas eval は、インライン JS（--js）または位置引数を受け付けます。

A2UI（Canvas）

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

注：

• モバイルおよび Linux デスクトップの Node は、アクション対応のレンダリングに、アプリが所有するバンドル済み A2UI ページを使用します。
• A2UI v0.8 JSONL のみがサポートされます（v0.9/createSurface は拒否されます）。
• iOS と Android はリモートの Gateway Canvas ページをレンダリングしますが、A2UI ボタンアクションは、アプリが所有するバンドル済み A2UI ページからのみディスパッチされます。Gateway がホストする HTTP/HTTPS A2UI ページは、これらのモバイルクライアントではレンダリング専用です。
• macOS は、アプリによって選択された、機能スコープが完全に一致する Gateway A2UI ページからアクションをディスパッチできます。その他の HTTP/HTTPS ページは引き続きレンダリング専用です。
• Linux は、バンドル済み A2UI ページからのみアクションをディスパッチします。その他の HTTP/HTTPS ページは引き続きレンダリング専用であり、デスクトップアプリを持たないヘッドレス Linux Node は Canvas を公開しません。

写真と動画（Node カメラ）

写真（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>openclaw nodes camera snap --node <idOrNameOrIp>            # デフォルト: 前面と背面の両方（MEDIA 行 2 つ）openclaw nodes camera snap --node <idOrNameOrIp> --facing frontopenclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

動画クリップ（mp4）:

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

注:

• canvas.* と camera.* を使用するには、Node がフォアグラウンドにある必要があります（バックグラウンド呼び出しは NODE_BACKGROUND_UNAVAILABLE を返します）。
• Node は、base64 ペイロードを扱いやすいサイズに保つため、クリップの長さを制限します（プラットフォームごとの正確な制限については、カメラキャプチャを参照してください）。nodes エージェントツールはさらに、呼び出しを転送する前に、要求された durationMs を 300000（5 分）に制限します。Node 自体では、より厳しい制限が適用されます。
• Android は、可能な場合に CAMERA/RECORD_AUDIO 権限を要求します。権限が拒否されると *_PERMISSION_REQUIRED で失敗します。

画面録画（Node）

対応する Node は screen.record（mp4）を公開します。例:

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

注:

• screen.record を利用できるかどうかは、Node のプラットフォームによって異なります。
• nodes エージェントツールは、要求された durationMs を 300000（5 分）に制限します。返されるペイロードのサイズを抑えるため、Node ではさらに厳しい制限が適用される場合があります。
• --no-audio は、対応するプラットフォームでマイクのキャプチャを無効にします。
• 複数の画面を利用できる場合は、--screen <index> を使用してディスプレイを選択します（0 = プライマリ）。

位置情報（Node）

設定で位置情報が有効になっている場合、Node は location.get を公開します。

CLI ヘルパー:

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

注:

• 位置情報はデフォルトでオフです。
• 「Always」にはシステム権限が必要です。バックグラウンド取得はベストエフォートです。
• レスポンスには緯度/経度、精度（メートル）、タイムスタンプが含まれます。
• パラメーターとレスポンスの完全な形式、およびエラーコードについては、位置情報コマンドを参照してください。

SMS（Android Node）

ユーザーが SMS 権限を付与し、デバイスが電話機能に対応している場合、Android Node は sms.send と sms.search を公開できます。どちらのコマンドもデフォルトでは危険なコマンドとして扱われます。呼び出し可能にするには、Gateway オペレーターがこれらを gateway.nodes.commands.allow に追加する必要もあります（コマンドポリシーを参照してください）。

読み取り専用の SMS 検索を使用するには、openclaw.json で明示的にオプトインします。

{  gateway: {    nodes: {      commands: { allow: ["sms.search"] },    },  },}

Node からメッセージも送信できるようにする場合に限り、sms.send を別途追加します。Android の権限と Gateway のコマンド認可は独立しています。端末の権限を付与しても、Gateway ポリシーは変更されません。

低レベルの呼び出し:

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

注:

• 呼び出し時に権限の診断情報を返せるように、READ_SMS が付与される前に sms.search が宣言される場合があります。メッセージを読み取るには、引き続きその Android 権限が必要です。
• 電話機能のない Wi-Fi 専用デバイスは、sms.send を公開しません。
• requires explicit gateway.nodes.commands.allow opt-in エラーは、端末がコマンドを宣言しているものの、Gateway オペレーターがそのコマンドを認可していないことを意味します。

デバイスおよび個人データのコマンド

iOS と Android の Node は、複数の読み取り専用データコマンドをデフォルトで公開します（コマンドポリシーの表を参照してください）。Android はさらに、アプリ内の各設定によって制御される、より多くのコマンド群を公開します。macOS またはヘッドレス Mac の TypeScript Node ホストは、オペレーターが --share-installed-apps でインストール済みアプリの共有を有効にした場合にのみ、device.apps を公開します。

利用可能なコマンド群:

• device.status、device.info — iOS、Android、Windows。
• device.permissions、device.health — Android のみ。
• device.apps — Android、macOS、およびヘッドレス Mac の Node。Android では Settings で Installed Apps の共有を有効にする必要があり、デフォルトではランチャーに表示されるアプリを返します。TypeScript Node ホストでは共有がデフォルトでオフになっており、query、limit、includeSystem を受け付けます。macOS の結果には、label、bundleId、path、system が含まれます。
• notifications.list、notifications.actions — Android のみ。
• photos.latest — iOS、Android。
• contacts.search — iOS、Android（デフォルトは読み取り専用）。contacts.add は危険なコマンドであり、gateway.nodes.commands.allow が必要です。
• calendar.events — iOS、Android（デフォルトは読み取り専用）。calendar.add は危険なコマンドであり、gateway.nodes.commands.allow が必要です。
• reminders.list — iOS、Android（デフォルトは読み取り専用）。reminders.add は危険なコマンドであり、gateway.nodes.commands.allow が必要です。
• callLog.search — Android のみ。
• motion.activity、motion.pedometer — iOS、Android。利用可能なセンサーのケイパビリティによって制御されます。

呼び出し例:

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

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

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

例:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

注:

• system.run は、ペイロード内に標準出力、標準エラー出力、終了コードを返します。
• シェル実行は現在、host=node を指定した exec ツールを経由します。nodes は、明示的な Node コマンド用の直接 RPC サーフェスとして残ります。
• nodes invoke は system.run または system.run.prepare を公開しません。これらは exec パスでのみ引き続き使用されます。
• exec パスは、承認前に正規の systemRunPlan を準備します。承認後、Gateway は保存されたそのプランを転送し、呼び出し元が後から編集したコマンド、cwd、セッションの各フィールドは転送しません。
• system.notify は macOS アプリの通知権限の状態に従い、--priority <passive|active|timeSensitive> と --delivery <system|overlay|auto> に対応します。
• 認識されない Node の platform / deviceFamily メタデータでは、system.run と system.which を除外する保守的なデフォルト許可リストが使用されます。不明なプラットフォームでこれらのコマンドが意図的に必要な場合は、gateway.nodes.commands.allow を使用して明示的に追加してください。
• 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 Node ホストの許可リストモードでは、cmd.exe /c 経由のシェルラッパー実行に承認が必要です（許可リストのエントリだけでは、ラッパー形式は自動的に許可されません）。
• Node ホストは、--env 内の PATH オーバーライドを無視し、コマンドの実行前に、保守されている多数のインタープリター/シェル起動変数（例: NODE_OPTIONS、PYTHONPATH、BASH_ENV、DYLD_*、LD_*）を削除します。PATH に追加のエントリが必要な場合は、--env で PATH を渡すのではなく、Node ホストサービスの環境を設定するか、標準の場所にツールをインストールしてください。
• macOS Node モードでは、system.run は macOS アプリの exec 承認（Settings → Exec approvals）によって制御されます。確認/許可リスト/完全の各モードは、ヘッドレス Node ホストと同じように動作します。拒否されたプロンプトは SYSTEM_RUN_DENIED を返します。
• ヘッドレス Node ホストでは、system.run は exec 承認（~/.openclaw/exec-approvals.json）によって制御されます。特に macOS については、以下のヘッドレス Node ホストにある exec ホストのルーティング環境変数を参照してください。

exec Node のバインド

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

グローバルデフォルト:

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

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

openclaw config get agents.entriesopenclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"

どの Node でも使用できるように設定を解除するには:

openclaw config unset tools.exec.nodeopenclaw config unset 'agents.entries.main.tools.exec.node'

権限マップ

Node は、node.list / node.describe に permissions マップを含める場合があります。このマップは権限名（例: screenRecording、accessibility、location）をキーとし、ブール値（true = 付与済み）を値とします。

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

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

起動方法:

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

注:

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

Mac Node モード

• macOS メニューバーアプリは Node として Gateway WS サーバーに接続します（そのため、この Mac に対して openclaw nodes … を使用できます）。
• リモートモードでは、アプリが Gateway ポート用の SSH トンネルを開き、localhost に接続します。