2026 年 OpenClaw Skills 安裝實戰：ClawHub 啟用、私有技能包上傳與遠端 Mac Mini M4 Pro 磁碟分層排障 // NOVAKVM 工程部落格

Gateway 已常駐、頻道也接好了，對話裡 Agent 卻仍「不會用新工具」——多半不是模型能力問題，而是 Skills 根本沒裝進正確目錄。2026 年 OpenClaw 2026.5.x 把 Skills 載入、ClawHub 社群安裝與私有 zip 上傳拆成清晰路徑：Plugins 管頻道與 Gateway 擴充，Skills 管含 SKILL.md 的能力包，兩者目錄樹、設定鍵與排障手法完全不同。本文面向已在 遠端 Mac mini M4 Pro 跑通首跑閉環的進階使用者，先拆六大痛點，再給 Skills / Plugins 決策矩陣與內建技能啟用表，隨後整理 ClawHub 安裝、skills.install.allowUploadedArchives 私有包上傳與十二步跟做清單，並收束 ~/.openclaw/skills 磁碟分層、六地節點選型與報錯對照矩陣。指令與設定欄位以 OpenClaw 官方文件為準，發版後請重新開啟連結核對。價格見租用價格頁，下單見訂購頁，遠端工作階段見說明中心；可與外部外掛 npm 篇、多 Workspace 篇、首跑閉環篇交叉閱讀。

[ SECTION_01 ] // PAIN_MAP Skills 安裝時最常見的翻車點有哪些

把 Skills 當 Plugins 裝：在 ~/.openclaw/npm 或全域 npm 裡找技能包，Gateway 日誌卻報 skill not found——頻道外掛與 Agent 技能是兩套目錄樹，混用會浪費整個下午。
裝進 Workspace 卻期望全域生效：openclaw skills install 預設寫入目前活躍 Workspace 的 skills/，未加 --global 時其它 Agent 完全看不到。
ClawHub slug 與目錄名不一致：安裝後資料夾名與 skills.entries 設定鍵對不上，enabled: false 或 allowlist 會把技能靜默屏蔽，表面像「ClawHub 壞了」。
私有 zip 未開 allowUploadedArchives：已透過 skills.upload.* staging 完成，skills.install 仍拒絕 upload 模式，表現為「上傳成功、安裝被拒」。
符號連結越界被略過：Workspace 下 skills/manager 鏈到外部儲存庫時，未設定 load.allowSymlinkTargets，日誌出現 Skipping escaped skill path。
磁碟全堆系統卷：ClawHub 快取、~/.openclaw/skills 與 Gateway 日誌同卷，256GB 遠端 Mac 在批次安裝後 APFS 水位告警，watch 重新整理失敗被誤判為「技能損壞」。
Agent allowlist 誤傷：agents.list[].skills 寫死白名單後，新裝的社群技能不會自動出現，團隊以為是網路或 ClawHub 故障。

[ SECTION_02 ] // ROUTE_MATRIX Skills 與 Plugins 邊界：內建技能與安裝路徑怎麼選

立項前先凍結「這是頻道擴充還是 Agent 能力包」。下列矩陣把 2026.5.x 常見路徑放在同一張表裡，避免裝完才發現走錯分支。

OpenClaw Skills 與 Plugins 邊界對照（2026.5.x 遠端 Mac 實戰）
維度	Skills（技能包）	Plugins（外掛／頻道）
核心載體	含 `SKILL.md` 的資料夾	npm 套件或 ClawHub 頻道擴充
典型用途	工具呼叫、工作流、領域知識注入 Agent	Telegram、Discord、微信 ClawBot 等 IM 入口
預設安裝根	Workspace `skills/` 或 `~/.openclaw/skills`	`~/.openclaw/npm/node_modules`
CLI 入口	`openclaw skills install` / `clawhub install`	`openclaw plugin install` / npm 到外掛根
設定域	`skills.`、`agents..skills`	`plugins.*`、頻道 manifest
私有交付	zip + `skills.upload.*`（需明確開啟）	私有 npm registry 或手動 stage 目錄

2026.5.x Skills 模型變化（前置檢查）：載入 precedence 固定為 Workspace /skills → 專案 /.agents/skills → ~/.agents/skills → 託管 ~/.openclaw/skills → 內建 bundled → skills.load.extraDirs。同名技能先掃描到的優先，因此生產環境應約定「全域技能放 ~/.openclaw/skills、專案客製放 Workspace」，避免覆蓋順序失控。Watcher 預設開啟（load.watch: true，debounce 250ms），改完 SKILL.md 通常下一個 Agent turn 即生效，無需重啟 Gateway；若你在遠端 Mac 上關閉了 watch，需手動觸發工作階段重新整理。

內建 bundled 技能啟用決策矩陣（節選）
技能族	典型場景	啟用建議	設定要點
gemini / image-lab	影像生成與編輯工作流	需要 Gemini 或 fal 時啟用	`skills.entries.*.apiKey` 或 `GEMINI_API_KEY`
peekaboo	螢幕／UI 自動化探測	macOS 遠端除錯場景可選	`allowBundled` 白名單或 `enabled: true`
github	儲存庫 Issue／PR 操作	研發 Agent 預設開	Token 走 `skills.entries.github.env`
weather	輕量資訊查詢示範	PoC 可開，生產按 allowlist 收窄	`agents.defaults.skills` 控制可見性
sag 等實驗技能	非預設工作流	預設 `enabled: false` 較安全	用 `allowBundled` 限制 bundled 面

Skills 解決的是「Agent 會什麼」；Plugins 解決的是「使用者從哪發訊息」。混目錄排查，平均多花四十分鐘 grep 日誌。

[ SECTION_03 ] // INSTALL_RUNBOOK ClawHub 社群技能、私有 zip 上傳與十二步跟做閉環

下列步驟綜合 OpenClaw 官方 Skills 文件、Gateway 協定與 ClawHub 公開 registry 說明整理；若上游更新 CLI 子命令，請以連結為準。

https://docs.openclaw.ai/tools/skills-config

https://github.com/openclaw/openclaw/blob/main/docs/tools/skills.md

https://github.com/openclaw/openclaw/blob/main/docs/gateway/protocol.md

https://clawhub.ai

確認 Gateway 與版本基線：在遠端 Mac 上執行 openclaw --version，建議對齊 2026.5.2+；用 openclaw doctor 排除 Node 與連接埠 18789 問題，參見首跑篇。
備份 openclaw.json：變更 skills.* 前先複製 ~/.openclaw/openclaw.json 與時間戳快照，便於 allowlist 誤配時秒級回滾。
選定安裝作用域：單專案客製用 Workspace skills/；多 Agent 共享用 openclaw skills install --global 寫入 ~/.openclaw/skills。
ClawHub 搜尋與釘版本：在 registry 或 CLI 確認 slug 與 --version；生產建議明確釘版本而非永遠 latest。
執行 ClawHub 安裝：見下方終端機區塊；安裝後 ls 目標目錄確認存在 SKILL.md。
設定 entries 與金鑰：在 skills.entries.<name> 寫入 enabled、env、apiKey；sandbox 工作階段需另行設定 Docker env，見官方 Skills config 說明。
核對 Agent allowlist：若設定了 agents.list[].skills，把新 slug 加入該 Agent 白名單，或暫時移除白名單做冒煙測試。
私有 zip 開啟開關（僅內網交付時需要）：在 openclaw.json 設 skills.install.allowUploadedArchives: true；正常 ClawHub 安裝不需要此開關。
staging 私有包：受信 operator.admin 用戶端依序呼叫 skills.upload.begin、skills.upload.chunk、skills.upload.commit；zip 根目錄須含 SKILL.md，內部資料夾名不決定安裝目標。
upload 模式安裝：skills.install({ source: "upload", uploadId, slug, force? })，slug 須與 begin 時一致；commit 只 finalize 上傳，不自動安裝。
工作階段冒煙：在新工作階段傳送會觸發該技能的指令，觀察 Gateway 日誌是否載入 snapshot；失敗時先查 precedence 是否被 Workspace 同名目錄覆蓋。
寫入維運台帳：記錄 slug、版本、安裝根（Workspace／global）、allowUploadedArchives 狀態、磁碟占用基線與回滾指令（刪除目錄 + 還原 json 快照）。

SKILLS_INSTALL.SH

$ openclaw skills install weather --version 1.2.0

$ openclaw skills install github --global

$ clawhub install docs-search --workdir ~/.openclaw/workspace/acme

$ openclaw skills list --json | jq '.[].name'

OPENCLAW.JSON SKILLS SNIPPET

{
  "skills": {
    "install": {
      "allowUploadedArchives": true,
      "nodeManager": "npm",
      "preferBrew": true
    },
    "load": {
      "watch": true,
      "watchDebounceMs": 250,
      "extraDirs": ["~/Projects/oss/skill-pack/skills"]
    },
    "entries": {
      "weather": { "enabled": true },
      "internal-ops": {
        "enabled": true,
        "env": { "OPS_TOKEN": "from-vault" }
      }
    }
  },
  "agents": {
    "defaults": { "skills": ["github", "weather"] }
  }
}

[ SECTION_04 ] // LIMITS_AND_OPS 遠端 Mac 上 ~/.openclaw/skills 磁碟分層與 watch 維運注意

Skills 安裝比 Plugins 更「靜默」：目錄不大，但 ClawHub 快取、Git 技能 clone 與 skills.load.extraDirs symlink 布局會在 256GB 機型上與其它 OpenClaw 子樹爭用系統卷。建議在遠端 Mac M4／M4 Pro 上採三層分盤：

系統卷（不可動）：僅保留 openclaw.json、LaunchAgent plist 與輕量狀態；避免把大量社群技能直接堆在預設 home。
資料卷 A — 託管技能：~/.openclaw/skills 鏈到獨立 APFS 卷或 /Volumes/openclaw-data/skills，供 --global 安裝與 ClawHub 快取。
資料卷 B — Workspace 技能：各專案 <workspace>/skills 與 skills.load.extraDirs 指向客戶儲存庫，用 allowSymlinkTargets 精確放行，禁止寬到 ~/Projects 整樹。
日誌與 watch：Gateway 日誌單獨輪替；watch 高峰時 debounce 250ms 內多次儲存會觸發重複 snapshot，磁碟 IO 斜率異常時先查 watch 而非 skill 內容。
M4 vs M4 Pro：Skills 本身 CPU 占用低於並行頻道外掛；當單節點 >15 個 Git 技能且同時開 peekaboo 類 UI 技能時，建議升 M4 Pro 並擴至 512GB，參見磁碟與守護行程篇。
多 Workspace 隔離：與多專案篇一致——共享 ~/.openclaw/skills 時，Workspace 級技能仍應用 --workspace 明確安裝，避免 A 專案覆蓋 B 專案同名 slug。

小團隊真實案例：三人工作室在新加坡節點跑 OpenClaw，先用 ClawHub 裝了 8 個公開技能在 Workspace，又把 2 個內部 zip 走 upload 路徑；未分盤時系統卷 256GB 在兩週內剩 11GB，watch 重新整理逾時。遷出 ~/.openclaw/skills 到獨立 128GB 卷、關閉非必要 bundled 後，Gateway 探針恢復穩定，內部技能升級窗口從「不敢動」變成「按 slug 回滾」。

[ SECTION_05 ] // HARD_FACTS 可引用參數與 Skills 安裝報錯對照

載入 precedence：Workspace /skills → /.agents/skills → ~/.agents/skills → ~/.openclaw/skills → bundled → extraDirs（來源：Skills config 官方文件）
allowUploadedArchives 預設：false；僅影響 upload 模式私有 zip，不影響 ClawHub 正常安裝（來源：同上及 Gateway protocol）
watch debounce：預設 250ms；生產大批量同步技能包時可暫時調大，降低 snapshot 風暴（來源：Skills config）
install.nodeManager：預設 npm，可選 pnpm／yarn／bun；Gateway 執行時仍應 Node，Bun 不建議用於 WhatsApp／Telegram 頻道（來源：Skills 文件）
Gateway 連接埠慣例：除錯與探針仍常圍繞 18789；Skills 變更不重啟 Gateway，但 upload 安裝需 admin 用戶端連上同一 Gateway（來源：openclaw README）

OpenClaw Skills 安裝與載入排障對照
表面症狀	優先懷疑	最小驗證動作
ClawHub 裝完 Agent 仍不會	裝錯 Workspace／未 --global	`openclaw skills list`；核對活躍 Workspace 路徑
upload 安裝被拒	`allowUploadedArchives` 為 false	檢查 json；確認 operator.admin 權限
日誌 Skipping escaped skill path	symlink 越界	設定 `load.allowSymlinkTargets` 或改為 extraDirs
bundled 技能消失	`allowBundled` 白名單過窄	放寬 allowlist 或 `entries.*.enabled`
sandbox 裡 apiKey not configured	host env 未注入容器	設定 `sandbox.docker.env` 或自訂映像檔
改 SKILL.md 不生效	watch 關閉或同名被高優先級覆蓋	查 precedence；開新工作階段；`load.watch`

[ SECTION_06 ] // PLATFORM_CLOSE 六地節點選型與為什麼 Skills 生產更適合 7×24 遠端 Mac

Skills 安裝本身可在筆電完成，但持續載入、watch 與 ClawHub 同步依賴 Gateway 宿主 7×24 線上。個人 Mac 合蓋後，遠端同事剛裝好的技能在次日工作階段裡「時有時無」，根因是宿主睡眠而非 skill 內容。虛擬化 VPS 雖常線上，對 macOS 原生 brew 安裝器、peekaboo 類 UI 技能與 OpenClaw Node 工具鏈的貼合度往往不如裸金屬 Mac mini；家用寬頻 NAT 與睡眠策略還會讓 ClawHub 拉取在尖峰時段不穩。

六地節點選型（Skills 視角）：① 新加坡／香港——台港團隊 SSH 與 ClawHub 拉取 RTT 較低，適合作為預設技能 staging 節點；② 東京／首爾——日韓客戶資料 residency 要求時，把 ~/.openclaw/skills 與 Workspace 同區存放；③ 美東／美西——對接 GitHub、OpenAI 等美區 API 回程更穩，適合研發 Agent 密集更新 Git 技能；④ 跨區遷移時須打包 skills/ 子樹與 json 快照，勿只 rsync 設定。更多區域對照見六地租期矩陣篇。

若你需要在六地節點中選延遲與租期組合，或從 M4 升級到 M4 Pro 以承載更多全域技能與頻道外掛並存，可在 NOVAKVM 租用價格頁對照梯度，在訂購頁拉起試驗機跑滿兩個迭代週期。對要把 ClawHub 社群技能、私有 zip 與 iOS CI 放在同一維運邊界的工作室而言，NOVAKVM 的 Mac Mini 雲端裸金屬租用通常比湊合家用電腦或混用虛擬化節點更適合承接生產形 OpenClaw Skills。更多遠端連線與備份策略見說明中心；Gateway 健康與外掛頻道進階見 2026.5.x 生產落地篇。