安裝路徑選擇：一鍵腳本 vs npm vs git
OpenClaw 的安裝方式有三種，各自的適用場景與注意點如下：
一鍵安裝腳本（推薦路徑）：執行 `curl -fsSL https://openclaw.ai/install.sh | bash`。腳本會自動檢測 Node.js 版本（需 ≥ 22），如未安裝則提示安裝；隨後透過 npm 全局安裝 openclaw CLI；最後自動啟動 onboarding 精靈。適用於絕大多數想在乾淨系統快速上手的使用者。
npm 全局安裝：`npm install -g openclaw@latest` 後手動執行 `openclaw onboard`。適用於已具備 Node 22+ 環境、或需要在 CI/CD 腳本中自動部署的场景。優勢在於可精確控制版本與安裝參數。
git 開發安裝：從 GitHub 克隆原始碼後 `npm install`，適合需要修改核心邏輯或參與社群開發的進階使用者。注意：開發模式不自動註冊 daemon，需手動執行 `openclaw onboard --install-daemon`。
不論選擇哪種方式，都必須在安裝完成後立即執行 `openclaw onboard --install-daemon`，否則 Gateway 僅在當前終端 session 內運行，重啟後丟失。
Gateway 服務化：systemd / LaunchAgent / Windows 工作排程
`--install-daemon` 會在不同平台註冊對應的使用者級服務，確保持久化運行：
| 平台 | 服務類型 | 驗證命令 | 管理命令 |
|---|---|---|---|
| Linux (systemd) | 使用者級 systemd unit | `systemctl --user is-enabled openclaw-gateway.service` | `systemctl --user start|stop|restart openclaw-gateway` |
| macOS (launchd) | LaunchAgent plist | `launchctl list | grep openclaw` | `launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist` 再 `load` |
| Windows (WSL2) | 工作排程（Scheduled Task） | `schtasks /Query /TN "OpenClaw Gateway"` | `schtasks /Run /TN "OpenClaw Gateway"` |
關鍵注意點：
使用者級而非系統級：OpenClaw daemon 預設以當前使用者身份運行，不需要 root。使用 `systemctl --user` 而非 `sudo systemctl`；root 級命令找不到該服務。
端口 18789 佔用檢查：若 Gateway 啟動失敗，常見原因是端口被佔用。執行 `lsof -i :18789`（macOS/Linux）或 `netstat -ano | findstr :18789`（Windows）定位並終止佔用進程。
狀態目錄位置：預設 `~/.openclaw/`。若需自訂，透過環境變數 `OPENCLAW_STATE_DIR` 指定；禁止放在 iCloud、Dropbox 等雲同步目錄，會導致鎖競爭與資料不一致。
Windows WSL2 特別說明：WSL2 中安裝需確保 Node.js 在 WSL 環境內，且使用 `openclaw onboard --install-daemon` 會建立 WSL 使用者級 service。外部存取需在 Windows 防火牆放行 18789 埠或透過 SSH 隧道。
配置基線：gateway.bind、gateway.auth 與狀態目錄
安裝後首次執行 `openclaw onboard` 會產生 `~/.openclaw/openclaw.json`。以下是必須核驗的基線配置欄位：
gateway.bind（綁定地址）：預設 `127.0.0.1`（loopback），僅本機存取。若需從外網存取（如將 Gateway 放在 VPS），必須改為 `0.0.0.0` 或具體 IP，並同步配置鑑權。注意：綁定非 loopback 地址時若未設定 token/password，Gateway 會拒絕啟動（安全保護）。
gateway.auth（鑑權方式）：支援 `token` 或 `password`。Token 模式下，透過 `openclaw config set gateway.auth.token
OPENCLAW_STATE_DIR（狀態目錄）：存放資料庫、會話與技能快取。生產環境建議放在本地 SSD，禁止掛載雲同步碟（OneDrive、iCloud、Dropbox 等），會導致並寫入衝突與資料損壞。
gateway.port：預設 18789。若該埠被佔用，可透過 `openclaw gateway --port
健康檢查階梯：status → logs → doctor → channels probe
當 Gateway 行為異常時，按以下順序逐層檢查，避免盲目重啟：
openclaw gateway status：查看 Gateway 進程狀態（running/stopped/error）、監聽地址與埠、已連接通道列表。若顯示 `disconnected` 或 `unauthorized`，進入下一步。
openclaw logs --follow：即時日誌流。重點關注 ERROR 與 WARN 級别的訊息，常見線索包括：埠綁定失敗、config key 錯誤、鑑權失敗、通道連接被拒。日誌位置也可直接查看 `~/.openclaw/logs/` 目錄。
openclaw doctor：自動健康診斷工具。檢查項包括：Node 版本、埠可用性、配置檔語法、state dir 權限、API 密鑰有效性、通道配對狀態。doctor 輸出通常包含可執行的修復命令建議。
openclaw channels status --probe：通道級探測。列出所有已配置通道（Telegram、Discord 等）的連接狀態、配對請求、訊息傳送成功率。若通道顯示 `pairing required` 或 `disconnected`，需重新執行配對流程。
該階梯的核心思想是先服務層（gateway status）→ 再日誌層（logs）→ 然後配置層（doctor）→ 最後業務層（channels），層層遞進，避免在錯誤層面浪費時間。
常見故障恢復清單：埠佔用、環境變數、config key 漂移等
以下是高頻故障場景與對應的修復步驟，可按表排查：
Gateway 啟動失敗：埠 18789 被佔用：執行 `lsof -i :18789` 定位佔用進程 PID，`kill -9
Daemon 未自啟（ reboot 後未運行）：驗證服務是否註冊：`systemctl --user is-enabled openclaw-gateway.service`（Linux）或 `launchctl list | grep openclaw`（macOS）。如未註冊，重新執行 `openclaw onboard --install-daemon`。
環境變數未加載：若透過 systemd/LaunchAgent 啟動，確保必要環境變數（如 `ANTHROPIC_API_KEY`）已配置在服務單元檔案中，或寫入 `~/.config/environment.d/`。手動啟動正常但 daemon 啟動失敗時，優先檢查此點。
升級後 config key 漂移：OpenClaw 2026.4.x 將 `gateway.token` 更名為 `gateway.auth.token`，並將 `gateway.mode` 的預設值從空調整為需顯式設定。升級後執行 `openclaw doctor` 查看遷移建議，或手動編輯 `openclaw.json` 對齊新 schema。
非 loopback 綁定卻無鑑權：當 `gateway.bind` 設為 `0.0.0.0` 或外網 IP 時，必須同時設定 `gateway.auth.token` 或 `gateway.auth.password`，否則 Gateway 拒絕啟動並提示 "non‑loopback binding requires authentication"。
通道配對失效（Token 過期/ Bot 被刪）：進入 Control UI (http://127.0.0.1:18789) → Devices 頁面，刪除失效裝置後重新 `openclaw onboard` 完成配對；或使用 `openclaw pairing list --channel
Docker 部署的 bind 模式陷阱：官方 Docker 配置中 `gateway.bind` 應使用 `lan`（內網）而非 `localhost` 或 `0.0.0.0`；若容器內透過 `172.x.x.x` 存取，需重置 `openclaw config set gateway.bind lan` 並重啟容器。
注意：任何修改配置後，優先使用 `openclaw gateway restart` 重啟服務；若無效，使用平台專用服務管理器：`systemctl --user restart openclaw-gateway`（Linux）或 `launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway`（macOS）強制重新加載。
可能原因：① 未執行 `openclaw onboard --install-daemon`，Gateway 僅在當前 session 存活；② Node.js 版本 < 22，需先升級；③ 埠 18789 被佔用。解決：依次執行 `openclaw onboard --install-daemon` → `openclaw gateway status` → `openclaw doctor` 診斷。
2026.4.x 變更了 config key（如 `gateway.token` → `gateway.auth.token`）且現在需要顯式設定 `gateway.mode`。執行 `openclaw doctor` 查看遷移建議，修改 `~/.openclaw/openclaw.json` 後執行 `openclaw gateway restart`。若仍無效，使用 `systemctl --user restart openclaw-gateway`（Linux）或 `launchctl kickstart`（macOS）強制重載服務。
有，生產環境推薦。雲端 Mac（如 MESHLAUNCH 裸金屬節點）提供 7×24 在線、免睡眠、穩定公網 IP，便於防火牆與反代配置。搭配 Nginx/Caddy 做 TLS 終止，可實現高可用架構。詳情見 價格頁。
原生 Windows 使用 PowerShell 腳本 `iwr -useb https://openclaw.ai/install.ps1 | iex`；為求最佳相容性建議使用 WSL2（Ubuntu）並遵循 Linux 流程。daemon 會註冊為 Windows 工作排程，確保以使用者帳戶執行且環境變數（API keys）對任務可見。
替代方案的局限：僅依賴本地 Mac 跑 Gateway 會受睡眠、網路波動、家庭寬頻 IP 變更等影響；Docker 未配置持久化 volume 會導致容器重建後狀態丟失；純用手動啟動未加入開機自啟，必然導致服務中斷。對於更穩定、更適合 AI Agent 自動化的生產環境，MESHLAUNCH 的雲端 Mac Mini 節點配合正確的服務化配置（systemd/LaunchAgent）與鑑權策略，是保障 Gateway 7×24 可用的更優解。