導讀

第一次裝 OpenClaw，卡住你的往往不是「不會複製命令」，而是不知道每一步在驗證什麼。終端沒報錯、Dashboard 能打開、模型能回答、文件能寫入——這是四個不同檢查點。本文按準備 → 安裝 → 配置 → 權限 → Dashboard → 首次測試一條主線走完，失敗時知道去哪看日誌。

〇 這篇教學會幫你完成什麼

跟完本文，你應能確認四件事：① CLI 與 Gateway 已安裝；② 模型 provider 與 API Key 已連通；③ 瀏覽器能打開本機 Control UI；④ 在測試目錄裡完成一次低風險讀寫。目標不是「裝上了」，而是「在可控範圍內能工作，且出錯能自查」。

4步
核心檢查點：CLI / 模型 / UI / 文件
5分
官方文檔寫的最短上手時間
1個
建議先隔離的測試工作目錄

一 安裝前準備：Mac、網路與測試目錄

做什麼：在動手前把環境湊齊。為什麼：缺一項會在中途反覆試錯。成功標誌：你能打開終端、訪問 官方安裝文檔，並已在桌面建好測試文件夾。

  • 系統 — macOS（Apple Silicon 或 Intel 均可）。官方要求 Node 24（推薦）或 Node 22.19+；用官方安裝腳本時會自動處理 Node，不必提前折騰 Homebrew（可選）。
  • 網路與權限 — 能訪問 openclaw.ai 與模型服務商；安裝與寫配置需要本機管理員密碼（改系統設定、LaunchAgent 時）。
  • 模型帳號 — 在 Anthropic、OpenAI、OpenRouter 等任選一家註冊，拿到 API Key（模型服務憑證，相當於密碼，勿分享、勿提交 Git）。
  • 測試目錄 — 例如 ~/openclaw-test，裡面放一份 notes.txt。工作目錄即 Agent 允許操作的範圍，第一次只開這裡。
失敗先查：網頁打不開 → 網路/DNS；沒有管理員密碼 → 換有權限的 macOS 用戶。新手不要做：關閉 Gatekeeper/SIP/防火牆、運行來歷不明的「一鍵腳本」、把 API Key 貼進公開倉庫。

二 安裝：只用官方來源，並保存輸出

做什麼：安裝 OpenClaw CLI 與 Gateway。為什麼：非官方包可能被篡改。成功標誌：openclaw --version 有版本號。

Mac 推薦（會自動檢測系統、安裝 Node、啟動引導）：

curl -fsSL https://openclaw.ai/install.sh | bash

若你已自行管理 Node，也可用：npm install -g openclaw@latest，然後執行 openclaw onboard --install-daemon（安裝 macOS 後台服務 LaunchAgent）。

安裝結束後請保存終端裡的版本號與完整輸出（截圖或複製到備忘錄），報錯時對照官方 Troubleshooting。驗證三連：

openclaw --version · openclaw doctor · openclaw gateway status

若提示 openclaw: command not found，把 $(npm prefix -g)/bin 加入 ~/.zshrc 的 PATH，重開終端再試（見官方說明）。

三 配置：provider、API Key 與配置文件

幾個詞先對齊（不展開成百科）：模型 provider 是哪家雲服務（如 Anthropic）；API Key 是訪問憑證；環境變量 是終端裡的臨時配置（如 export ANTHROPIC_API_KEY=...）；配置文件 是持久設置，預設在 ~/.openclaw/openclaw.json（JSON5 格式）；本地模型 指在本機跑 Ollama 等——新手第一次用雲端 Key 即可，不必強行上本地推理。

運行引導向導（按提示選 provider、貼上 Key、選預設模型）：

openclaw onboard --install-daemon

成功標誌：openclaw doctor 無阻塞性報錯；在 Dashboard 或 CLI 裡發一句「你好」能收到模型回覆。失敗先查：Key 是否複製完整、帳戶餘額/限額、本機代理是否攔截 HTTPS。

四 權限：第一次只開放測試目錄

做什麼：限制 Agent 能讀寫的路徑，並謹慎對待 macOS 彈窗。為什麼：全盤授權等於把整臺 Mac 交給自動化工具。成功標誌：測試任務只能在 ~/openclaw-test 內創建/修改文件。

系統設定裡的「文件與文件夾」「自動化」「輔助功能」等名稱會隨 macOS 版本變化——以你屏幕上爲準逐項核對。建議：

  • 只勾選測試目錄，不要一開始給「整個磁盤」或 iCloud 根目錄。
  • 日曆、通訊錄、屏幕錄製等與首次跑通無關的權限先拒絕，需要時再開。
  • 不要把 Gateway 端口暴露到公網；家庭網路保持本機或 VPN 訪問即可。

五 打開 Dashboard：本機地址與遠端 Mac

做什麼：用瀏覽器打開 Control UI。為什麼：可視化確認 Gateway 在跑、會話正常。成功標誌：頁面能加載且可發消息。

終端執行 openclaw dashboard，或瀏覽器訪問官方預設地址 http://127.0.0.1:18789/（僅本機）。

現象更可能原因先做什麼
無法連接Gateway 未啟動openclaw gateway status，必要時 openclaw onboard --install-daemon
本機能開、別的機器不行只監聽了 127.0.0.1遠端 Mac 用 SSH 轉發：ssh -L 18789:127.0.0.1:18789 user@mac，再在本地瀏覽器打開上述地址
地址對仍白屏瀏覽器緩存/插件換 Safari 無痕窗口，或禁用廣告攔截後重試

日誌是排錯證據：Gateway 異常時結合 openclaw doctor 輸出與官方 Help / Troubleshooting 對照，不要憑感覺改配置。

六 首次運行：低風險測試任務

在 ~/openclaw-test/notes.txt 寫兩行字，例如「專案代號：Alpha」。在 Dashboard 或 CLI 發送：

請讀取 openclaw-test 目錄下的 notes.txt，用三句話總結，並把 summary.md 寫在同一目錄。

算跑通的標準：① 模型回覆內容與文件一致；② 目錄裡出現 summary.md；③ openclaw doctor 仍正常；④ 日誌裡有對應請求記錄（非空）。若寫入失敗，先看 macOS 是否拒絕文件訪問，而不是先懷疑模型「變笨」。

七 新手常見錯誤速查

①

command not found

PATH 未包含 npm 全局 bin → 改 ~/.zshrc 後重開終端。

②

API Key 無效 / 401

重新生成 Key，確認 provider 與 onboard 選項一致，檢查是否多了空格。

③

Dashboard 打不開

先 gateway status，再查端口與是否用錯機器（本機 vs 遠端）。

④

權限拒絕 / 寫不進文件

系統設定 → 隱私與安全性 → 給終端或 OpenClaw 相關進程開測試目錄，勿全盤授權。

完成後下一步

測試案例通過後，再逐步接入真實專案目錄、Telegram/Slack 等頻道、日曆或提醒事項。每擴一步，重複「小範圍試 → 看日誌 → 再放大」。

  1. 1把允許目錄從測試文件夾擴到一個真實但非生產的 repo
  2. 2在 openclaw.json 裡加頻道白名單（如 allowFrom）
  3. 3需要 24/7 時確認 LaunchAgent 開機自啟，定期 openclaw doctor

八 在 Mac mini 上跑 OpenClaw 更省心

OpenClaw 是自託管 Gateway：要長期在線、又要控制權限邊界，放在主力 MacBook 上容易和日常辦公搶資源。Mac mini M4 體積小、待機功耗約 4W 級、適合靜默 24/7；macOS 原生 Unix 環境讓官方安裝腳本、LaunchAgent 守護與 SSH 遠端維護都更順；Gatekeeper、SIP 與 FileVault 也便於把 Agent 限制在專用帳戶與測試目錄裡。若你打算把 OpenClaw 當成家庭或小團隊的常駐節點，Mac mini M4 是目前性價比很清晰的硬體起點——先在本機跑通測試案例，再把它遷到專用 Mac mini 上長期運行。現在正是入手 Mac mini M4、把這套自託管工作流穩定下來的好時機。

OpenClaw 常駐 · 低功耗 24/7
zuvcloud · Mac 專屬雲

獲取 Mac mini，搭建你的 OpenClaw 節點

分鐘級開通 · 遠端 SSH · 穩定網路 · 適合自託管 AI Gateway 與 Dashboard 長期運行。

立即獲取