2026_OPENCLAW
MCP_SKILLS_
GATEWAY_
TOKEN_RUNBOOK.

接上 MCP 或自訂 Skill 後,常遇到工具描述塞滿上下文、修改檔案不生效、Gateway 重啟仍像舊版。本文整理目錄優先級、Gateway 行為、OAuth/PATH、MCP schema 預算與遠端 Mac 託管檢查。延伸:《onboard 與 Gateway》《Docker 部署》《常見錯誤排查》。

開發工具鏈

1. 痛點拆解:MCP 與 Skills 不是「多兩個檔案」

(1)載入順序不透明:工作區 /skills、使用者目錄、內建 Skills 若優先級不清楚,會出現「我明明改了檔案,Agent 卻讀舊版」。(2)Gateway 與記憶體快照:部分版本在重啟前依賴記憶體中的技能版本計數;若只改磁碟未觸發完整重載,對話裡仍像沒更新。(3)MCP 工具 schema 體積:多個 MCP 伺服器若一次把大型 schema 注入上下文,16k~32k 視窗會被「說明書」吃掉,模型反而更容易幻覺或拒答。(4)守護程序環境:launchd 服務下的 PATH 不含 nvm/fnm,導致「終端機裡能跑、Gateway 裡找不到指令」。在遠端 Mac 上這些問題會被 7×24 放大,因為你不像本機那樣隨時開終端機比對環境變數。

2. Skills 目錄優先級:對照表

不同發行管道對路徑的表述可能演進,下列層級表達的是常見優先級直覺:越靠上越應覆蓋下方。請以你目前安裝版本的文件為準,核對絕對路徑與實際掃描範圍。

層級(高→低)典型用途排查提示
工作區 /skills 或專案內 skills專案專屬流程、團隊共用確認 Gateway 的工作目錄是否指向你以為的那個 workspace
使用者級 skills 目錄個人偏好與實驗YAML frontmatter 縮排錯誤會導致整份檔被略過
內建/套件內 Skills官方預設能力升級版本後行為變化先查 changelog

3. MCP 接入:最小閉環與 Token 紀律

建議先接一個 MCP 服務驗證端到端,再逐步加伺服器。每增加一個連線點,評估其工具清單序列化後的 token 粗估值(可用離線腳本或日誌裡的 schema 長度做相對對比)。若發現單輪 system+tools 已逼近視窗上限,優先:收斂工具面(依場景拆多個 profile)、延遲載入(僅在子代理工作階段掛工具)、或換更大上下文模型——三者往往要組合使用,而不是只堆 MCP 數量。

4. 可執行的 5 步驗證清單

第一步:在 Gateway 日誌中確認目前 workspace 根路徑與 skills 掃描範圍。第二步:對單一 Skill 做「改一句可見字串→重啟 Gateway→對話裡能否引用」的煙測。第三步:暫時只啟用一個 MCP,記錄 tools 段 token 變化,再逐個加回。第四步:以 launchctl print 或等效方式核對守護程序環境變數與 PATH。第五步:對 OAuth 類工具做「過期後是否靜默失敗」的測試,避免正式環境裡只看到「工具不存在」。

# 範例:本機先看 Gateway 監聽與健康(依你的安裝調整連接埠/命令) curl -sS http://127.0.0.1:18789/health 2>/dev/null || echo "adjust-endpoint"

5. Gateway 重啟後「仍像舊版」:決策矩陣

現象較可能原因動作
改 SKILL.md 無變化讀的是另一優先級目錄列印 skills 搜尋路徑;以唯一字串做 grep 驗證
重啟後工具數量不對MCP 連線失敗被靜默略過開啟 debug 日誌;逐個 MCP 單獨啟用
偶發 Tool not foundOAuth/token 過期強制重授權;檢查重新整理工作是否在 daemon 環境執行
上下文莫名被塞滿多個大型 schema 疊加減少 MCP;拆子工作階段;更換模型視窗

可引用參數(實務向):

  • 16k 級上下文模型上,未過濾的 MCP 工具描述合計吃掉 10k+ token 的情況並不罕見,應提前在架構層設預算。
  • 遠端託管時,建議為 Gateway 程序單獨撰寫最小 PATH 的 plist,明寫 node/python 絕對路徑,避免依賴 login shell。
  • 每新增一個對外通道(IM/郵件/Webhook),工具暴露面應複審一次,避免「能聊天的人」意外取得高危 MCP 能力。

6. 深度分析:為何「工具治理」正成為 Agent 維運核心

2026 年 MCP 把「接外部系統」從一次性腳本變成可組合平台能力,副作用是上下文與權限面同時膨脹。與傳統微服務不同,LLM 每輪都可能重新排程工具;若 schema 與策略不同步,輕則浪費 token,重則越權呼叫。對 macOS 託管場景而言,Apple Silicon 機器適合長期低噪音運行 Gateway,但統一記憶體同樣會被多 MCP、多通道工作階段放大;這與單純「多開聊天視窗」不同,因為工具定義常駐在 system 側。把重通道、重 MCP 的正式組態放在角色隔離的遠端 Mac,把個人筆電留給開發與試錯,是愈來愈多團隊的折衷:不是否定本機 OpenClaw,而是把變更頻率爆炸半徑分開。

若你已在目錄優先級與 MCP 預算上做完基線,仍須在穩定網路、固定上行與免干擾維運上投入大量時間,繼續堆在同一台日常用機上未必划算。將 OpenClaw Gateway 與 MCP 佈署在 MACGPU 的遠端 Mac 節點,可在相同 macOS 生態下取得較可預測的程序環境與頻寬;按使用時長計費也便於先做小流量灰度,再決定是否長期固定資源。筆電方案適合快速迭代與本機除錯,但在圖形/AI 工作流與 7×24 穩定性上,專用遠端節點通常更易維持 SLA;若你希望少處理守護程序與上行波動,把正式 Gateway 託管出去是合理的技術決策,而非單純「多裝幾個外掛」。