常見問題：首次執行設定

使用可以看見你的機器的本機 AI agent。這比在 Discord 詢問有效得多，因為多數「我卡住了」的情況都是本機設定或環境問題， 遠端協助者無法檢查。

• Claude Code: https://www.anthropic.com/claude-code/
• OpenAI Codex: https://openai.com/codex/

這些工具可以讀取 repo、執行命令、檢查日誌，並協助修正機器層級 設定（PATH、服務、權限、驗證檔案）。請透過 可修改的（git）安裝方式，把完整 source checkout 提供給它們：

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

這會從 git checkout 安裝 OpenClaw，因此 agent 可以讀取程式碼 + 文件， 並針對你正在執行的確切版本推理。你之後隨時可以重新執行不帶 --install-method git 的安裝程式，切回穩定版。

提示：請 agent 規劃並監督修正（逐步），然後只執行 必要命令。這能讓變更更小，也更容易稽核。

如果你發現真正的 bug 或修正，請建立 GitHub issue 或送出 PR： https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls

先從這些命令開始（求助時請分享輸出）：

openclaw statusopenclaw models statusopenclaw doctor

它們的作用：

• openclaw status: Gateway/agent 健康狀態 + 基本設定的快速快照。
• openclaw models status: 檢查 provider 驗證 + 模型可用性。
• openclaw doctor: 驗證並修復常見的設定/狀態問題。

其他實用的 CLI 檢查：openclaw status --all、openclaw logs --follow、 openclaw gateway status、openclaw health --verbose。

快速除錯流程：如果有東西壞了，前 60 秒該做什麼。 安裝文件：安裝、安裝程式旗標、更新。

常見的 Heartbeat 跳過原因：

• quiet-hours: 位於已設定的作用時段之外
• empty-heartbeat-file: HEARTBEAT.md 存在，但只包含空白/僅標頭的骨架內容
• no-tasks-due: HEARTBEAT.md 任務模式已啟用，但尚未有任何任務間隔到期
• alerts-disabled: 所有 Heartbeat 可見性都已停用（showOk、showAlerts 和 useIndicator 全部關閉）

在任務模式中，到期時間戳只會在真正的 Heartbeat 執行 完成後才會前進。被跳過的執行不會將任務標記為已完成。

文件：Heartbeat、自動化。

repo 建議從原始碼執行並使用 onboarding：

curl -fsSL https://openclaw.ai/install.sh | bashopenclaw onboard --install-daemon

精靈也可以自動建置 UI 資產。onboarding 之後，你通常會在連接埠 18789 上執行 Gateway。

從原始碼（貢獻者/dev）：

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm buildpnpm ui:buildopenclaw onboard

如果你還沒有全域安裝，請透過 pnpm openclaw onboard 執行。

精靈會在 onboarding 後立即用乾淨的（非 tokenized）儀表板 URL 開啟瀏覽器，並且也會在摘要中列印連結。請保持該分頁開啟；如果沒有啟動，請在同一台機器上複製/貼上列印出的 URL。

Localhost（同一台機器）：

• 開啟 http://127.0.0.1:18789/。
• 如果它要求 shared-secret 驗證，請將已設定的 token 或 password 貼到 Control UI 設定中。
• Token 來源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• Password 來源：gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 如果尚未設定 shared secret，請用 openclaw doctor --generate-gateway-token 產生 token。

不在 localhost 上：

• Tailscale Serve（建議）：保持 bind loopback，執行 openclaw gateway --tailscale serve，開啟 https://<magicdns>/。如果 gateway.auth.allowTailscale 是 true，identity headers 會滿足 Control UI/WebSocket 驗證（無需貼上 shared secret，假設 gateway host 可信）；HTTP API 仍需要 shared-secret 驗證，除非你刻意使用 private-ingress none 或 trusted-proxy HTTP auth。 來自同一 client 的錯誤並行 Serve 驗證嘗試，會在 failed-auth limiter 記錄前被序列化，因此第二次錯誤重試可能已經顯示 retry later。
• Tailnet bind：執行 openclaw gateway --bind tailnet --token "<token>"（或設定 password auth），開啟 http://<tailscale-ip>:18789/，然後在儀表板設定中貼上相符的 shared secret。
• 具身分感知的 reverse proxy：將 Gateway 保持在受信任的 proxy 後方，設定 gateway.auth.mode: "trusted-proxy"，然後開啟 proxy URL。同主機 loopback proxy 需要明確設定 gateway.auth.trustedProxy.allowLoopback = true。
• SSH tunnel：ssh -N -L 18789:127.0.0.1:18789 user@host，然後開啟 http://127.0.0.1:18789/。shared-secret 驗證仍會套用於 tunnel；若出現提示，請貼上已設定的 token 或 password。

請參閱 儀表板 和 Web surfaces 了解 bind 模式與驗證詳細資訊。

它們控制不同層：

• approvals.exec: 將 approval prompts 轉送到 chat destinations
• channels.<channel>.execApprovals: 讓該 channel 作為 exec approvals 的 native approval client

host exec policy 仍是真正的 approval gate。Chat 設定只控制 approval prompts 顯示在哪裡，以及人們如何回覆。

多數設定中你不需要兩者：

• 如果 chat 已支援命令與回覆，same-chat /approve 會透過共用路徑運作。
• 如果受支援的 native channel 可以安全推斷 approvers，當 channels.<channel>.execApprovals.enabled 未設定或為 "auto" 時，OpenClaw 現在會自動啟用 DM-first native approvals。
• 當 native approval cards/buttons 可用時，該 native UI 是主要路徑；agent 只有在工具結果表示 chat approvals 不可用，或手動 approval 是唯一路徑時，才應包含手動 /approve 命令。
• 只有在 prompts 也必須轉送到其他 chats 或明確的 ops rooms 時，才使用 approvals.exec。
• 只有在你明確想把 approval prompts 發回原始 room/topic 時，才使用 channels.<channel>.execApprovals.target: "channel" 或 "both"。
• Plugin approvals 又是分開的：它們預設使用 same-chat /approve、可選的 approvals.plugin 轉送，且只有部分 native channels 會在其上保留 plugin-approval-native 處理。

簡短版：forwarding 用於路由，native client config 用於更豐富的 channel-specific UX。 請參閱 Exec Approvals。

需要 Node >= 22。建議使用 pnpm。Gateway 不建議使用 Bun。

可以。Gateway 很輕量，文件列出的個人使用需求為 512MB-1GB RAM、1 core， 以及約 500MB 磁碟空間，並註明 Raspberry Pi 4 可以執行它。

如果你想要更多餘裕（日誌、媒體、其他服務），建議 2GB，但這 不是硬性最低需求。

提示：小型 Pi/VPS 可以託管 Gateway，而你可以在筆電/手機上配對 nodes， 供本機螢幕/相機/canvas 或命令執行使用。請參閱 Nodes。

簡短版：可以運作，但預期會有粗糙邊角。

• 使用 64-bit OS，並保持 Node >= 22。
• 優先使用可修改的（git）安裝，這樣你可以查看日誌並快速更新。
• 先不要啟用 channels/skills，然後逐一加入。
• 如果遇到奇怪的二進位問題，通常是 ARM compatibility 問題。

文件：Linux、安裝。

該畫面依賴 Gateway 可連線且已驗證。TUI 也會在首次 hatch 時自動傳送 "Wake up, my friend!"。如果你看到那行但沒有回覆， 且 tokens 維持 0，表示 agent 從未執行。

1. 重新啟動 Gateway：

openclaw gateway restart

2. 檢查狀態 + 驗證：

openclaw statusopenclaw models statusopenclaw logs --follow

3. 如果仍然卡住，執行：

openclaw doctor

如果 Gateway 是遠端的，請確認 tunnel/Tailscale 連線已啟動，且 UI 指向正確的 Gateway。請參閱 遠端存取。

可以。複製狀態目錄和工作區，然後執行一次 Doctor。只要你複製兩個 位置，這會讓你的 bot 保持「完全相同」（memory、工作階段歷史、驗證和 channel 狀態）：

1. 在新機器上安裝 OpenClaw。
2. 從舊機器複製 $OPENCLAW_STATE_DIR（預設：~/.openclaw）。
3. 複製你的工作區（預設：~/.openclaw/workspace）。
4. 執行 openclaw doctor 並重新啟動 Gateway 服務。

這會保留設定、auth profiles、WhatsApp creds、sessions 和 memory。如果你處於 遠端模式，請記得 gateway host 擁有 session store 和 workspace。

重要：如果你只把工作區 commit/push 到 GitHub，就是備份了 memory + bootstrap files，但沒有備份 session history 或 auth。它們位於 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。

相關：遷移、磁碟上的位置、 Agent 工作區、Doctor、 遠端模式。

查看 GitHub changelog： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

最新項目位於頂部。如果頂端區段標示為 Unreleased，下一個有日期的 區段就是最新已發佈版本。項目會依 Highlights、Changes 和 Fixes 分組（需要時也會有 docs/其他區段）。

部分 Comcast/Xfinity 連線會被 Xfinity Advanced Security 錯誤封鎖 docs.openclaw.ai。請停用它或將 docs.openclaw.ai 加入 allowlist，然後重試。 請在此回報，協助我們解除封鎖：https://spa.xfinity.com/check_url_status。

如果你仍無法連上該網站，文件在 GitHub 上有鏡像： https://github.com/openclaw/openclaw/tree/main/docs

Stable 和 beta 是 npm dist-tags，不是不同的程式碼線：

• latest = 穩定版
• beta = 早期測試建置

通常，穩定版會先發佈到 beta，然後透過明確的 推廣步驟將同一個版本移到 latest。維護者也可以在需要時 直接發佈到 latest。這就是為什麼 beta 和 stable 在推廣後 可以指向同一個版本。

查看變更內容： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

如需安裝單行指令，以及 beta 和 dev 的差異，請參閱下方的手風琴區塊。

Beta 是 npm dist-tag beta（推廣後可能與 latest 相同）。 Dev 是 main（git）的移動前端；發佈時會使用 npm dist-tag dev。

單行指令（macOS/Linux）：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Windows 安裝程式（PowerShell）： https://openclaw.ai/install.ps1

更多詳細資訊：開發通道和安裝程式旗標。

兩個選項：

1. Dev 通道（git checkout）：

openclaw update --channel dev

這會切換到 main 分支，並從原始碼更新。

2. 可修改安裝（來自安裝程式網站）：

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

這會給你一個可編輯的本機 repo，之後可透過 git 更新。

如果你偏好手動乾淨複製，請使用：

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm build

文件：更新、開發通道、 安裝。

粗略指南：

• 安裝： 2-5 分鐘
• 入門設定： 5-15 分鐘，取決於你設定的通道/模型數量

如果卡住，請使用安裝程式卡住 以及我卡住了中的快速偵錯迴圈。

使用詳細輸出重新執行安裝程式：

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

使用詳細輸出的 beta 安裝：

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

可修改（git）安裝：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

Windows（PowerShell）對應作法：

# install.ps1 has no dedicated -Verbose flag yet.Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-PSDebug -Trace 0

更多選項：安裝程式旗標。

兩個常見的 Windows 問題：

1) npm error spawn git / 找不到 git

• 安裝 Git for Windows，並確認 git 位於你的 PATH。
• 關閉並重新開啟 PowerShell，然後重新執行安裝程式。

2) 安裝後無法辨識 openclaw

• 你的 npm 全域 bin 資料夾不在 PATH 上。

• 檢查路徑：

  npm config get prefix

• 將該目錄加入你的使用者 PATH（Windows 不需要 \bin 後綴；在大多數系統上是 %AppData%\npm）。

• 更新 PATH 後，關閉並重新開啟 PowerShell。

如果你想要最順暢的 Windows 設定，請使用 WSL2，而不是原生 Windows。 文件：Windows。

這通常是原生 Windows shell 上的主控台字碼頁不相符。

症狀：

• system.run/exec 輸出將中文呈現為亂碼
• 同一個命令在另一個終端機設定檔中看起來正常

PowerShell 中的快速因應方式：

chcp 65001[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

然後重新啟動 Gateway 並重試你的命令：

openclaw gateway restart

如果你在最新版 OpenClaw 上仍能重現，請在此追蹤/回報：

• Issue #30640

使用可修改（git）安裝，讓你在本機擁有完整原始碼和文件，然後 從該資料夾向你的機器人（或 Claude/Codex）提問，讓它能讀取 repo 並精準回答。

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

更多詳細資訊：安裝和安裝程式旗標。

簡短回答：依照 Linux 指南操作，然後執行入門設定。

• Linux 快速路徑 + 服務安裝：Linux。
• 完整逐步指南：開始使用。
• 安裝程式 + 更新：安裝與更新。

任何 Linux VPS 都可以。安裝在伺服器上，然後使用 SSH/Tailscale 連到 Gateway。

指南：exe.dev、Hetzner、Fly.io。 遠端存取：Gateway 遠端。

我們維護了一個託管中心，涵蓋常見供應商。選一個並依照指南操作：

• VPS 託管（所有供應商集中在一處）
• Fly.io
• Hetzner
• exe.dev

它在雲端的運作方式：Gateway 在伺服器上執行，你透過 Control UI（或 Tailscale/SSH） 從筆電/手機存取它。你的狀態 + 工作區 會存在伺服器上，因此請將主機視為真實來源並備份。

你可以將節點（Mac/iOS/Android/headless）配對到該雲端 Gateway，以存取 本機螢幕/相機/canvas，或在筆電上執行命令，同時讓 Gateway 保持在雲端。

中心：平台。遠端存取：Gateway 遠端。 節點：節點、節點 CLI。

簡短回答：可以，但不建議。更新流程可能重新啟動 Gateway（這會中斷使用中的工作階段）、可能需要乾淨的 git checkout，且 可能提示確認。較安全的做法：由操作者從 shell 執行更新。

使用 CLI：

openclaw updateopenclaw update statusopenclaw update --channel stable|beta|devopenclaw update --tag <dist-tag|version>openclaw update --no-restart

如果你必須從代理自動化：

openclaw update --yes --no-restartopenclaw gateway restart

文件：更新、更新中。

openclaw onboard 是建議的設定路徑。在本機模式中，它會引導你完成：

• 模型/auth 設定（供應商 OAuth、API keys、Anthropic setup-token，以及 LM Studio 等本機模型選項）
• 工作區位置 + 啟動檔案
• Gateway 設定（bind/port/auth/tailscale）
• 通道（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及 QQ Bot 等內建通道 plugins）
• Daemon 安裝（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 使用者單元）
• 健康檢查和 skills 選擇

如果你設定的模型未知或缺少 auth，它也會警告。

不需要。你可以使用 API keys（Anthropic/OpenAI/其他）執行 OpenClaw，或使用 純本機模型讓你的資料留在裝置上。訂閱（Claude Pro/Max 或 OpenAI Codex）是驗證這些供應商的選用方式。

對 OpenClaw 中的 Anthropic 而言，實務上的區分是：

• Anthropic API key：一般 Anthropic API 計費
• OpenClaw 中的 Claude CLI / Claude 訂閱 auth：Anthropic 員工 告訴我們此用法再次被允許，且除非 Anthropic 發佈新政策，OpenClaw 會將 claude -p 用法視為此整合的核准用法

對長期執行的 gateway 主機而言，Anthropic API keys 仍是更 可預測的設定。OpenAI Codex OAuth 明確支援 OpenClaw 這類外部 工具。

OpenClaw 也支援其他託管訂閱式選項，包括 Qwen Cloud Coding Plan、MiniMax Coding Plan 和 Z.AI / GLM Coding Plan。

文件：Anthropic、OpenAI、 Qwen Cloud、 MiniMax、GLM Models、 本機模型、模型。

可以。

Anthropic 員工告訴我們，OpenClaw 風格的 Claude CLI 用法再次被允許，因此 除非 Anthropic 發佈新政策，OpenClaw 會將 Claude 訂閱 auth 和 claude -p 用法視為 此整合的核准用法。如果你想要最可預測的伺服器端設定，請改用 Anthropic API key。

支援。

Anthropic 員工告訴我們此用法再次被允許，因此除非 Anthropic 發佈新政策， OpenClaw 會將 Claude CLI 重用和 claude -p 用法視為此整合的核准用法。

Anthropic setup-token 仍可作為受支援的 OpenClaw token 路徑，但 OpenClaw 現在在可用時偏好 Claude CLI 重用和 claude -p。 對生產或多使用者工作負載而言，Anthropic API key auth 仍是 更安全、更可預測的選擇。如果你想在 OpenClaw 中使用其他訂閱式託管 選項，請參閱 OpenAI、Qwen / Model Cloud、MiniMax 和 GLM Models。

這表示你目前視窗的 Anthropic 配額/速率限制已用盡。如果你 使用 Claude CLI，請等待視窗重設或升級你的方案。如果你 使用 Anthropic API key，請到 Anthropic Console 檢查用量/帳單，並視需要提高限制。

如果訊息明確是： Extra usage is required for long context requests，表示請求正在嘗試使用 Anthropic 的 1M context beta (context1m: true)。這只有在你的 憑證符合長上下文計費資格時才可用（API key 計費，或 啟用 Extra Usage 的 OpenClaw Claude-login 路徑）。

提示：設定一個後援模型，讓 OpenClaw 在供應商受到速率限制時仍可繼續回覆。 請參閱模型、OAuth，以及 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

是。OpenClaw 內建 Amazon Bedrock (Converse) 供應商。若 AWS env 標記存在，OpenClaw 可以自動探索串流/文字 Bedrock 目錄，並將其合併為隱含的 amazon-bedrock 供應商；否則你可以明確啟用 plugins.entries.amazon-bedrock.config.discovery.enabled，或新增手動供應商項目。請參閱 Amazon Bedrock 和模型供應商。如果你偏好受管理的金鑰流程，在 Bedrock 前方放置 OpenAI 相容 Proxy 仍是有效選項。

OpenClaw 透過 OAuth（ChatGPT 登入）支援 OpenAI Code (Codex)。常見設定請使用 openai/gpt-5.5：ChatGPT/Codex 訂閱驗證，加上 原生 Codex app-server 執行。openai-codex/gpt-* 模型參照屬於 由 openclaw doctor --fix 修復的舊版設定。直接 OpenAI API 金鑰 存取仍可用於非 agent 的 OpenAI API 介面，以及透過排序後的 openai-codex API 金鑰 profile 使用於 agent 模型。 請參閱模型供應商和入門設定（CLI）。

openai-codex 是 ChatGPT/Codex OAuth 的供應商與 auth-profile id。 較舊的設定也將它用作模型前綴：

• openai/gpt-5.5 = ChatGPT/Codex 訂閱驗證，agent 回合使用原生 Codex runtime
• openai-codex/gpt-5.5 = 由 openclaw doctor --fix 修復的舊版模型路由
• openai/gpt-5.5 加上排序後的 openai-codex API 金鑰 profile = OpenAI agent 模型的 API 金鑰驗證
• openai-codex:... = auth profile id，不是模型參照

如果你想使用直接 OpenAI Platform 帳單/限制路徑，請設定 OPENAI_API_KEY。如果你想使用 ChatGPT/Codex 訂閱驗證，請使用 openclaw models auth login --provider openai-codex 登入。模型參照保持為 openai/gpt-5.5；openai-codex/* 模型參照是 openclaw doctor --fix 會改寫的舊版設定。

Codex OAuth 使用由 OpenAI 管理、依方案而定的配額視窗。實務上， 即使兩者綁定同一個帳號，這些限制也可能不同於 ChatGPT 網站/應用程式體驗。

OpenClaw 可以在 openclaw models status 中顯示目前可見的供應商用量/配額視窗， 但它不會捏造或標準化 ChatGPT 網頁版 權益成為直接 API 存取。如果你想使用直接 OpenAI Platform 帳單/限制路徑，請搭配 API 金鑰使用 openai/*。

是。OpenClaw 完整支援 OpenAI Code (Codex) 訂閱 OAuth。 OpenAI 明確允許在 OpenClaw 這類外部工具/工作流程中使用訂閱 OAuth。 入門設定可以替你執行 OAuth 流程。

請參閱 OAuth、模型供應商和入門設定（CLI）。

Gemini CLI 使用的是 Plugin 驗證流程，不是 openclaw.json 中的用戶端 id 或 secret。

步驟：

1. 在本機安裝 Gemini CLI，讓 gemini 位於 PATH
   • Homebrew：brew install gemini-cli
   • npm：npm install -g @google/gemini-cli
2. 啟用 Plugin：openclaw plugins enable google
3. 登入：openclaw models auth login --provider google-gemini-cli --set-default
4. 登入後的預設模型：google-gemini-cli/gemini-3-flash-preview
5. 如果請求失敗，請在 gateway host 上設定 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID

這會將 OAuth token 儲存在 gateway host 的 auth profile 中。詳細資訊：模型供應商。

通常不適合。OpenClaw 需要大型 context + 強安全性；小型顯示卡會截斷並洩漏。如果你必須使用，請在本機（LM Studio）執行你能跑的最大模型 build，並參閱 /gateway/local-models。較小/量化模型會增加 prompt-injection 風險 - 請參閱安全性。

選擇綁定區域的 endpoint。OpenRouter 提供 MiniMax、Kimi 和 GLM 的美國託管選項；選擇美國託管變體即可讓資料留在區域內。你仍可透過使用 models.mode: "merge" 同時列出 Anthropic/OpenAI，讓 fallback 保持可用，同時遵守你選取的區域化供應商。

不需要。OpenClaw 可在 macOS 或 Linux（Windows 透過 WSL2）上執行。Mac mini 是選用的 - 有些人 會買一台作為 always-on host，但小型 VPS、家用伺服器或 Raspberry Pi 等級的機器也可以。

你只在僅限 macOS 的工具上需要 Mac。對於 iMessage，請在任何已登入 Messages 的 Mac 上搭配 imsg 使用 iMessage。如果 Gateway 在 Linux 或其他地方執行，請將 channels.imessage.cliPath 設為會在該 Mac 上執行 imsg 的 SSH wrapper。如果你想使用其他僅限 macOS 的工具，請在 Mac 上執行 Gateway，或配對 macOS node。

文件：iMessage、Nodes、Mac 遠端模式。

你需要某台 macOS 裝置已登入 Messages。它不一定要是 Mac mini - 任何 Mac 都可以。搭配 imsg 使用 iMessage；Gateway 可以在該 Mac 上執行，也可以在其他地方執行並使用 SSH wrapper cliPath。

常見設定：

• 在 Linux/VPS 上執行 Gateway，並將 channels.imessage.cliPath 設為會在已登入 Messages 的 Mac 上執行 imsg 的 SSH wrapper。
• 如果你想要最簡單的單機設定，則在 Mac 上執行所有內容。

文件：iMessage、Nodes、 Mac 遠端模式。

可以。Mac mini 可以執行 Gateway，你的 MacBook Pro 可以作為 node（伴隨裝置）連線。Node 不會執行 Gateway - 它們會提供該裝置上的 額外能力，例如螢幕/相機/canvas 和 system.run。

常見模式：

• Gateway 在 Mac mini 上（always-on）。
• MacBook Pro 執行 macOS app 或 node host，並配對到 Gateway。
• 使用 openclaw nodes status / openclaw nodes list 查看它。

文件：Nodes、Nodes CLI。

不建議使用 Bun。我們看過 runtime bug，尤其是 WhatsApp 和 Telegram。 請使用 Node 以獲得穩定的 Gateway。

如果你仍想試用 Bun，請在非正式環境 Gateway 上進行， 且不要使用 WhatsApp/Telegram。

channels.telegram.allowFrom 是人類傳送者的 Telegram 使用者 ID（數字）。它不是 bot 使用者名稱。

設定流程只會要求數字使用者 ID。如果你的設定中已有舊版 @username 項目，openclaw doctor --fix 可以嘗試解析它們。

較安全（不使用第三方 bot）：

• DM 你的 bot，然後執行 openclaw logs --follow 並讀取 from.id。

官方 Bot API：

• DM 你的 bot，然後呼叫 https://api.telegram.org/bot<bot_token>/getUpdates 並讀取 message.from.id。

第三方（隱私性較低）：

• DM @userinfobot 或 @getidsbot。

請參閱 /channels/telegram。

可以，透過多 agent 路由。將每個傳送者的 WhatsApp DM（peer kind: "direct"，傳送者 E.164 如 +15551234567）綁定到不同的 agentId，讓每個人都有自己的 workspace 和 session store。回覆仍會來自同一個 WhatsApp 帳號，而 DM 存取控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）是每個 WhatsApp 帳號的全域設定。請參閱多 Agent 路由和 WhatsApp。

可以。使用多 agent 路由：為每個 agent 指定自己的預設模型，然後將 inbound routes（供應商帳號或特定 peer）綁定到各個 agent。範例設定位於多 Agent 路由。另請參閱模型和設定。

可以。Homebrew 支援 Linux（Linuxbrew）。快速設定：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profileeval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"brew install <formula>

如果你透過 systemd 執行 OpenClaw，請確保 service PATH 包含 /home/linuxbrew/.linuxbrew/bin（或你的 brew prefix），讓 brew 安裝的工具可在非登入 shell 中解析。 近期 build 也會在 Linux systemd service 上前置常見使用者 bin 目錄（例如 ~/.local/bin、~/.npm-global/bin、~/.local/share/pnpm、~/.bun/bin），並在設定時遵守 PNPM_HOME、NPM_CONFIG_PREFIX、BUN_INSTALL、VOLTA_HOME、ASDF_DATA_DIR、NVM_DIR 和 FNM_DIR。

• **可修改（git）安裝：**完整原始碼 checkout，可編輯，最適合貢獻者。 你會在本機執行 build，並可修補程式碼/文件。
• **npm 安裝：**全域 CLI 安裝，沒有 repo，最適合「只想直接執行」。 更新來自 npm dist-tag。

文件：開始使用、更新。

可以。當 OpenClaw 已安裝時，使用 openclaw update --channel ...。 這不會刪除你的資料 - 它只會變更 OpenClaw 程式碼安裝。 你的狀態（~/.openclaw）和 workspace（~/.openclaw/workspace）會保持不變。

從 npm 到 git：

openclaw update --channel dev

從 git 到 npm：

openclaw update --channel stable

加上 --dry-run 可先預覽計畫中的模式切換。更新程式會執行 Doctor 後續處理、重新整理目標 channel 的 plugin source，並在你未傳入 --no-restart 時 重新啟動 Gateway。

安裝程式也可以強制使用任一模式：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method gitcurl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

備份提示：請參閱備份策略。

簡短回答：如果你想要 24/7 可靠性，請使用 VPS。如果你想要 最低摩擦，且可以接受睡眠/重新啟動，就在本機執行。

筆電（本機 Gateway）

• **優點：**沒有伺服器成本、可直接存取本機檔案、即時瀏覽器視窗。
• **缺點：**睡眠/網路中斷 = 斷線、作業系統更新/重開機會中斷、必須保持喚醒。

VPS / 雲端

• 優點： 永遠在線、網路穩定、不會有筆電睡眠問題、較容易持續運作。
• 缺點： 通常以無頭模式執行（使用螢幕截圖）、只能遠端存取檔案，更新時必須使用 SSH。

OpenClaw 專屬備註： WhatsApp/Telegram/Slack/Mattermost/Discord 都能在 VPS 上正常運作。唯一真正的取捨是無頭瀏覽器與可見視窗之間的差異。請參閱 瀏覽器。

建議預設： 如果你之前遇過 Gateway 中斷連線，建議使用 VPS。當你正在主動使用 Mac，並且想要本機檔案存取或透過可見瀏覽器進行 UI 自動化時，本機執行很適合。

不是必要，但建議這麼做以提升可靠性與隔離性。

• 專用主機（VPS/Mac mini/Pi）： 永遠在線、較少睡眠/重新啟動中斷、權限更乾淨、較容易持續運作。
• 共用筆電/桌機： 用於測試和主動使用完全沒問題，但機器睡眠或更新時會暫停。

如果你想兼顧兩者，請將 Gateway 保持在專用主機上，並將你的筆電配對為用於本機螢幕/相機/執行工具的 Node。請參閱 Nodes。 如需安全性指引，請閱讀 安全性。

OpenClaw 很輕量。對於基本 Gateway 加上一個聊天頻道：

• 絕對最低需求： 1 vCPU、1GB RAM、約 500MB 磁碟空間。
• 建議： 1-2 vCPU、2GB RAM 或更多，以保留餘裕（日誌、媒體、多個頻道）。Node 工具和瀏覽器自動化可能會消耗較多資源。

作業系統：使用 Ubuntu LTS（或任何現代 Debian/Ubuntu）。Linux 安裝路徑在此環境中測試最完整。

文件：Linux、VPS 託管。

可以。請把 VM 視為 VPS：它需要保持開機、可連線，並且有足夠 RAM 可供 Gateway 和你啟用的任何頻道使用。

基準指引：

• 絕對最低需求： 1 vCPU、1GB RAM。
• 建議： 如果你執行多個頻道、瀏覽器自動化或媒體工具，請使用 2GB RAM 或更多。
• 作業系統： Ubuntu LTS 或其他現代 Debian/Ubuntu。

如果你使用 Windows，WSL2 是最簡單的 VM 風格設定，並且具備最佳工具 相容性。請參閱 Windows、VPS 託管。 如果你在 VM 中執行 macOS，請參閱 macOS VM。