照著清單裝 OpenClaw：2026 全流程安裝配置 Checklist 保姆教程
如果你想邊裝邊確認 OpenClaw 到底有沒有裝好，不要只看終端最後一行。完整安裝至少要過七個檢查點：環境、安裝、初始化、模型、權限、Dashboard、首次任務。本文把 2026 OpenClaw 安裝與配置寫成可執行 checklist——任何一項沒通過，先停在當前層排查，而不是繼續往下做。
等所有檢查項通過，再把 OpenClaw 接入真實目錄、帳號或自動化流程，風險會低很多。先行結論：OpenClaw 的關鍵不是「裝上」，而是每個檢查點都可驗證；跳過模型、權限、端口或日誌檢查，後面很容易把「SSH 沒轉發」誤判成「Gateway 掛了」。
下文每條清單採用統一格式：檢查項 → 為什麼重要 → 通過標準 → 失敗先查。命令與路徑以 OpenClaw 官方安裝文檔 爲準；發佈前請在你本機再跑一遍 openclaw --version 覈對版本差異。安裝路徑選型可參考本站 install.sh、npm 與 Docker 對比文。
先看總清單：七塊驗收地圖
按順序勾選。某一階段未通過時，不要進入下一階段。
| 階段 | 核心驗收 | 關鍵命令 / 路徑 |
|---|---|---|
| ① 安裝前 | Node 22+、端口 18789 空閒、測試目錄與密鑰就緒 | node --version、~/openclaw-workspace |
| ② 安裝 | CLI 可用、來源爲官方、安裝日誌無致命錯誤 | openclaw --version、which openclaw |
| ③ 初始化與模型 | onboard 完成、provider/API Key、預設模型可調用 | openclaw onboard、~/.openclaw/openclaw.json |
| ④ 權限與安全 | 最小工作目錄、密鑰不入庫、Dashboard 不裸暴露 | agents.defaults.workspace |
| ⑤ Dashboard 與服務 | 本機/SSH 轉發可訪問、Gateway 監聽、launchd 正常 | 127.0.0.1:18789、openclaw gateway status |
| ⑥ 首次實戰 | 模型回覆、文件讀寫、日誌可追溯、可回滾 | 測試目錄內 sample.txt |
| ⑦ 交付與維護 | 版本、配置、日誌、入口、回滾方式已記錄 | openclaw doctor、交付表（見文末） |
1. 安裝前檢查
在複製任何 curl | bash 之前完成下表。官方安裝器會檢測系統並可能自動安裝 Node；你仍應提前確認硬體與網路，避免裝到一半才發現端口被佔或 provider 帳號未開通。
| ☐ | 檢查項 | 為什麼重要 | 通過標準 | 失敗先查 |
|---|---|---|---|---|
| ☐ | macOS / 芯片 / 記憶體 | Gateway、本地模型與 Skills 都喫記憶體；記憶體不足會 swap 拖垮響應 | Apple Silicon 或 Intel Mac；建議 ≥16GB 統一記憶體；磁碟預留 ≥10GB | 換輕量模型、關本地 Ollama、或升級機器 |
| ☐ | node --version |
OpenClaw CLI 基於 Node；版本過低會導致安裝或 onboard 失敗 | 輸出 v22.x 或更高（以當前官方文檔爲準） | nvm/fnm 切換版本；或讓官方 install.sh 自動裝 Node |
| ☐ | 端口 18789 空閒 | Dashboard / Control UI 預設監聽 18789；衝突會導致「裝完打不開」 | lsof -nP -iTCP:18789 -sTCP:LISTEN 無輸出，或確認爲舊 OpenClaw 實例 |
結束佔用進程；或 openclaw config set gateway.port <新端口> |
| ☐ | 網路與官方源 | 安裝腳本、npm 與 LLM API 都依賴外網；公司代理常導致半截失敗 | curl -I https://openclaw.ai 與所選 provider 域名可達 |
代理、DNS、防火牆；勿使用來歷不明的第三方一鍵腳本 |
| ☐ | Provider 帳號與 API Key | 沒有可用模型，後面所有「任務成功」都是假象 | 已在 provider 控制台創建 Key；餘額/限額/地區可用性已自行覈對（不寫死數字） | 控制台賬單、模型 ID 拼寫、組織策略 |
| ☐ | 專用測試目錄 | 首次任務必須在隔離目錄跑，避免誤改真實項目 | mkdir -p ~/openclaw-workspace && echo ok > ~/openclaw-workspace/sample.txt |
路徑權限、磁碟只讀卷 |
| ☐ | 備份舊配置（若有） | 重裝或升級可能覆蓋 ~/.openclaw |
tar czf ~/openclaw-backup-$(date +%Y%m%d).tgz ~/.openclaw 2>/dev/null || true |
備份路徑空間、是否誤打包進 git |
2. 安裝過程檢查
推薦兩條官方路徑（二選一，不要混用後不記來源）：
- 一鍵腳本：
curl -fsSL https://openclaw.ai/install.sh | bash - npm 全局：
npm install -g openclaw@latest，然後openclaw onboard --install-daemon
若只要安裝、稍後再向導：curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard。安裝輸出請保存到 ~/openclaw-workspace/install.log，便於排錯。
| ☐ | 檢查項 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 命令來源 | 腳本域名爲 openclaw.ai；npm 包名爲 openclaw；which openclaw 指向預期 prefix |
PATH 衝突、多版本 Node、舊別名 |
| ☐ | CLI 版本 | openclaw --version 輸出版本號且無 command not found |
重裝 npm 全局；SSH 非登錄 shell 的 PATH |
| ☐ | 配置目錄生成 | ls ~/.openclaw/openclaw.json 存在（onboard 後） |
是否跳過 onboard；OPENCLAW_CONFIG_PATH 自定義路徑 |
| ☐ | 雙棧版本一致 | CLI 與 ~/.openclaw/lib 時間戳/版本策略不衝突（大版本升級後必查） |
見本站 CLI 與 Gateway 版本不一致 文 |
| ☐ | 官方三聯驗證 | openclaw --version → openclaw doctor → openclaw gateway status 均可執行 |
doctor 輸出項；daemon 是否安裝 |
3. 初始化與模型配置檢查
運行 openclaw onboard --install-daemon（或安裝腳本自動觸發的嚮導）。--install-daemon 會在 macOS 註冊 LaunchAgent（預設 label 常爲 ai.openclaw.gateway），讓 Gateway 在重啓後仍可用。
| ☐ | 檢查項 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | Provider 與 API Key | Key 寫入 secrets/環境變量，未出現在 shell 歷史或 git；openclaw doctor 無鑑權類 WARN |
變量名、Key 過期、地區限制 |
| ☐ | 預設模型 | openclaw config get 相關模型鍵與嚮導選擇一致；試發一條最小 prompt 有 token 消耗或等價成功響應 |
模型 ID、配額 429、provider 故障頁 |
| ☐ | 本地模型（可選） | 若用 Ollama：本機 ollama list 含目標模型；OpenClaw 路由指向本地 endpoint 且延遲可接受 |
Ollama 未啓動、端口、記憶體 OOM |
| ☐ | 工作區 workspace | agents.defaults.workspace 指向 ~/openclaw-workspace（或你登記的測試目錄） |
配置合併順序、多 profile 衝突 |
| ☐ | Gateway 認證 | 預設要求 token/密碼（gateway.auth.* 或環境變量）；未使用空認證暴露端口 |
openclaw doctor --generate-gateway-token（若文檔支持）；重新 onboard |
4. 權限與安全檢查
OpenClaw Gateway 屬於高權限長期進程。安裝階段就應收斂邊界，而不是等出事再改。
| ☐ | 檢查項 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 最小工作目錄 | 未把 workspace 設爲 ~ 或公司主倉庫根；工具寫文件僅在測試目錄可見 |
改 workspace；exec 審批策略 |
| ☐ | macOS 系統權限 | 僅授予 Skills 必需項（輔助功能、文件、自動化等）；無頭機避免依賴桌面鑰匙串彈窗 | TCC 數據庫、換文件型密鑰 |
| ☐ | 密鑰存放 | ~/.openclaw 權限爲當前用戶可讀；.gitignore 排除 openclaw 配置；永不提交 API Key |
誤提交 → 立即輪換 Key |
| ☐ | 端口暴露 | gateway.bind 爲 loopback（127.0.0.1）或等價；公網訪問必須經 SSH 轉發 / 零信任 / 反代 + 認證 |
誤綁 0.0.0.0；防火牆規則 |
| ☐ | 日誌脫敏 | openclaw logs --follow 抽樣檢查無完整 Key/token；分享日誌前人工脫敏 |
調高日誌級別前先確認脫敏策略 |
5. Dashboard 與服務檢查
Dashboard（Control UI）預設在 http://127.0.0.1:18789。端口解析順序一般爲：--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789。遠程 Mac 上裝完嚮導，在筆記本瀏覽器直接打開 127.0.0.1 會連到筆記本自己——需要 SSH 轉發。詳細排錯見 Dashboard 18789 + SSH + doctor + launchd。
| ☐ | 檢查項 | 通過標準 | 失敗先查 |
|---|---|---|---|
| ☐ | 本機監聽 | lsof -nP -iTCP:18789 -sTCP:LISTEN 有進程；curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/ 返回非 000 |
openclaw gateway restart；端口占用 |
| ☐ | Gateway 狀態 | openclaw gateway status（可加 --deep）顯示運行中；openclaw doctor 無未修復 CRITICAL |
doctor --fix；配置 reload 失敗 |
| ☐ | SSH 遠程訪問 | 筆記本執行 ssh -N -L 18789:127.0.0.1:18789 user@remote-mac 後，本地瀏覽器可開 Dashboard |
SSH 主機是否選對、本地 18789 是否已被佔 |
| ☐ | launchd 後臺 | launchctl list | grep -i openclaw 中 Gateway label 退出碼爲 0；plist 內 PATH 含 node/openclaw |
openclaw gateway install；bootout/bootstrap 重複註冊 |
| ☐ | 日誌流 | openclaw logs --follow 在發起一次測試請求後能看到對應條目 |
日誌路徑配置、磁碟滿 |
6. 首次實戰檢查
在 ~/openclaw-workspace 完成一次端到端任務，驗證「模型 + 工具 + 文件 + 日誌 + 回滾」閉環。
- 測試輸入：在 Dashboard 或 CLI 發送：「讀取
sample.txt，寫一份 3 條要點摘要到summary.md，不要訪問其他目錄。」 - 通過標準：
summary.md生成且內容合理；openclaw logs能對應到該次會話；provider 控制台可見本次調用（若有計費）。 - 回滾：
rm ~/openclaw-workspace/summary.md或git checkout -- .（若目錄在 git 內）；確認 agent 未在 workspace 外留下文件。 - 失敗先查：模型層（401/429）→ 權限/workspace → Gateway 是否重啓 → 日誌中的 tool denied。
7. 失敗項排查索引
某一項打叉時，按 symptom 回到對應層，避免在 Dashboard 層狂改配置，其實根因是 API Key。
| 現象 | 先回到哪一層 | 首要動作 |
|---|---|---|
command not found: openclaw |
② 安裝 | 查 PATH、npm prefix、launchd 環境變量 |
| doctor 報配置/鑑權 WARN | ③ 模型/配置 | openclaw doctor 按提示修復；檢查 ~/.openclaw/openclaw.json |
| 0 tokens / 模型無響應 | ③ 模型 | 驗證 Key、模型名、provider 狀態頁 |
| Dashboard 連不上 | ⑤ 服務/網路 | 遠端 curl 127.0.0.1:18789；SSH -L；是否誤綁 loopback |
| RPC probe failed / 端口占用 | ⑤ 服務 | lsof -i :18789；openclaw gateway --force（調試時） |
| 重啓後 Gateway 不起來 | ⑤ launchd | launchctl list；openclaw gateway install；Console 崩潰日誌 |
| CLI 新、Gateway 舊 | ② 安裝 + ⑤ 服務 | 同步 ~/.openclaw/lib 與 npm；冷重啓 LaunchAgent |
8. 安裝完成交付清單
團隊交接或一個月後你自己回來看，靠這張表就能快速恢復上下文（請把敏感項存密碼管理器，表中只寫「已配置」）。
| 交付項 | 記錄內容（示例） |
|---|---|
| 版本 | openclaw --version 輸出；安裝日期 2026-05-27 |
| 配置位置 | ~/.openclaw/openclaw.json；若有 OPENCLAW_CONFIG_PATH 寫絕對路徑 |
| 日誌位置 | openclaw logs 指向路徑；launchd StandardOutPath（若自定義 plist） |
| 訪問入口 | 本機 http://127.0.0.1:18789；遠程 ssh -L 18789:127.0.0.1:18789 … |
| 測試目錄 | ~/openclaw-workspace |
| 回滾方式 | 配置備份 tgz 路徑；openclaw gateway stop；移除 LaunchAgent label |
9. 完成後的維護清單
- ☐ 大版本升級前：
tar備份~/.openclaw，升級後跑openclaw doctor+openclaw gateway restart - ☐ 每月：在 provider 控制台覈對用量與限額；輪換長期 API Key
- ☐ 日誌輪轉：避免
~/.openclaw撐滿磁碟；按需歸檔openclaw logs輸出 - ☐ 安全：禁止將 18789 直接映射到公網；定期
openclaw security audit（若版本提供） - ☐ 變更後複驗：重複本文「⑤ Dashboard」+「⑥ 首次實戰」各一項
全部階段打勾後，再接入 Telegram/Slack、Skills 鏈或 CI。若需官方 App 與 CLI 雙網關並存，繼續讀 macOS 官方 App 與 Gateway 外置決策表。
在 Mac mini 上按清單驗收，更穩也更安靜
OpenClaw 的 Gateway、LaunchAgent 與 Dashboard 都偏愛長期在線、低抖動的環境。macOS 原生支援 launchd、Unix 工具鏈與 SSH 端口轉發，無需 WSL 即可按本文清單逐項打勾；Apple Silicon Mac mini 待機功耗可維持在很低水平，適合作爲 7×24 的 agent 節點，把試錯限制在 ~/openclaw-workspace，與主力 MacBook 的個人數據隔離。
同價位小型 PC 往往風扇與功耗更高，而 macOS 的 Gatekeeper、SIP 與 FileVault 能降低惡意軟體與誤配置風險。若你正按 checklist 安裝 OpenClaw，Mac mini M4 是目前性價比很高的專用主機——現在即可入手，讓清單裡的端口監聽、doctor 與首次任務在穩定硬體上一次性通過。