這篇與安裝指南、Docker 正式環境 Runbook 有什麼不同？

安裝指南負責把 OpenClaw 與 Gateway 拉起來；Docker 正式環境 Runbook 覆蓋 Compose、健康檢查與釋出節奏。本篇假設程序已能啟動，聚焦 MCP 註冊、ClawHub／本機 Skills 的落地位置，以及在日誌中區分模型、工具與通道失敗。

是否應先檢查卷再改 MCP 設定？

若 Skills 或狀態目錄位於容器短命層或唯讀掛載，ClawHub 下載看起來成功，重啟後才消失。請先修正 bind 掛載與權限，再回到工具註冊。

如何把 MCP 權限降到最低？

將唯讀查詢伺服器與寫入／對外呼叫伺服器拆開，使用不同權杖，並在同一份變更紀錄保存允許工具清單；避免單一 MCP 設定檔暴露整個內部 API 介面。

2026 OpenClaw：MCP 工具、ClawHub Skills 安裝／驗證與 Gateway 分診 Runbook

約 13 分鐘閱讀 · MACCOME

讀者：Gateway 已跑，但 MCP 工具不出現、呼叫逾時，或 Skills 重啟後不見。目標：bootstrap 留在安裝指南與Docker 正式環境 Runbook；持久化留在卷與 Skills 權限檢查清單。本篇涵蓋宣告 → 程序可見性 → Gateway 註冊 → 模型／工具／通道分診。架構：六個常見誤區、兩張表、設定草圖、警示框、六步流程、三個 KPI、收尾建議。

為何 Gateway 表現得像沒有 MCP

MCP 是 Gateway 與子程序或遠端端點之間的JSON-RPC 連線。設定有項目不代表子程序會啟動；子程序啟動也不代表會回傳 schema。以下六種誤讀很常見。

環境變數只在互動式 shell：daemon、systemd、launchd 或 Compose 讀不到 ~/.zshrc 裡的 PATH 與 API 金鑰。
ClawHub Skills 在唯讀或匿名卷：下載看似成功，容器重建後才露餡；請對照卷篇。
工具快取過舊：設定已改，UI／CLI 列表仍舊；依文件重載，不要先假設是故障。
逾時過緊：首次冷啟動跨 RTT，與穩態需要不同門檻。
AGENTS.md 與 bootstrap 文意重疊：MCP 與 Skills 重複指令會膨脹上下文；邊界請依Skills 調參清單切開。
把通道問題誤認成 MCP：先修 Slack／Telegram OAuth 路徑，再怪工具。

依裝後 doctor 指南的順序執行 openclaw doctor；本文補的是工具註冊的證據鏈，不是另一份安裝教學。

為每個 MCP 伺服器準備一張「最小重現卡」：一則唯讀查詢、一則應被拒絕的負向測試、三個預期日誌片段，讓值班不用重讀長 prompt 也能比對設定是否退步。卡片上註明允許對外連線範圍與資料分級，避免事故時無紀錄擴權。

表一：MCP 症狀 → 證據 → 行動

欄位名稱隨 OpenClaw 版本而異；本表鎖定操作順序。

症狀	先蒐集	可能根因	可稽核行動
工具列表空白或缺段	Gateway 日誌、子程序離開碼	執行檔缺失、cwd、permission denied	使用絕對路徑 `command`／`args`／`cwd`；子程序以與 Gateway相同使用者執行
首次呼叫慢、之後正常	冷啟時間、套件拉取日誌	`npx -y` 或 runtime JIT	預熱、映像鎖版、放寬首次呼叫逾時
持續逾時	子程序存活、CPU、FD 使用	死鎖、阻塞 IO	在允許範圍取樣／追蹤；用唯讀工具做 A／B
「工具未註冊」	schema 日誌、協定版本	實作不一致	對齊 MCP 版本、鎖小版本、閱讀上游變更說明

表二：ClawHub Skills 對上 repo 內 Skills 對上 MCP

公開能力矩陣，避免同一條工作流程用三種說法各講一次。

來源	最適場景	版本策略	風險
ClawHub／市集	快速實驗	鎖 commit 或 semver 區間；每週 diff	上游漂移，需要迴歸測試
repo `SKILL.md`／私有套件	合規重的流程	經 PR 與主線一併交付	維護成本；須與 MCP 範圍對齊
MCP（權威介面）	資料庫、工單、內部 HTTP API	獨立釋出節奏	權杖過寬；需維護允許清單

config

# 僅結構示意；實際鍵名、巢狀與熱重載請依現行 OpenClaw 文件。
# 目標：Gateway 以固定使用者經 stdio 啟動 MCP 伺服器。
#
# mcpServers:
#   internal-readonly-lookup:
#     command: /usr/local/bin/node
#     args: ["/opt/mcp-servers/lookup/dist/index.js"]
#     env:
#       LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# ClawHub Skill：解壓／clone 至團隊 skills 目錄後，依版本刷新 skill 索引
# 或執行文件載明的 reload 指令。

warning

警示：MCP 把助理接到正式資料。最小權限與稽核軌跡優先於「先跑再說」。讀寫分離不同伺服器、分開權杖，並把允許清單摘錄附在變更單上。

六步：從「聊天可用」到「工具呼叫可重播」

凍結拓撲：裸機、遠端 Mac 或容器—記錄使用者、PATH、cwd、bind 掛載。
註冊 MCP：依文件填 command／args／env；以與 Gateway相同身分手動啟動子程序並確認交握日誌。
安裝 ClawHub Skills：落在持久儲存；記錄版本與校驗碼，不要只放在短命層。
修剪重疊的 Skills 內文：長檢索改走 memory_search 或文件工具，抑制上下文膨脹。
自動化三項檢查：冷啟、穩態呼叫、刻意失敗（例如斷線）以驗證逾時與降級。
更新維運手冊：重載順序、回滾（移除伺服器＋重啟 Gateway）、負責人—與值班同一頁。

值得每週檢視的三個 KPI

註冊覆蓋率：宣告的 MCP 伺服器數對上實際列出的工具數，按釋出切分。
首次呼叫 P95 對穩態 P95：暖機與穩態分開看。
重複能力計數：同一動作出現在 MCP、ClawHub、AGENTS.md 的次數；大於一需有簽核豁免。

在遠端 Mac 或雲端主機上，磁碟空間與日誌輪替會影響把暫存寫進小系統卷的 MCP 子程序，模型設定未改也可能看起來「隨機逾時」。請同步檢視主機維運與工具設定。

若 MCP 走 HTTP／SSE 前端，納入反向代理閒置逾時、Upgrade 處理與 TLS 終止：Gateway 日誌可能顯示交握成功，邊緣卻回 499／504。在只調高 OpenClaw 逾時前，先對照Nginx／Caddy 反向代理檢查清單。

社群向備註（非基準測試）：三台重型 MCP 加上寬檢索，佇列抖動常達分鐘級；要 SLA 寧可靠能力矩陣與允許清單，而非無上限外掛。

為何筆電與臨時主機難以長期治理工具

睡眠、VPN 瞬斷、路徑漂移讓子程序與 skill 索引不穩。接真實商業資料需要7×24 上線、可預期路徑、可稽核權限。

缺乏多地區選擇與彈性合約的自管機器，容易落到共享主機，冷啟與日誌 IO 互搶。把 Gateway 放在磁碟與出站可預測的專用 Apple Silicon上，是專業 Mac 雲常見做法。MACCOME 提供多地區 Mac mini M4／M4 Pro 彈性租賃，作為 Gateway 與建置叢集的穩定底座；下單前請確認公開價格與幫助中心 SLA。

在映像推滿整個叢集前，先在遠端 Mac 試跑本篇三項檢查，避開「本機 OK、正式環境逾時」迴圈。若 Gateway 對外，TLS、速率限制、IP 允許清單應與同一變更一併上線，不要留成後補 patch。

常見問題

這篇與通道接入文件如何搭配？

通道文檔處理 Slack／Discord／Telegram OAuth；本篇處理工具探索。若訊息已進 Gateway 但工具失敗，請先依表一蒐集證據，再回頭看「已連線但無回應」類案例。

回滾應包含什麼？

移除 MCP 項目、記錄重啟順序、執行唯讀驗證查詢，並在儀表板確認工具數回到基線。帳務對齊請見租賃價格說明。

容器與裸機路徑不同怎麼辦？

為每種 runtime 維護絕對路徑矩陣；勿讓模型在對話裡猜路徑。請將幫助中心與 Docker 卷篇交叉比對。