2026 OpenClaw 全網最完整安裝與配置指南：從 0 到跑通的保姆教程

4. 按官方方式安裝 OpenClaw

目的：用 OpenClaw 官方維護的安裝入口，讓 install.sh 自動處理 Node 與 CLI。來源：官方 Installation 文檔（發佈前請再核對是否有新版本號或額外參數）。

4.1 推薦：官方 install.sh（macOS / Linux）

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

# 僅安裝、稍後自行 onboard：
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

安裝器會檢測系統、按需安裝 Node（文檔推薦 Node 24，或 Node 22.19+），並安裝 OpenClaw CLI。典型目錄（以當前文檔為準，發佈前請再核對）：

• 用戶配置：~/.openclaw/（含 openclaw.json5、secrets/、狀態與日誌）
• Gateway 默認端口：18789（本機 Control UI / WebSocket）
• macOS 後台：openclaw onboard --install-daemon 註冊 LaunchAgent

4.2 初始化：onboard 嚮導

openclaw onboard --install-daemon

# 驗證安裝（官方推薦三連）：
openclaw --version
openclaw doctor
openclaw gateway status

嚮導會引導選擇模型 provider、寫入 API Key、配置 Gateway。切忌執行未知來源的安裝腳本；不要把密鑰提交到 git 或截圖發到羣聊。

4.3 安裝後必做記錄

source ~/.zshrc          # 或新開一個終端窗口
openclaw --version         # 記錄版本號到筆記，便於日後排錯
openclaw doctor            # 自動診斷缺失項；可加 --fix 嘗試修復

通過標準：which openclaw 指向 PATH 中的 openclaw（常見爲 npm 全局 bin）；openclaw doctor 無阻塞性 FAIL。失敗先看：安裝腳本最後 20 行日誌 → PATH → 是否 Node 版本低於官方要求，或 PATH 未包含 npm 全局 bin openclaw 文件（應使用 venv 啟動器）。

切忌：安裝失敗後不要立刻「刪掉 ~/.openclaw 再裝」——先保存終端輸出與 openclaw doctor 結果，否則難以區分是網路問題還是權限問題。

5. 配置模型與 API Key

目的：讓 OpenClaw Agent 能調用你選的 LLM provider。通過標準：非交互式冒煙收到合理回覆；openclaw auth list 或 .env 中有對應項且不在 shell history 明文長期停留。

5.1 交互式配置（首次推薦）

openclaw onboard        # 交互式嚮導：模型、密鑰、Gateway（可與 --install-daemon 合用）
# 密鑰也可通過 auth-profiles / 環境變數注入，詳見官方 Authentication 文檔

5.2 環境變數與配置文件

主配置一般在 ~/.openclaw/openclaw.json5；密鑰引用多在 ~/.openclaw/.env（用 openclaw config path、openclaw config env-path 確認實際路徑）。示例（變數名以你所選 provider 的官方文檔為準，勿照抄過期名稱）：

# 示例：OpenRouter（請替換爲你的 key，勿提交到 git）
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 或直接編輯 .env（chmod 600 ~/.openclaw/.env）
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

邊界提示：模型價格、API 限額、地區可用性與隱私政策會隨 provider 調整——上線前務必閱讀其最新條款。本文不綁定某一固定模型名。

6. 工作目錄、權限與日誌

目的：裝好後「可追蹤、可限制、可回滾」。原則：最小權限——先只允許動測試目錄，再逐步放開真實項目。

• 工作區：在 openclaw.json5 或會話中指定 ~/openclaw-lab；可在該目錄放 AGENTS.md 描述允許的工具與邊界（參見官方 Context Files 文檔）。
• macOS 權限：若啓用終端/文件類工具，系統可能提示「完全磁盤訪問」——首次驗收階段可只授予測試目錄相關權限，避免對整個磁盤放權。
• 日誌目錄：默認 ~/.openclaw/logs/（含 agent.log、errors.log、gateway.log）。用 openclaw logs list、openclaw logs errors --since 30m 查看。
• 密鑰安全：chmod 600 ~/.openclaw/.env；備份 zip 不要放進同步盤；勿讓 Agent 讀取 ~/.ssh、支付或生產 kubeconfig。
• 後台運行（可選）：需要 Telegram/Discord 等閘道時，用 openclaw gateway setup 與 openclaw gateway install；長期運維見本站OpenClaw 7×24 閘道運維指南。

通過標準：對 Agent 說「只讀寫 ~/openclaw-lab」後，嘗試訪問主目錄外路徑應被拒絕或在日誌中留下審計記錄。

7. 打開 Dashboard 並驗證 Gateway（端口 18789）

目的：確認 Control UI 與 WebSocket Gateway 正常。通過標準：本機 http://127.0.0.1:18789 可加載；openclaw gateway status 顯示監聽 18789。

openclaw gateway status
openclaw dashboard
# 瀏覽器也可直接訪問：
# http://127.0.0.1:18789/

# 遠端 Mac（SSH 轉發，勿把 18789 裸露到公網）：
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# 端口占用排查：
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

失敗先看：端口被佔用 → lsof 結束衝突進程；Dashboard 空白但 status 正常 → 瀏覽器緩存或 WebSocket 被代理攔截；遠端訪問失敗 → 是否只做 SSH 本地轉發而非公網暴露。launchd：若 onboard 時加了 --install-daemon，重啟 Mac 後應仍 openclaw gateway status 爲 running；否則檢查 LaunchAgent 日誌與用戶是否一致（詳見本站 launchd 環境變數 一文）。

8. 首次運行驗收：七步 Runbook

下面七步把「配置完成」推到「實戰可用」的門檻——建議原樣執行並保存輸出截圖或日誌片段。

1. 診斷：openclaw doctor --fix → 無未處理 FAIL。
2. 模型 ping：openclaw agent --message "Reply with exactly: OPENCLAW_OK" → 回覆含 OPENCLAW_OK。
3. 文件讀：讓 Agent 讀取 ~/openclaw-lab/inbox/sample.txt 並複述首句。
4. 文件寫：寫入 ~/openclaw-lab/outbox/ping.txt → cat 可見。
5. 日誌：openclaw logs errors --since 10m → 無新 ERROR（或已知可忽略項已記錄）。
6. 關終端：關閉窗口，新開終端重複步驟 2 → 排除 PATH 僅當前 session 生效。
7. 可選重啟：重啟 Mac 後再跑步驟 2（若已裝 gateway，再加 openclaw gateway status）。

可引用閾值（個人驗收參考，非官方 SLA）：冒煙回覆 < 60s；errors.log 10 分鐘內 0 條未解釋 ERROR；測試文件寫入後 ls -la ~/openclaw-lab/outbox 可見新文件。

9. 跑通第一個實戰案例：摘要 + 待辦 + 可回滾輸出

場景設計：在測試目錄讀取樣本文本，生成中文摘要與 3 條待辦，寫入 Markdown，並保留回滾副本。該案例同時覆蓋安裝結果（CLI）、配置結果（模型）、真實 workflow（讀→推理→寫→日誌）。

# 1. 準備輸入（若第 3 節已創建可跳過）
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
本週完成：OpenClaw 安裝文檔草稿。
待跟進：配置 OpenRouter 預算告警；下週評估 gateway 接 Telegram。
風險：勿把 API Key 提交到 git。
EOF

# 2. 啟動交互會話（或使用一條複合指令）
openclaw
# 在會話中發送（示例提示詞）：
# 「請只使用 ~/openclaw-lab 目錄。讀取 inbox/weekly-notes.txt，
#   用中文寫 150 字以內摘要 + 3 條待辦，保存到 outbox/summary-and-todos.md，
#   並把原文件複製到 archive/weekly-notes.bak」

# 3. 非交互驗收
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

通過標準：

• summary-and-todos.md 含摘要與 3 條待辦，且與源文件語義一致。
• archive/ 下有備份，可用 diff 對比。
• 日誌中有對應 tool call 記錄；provider 賬單/dashboard 有本次調用（便於核對成本）。

回滾：rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt。失敗先看：模型是否因上下文截斷未讀完文件 → 權限是否拒絕寫入 outbox → errors.log 中 tool 報錯詳情。

10. 常見問題排查：按層定位，避免盲目重裝

發佈前事實核對清單（維護者用）：官方 install.sh URL、最低 macOS、默認目錄名、CLI 子命令、provider 環境變數名、日誌路徑——任一項變更都應先改文檔再發布。讀者側只需記住：遇錯先 openclaw doctor，再查 errors.log，最後才考慮重裝。

11. 下一步怎麼擴展：從測試目錄到真實 workflow

驗收通過後，建議按下面節奏擴展，不要一步接入生產倉庫或支付系統：

1. 把單個真實 side project 目錄加入白名單，仍禁止 ~/.ssh 與全局 * 讀寫。
2. 啓用 openclaw cron 跑每日低風險任務（如整理下載文件夾清單——仍限測試目錄）。
3. 配置一個訊息閘道（Telegram/Discord）並用配對模式限制陌生人（見官方 Security 文檔）。
4. 建立 openclaw backup --quick 的每週節奏，再讀長期維護文做升級與回滾演練。