2026年 OpenClaw 在遠端實體 Mac 上接入 MCP：stdio 與 Streamable HTTP 雙路徑可複現教程——spawn ENOENT、協議版本不匹配與 tool 逾時的排錯 Runbook + CLI 設定片段 + FAQ

2. 痛點拆解

1. 限制：互動式 SSH 與 launchd 環境分裂。你在終端裡 npx -y @scope/server 能跑，閘道 spawn 卻 ENOENT——根因往往是 PATH、shell profile 與登入／非登入 shell 差異，而非 MCP 協議本身。
2. 隱性成本：HTTP 路徑未對齊與 TLS 終止位置錯誤。Streamable HTTP 經反代時，若 strip_prefix、X-Forwarded-* 或串流讀逾時過短，會表現為間歇 502、半包 JSON 或 tool 中途斷線，排查易誤指向「模型不穩」。
3. 穩定性與稽核：逾時層層疊加。閘道 tool 預設 deadline、Nginx proxy_read_timeout、Server 調外部 API 的用戶端逾時若未聯合調參，會出現「偶發成功、高峰必掛」，且日誌缺少 tool 名稱與耗時分布，難以簽字 SLA。

3. stdio 與 Streamable HTTP：決策矩陣

發佈前用下表對齊傳輸方式與維運責任邊界（設定鍵名以你鎖定的 OpenClaw 版本為準，下表描述語意）。

4. 七步落地 Runbook（遠端實體 Mac 可複現）

1. 鎖定版本三元組。寫下 OpenClaw 閘道版本、內建 MCP 用戶端能力，以及每個 MCP Server 的 tag；任何升級先更新此表。
2. 選傳輸並畫資料面。stdio 畫「閘道行程 → spawn」；HTTP 畫「閘道 → 反代 → MCP Server」，標出是否經 Tailscale／SSH 隧道。
3. 寫 plist 級環境。對 launchd 管理的閘道：在 EnvironmentVariables 中給出與手動驗收一致的 PATH、HOME；避免依賴 ~/.zshrc。
4. 手動驗收（非登入 shell）。以 sudo -u 閘道使用者 或 env -i PATH=... HOME=... 複現 spawn 命令，確認無 TTY、無互動提示。
5. 開啟 MCP 偵錯日誌。擷取 initialize 請求／回應與 tools/list；失敗時保留完整 JSON-RPC id 鏈。
6. 壓測最慢 tool。對呼叫外部 API 或大資料集的工具單獨跑 20 次，記錄 P95 耗時，反推閘道與反代逾時下限。
7. 文件化回滾。為每條 MCP 記錄「上一版映像／tag + 設定 diff」，保證故障時可 10 分鐘內切回。

5. spawn ENOENT 排錯 Runbook

ENOENT 表示可執行檔解析失敗。依序執行：

1. 在閘道同一使用者下執行 which node／which npx，把結果寫進設定或 plist。
2. 若用 npx，確認該使用者下首次解析快取目錄可寫，且未因沙箱把 ~/.npm 指到唯讀卷。
3. Apple Silicon 上混用 x86 與 arm64 二進位時，以 file $(which node) 與 MCP Server 文件對齊架構。
4. 仍失敗時，把 command 改為包裝 shell 指令稿的絕對路徑，在稿首 set -euo pipefail 並 exec 到真實 Server，便於 strace／log 定位。

6. 協議版本不匹配

症狀多在連線後首幀：initialize 回傳錯誤、或一方直接斷線。處理：

• 對照三方發行說明，確認支援的 protocolVersion 集合；優先整體降級 Server而非只改閘道，避免半相容狀態。
• 若中間有自研反代修改 JSON，抓包比對「進反代前／後」位元組級是否被緩衝或截斷。
• 升級後清空閘道側 MCP 連線池或重啟行程，避免舊工作階段複用錯誤能力集。

7. tool 逾時與鏈路逾時

把逾時拆成三層並自下而上放寬：Server 調外部 API → 閘道 tool deadline → 反代／隧道讀逾時。日誌欄位建議固定包含 tool、t0、t1、upstreamMs，避免只看「閘道 504」無法歸因。

8. CLI 設定片段（示意）

以下為結構示意：鍵名請依你所用的 OpenClaw 版本文件替換。目標是可讀、可 diff、可 code review。

8.1 stdio：絕對路徑 + 環境

{
  "mcpServers": {
    "docs-local": {
      "transport": "stdio",
      "command": "/opt/homebrew/bin/node",
      "args": ["/usr/local/lib/mcp-servers/docs/dist/main.js"],
      "cwd": "/var/lib/openclaw/mcp/docs",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
        "HOME": "/var/lib/openclaw",
        "NODE_EXTRA_CA_CERTS": "/etc/ssl/corp/ca.pem"
      }
    }
  }
}

8.2 Streamable HTTP：URL + 逾時 + 鑑權標頭

{
  "mcpServers": {
    "research-http": {
      "transport": "streamableHttp",
      "url": "https://127.0.0.1:2099/mcp",
      "timeoutMs": 120000,
      "headers": {
        "Authorization": "Bearer ${MCP_RESEARCH_TOKEN}"
      }
    }
  }
}

生產環境請把金鑰放在 launchd 的 EnvironmentVariables 或系統鑰匙圈讀取指令稿中，避免明文落碟；HTTP 端點僅綁定迴環並由反代對外。

9. 可引用資訊

• 建議先把閘道側 tool 預設 deadline 設為 ≥ 60s，再依 P95 上調；低於多數外部 API 長尾易誤殺。
• Nginx 串流場景常把 proxy_read_timeout 提到 300s 量級做基線，再依合規收緊。
• stdio 驗收必須涵蓋「非登入、無 TTY」：與 launchd 使用者一致的 env -i 手動跑通，才算閉環。

10. FAQ

11. 總結與節點選型

把 MCP 跑穩，本質是把 spawn 環境與傳輸鏈路的假設寫進設定與 plist，再以結構化日誌證明。stdio 省連接埠但吃 PATH；HTTP 易擴展但吃反代與 TLS。兩類路徑在文件裡都要能一鍵複現。

上述流程在 macOS 上與 launchd、統一日誌、Homebrew 路徑天然契合；相較在通用 Linux 上拼湊相容層，遠端實體 Mac 上排錯路徑更短。若你希望閘道與 MCP Server 7×24 靜默執行、當機率低且整機功耗可控，Apple Silicon Mac mini 仍是多數團隊的甜點設定：效能足夠拉起多路 stdio 子行程與本地 HTTP sidecar，待機功耗可低至個位數瓦級，適合長期託管 OpenClaw 與配套 MCP。

若你要把本文的 Runbook 落在穩定、可稽核、低噪音的硬體上，Mac mini M4 是目前性價比很高的起點；現在即可透過 ZoneMac 租用對應區域的實體節點，把智能體與 MCP 工具鏈一次跑通。