Mac mini 完整安裝流程

從開箱到 24/7 運作 — 在 Mac mini 上部署 OpenClaw 的完整七步驟指南

這是 Mac mini 上安裝 OpenClaw 的完整流程。從系統初始化到設定開機自啟，七個步驟走完，你的 AI Agent 就能 24/7 運作。

全程大約需要 30-45 分鐘。如果你已經完成安裝前準備，會更快。

Step 1：系統初始化

更新 macOS

確保你的 macOS 是最新版本。開啟 系統設定 → 一般 → 軟體更新，安裝所有可用更新。

或者用指令：

softwareupdate --install --all

如果需要重新開機，先完成更新再繼續。OpenClaw 需要 macOS 13 (Ventura) 以上，但我們推薦 macOS 14+ (Sonoma)。

安裝 Homebrew

Homebrew 是 macOS 上的套件管理器，後面安裝 cloudflared 會用到。

你的 macOS 帳號必須是**管理員（Administrator）**才能安裝 Homebrew。確認方式：系統設定 → 使用者與群組，你的帳號旁邊應該標示「管理者」。如果不是管理員，Homebrew 安裝會直接失敗。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安裝完成後，根據終端機提示將 Homebrew 加入 PATH：

# Apple Silicon (M1/M2/M3/M4)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 驗證
brew --version

確保 Terminal 能找到指令

這是最常見的安裝卡關點。 Homebrew 和 NVM 的安裝腳本會把 PATH 寫入 ~/.zprofile，但 macOS Terminal.app 開啟的是互動式 shell，預設只讀 ~/.zshrc。結果就是：安裝都成功了，但開 Terminal 執行 openclaw 卻得到 command not found。

請確認以下內容也存在於 ~/.zshrc：

# 加入 ~/.zshrc（如果還沒有的話）
echo '' >> ~/.zshrc
echo '# Homebrew' >> ~/.zshrc
echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> ~/.zshrc
echo '' >> ~/.zshrc
echo '# NVM' >> ~/.zshrc
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc

設定完成後，關閉並重新開啟 Terminal，然後驗證：

brew --version
nvm --version

如果兩個指令都有正確輸出，PATH 設定就沒問題了。

安裝 Node.js 22+（透過 nvm）

如果你還沒安裝 nvm 和 Node.js，參考安裝前準備。已經裝好的話，確認版本：

node --version
# 應該是 v22.x.x 或更新

npm --version
# 應該是 10.x.x 或更新

Step 2：安裝 OpenClaw

一行指令：

npm install -g openclaw@latest

驗證安裝成功：

openclaw --version

你應該會看到版本號。如果出現 command not found，確認 npm 的全域路徑在你的 PATH 中：

# 檢查 npm 全域安裝路徑
npm config get prefix

# 確認該路徑的 bin 目錄在 PATH 中
echo $PATH

不要用 sudo npm install -g — 如果你需要 sudo 才能全域安裝，代表 npm 的權限設定有問題。用 nvm 安裝的 Node.js 不需要 sudo。

Step 3：初始設定（Onboarding）

執行 onboarding 精靈，它會引導你完成所有初始設定：

openclaw onboard --install-daemon

這個指令會依序要求你設定：

設定 AI Model

? Select your AI provider: Anthropic (Claude)

接下來會出現三個選項 — 選擇 Anthropic Token（第一個選項），不是 Anthropic API。

? Enter your Claude Token: [貼上你的 Token]

輸入你在安裝前準備中取得的 Claude Token。

注意：Claude Token 複製時很容易帶到尾端的空格，會導致 HTTPS 錯誤。貼上之後請確認沒有多餘的空格。如果 onboarding 過程中遇到 HTTPS 錯誤，幾乎都是這個原因 — 重新貼一次去掉空格就好。

認證檔案在哪裡？

openclaw onboard 會自動建立兩個層級的認證設定：

~/.openclaw/openclaw.json 的 auth.profiles：宣告你用哪些 provider 和認證模式
~/.openclaw/agents/main/agent/auth-profiles.json：儲存實際的 Token 和 API Key

如果你需要手動遷移設定到另一台機器，兩個檔案都要複製。只複製 openclaw.json 會導致 No API key found 錯誤。

選擇預設模型

? Select default model: claude-sonnet-4-20250514

我們推薦 Claude Sonnet 作為預設模型 — 速度和品質的最佳平衡。需要更強推理能力時可以在個別 Agent 中切換到 Opus。

設定 Gateway Token

? Set your Gateway Token: [自動產生或手動輸入]

Gateway Token 是你存取 Dashboard 和 API 的認證金鑰。系統會自動產生一組，你也可以自己指定。務必記下這個 Token — 之後登入 Dashboard 需要用到。

--install-daemon flag 會同時安裝背景執行的 daemon。如果你之後要手動設定 launchd（Step 6），可以先省略這個 flag，只執行 openclaw onboard。

Step 4：啟動 Gateway

設定 Gateway 模式

在啟動之前，需要先設定 Gateway 的運行模式：

openclaw config set gateway.mode local

如果跳過這一步，執行 openclaw gateway 時會得到：

Gateway start blocked: set gateway.mode=local (current: unset)

即使之後要透過 Cloudflare Tunnel 對外，仍然選 local — 這是指 Gateway 的運行模式，不是網路存取範圍。

啟動

# 推薦：以服務方式啟動（自動建立開機自啟）
openclaw gateway start

# 或者：前台運行（適合 debug，Ctrl+C 停止）
openclaw gateway

openclaw gateway start 會以背景服務方式啟動，並自動建立 LaunchAgent（開機自啟）。如果你用 gateway start，Step 6 的 launchd 設定可以跳過 — 它已經幫你做好了。

第一次啟動會看到初始化訊息。等到看到類似以下輸出，代表 Gateway 已就緒：

[Gateway] Listening on http://127.0.0.1:18789
[Gateway] Dashboard available at http://127.0.0.1:18789/

開啟另一個終端機視窗，確認狀態：

openclaw status

你應該看到 Gateway 狀態為 running。

存取 Dashboard

打開瀏覽器，前往：

http://127.0.0.1:18789/

輸入你在 Step 3 設定的 Gateway Token 登入。你會看到 OpenClaw 的 Web Dashboard — 這是你管理 Agent、頻道、設定的主要介面。

此時 Dashboard 只能從本機存取（127.0.0.1）。要從外部存取，需要設定 Cloudflare Tunnel（Step 5）。

Step 5：設定 Cloudflare Tunnel

Cloudflare Tunnel 讓你不用開放任何 port，就能讓外部服務（LINE Webhook、Telegram Bot API 等）連到你的 Gateway。

安裝 cloudflared

brew install cloudflared

登入 Cloudflare

cloudflared tunnel login

瀏覽器會自動開啟，選擇你要使用的網域並授權。

建立 Tunnel

cloudflared tunnel create openclaw

記下輸出中的 Tunnel ID（一串 UUID），後面會用到。

設定 DNS

將你想要的子網域指向 Tunnel：

cloudflared tunnel route dns openclaw agent.yourdomain.com

把 agent.yourdomain.com 換成你自己的子網域。

建立設定檔

mkdir -p ~/.cloudflared

建立 ~/.cloudflared/config.yml：

tunnel: <你的 Tunnel ID>
credentials-file: /Users/<你的使用者名稱>/.cloudflared/<Tunnel ID>.json

ingress:
  - hostname: agent.yourdomain.com
    service: http://localhost:18789
  - service: http_status:404

啟動 Tunnel

cloudflared tunnel run openclaw

驗證外部存取

從手機或其他裝置打開：

https://agent.yourdomain.com

如果看到 OpenClaw Dashboard 登入頁面，Tunnel 設定成功。

DNS 傳播需要時間。如果子網域解析失敗，等幾分鐘再試。通常 Cloudflare 自家的 DNS 記錄幾秒內就會生效，但如果你用其他 DNS 解析器（如 ISP 預設的），可能需要等更久。

Step 6：設定 launchd 開機自啟

Mac mini 偶爾會因為 macOS 更新、停電、或其他原因重新開機。launchd 確保 OpenClaw 和 cloudflared 在開機後自動啟動。

OpenClaw Gateway 的 plist

建立 ~/Library/LaunchAgents/com.openclaw.gateway.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<你的使用者名稱>/.nvm/versions/node/v22.0.0/bin/node</string>
        <string>/Users/<你的使用者名稱>/.nvm/versions/node/v22.0.0/bin/openclaw</string>
        <string>gateway</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/openclaw-gateway.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/openclaw-gateway-error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
    </dict>
</dict>
</plist>

注意替換 <你的使用者名稱> 和 Node.js 版本路徑。用 which openclaw 和 which node 確認實際路徑。如果你在 Step 3 使用了 --install-daemon，這個 plist 可能已經自動建立 — 用 launchctl list | grep openclaw 確認。

載入服務

launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

Cloudflare Tunnel 的 plist

cloudflared 有內建的服務安裝指令：

cloudflared service install

這會自動建立 launchd plist 並載入。

驗證自動啟動

重新開機測試是最可靠的驗證方式：

sudo reboot

開機後，檢查兩個服務是否都在運作：

# 檢查 OpenClaw
openclaw status

# 檢查 cloudflared
launchctl list | grep cloudflared

Step 7：驗證一切正常

完整狀態檢查

openclaw status --all

這個指令會輸出所有元件的狀態，包含 Gateway、已設定的頻道、API Key 狀態等。

從外部發送測試訊息

如果你已經設定了通訊頻道（LINE、Telegram 等），從手機發一條訊息給你的 Bot。如果還沒設定頻道，先確認 Dashboard 可以從外部網址存取。

檢查日誌

openclaw logs --follow

觀察日誌輸出，確認沒有錯誤訊息。按 Ctrl+C 停止追蹤。

常見安裝問題

HTTPS 錯誤 / Token 認證失敗

這是最常見的安裝問題。原因幾乎都是 Claude Token 複製時帶了尾端空格。

解法：

重新執行 claude setup-token
仔細複製 Token，確認前後沒有多餘空格
重新執行 onboarding：openclaw onboard

如果問題持續，在終端機中手動檢查 Token：

# 檢查 Token 是否有多餘空格
echo -n "你的Token" | xxd | tail -1
# 最後不應該有 '20'（空格的 hex 值）

Node.js 版本不對

Error: OpenClaw requires Node.js >= 22

解法：

nvm install 22
nvm use 22
nvm alias default 22
# 重新安裝 OpenClaw
npm install -g openclaw@latest

Gateway 啟動失敗（port 被佔用）

Error: listen EADDRINUSE: address already in use :::18789

解法：

# 找出佔用 port 的程序
lsof -i :18789

# 如果是舊的 openclaw 程序，停止它
openclaw gateway stop

# 或直接終止程序
kill -9 <PID>

cloudflared 連線失敗

ERR Unable to establish connection

解法：

確認 ~/.cloudflared/config.yml 的 Tunnel ID 和 credentials-file 路徑正確
確認你已經執行過 cloudflared tunnel login
確認 DNS 記錄已建立：cloudflared tunnel route dns openclaw agent.yourdomain.com
檢查 Cloudflare Dashboard 中的 Tunnel 狀態

launchd 服務沒有自動啟動

診斷：

# 檢查服務狀態
launchctl list | grep openclaw

# 如果沒有出現，重新載入
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 檢查錯誤日誌
cat /tmp/openclaw-gateway-error.log

常見原因：

plist 中的執行檔路徑不正確（Node.js 升級後路徑會變）
環境變數 PATH 不包含 nvm 的路徑
plist 檔案權限不正確（應該是 644）

chmod 644 ~/Library/LaunchAgents/com.openclaw.gateway.plist

透過 SSH 遠端安裝？

很多人會透過 SSH 連線到 Mac mini（headless 模式）進行安裝。注意以下幾點：

使用 -tt 強制分配 TTY：ssh -tt user@host，否則互動式精靈無法正常運作
SSH 的 shell 環境和本機 Terminal 不同：SSH 使用 login shell（讀 ~/.zprofile），本機 Terminal 使用 interactive shell（讀 ~/.zshrc）。如果 SSH 中一切正常但本機操作失敗，請確認 Step 1 的 .zshrc PATH 設定

非互動式 onboarding：如果互動式精靈有問題，可以用非互動模式：

# 設定 Anthropic Token
openclaw onboard --non-interactive --accept-risk \
  --auth-choice token \
  --anthropic-token "sk-ant-..."

Unsupported channel 錯誤

如果執行 openclaw channels login --channel <name> 時得到 Unsupported channel 錯誤，這通常不是 plugin 問題，而是 PATH 沒有正確載入。

which openclaw
# 應該顯示 ~/.nvm/versions/node/v22.x.x/bin/openclaw

openclaw plugins list
# 確認你需要的 channel 顯示為 loaded 狀態

如果 which openclaw 顯示 not found，請回到 Step 1 確認 .zshrc 的設定。

GetClaw 觀點

Mac mini 安裝看似簡單，但 Cloudflare Tunnel 穩定性、launchd 設定、斷電恢復... 這些細節決定了你的 Agent 是「偶爾能用」還是「24/7 穩定運作」。

我們見過太多人在 Step 4 就覺得「搞定了」，然後第一次停電或 macOS 更新後才發現 Agent 靜悄悄地停了。Step 5 和 Step 6 才是真正讓你的 Mac mini 從「開發機」變成「伺服器」的關鍵。

如果你想要有人幫你把這些細節都處理好，包含 UPS 斷電保護、自動重連、健康監控通知 — 這正是 GetClaw 部署服務在做的事。

Mac mini 完整安裝流程

On this page