OpenClaw 安裝與配置指南

每次設定新工具最怕的就是改了一堆設定，結果下次 git pull 更新時全部衝突，或者更慘，直接把你的個人配置蓋掉。如果你也曾被這種「更新地獄」折磨過，這篇指南會告訴你如何優雅地安裝並配置 OpenClaw，確保你的自定義內容與核心程式碼完美分離。

設定過程其實很直覺，只要掌握好檔案放哪裡，剩下的就是選一個適合你的工作流。

快速入門 (TL;DR)

• 你的自定義內容都在 Repo 之外： 所有的個人化設定都存在 ~/.openclaw/workspace (workspace) 與 ~/.openclaw/openclaw.json (config)。
• 工作流選擇： 追求穩定請安裝 macOS App 並執行內建 Gateway；想玩最新功能則可透過 pnpm gateway:watch 手動執行，再讓 App 以 Local 模式連入。

前置需求 (Prereqs)

• 推薦使用 Node 24 (Node 22 LTS, 目前 22.14+ 仍支援)，並安裝 pnpm。
• Docker (選配；僅用於容器化設定/e2e — 詳見 Docker)。

自定義策略（讓更新不再痛苦）

如果你想要「100% 專屬自定義」且能輕鬆更新，請把你的修改放在以下路徑：

• Config: ~/.openclaw/openclaw.json (支援 JSON/JSON5 格式)
• Workspace: ~/.openclaw/workspace (包含 skills, prompts, memories；建議將此目錄設為私人的 git repo)

先執行一次初始化：

openclaw setup

如果你是在此 Repo 內開發，請使用本地 CLI 入口：

openclaw setup

如果你還沒安裝全域指令，可以透過 pnpm openclaw setup 來執行。

從此 Repo 執行 Gateway

執行 pnpm build 之後，你可以直接執行封裝好的 CLI：

node openclaw.mjs gateway --port 18789 --verbose

穩定工作流（優先使用 macOS App）

1. 安裝並啟動 OpenClaw.app (選單列圖示)。
2. 完成初始化設定與權限檢查 (TCC 提示)。
3. 確保 Gateway 處於 Local 模式且正在執行 (App 會幫你管理)。
4. 連結通訊平台 (例如 WhatsApp)：

openclaw channels login

5. 執行健康檢查：

openclaw health

如果你的版本沒有內建初始化引導：

• 請先執行 openclaw setup，接著 openclaw channels login，最後手動啟動 Gateway (openclaw gateway)。

開發者工作流（在終端機執行 Gateway）

目標：直接修改 TypeScript 寫的 Gateway 並享受熱重載 (hot reload)，同時保持 macOS App 的 UI 連線。

0) (選配) 從原始碼執行 macOS App

如果你連 macOS App 都想用最新開發版：

./scripts/restart-mac.sh

1) 啟動開發版 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 會以監聽模式啟動 Gateway，當原始碼、設定檔或內建插件的元數據 (metadata) 變動時會自動重載。

2) 將 macOS App 指向你正在執行的 Gateway

在 OpenClaw.app 中：

• Connection Mode 選擇：Local App 會自動連線到你在指定連接埠執行的 Gateway。

3) 驗證

• App 內的 Gateway 狀態應顯示 「Using existing gateway …」
• 或者透過 CLI 檢查：

openclaw health

常見踩坑點

• 連接埠錯誤： Gateway WS 預設使用 ws://127.0.0.1:18789；請確保 App 與 CLI 使用相同的連接埠。
• 狀態儲存位置：
  • 憑證 (Credentials): ~/.openclaw/credentials/
  • 對話紀錄 (Sessions): ~/.openclaw/agents/<agentId>/sessions/
  • 日誌 (Logs): /tmp/openclaw/

憑證儲存路徑一覽

除錯身份驗證或備份資料時，請參考以下路徑：

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Telegram bot token: 設定檔/環境變數或 channels.telegram.tokenFile (僅限一般檔案；不支援軟連結)
• Discord bot token: 設定檔/環境變數或 SecretRef (支援 env/file/exec 等來源)
• Slack tokens: 設定檔/環境變數 (channels.slack.*)
• 配對白名單 (Pairing allowlists):
  • ~/.openclaw/credentials/<channel>-allowFrom.json (預設帳號)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (非預設帳號)
• 模型驗證設定檔: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 檔案加密金鑰 (選配): ~/.openclaw/secrets.json
• 舊版 OAuth 匯入: ~/.openclaw/credentials/oauth.json 更多細節請參考：Security。

如何更新（且不弄壞你的設定）

• 始終將 ~/.openclaw/workspace 與 ~/.openclaw/ 視為「你的東西」；不要把個人的 prompts 或設定放進 openclaw 的 repo 裡。
• 更新原始碼：執行 git pull + pnpm install (當 lockfile 有變動時)，然後繼續使用 pnpm gateway:watch 即可。

Linux (systemd 使用者服務)

Linux 安裝程式會使用 systemd 使用者 (user) 服務。預設情況下，systemd 會在使用者登出或閒置時停止服務，這會導致 Gateway 斷線。初始化程式會嘗試幫你開啟 lingering 功能 (可能會要求 sudo 權限)。如果還是沒開，請手動執行：

sudo loginctl enable-linger $USER

如果是為了長期運作或多使用者伺服器，建議考慮使用 系統 (system) 服務而非使用者服務。相關說明請見 Gateway 運作指南。

相關文件

• Gateway 運作指南 (參數、監控、連接埠)
• Gateway 設定 (設定結構與範例)
• Discord 與 Telegram (回覆標籤與 replyToMode 設定)
• OpenClaw 助手設定
• macOS App (Gateway 生命週期管理)

下一步

• 想要更深入了解如何調整你的機器人？查看 Gateway 設定。
• 遇到連線問題？試試 AI Setup Assistant。