2026年 OpenClaw Node(VS Code 擴充功能)× 獨佔遠端 Mac:安裝、工作區技能讀取、閘道與 ACP 聯調及 SSH 埠轉發排錯的可復現教程 + FAQ
把「遠端 Mac 上的 OpenClaw 閘道」接到「本機編輯器裡的 Node 擴充功能」,並讓工作區技能、ACP 工作階段與 SSH 隧道在同一套驗收表裡可復現;本文給安裝、載入順序、聯調與埠轉發分診,便於寫入 Runbook。若要先對齊大版本升級後的 doctor 與 OPENCLAW_* 環境變數,請參考
2026年 OpenClaw 大版本升級實戰:2026.3.22 破壞性變更後的 doctor 修復、Plugin SDK 遷移與 OPENCLAW_* 環境變數對照(遠端 Mac SSH 可復現步驟)。
1. 目標、元件與邊界
本教程鎖定四件事可復現:① 在 VS Code/相容編輯器安裝 OpenClaw Node 擴充功能並指向獨佔遠端 Mac;② 讓擴充功能讀到工作區根目錄下的技能(.cursor/skills、專案內 SKILL.md 或團隊約定的等價路徑);③ 與遠端 Gateway 及 ACP(Agent Client Protocol) 端點完成聯調(含本機回呼埠);④ 用 SSH 埠轉發把僅在遠端 loopback 上的服務帶到筆電,並用分診表排錯。
不在本文展開:多租戶身分供應商整合、完整零信任公網暴露設計——應另開架構審查與滲透測試項。技能鏈安裝與外掛隔離可延伸閱讀 2026年 OpenClaw ClawHub 技能鏈實戰:安裝前審計清單、`plugins install` 可復現排錯與遠端 Mac SSH 無頭隔離(含 `openclaw update` 與健康檢查 FAQ)。
2. 前置條件(遠端 Mac)
- 已可用 SSH 登入的獨佔遠端 Mac,且 OpenClaw CLI/閘道版本與組織 Runbook 一致(升級後務必跑
openclaw doctor)。 - 閘道預設僅監聽
127.0.0.1:18789(埠號以你環境為準);ACP 或擴充功能回呼埠亦應避免裸奔0.0.0.0,除非已疊防火牆與審核。 - 工作區目錄已含技能定義;若多工作區,先釐清「哪個資料夾是單一工作區根」以免載入順序打架(可對照站內 Skills 優先級文章)。
3. 安裝 OpenClaw Node(VS Code 擴充功能)
建議路徑 A(市集/VSIX):在編輯器擴充功能面板搜尋 OpenClaw Node,安裝後重新載入視窗。若組織只允許離線 VSIX,請從內部構件庫取得簽章版本並記錄 SHA256。
建議路徑 B(Remote-SSH):使用 Remote - SSH 直接開遠端資料夾時,確認擴充功能在「遠端」而非「本機」脈絡啟用;否則會讀不到遠端工作區內技能檔。切換方式:命令選擇板 → Developer: Show Running Extensions,檢視 OpenClaw Node 是否標記為 SSH: …。
設定鍵(範例語意,實際鍵名以擴充功能版本為準):
- Gateway Base URL:若走 SSH 隧道,填
http://127.0.0.1:<本地轉發埠>,勿在設定檔硬編碼生產權杖。 - 工作區技能根:留空表示「自動偵測工作區根」;多根目錄時改為明確相對路徑並寫入 Runbook。
- ACP/回呼埠:與閘道約定同一埠區間,避免與本機其他代理或 Docker 綁定衝突。
4. 工作區技能讀取:可復現檢查清單
當擴充功能顯示「找不到技能」時,依序核對:
- 工作區根是否正確:只開單一資料夾測試;若使用 multi-root,確認技能檔落在「被標記為預設根」的那個資料夾。
- 檔名與層級:常見約定為
.cursor/skills/<name>/SKILL.md或專案根skills/;大小寫在 macOS 預設檔案系統上不區分,但在同步工具與 CI 上可能區分——Runbook 應寫死一種。 - 重新載入:變更技能後執行
Developer: Reload Window;遠端連線時順便觀察擴充功能輸出通道是否報 YAML/JSON 解析錯誤。 - 權限:SSH 使用者對技能目錄需可讀;若技能內含可執行腳本,確認未違反組織的簽章政策。
5. 閘道與 ACP 聯調
閘道健康檢查:在遠端 Mac 上先以 curl 打 loopback 健康或最小 API(依你版本文件),確認 200/預期 JSON。筆電端再透過 SSH 隧道重複同一步驟,若僅筆電失敗,問題在隧道或本機代理。
ACP 聯調:ACP 讓編輯器以標準化訊息與代理/閘道交換能力宣告與工具呼叫。實務上請對齊三件事:① 擴充功能與閘道使用同一協定版本;② WebSocket/HTTP+SSE 等傳輸層與公司代理相容;③ 回呼 URL 若指向 127.0.0.1,必須發生在「發起請求的那台機器」上——遠端閘道要回呼筆電時,需改為可路由位址或再加一條反向隧道/內網服務發現。
若你的主線還包含 OpenAI 相容 HTTP 層與 /v1/chat/completions,請與 Gateway 設定一併驗收,細節可對照站內「Gateway OpenAI 相容 API」長文。
6. SSH 埠轉發:範例與分診
單埠(閘道 loopback):
ssh -N -L 18080:127.0.0.1:18789 user@remote-mac.example
多埠(閘道 + ACP 回呼測試埠範例):
ssh -N \
-L 18080:127.0.0.1:18789 \
-L 19090:127.0.0.1:19090 \
user@remote-mac.example
分診表:
| 現象 | 優先檢查 |
|---|---|
bind: Address already in use |
本機 18080/19090 是否被其他專案占用;改埠後同步更新擴充功能設定。 |
隧道可建但 curl 逾時 |
遠端服務是否只監聽 IPv6;試 ::1 映射或改閘道監聽位址。 |
| ACP 握手成功但工具呼叫 401 | Bearer/閘道權杖是否與 launchd 環境變數一致;是否半舊行程未重啟。 |
| 僅在公司網路失敗 | 系統代理、PAC、SSL 檢查;必要時為 SSH 單獨設 ProxyCommand。 |
若需把 SSH 邊界與企業資源池金鑰輪換寫進同一套治理敘事,可參考 2026年企業獨享遠端 Mac 資源池:SSH 憑證(SSH-CA)與按機金鑰的權限邊界、金鑰輪換與稽核對比決策矩陣 + FAQ。
7. 可復現驗收表(Runbook 片段)
- E1:遠端 loopback
curl閘道健康 → 通過。 - E2:筆電經隧道
curl同一健康 → 通過。 - E3:擴充功能「技能列表」載入專案內測試技能 → 通過。
- E4:ACP 能力宣告與一筆最小工具呼叫(唯讀)→ 通過。
- E5:關閉隧道後請求應失敗 → 證明未繞過 SSH 邊界。
8. FAQ
Q:擴充功能連得到閘道,但技能永遠是空的?
A:十之八九是「工作區根錯位」或「擴充功能跑在本機脈絡」。先用單根目錄復現,再開 multi-root;並確認 Remote-SSH 延伸啟用位置。
Q:ACP 顯示版本不相容?
A:將閘道、CLI 與擴充功能升到同一發行線;升級後跑 doctor,並清掉舊的權杖快取(路徑依版本文件)。
Q:只想暫時把閘道暴露給同事筆電,可以嗎?
A:優先短期憑證 + 已知裝置 SSH,而非直接把 Gateway 監聽改到公網;並設定到期提醒與稽核。
在 Mac mini 上固定這條「編輯器 ↔ 閘道」鏈路
OpenClaw Node、閘道與 ACP 聯調都依賴可預測的檔案系統、長連線與低抖動網路。macOS 上 launchd、原生 OpenSSH 與開發者工具鏈成熟,獨佔遠端 Mac mini 能把「監聽埠、日誌目錄、權杖環境」收斂在單一使用者脈絡,排錯時 SSH 登入即可復現;Apple Silicon 統一記憶體也有利於同機承載閘道、輕量模型與自動化腳本而不必忍受高噪音機箱。
與同價位小型主機相比,Mac mini M4 在待機功耗與日常靜音表現上通常更適合 24/7 節點;Gatekeeper、SIP 與 FileVault 也降低無人值守機器的惡意軟體面。若你希望把本文的 VS Code 擴充功能、閘道與 SSH 隧道方案落在安靜、低功耗、可稽核的硬體上,Mac mini M4 是值得優先考慮的起點——現在即可入手,讓 ACP 與技能驅動的工作流真正可復現、可交接。