2026年 OpenClaw Node for VS Code 在遠端實體 Mac 閘道上可複現落地
——裝擴充、連 18789、本機回環語意與 SSH -L、macOS 權限（TCC）摩擦的逐步 Runbook（排錯 + FAQ）
租用無頭實體 Mac 跑 OpenClaw 的團隊，常在 SSH 與遠端 curl 都綠燈後，仍卡在筆電 VS Code 擴充還指向 127.0.0.1。本文給傳輸路徑決策矩陣、七步可複製驗收、可貼上診斷片段、可寫進 SLO 的數字，以及與 ZoneMac 類節點一致的 FAQ。若你尚未在機上裝好閘道本體，可先對照
OpenClaw v2026.4 安裝教學（ZoneMac 實體節點）。
1. 痛點拆解：為什麼「遠端 curl 成功」不等於「擴充也成功」
1）本機回環不可遞移。在伺服器上證明 curl http://127.0.0.1:18789/health 僅證明該主機上的閘道行程與防火牆行為；在另一台機器開啟的 VS Code 視窗若未經隧道、分割 DNS 或反代路徑，擴充會改去連「自己電腦」的 127.0.0.1，最後以逾時收場。
2）權限拒絕常被誤認成「埠壞了」。TCC 可能擋下鑰匙圈讀取、終端機自動化或受保護目錄寫入，而 lsof 仍顯示 LISTEN。維運若先查 nginx 一小時， stderr 裡的 EPERM 才是真凶。
3）JSON、plist 與 UI 三者靜默漂移。有人在 openclaw.json 改了繫結卻未改 LaunchAgent 的 ProgramArguments，或工作區仍存 http://127.0.0.1:18789 而正式環境已改 TLS 8443，不同成員載入不同設定同步快照時，問題會像間歇性幽靈。Windows／Linux 控制機若要對齊 Node 與企業 HTTPS 代理，可一併參考
OpenClaw Windows／Linux 與遠端 macOS 閘道聯通 Runbook。
2. 決策矩陣：VS Code 擴充應該怎麼連到閘道？
每個環境只選一條主路徑；臨時 SSH 轉發與共用 nginx upstream 混用卻沒寫進 Runbook，是 on-call 週末蒸發的主因。
| 型態 | 最適場景 | 注意事項 |
|---|---|---|
| Mac 上直接本機回環 | 自動化腳本、cron、本機 doctor | 遠端筆電「看不到」；建議繫結 127.0.0.1 以免意外對 WAN 開洞 |
SSH -L 本機轉發 |
在家或旅館網路開 VS Code 連公司閘道 | Keepalive 與跳板機需符合資安政策；文件化本機埠（例：18789→筆電 18789） |
| nginx／Caddy 回環 + TLS | 需要 mTLS、SSO 標頭或多後端路由 | 憑證續期與 proxy_pass 筆誤；擴充 base 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建議清單釘選擴充版本，讓全隊載入相同 RPC schema。 - 發佈 base 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 片段，勿用世界可寫的 dotfile。 - 刻意走一遍 TCC。若閘道會 shell 出 AppleScript 或讀開發者憑證，先在「隱私與安全性」預核可二進位並留存內部資安截圖。
- 用戶端驗收。隧道起來後在筆電：
nc -vz 127.0.0.1 18789；若前置 TLS：openssl s_client -connect openclaw.internal:443 -servername openclaw.internal。 - 凍結基線。將 JSON＋plist 片段納入平台倉庫；閘道與擴充語意化版本聯合驗證後再打 tag。若主機上還並存多組監聽器或負載均衡，請在內部平台文件同步記錄
/health／/ready與路徑遮蔽規則，避免 LB 誤判「未就緒」。
4. 可引用參數與清單（寫進 SLO／工單腳註）
- 18789——2026 多數模板中本機 OpenClaw HTTP 控制的慣例埠；務必視為可設定而非魔法常數。
- 127.0.0.1 對 0.0.0.0——繫結回環可避免意外對外曝光；全介面繫結需搭配防火牆／VPC，且多數 VS Code 整合不需要。
- 約 30–60 秒——重開機後 LaunchAgent 冷啟動的合理觀察窗，再決定是否呼叫 on-call；可搭配
ThrottleInterval降低重啟風暴。
5. 排錯速查表
| 症狀 | 較可能原因 | 優先指令／處置 |
|---|---|---|
| 僅筆電 ECONNREFUSED | 未開 SSH 轉發／本機埠填錯 | SSH 加 -v；檢查 ~/.ssh/config 的 LocalForward |
| nginx 回 502 | upstream 未起或 socket 指錯 | 在 Mac 本機直打 curl -v http://127.0.0.1:18789；查 error log |
| 行程 exit 1、埠卻空著 | TCC／缺密鑰 | Console.app 依子系統過濾；為二進位加完整磁碟取用；launchctl unload/load |
6. FAQ
埠 18789 到底做什麼用？
在常見套件裡它是本機 HTTP 管理與擴充流量的預設面——仍以你的 openclaw.json 與 LaunchAgent 為準。
遠端 curl 正常，VS Code 仍不行？
兩邊的「本機」不是同一台。請改走隧道，或把擴充 base URL 改成你已用 nc／curl 驗證過的主機名與埠。
可以把 18789 直接丟上公網嗎？
強烈不建議在無 TLS、無身分驗證與無限速下暴露。較佳做法：VPN、Tailscale 或 SSH；若瀏覽器必須存取，讓裸埠留在 127.0.0.1 後面接 nginx。
同一台 Mac 跑多個實例？
分配不重疊埠與不同 Label；每次佈建前 grep LISTEN 確認。
7. 在 Mac mini 上固化這套閘道＋VS Code 工作流
OpenClaw 搭配 VS Code 驅動的自動化，需要一台能長開、安靜、又把 launchd、鑰匙圈與原生 Unix 工具鏈放在同一信任邊界的機器。Apple Silicon Mac mini 待機約 4W 量級即可掛 7×24；Gatekeeper、SIP、FileVault 讓長效 API 金鑰比典型 Windows／Linux 跳板更可控。
統一記憶體頻寬讓 Node 閘道、輕量 nginx 與日誌外送在同機尖峰時仍較不侷促——doctor 探針、擴充 RPC 與 log shipping 同時抽風時特別有感。若你不想自建機房卻要與本文相同的 plist 語意，租用獨佔 Mac mini 節點通常是最快對齊團隊基線的做法。
若你正標準化多區團隊的 OpenClaw 閘道，Mac mini M4 是目前極具性價比的錨點硬體——先把本文 Runbook 落盤，再 到 ZoneMac 首頁選擇合適的實體節點與地區，把 18789 契約與權限邊界一次對齊。
今天要一台實體 Mac 跑 OpenClaw 閘道？
開通 ZoneMac Apple Silicon 節點，沿用 SSH、launchd 友善映像與本文驗證過的 18789 埠語意。