跳轉到主要內容
如果你是第一次設定，請從入門開始。 如需上手流程的詳細資訊，請參閱上手流程（命令列介面）。

​
TL;DR

根據你想要更新的頻率，以及是否想自行執行閘道，選擇設定工作流程：
  • **客製化內容放在 repo 外：**將你的設定與工作區保留在 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace/，這樣 repo 更新就不會動到它們。
  • **穩定工作流程（建議多數人使用）：**安裝 macOS app，並讓它執行內建的閘道。
  • **前沿開發工作流程（dev）：**透過 pnpm gateway:watch 自行執行閘道，然後讓 macOS app 以本機模式附加。

​
先決條件（從原始碼）

  • 建議使用 節點 24（仍支援 節點 22 LTS，目前為 22.19+）
  • 原始碼 checkout 需要 pnpm。OpenClaw 在 dev 模式會從 extensions/* pnpm workspace packages 載入內建外掛，因此根目錄的 npm install 不會準備完整的原始碼樹。
  • Docker（選用；僅用於容器化設定/e2e - 請參閱 Docker）

​
客製化策略（讓更新不造成傷害）

如果你想要「100% 依照我的需求客製化」_同時_方便更新，請將你的自訂內容放在：
  • 設定：~/.openclaw/openclaw.json（JSON/類 JSON5）
  • 工作區：~/.openclaw/workspace（skills、prompts、memories；將它做成私有 git repo）
只需初始化設定/工作區資料夾一次，不必執行完整的上手精靈： 
openclaw setup --baseline
還沒有全域安裝嗎？改從這個 repo 執行： 
pnpm openclaw setup --baseline
（裸用 openclaw setup、不加 --baseline，是 openclaw onboard 的別名，會執行完整互動式精靈。）

​
從這個 repo 執行閘道

執行 pnpm build 後，你可以直接執行封裝好的命令列介面： 
node openclaw.mjs gateway --port 18789 --verbose

​
穩定工作流程（先使用 macOS app）

  1. 安裝並啟動 OpenClaw.app（選單列）。
  2. 完成上手/權限檢查清單（TCC prompts）。
  3. 確認閘道為本機且正在執行（由 app 管理）。
  4. 連結介面（範例：WhatsApp）：
openclaw channels login
  1. 健全性檢查：
openclaw health
如果你的組建沒有上手流程：
  • 執行 openclaw setup，接著執行 openclaw channels login，然後手動啟動閘道（openclaw gateway）。

​
前沿開發工作流程（在終端機中執行閘道）

目標：開發 TypeScript 閘道、取得熱重載，並讓 macOS app UI 保持附加。

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

如果你也想讓 macOS app 使用前沿開發版： 
./scripts/restart-mac.sh

​
1) 啟動 dev 閘道

pnpm install
# 僅第一次執行（或重設本機 OpenClaw 設定/工作區後）
pnpm openclaw setup
pnpm gateway:watch
gateway:watch 會在具名 tmux 工作階段（openclaw-gateway-watch-main）中啟動或重新啟動閘道監看程序，並從互動式 終端機自動附加。非互動式 shell 會保持分離並列印 tmux attach -t openclaw-gateway-watch-main；使用 OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch 可讓互動式執行 保持分離，或使用 pnpm gateway:watch:raw 以前景監看模式執行。監看器 會在相關原始碼、設定與內建外掛中繼資料變更時重新載入。如果被監看的 閘道在啟動期間結束，gateway:watch 會執行一次 openclaw doctor --fix --non-interactive 並重試；設定 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 可停用該僅限 dev 的修復步驟。 pnpm gateway:watch 不會重新建置 dist/control-ui，因此在 ui/ 變更後請重新執行 pnpm ui:build，或在開發 Control UI 時使用 pnpm ui:dev。

​
2) 將 macOS app 指向你正在執行的閘道

在 OpenClaw.app 中：
  • 連線模式：本機 app 會附加到設定連接埠上正在執行的閘道。

​
3) 驗證

  • app 內的閘道狀態應顯示 「正在使用現有閘道 …」
  • 或透過命令列介面：
openclaw health

​
常見陷阱

  • **連接埠錯誤：**閘道 WS 預設為 ws://127.0.0.1:18789；請讓 app 與命令列介面使用相同連接埠。
  • 狀態儲存位置：
    • 頻道/供應商狀態：~/.openclaw/credentials/
    • 模型驗證設定檔：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 工作階段：~/.openclaw/agents/<agentId>/sessions/
    • 日誌：/tmp/openclaw/

​
認證儲存對照表

除錯驗證或決定要備份哪些內容時使用：
  • WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token：設定/env 或 channels.telegram.tokenFile（僅限一般檔案；拒絕 symlinks）
  • Discord bot token：設定/env 或 SecretRef（env/file/exec providers）
  • Slack tokens：設定/env（channels.slack.*）
  • 配對允許清單：
    • ~/.openclaw/credentials/<channel>-allowFrom.json（預設帳號）
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非預設帳號）
  • 模型驗證設定檔：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 檔案支援的密鑰 payload（選用）：~/.openclaw/secrets.json
  • 舊版 OAuth 匯入：~/.openclaw/credentials/oauth.json 更多詳細資訊：安全性。

​
更新（不破壞你的設定）

  • 將 ~/.openclaw/workspace 和 ~/.openclaw/ 視為「你的東西」；不要把個人 prompts/設定放進 openclaw repo。
  • 更新原始碼：git pull + pnpm install + 持續使用 pnpm gateway:watch。

​
Linux（systemd 使用者服務）

Linux 安裝會使用 systemd 使用者服務。預設情況下，systemd 會在登出/閒置時停止使用者 服務，這會終止閘道。上手流程會嘗試為你啟用 lingering（可能會提示 sudo）。如果它仍然關閉，請執行： 
sudo loginctl enable-linger $USER
對於永遠在線或多使用者伺服器，請考慮使用系統服務，而不是 使用者服務（不需要 lingering）。systemd 注意事項請參閱閘道 runbook。

​
相關文件