2026年 OpenClaw Node for VS Code をリモート物理 Mac ゲートウェイで再現する Runbook——拡張機能の導入、ポート 18789、ループバックと SSH 転送の整理、権限（TCC）摩擦の切り分けと FAQ
ヘッドレス物理 Macで OpenClaw を運用するチームは、SSH とサーバ上の curl では成功するのに、ノート PC の VS Code 拡張がまだ 127.0.0.1 を指しているために失敗する、という段階でつまずきがちです。本稿は トランスポートの意思決定表、七ステップのチェックリスト、コピペ可能な診断、引用しやすいパラメータ、本番ゲートウェイに沿った FAQ を、ZoneMac スタイルのノード想定でまとめます。多地域での信頼境界やゲートウェイ配備の全体像は
2026年 OpenClaw 安全配備実践：ZoneMac多地域ノードを活用した高可用・低遅延AIエージェントゲートウェイの構築
も参照してください。CI で macOS Runner をどう割り当てるかの閾値整理は
2026年 グローバルチームの CI/CD：GitHub Actions セルフホスト macOS Runner か Ephemeral Mac？マルチリージョン物理ノード同時実行プール、Runner ラベルと Artifact 同期コストの閾値マトリクス（FAQ）
と併読すると運用設計が揃いやすいです。
はじめに：この記事が答える三つの問い
誰が——専用またはプールされたリモート Mac に OpenClaw を配線するプラットフォーム担当。何を——Marketplace の拡張機能から、上書きしたバインドを含む ポート 18789（または自前のポート）上の安定した HTTP 制御面まで、ループバック上の成功をエンドツーエンドの成功と取り違えない一本道。どう整理されているか——痛点、マトリクス、七ステップ、数値メモ、切り分け表、FAQ、無人ゲートウェイに向いた Apple Silicon Mac mini の理由、の順です。VS Code／Cursor から物理 Mac へ SSH で張る前提の整理は 2026年 越境チームの Cursor／VS Code Remote SSH×物理 Mac：マルチリージョンでノードはどう選べば Extension Host とインデックス尾部を抑えられる？——インタラクティブ開発リンクの遅延と安定性の意思決定マトリクス（コピペ SSH／Server パラメータ＋FAQ） も併読ください。
1. 三つの痛点
- ループバックは伝播しない。 サーバ上で
curl http://127.0.0.1:18789/healthが通るのは、そのホスト上のゲートウェイプロセスと macOS のファイアウォールまでを証明するに留まります。別マシンの VS Code には明示的なトンネル・split DNS・逆プロキシ経路が必要で、無い場合は拡張は自分自身のループバックに話しかけてタイムアウトします。 - 権限拒否が「ポートが悪い」に見える。 TCC が Keychain 読み取り、ターミナルへのオートメーション、保護ディレクトリへの書き込みを阻むと、
lsofでは LISTEN が残ったまま stderr にEPERMが出ることがあり、nginx を何時間も疑う原因になります。 - JSON・plist・UI の三者ドリフト。
openclaw.jsonのバインドだけ変えて LaunchAgent のProgramArgumentsを更新しない、あるいは VS Code のワークスペースがhttp://127.0.0.1:18789のままなのに本番はlocalhost:8443の TLS に移行済み、といったズレは、設定同期のブロブが人によって違うと断続的に見えます。
2. 意思決定表：VS Code 拡張はどうゲートウェイに届けるか
環境ごとに主経路を一つに決め、SSH 転送と共有 nginx upstream をドキュメント無しで混在させないことが、オンコールの週末を守ります。
| パターン | 向いている用途 | 注意点 |
|---|---|---|
| Mac 上の直接ループバック | オートメーション、cron、ローカル doctor スクリプト | リモートノートからは見えない。誤った WAN 露出を避けるため 127.0.0.1 バインドを推奨 |
SSH -L ローカル転送 |
自宅やホテル Wi-Fi から VS Code を繋ぐ開発者 | キープアライブと踏み台は社内方針に合わせる。ローカル側ポート（例：18789→18789）を Runbook に明記 |
| ループバック前面の nginx／Caddy + TLS | mTLS、SSO ヘッダ、パスベースで複数デーモンに振り分けたいチーム | 証明書更新と proxy_pass の typo。拡張のベース URL は公開ホスト名に揃え、生の 18789 と混同しない |
3. 七ステップ Runbook
- リスナーをベースライン化。 リモート Mac で
lsof -nP -iTCP:18789 -sTCP:LISTENとcurl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/（インストールがサブプレフィックスを使うならパスを調整）。 - VS Code に OpenClaw Node を入れる。
extensions.jsonの recommendations で拡張機能バージョンを揃え、全員が同一 RPC スキーマを読み込む。 - ベース URL の契約を公開。
ssh -L 18789:127.0.0.1:18789 user@gateway後にhttp://127.0.0.1:18789と書くのか、https://openclaw.internal仮想ホストにするのかをドキュメント化。 - launchd を堅牢化。
RunAtLoad、ThrottleInterval、明示的なWorkingDirectory。環境変数は root 可読の plist 断片から読み、world-writable な dotfile に依存しない。 - TCC を意図的に通す。 AppleScript や開発者証明書を触るなら、実バイナリをプライバシー設定で事前承認し、社内セキュリティレビュー用にスクリーンショットを残す。
- クライアント検収。 トンネル確立後、開発者ノートから
nc -vz 127.0.0.1 18789。TLS 前面ならopenssl s_client -connect openclaw.internal:443 -servername openclaw.internal。 - ベースラインを固定。 JSON と plist の断片をプラットフォームリポジトリにコミットし、ゲートウェイと拡張のセマバーを合同検証したタイミングでタグ付け。
4. 引用しやすいパラメータ
- 18789——2026 年時点の多くのテンプレートでローカル OpenClaw HTTP 制御に使われる慣例。必ず設定可能な定数として扱い、魔法の数字にしない。
- 127.0.0.1 と 0.0.0.0——ループバックにバインドすれば意図しない WAN 露出を避けやすい。全インタフェースにバインドするのはファイアウォール／VPC 規則が必須で、VS Code 連携単体では稀。
- 約 30〜60 秒——再起動後の LaunchAgent コールドスタートでオンコールに鳴らすまでの目安バジェット。
ThrottleIntervalと組み合わせて再起動嵐を抑える。
5. 切り分け早見表
| 症状 | ありがちな原因 | 最初のコマンド／対処 |
|---|---|---|
| ノートからだけ ECONNREFUSED | SSH 転送が無い／ローカルポート違い | SSH を -v で再実行し、~/.ssh/config の LocalForward を確認 |
| nginx から HTTP 502 | 上流ダウンまたはソケット誤り | Mac 上で直接 curl -v http://127.0.0.1:18789、エラーログ末尾を確認 |
| 終了コード 1 でポートは空 | TCC ／ シークレット欠落 | Console.app でサブシステムを絞り込み、バイナリにフルディスクアクセスを追加して plist をリロード |
6. FAQ
ポート 18789 の役割は？
多くのバンドルでは管理・拡張トラフィック用の既定ローカル HTTP 面です。自環境の openclaw.json と LaunchAgent で必ず確認してください。
リモートの curl は成功するのに VS Code がダメなのは？
ループバックの所在が異なります。トンネルを張るか、検証済みの転送経路に解決するホスト名へ拡張のベース URL を変更してください。
18789 を公網に晒してよい？
TLS・認証認可・レート制限なしの直晒しは非推奨です。オペレータ端末には VPN・Tailscale・SSH 転送を優先し、ブラウザ到達が必要なら 127.0.0.1 の生ポートを nginx の背後に置く構成が無難です。
1 台の Mac で複数インスタンス？
ポートと plist ラベルを重複させない。デプロイ前に LISTEN を grep する。
7. このゲートウェイスタックに Apple Silicon Mac mini を載せる理由
OpenClaw と VS Code 起点のオートメーションは、静かに常時稼働するマシン向きです。Apple Silicon Mac mini は待機時でもおおよそ 4 W 前後の消費電力に抑えつつ、ネイティブ Unix ツールチェーン、launchd、Keychain 連携をハイパーバイザ課金なしで使えます。Gatekeeper、SIP、FileVault により、長寿命 API キーを載せる信頼境界も、典型的な Windows／Linux 踏み台より整理しやすいです。
ユニファイドメモリの帯域により、複数の Node ゲートウェイ、nginx、軽量 CI エージェントが同一筐体で doctor プローブ、拡張 RPC、ログ転送のスパイクに同時に耐えやすくなります。コロハードを自前調達せず、上記 plist セマンティクスと同じ金属をすぐに揃えたい場合は、専用リモート Mac mini ノードが最短ルートです。
分散チーム向けに OpenClaw ゲートウェイを標準化するなら、Mac mini M4 は 24/7 macOS オートメーションの費用対効果の高い錨の一つです。リージョンとコンプライアンス要件に合う容量は、下の CTA から確認してください。
今日から物理 Mac ゲートウェイを動かす
ZoneMac の Apple Silicon ノードなら、SSH、launchd 向けイメージ、本稿で検証した 18789 周りのポートセマンティクスをそのまま再現しやすいです。