Setup

注意： 如果你是第一次設定，請從快速上手開始。精靈的詳細說明請參考 Onboarding 精靈。

最後更新：2026-01-01

摘要

客製化內容放在 repo 外面： ~/.openclaw/workspace（工作區）+ ~/.openclaw/openclaw.json（設定）。
穩定流程： 安裝 macOS app；讓它執行內建的 Gateway。
前沿流程： 自己透過 pnpm gateway:watch 執行 Gateway，然後讓 macOS app 以 Local 模式連接。

前置需求（從原始碼）

Node >=22
pnpm
Docker（選用；僅供容器化設定/端對端測試 — 參見 Docker）

客製化策略（讓更新不再痛苦）

如果你想要「100% 為我量身打造」_同時_方便更新，把客製化內容放在：

設定： ~/.openclaw/openclaw.json（JSON/JSON5 格式）
工作區： ~/.openclaw/workspace（skills、prompts、記憶；建議做成私有 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 優先）

安裝並啟動 OpenClaw.app（選單列）。
完成 onboarding 和權限清單（TCC 提示）。
確認 Gateway 為 Local 且正在執行（app 會管理它）。
連接通訊介面（範例：WhatsApp）：

openclaw channels login

快速檢查：

openclaw health

如果你的版本沒有 onboarding：

執行 openclaw setup，然後 openclaw channels login，再手動啟動 Gateway（openclaw gateway）。

前沿流程（在終端機中執行 Gateway）

目標：直接開發 TypeScript Gateway，啟用熱重載，同時保持 macOS app UI 連接。

0）（選用）也從原始碼執行 macOS app

如果你也想讓 macOS app 跑在最前沿：

./scripts/restart-mac.sh

1）啟動開發 Gateway

pnpm install
pnpm gateway:watch

gateway:watch 以 watch 模式執行 gateway，TypeScript 有變更時自動重載。

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 使用相同的埠號。
狀態檔案位置：
- 憑證：~/.openclaw/credentials/
- Sessions：~/.openclaw/agents/<agentId>/sessions/
- 日誌：/tmp/openclaw/

憑證儲存對照表

除錯驗證問題或決定備份範圍時可參考：

WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram bot token：設定/環境變數或 channels.telegram.tokenFile（僅接受一般檔案；拒絕 symlink）
Discord bot token：設定/環境變數或 SecretRef（env/file/exec 提供者）
Slack tokens：設定/環境變數（channels.slack.*）
配對白名單：
- ~/.openclaw/credentials/<channel>-allowFrom.json（預設帳號）
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非預設帳號）
模型驗證設定檔：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
檔案型 secrets（選用）：~/.openclaw/secrets.json
舊版 OAuth 匯入：~/.openclaw/credentials/oauth.json 更多細節：安全性。

更新（不破壞你的設定）

把 ~/.openclaw/workspace 和 ~/.openclaw/ 當作「你的東西」；不要把個人 prompts 或設定放進 openclaw repo。
更新原始碼：git pull + pnpm install（lockfile 有變更時）+ 繼續使用 pnpm gateway:watch。

Linux（systemd user service）

Linux 安裝使用 systemd user service。預設情況下，systemd 在登出或閒置時會停止 user service，這會終止 Gateway。Onboarding 會嘗試為你啟用 lingering（可能需要 sudo）。如果仍未啟用，執行：

sudo loginctl enable-linger $USER

對於永遠在線或多使用者的伺服器，考慮使用 system service 而非 user service（不需要 lingering）。systemd 相關說明請參考 Gateway 運維手冊。