Openclaw 新手安裝 | Mac OS 使用者，Docker 隔離版本

OpenClaw 安裝教學（macOS・Docker 隔離版）

適用對象：已經在使用 Mac 的一般使用者，想在不影響原有系統的前提下，安全安裝 OpenClaw
最後更新：2026-02-14
預計時間：約 40–60 分鐘（含下載等待）

📋 你完成後會得到什麼

/Users/<你的使用者名稱>/
│
├── .openclaw/                          [主工作目錄]
│   ├── 🔒 credentials/                [API key、token]
│   ├── 🔒 agents/                     [Session 狀態]
│   │   └── main/
│   │       └── sessions/
│   ├── 🔒 workspace/                  [工作檔案]
│   │   ├── .git/                      (版本控制)
│   │   └── memory/                    (MEMORY.md、日誌)
│   ├── 🔒 logs/                       [執行日誌]
│   ├── 🔒 telegram/                   [Bot 設定]
│   │
│   ├── cron/                          [定時任務]
│   ├── devices/                       [設備配對]
│   ├── identity/                      [身份設定]
│   ├── canvas/                        [畫布數據]
│   ├── completions/                   [自動完成]
│   │
│   ├── openclaw.json                  ← 主設定檔
│   ├── openclaw.json.bak*             ← 備份設定
│   └── update-check.json
│
└── docker/                            [備份目錄]
    ├── openclaw-backup.sh             ← 每日備份腳本
    └── openclaw-data/                 [每日備份]
        ├── credentials_*/             ← 敏感資料備份（時間戳記）
        ├── workspace_*/               ← 工作檔案備份
        ├── agents_*/                  ← Session 備份
        ├── logs/                      ← 備份執行日誌
        └── backups/                   ← 手動備份位置（預留）

🔒 權限分布：

私密區域（700，只有你能讀寫）：credentials、agents、workspace、logs、telegram、openclaw-data
公開讀取（755，但只有你能寫）：cron、devices、identity、canvas、completions

階段一：安裝 Homebrew（macOS 套件管理器）

做什麼：Homebrew 是 macOS 的「App Store for 開發者」，之後裝 Node.js 都靠它。

步驟 1-1：安裝 Homebrew

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

⏳ 安裝過程中會要求你輸入 Mac 登入密碼（輸入時畫面不會顯示字元，這是正常的）。
整個過程大約 2–5 分鐘。

步驟 1-2：設定 PATH（Apple Silicon M1/M2/M3/M4 必做）

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

做什麼：告訴系統「去哪裡找 brew 指令」。寫在 ~/.zprofile 是最乾淨的做法。

步驟 1-3：讓設定立刻生效

eval "$(/opt/homebrew/bin/brew shellenv)"

步驟 1-4：重新整理指令快取

hash -r

✅ 測試點：確認 Homebrew 安裝成功

brew -v

你應該看到：Homebrew x.x.x（版本號）
如果看到 command not found：回到步驟 1-2 重做

步驟 1-5：（選做）關閉 Homebrew 匿名統計

做什麼：Homebrew 預設會回傳匿名使用統計。如果你在意隱私，可以關閉。

brew analytics off

驗證已關閉：

brew analytics

你應該看到：Analytics are disabled.

階段二：安裝 Node.js

做什麼：OpenClaw 是用 JavaScript/Node.js 寫的，需要 Node.js 執行環境。

步驟 2-1：檢查是否已經有 Node.js

node --version

如果看到版本號（例如 v22.x.x）：跳到步驟 2-3 驗證路徑
如果看到 command not found：繼續步驟 2-2

步驟 2-2：用 Homebrew 安裝 Node.js

brew install node

⏳ 大約 1–3 分鐘。

✅ 測試點：驗證 Node.js 和 npm 路徑與版本

做什麼：確認系統使用的是 Homebrew 安裝的 Node.js，而非其他來源（避免日後衝突）。

which node

你應該看到：/opt/homebrew/bin/node

node -v

你應該看到：v22.x.x 或更高

which npm

你應該看到：/opt/homebrew/bin/npm

npm -v

你應該看到：10.x.x 或更高

⚠️ 重要提醒

如果你之前裝過 nvm（Node Version Manager），請不要混用。用 brew node 就夠了。混用會導致 OpenClaw 的背景服務（daemon）日後找不到正確的 Node.js 路徑。

階段三：安裝 OpenClaw

步驟 3-1：用 npm 全域安裝 OpenClaw

npm install -g openclaw@latest

✅ 測試點：確認 OpenClaw 安裝成功

openclaw --version

你應該看到：版本號（例如 0.x.x）

階段四：健康檢查

做什麼：讓 OpenClaw 自我診斷，確認所有依賴都就緒。

步驟 4-1：執行健檢

openclaw doctor

過程中會問：
Enable zsh shell completion for openclaw?
建議選 Yes — 之後打指令可以按 Tab 自動補全，少打字、少打錯。

階段五：啟動設定精靈（Onboarding + Daemon）

做什麼：這一步會引導你設定 API 金鑰、模型、Telegram Bot 等等，並安裝背景服務。

步驟 5-1：啟動設定精靈

openclaw onboard --install-daemon

以下是精靈會問你的重要設定，逐一說明：

🔧 設定 A：API Provider 與 Model

做什麼：選擇你要用哪家 AI 服務商和哪個模型。

如果你使用 OpenRouter（建議初學者用）：

設定項目	建議填寫
Provider	`openrouter`
API Key	你在 OpenRouter 網站取得的金鑰（格式如 `sk-or-v1-xxxx...`）
Default model	`openrouter/auto`（最省事，自動選模型）

⚠️ 不要把 default model 填成 anthropic/... 卻沒設定 Anthropic 的 API key，否則會出現警告：
No auth configured for provider "anthropic"

🔧 設定 B：Telegram Bot

做什麼：讓你的 Bot 可以在 Telegram 上回覆你。

B-1：取得 Bot Token

在 Telegram 搜尋 @BotFather
傳送 /newbot
輸入 Bot 顯示名稱（例如：我的AI助手）
輸入 Bot username（必須唯一，例如：MyAIHelper2026Bot）
BotFather 會回覆一串 Token，複製它

⚠️ 注意：如果你貼的是舊 Token，會連到舊的 Bot（不是新建的）。

B-2：設定 allowFrom

精靈會問：

Telegram allowFrom (username or user id)

強烈建議：填你的 user id（純數字），比 @username 更穩定、不會因為改名而失效。
取得 user id 的方法：在 Telegram 搜尋 @userinfobot，傳 /start，它會回覆你的 ID。

🔧 設定 C：Skills（技能模組）

精靈會問：

Configure skills now? (recommended)

建議先裝這兩個就好（低風險、最實用）：

Skill	用途
`summarize`	摘要、整理文件和輸出
`model-usage`	查看 API 用量和統計（省錢必備）

其他 skill 先不急，用到再補。看到「缺 XX 個 requirements」是正常的。

🔧 設定 D：Hooks（自動化鉤子）

精靈會問：

Enable hooks?

新手建議勾選：

Hook	說明	Token 影響
`boot-md`	每次啟動載入固定的上下文	微量（可接受）
`command-logger`	記錄你執行過的指令	幾乎不影響

⚠️ session-memory 會持續累積上下文，可能耗 token 也有隱私考量 → 等你熟悉後再開。

🔧 設定 E：Hatch（孵化方式）

精靈會問：

How do you want to hatch your bot?

建議選：Hatch in TUI (recommended)
理由：最穩、適合貼 log 和長內容，像是工程控制台。

階段六：首次配對與測試（Telegram）

步驟 6-1：在 Telegram 找到你的 Bot

搜尋你剛才建立的 Bot username（例如 @MyAIHelper2026Bot）

步驟 6-2：啟動對話

傳送：

/start

步驟 6-3：配對

如果畫面出現 pairing code，照 TUI 端的指示輸入或 approve 即可。

✅ 測試點：傳一句話測試

你好

你應該看到：Bot 回覆你（內容由 AI 模型產生）
如果沒回覆：檢查 TUI 畫面是否有錯誤訊息

階段七：設定目錄權限（安全加固）

做什麼：確保敏感資料只有你本人能存取。

步驟 7-1：鎖定私密目錄（700 = 只有你能讀寫）

chmod 700 ~/.openclaw/credentials

chmod 700 ~/.openclaw/agents

chmod 700 ~/.openclaw/workspace

chmod 700 ~/.openclaw/logs

chmod 700 ~/.openclaw/telegram

步驟 7-2：設定公開目錄（755 = 別人可讀，但只有你能寫）

chmod 755 ~/.openclaw/cron

chmod 755 ~/.openclaw/devices

chmod 755 ~/.openclaw/identity

chmod 755 ~/.openclaw/canvas

chmod 755 ~/.openclaw/completions

✅ 測試點：驗證權限

ls -la ~/.openclaw/

你應該看到：
credentials、agents、workspace、logs、telegram 顯示 drwx------（700）
cron、devices、identity、canvas、completions 顯示 drwxr-xr-x（755）

階段八：建立每日自動備份系統

做什麼：每天凌晨自動備份重要資料，保留 30 天，超過自動清理。

步驟 8-1：建立備份資料夾結構

mkdir -p ~/docker/openclaw-data/logs

mkdir -p ~/docker/openclaw-data/backups

步驟 8-2：鎖定備份資料夾權限

chmod 700 ~/docker/openclaw-data

步驟 8-3：建立備份腳本

cat > ~/docker/openclaw-backup.sh << 'BACKUP_SCRIPT'
#!/bin/bash
# ============================================
# OpenClaw 每日自動備份腳本
# 功能：備份 credentials、workspace、agents
# 保留：30 天，超過自動清理
# ============================================

# --- 設定 ---
OPENCLAW_DIR="$HOME/.openclaw"
BACKUP_DIR="$HOME/docker/openclaw-data"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
LOG_FILE="$BACKUP_DIR/logs/backup_${TIMESTAMP}.log"

# --- 開始備份 ---
echo "=== OpenClaw 備份開始：$(date) ===" > "$LOG_FILE"

# 備份 credentials（API key、token）
if [ -d "$OPENCLAW_DIR/credentials" ]; then
    cp -R "$OPENCLAW_DIR/credentials" "$BACKUP_DIR/credentials_${TIMESTAMP}/"
    chmod 700 "$BACKUP_DIR/credentials_${TIMESTAMP}/"
    echo "[OK] credentials 已備份" >> "$LOG_FILE"
else
    echo "[略過] credentials 目錄不存在" >> "$LOG_FILE"
fi

# 備份 workspace（工作檔案 + MEMORY.md）
if [ -d "$OPENCLAW_DIR/workspace" ]; then
    cp -R "$OPENCLAW_DIR/workspace" "$BACKUP_DIR/workspace_${TIMESTAMP}/"
    chmod 700 "$BACKUP_DIR/workspace_${TIMESTAMP}/"
    echo "[OK] workspace 已備份" >> "$LOG_FILE"
else
    echo "[略過] workspace 目錄不存在" >> "$LOG_FILE"
fi

# 備份 agents（Session 狀態）
if [ -d "$OPENCLAW_DIR/agents" ]; then
    cp -R "$OPENCLAW_DIR/agents" "$BACKUP_DIR/agents_${TIMESTAMP}/"
    chmod 700 "$BACKUP_DIR/agents_${TIMESTAMP}/"
    echo "[OK] agents 已備份" >> "$LOG_FILE"
else
    echo "[略過] agents 目錄不存在" >> "$LOG_FILE"
fi

# --- 清理 30 天以上的舊備份 ---
echo "--- 清理 30 天前的舊備份 ---" >> "$LOG_FILE"
find "$BACKUP_DIR" -maxdepth 1 -name "credentials_*" -type d -mtime +30 -exec rm -rf {} \; 2>> "$LOG_FILE"
find "$BACKUP_DIR" -maxdepth 1 -name "workspace_*" -type d -mtime +30 -exec rm -rf {} \; 2>> "$LOG_FILE"
find "$BACKUP_DIR" -maxdepth 1 -name "agents_*" -type d -mtime +30 -exec rm -rf {} \; 2>> "$LOG_FILE"
find "$BACKUP_DIR/logs" -name "backup_*.log" -mtime +30 -delete 2>> "$LOG_FILE"
echo "[OK] 舊備份清理完成" >> "$LOG_FILE"

echo "=== OpenClaw 備份完成：$(date) ===" >> "$LOG_FILE"
BACKUP_SCRIPT

步驟 8-4：讓腳本可執行

chmod +x ~/docker/openclaw-backup.sh

✅ 測試點：手動跑一次備份

bash ~/docker/openclaw-backup.sh

確認備份成功：

ls ~/docker/openclaw-data/

你應該看到：credentials_日期、workspace_日期、agents_日期 等資料夾

cat ~/docker/openclaw-data/logs/backup_*.log

你應該看到：每個項目顯示 [OK] 已備份

步驟 8-5：設定排程（每天凌晨 2:00 自動執行）

crontab -e

如果問你選擇編輯器，選 nano（最簡單）。

在打開的檔案最底部加上這一行：

0 2 * * * /bin/bash $HOME/docker/openclaw-backup.sh

意思是：每天凌晨 2:00 執行備份腳本。

儲存並離開（nano 的話：按 Ctrl+O 儲存 → Enter 確認 → Ctrl+X 離開）。

✅ 測試點：確認排程已設定

crontab -l

你應該看到：包含 openclaw-backup.sh 的那一行

階段九：最終驗證清單

做什麼：從頭到尾確認每個環節都正常。

9-1：Homebrew 正常

brew -v

9-2：Node.js / npm 路徑正確

which node && node -v

which npm && npm -v

9-3：OpenClaw 可用

openclaw --version

openclaw doctor

9-4：Gateway daemon 在執行中

launchctl list | grep ai.openclaw.gateway || echo "gateway 未載入"

你應該看到：一行包含 PID 數字和 ai.openclaw.gateway 的輸出
如果看到 gateway 未載入：執行 openclaw onboard --install-daemon 重新安裝

9-5：Web UI 可以打開

用瀏覽器打開：

http://127.0.0.1:18789/

9-6：Telegram Bot 能回覆

在 Telegram 傳 /start 或 你好 給你的 Bot。

🔐 安全規則（請務必遵守）

❌ 不要做	✅ 應該做
把 API key 貼到群組或公開地方	只放在 OpenClaw 設定或環境變數
把 key 寫進會同步到雲端的檔案	用 `~/.openclaw/credentials/` 存放
在文件中寫真實 key	用範例格式：`sk-or-v1-xxxxxxxxxxxxxxxx`
把 Bot Token 分享給別人	Token 只有你自己知道

🛠️ 常用維護指令

手動編輯設定檔

nano ~/.openclaw/openclaw.json

查看 daemon 狀態

launchctl list | grep ai.openclaw.gateway

重啟 daemon

launchctl stop ai.openclaw.gateway

launchctl start ai.openclaw.gateway

更新 OpenClaw

npm update -g openclaw

手動觸發備份

bash ~/docker/openclaw-backup.sh

查看最近的備份日誌

ls -lt ~/docker/openclaw-data/logs/ | head -5

❓ 常見問題排除

`brew: command not found`

回到 階段一步驟 1-2，重新設定 PATH 後執行：

eval "$(/opt/homebrew/bin/brew shellenv)"

`gateway.mode unset` 或 daemon 啟動後馬上退出

openclaw onboard --install-daemon

重新跑一次設定精靈。

Telegram Bot 沒有回應

確認 daemon 在跑：launchctl list | grep ai.openclaw.gateway
確認 Bot Token 正確：檢查 ~/.openclaw/telegram/ 裡的設定
確認 allowFrom 是你的 user id

混用 nvm 導致問題

如果之前用 nvm 裝了 Node.js，現在想改用 brew：

nvm deactivate

brew install node

然後確認 which node 顯示 /opt/homebrew/bin/node。

📝 備忘：這份文件假設你是一般 Mac 使用者，不需要 Docker 容器化。備份系統透過 cron + shell script 實現，資料存放在 ~/docker/openclaw-data/ 目錄，權限嚴格控管，敏感資料只有你本人能存取。

Openclaw 新手安裝 | Mac OS 使用者，Docker 隔離版本

📋 你完成後會得到什麼

階段一：安裝 Homebrew（macOS 套件管理器）

步驟 1-1：安裝 Homebrew

步驟 1-2：設定 PATH（Apple Silicon M1/M2/M3/M4 必做）

步驟 1-3：讓設定立刻生效

步驟 1-4：重新整理指令快取

✅ 測試點：確認 Homebrew 安裝成功

步驟 1-5：（選做）關閉 Homebrew 匿名統計

階段二：安裝 Node.js

步驟 2-1：檢查是否已經有 Node.js

步驟 2-2：用 Homebrew 安裝 Node.js

✅ 測試點：驗證 Node.js 和 npm 路徑與版本

⚠️ 重要提醒

階段三：安裝 OpenClaw

步驟 3-1：用 npm 全域安裝 OpenClaw

✅ 測試點：確認 OpenClaw 安裝成功

階段四：健康檢查

步驟 4-1：執行健檢

階段五：啟動設定精靈（Onboarding + Daemon）

步驟 5-1：啟動設定精靈

🔧 設定 A：API Provider 與 Model

🔧 設定 B：Telegram Bot

B-1：取得 Bot Token

B-2：設定 allowFrom

🔧 設定 C：Skills（技能模組）

🔧 設定 D：Hooks（自動化鉤子）

🔧 設定 E：Hatch（孵化方式）

階段六：首次配對與測試（Telegram）

步驟 6-1：在 Telegram 找到你的 Bot

步驟 6-2：啟動對話

步驟 6-3：配對

✅ 測試點：傳一句話測試

階段七：設定目錄權限（安全加固）

步驟 7-1：鎖定私密目錄（700 = 只有你能讀寫）

步驟 7-2：設定公開目錄（755 = 別人可讀，但只有你能寫）

✅ 測試點：驗證權限

階段八：建立每日自動備份系統

步驟 8-1：建立備份資料夾結構

步驟 8-2：鎖定備份資料夾權限

步驟 8-3：建立備份腳本

步驟 8-4：讓腳本可執行

✅ 測試點：手動跑一次備份

步驟 8-5：設定排程（每天凌晨 2:00 自動執行）

✅ 測試點：確認排程已設定

階段九：最終驗證清單

9-1：Homebrew 正常

9-2：Node.js / npm 路徑正確

9-3：OpenClaw 可用

9-4：Gateway daemon 在執行中

9-5：Web UI 可以打開

9-6：Telegram Bot 能回覆

🔐 安全規則（請務必遵守）

🛠️ 常用維護指令

手動編輯設定檔

查看 daemon 狀態

重啟 daemon

更新 OpenClaw

手動觸發備份

查看最近的備份日誌

❓ 常見問題排除

brew: command not found

gateway.mode unset 或 daemon 啟動後馬上退出

Telegram Bot 沒有回應

混用 nvm 導致問題

`brew: command not found`

`gateway.mode unset` 或 daemon 啟動後馬上退出