常見問題 - OpenClaw

快速解答，加上針對真實環境設定（本機開發、VPS、多代理、OAuth/API 金鑰、模型容錯移轉）的深入疑難排解。執行階段診斷請參閱疑難排解。完整設定參考請參閱設定。

如果發生故障，前 60 秒先做這些

快速狀態（第一項檢查）
```
openclaw status
```
快速本機摘要：作業系統 + 更新、gateway/服務可達性、代理/工作階段、提供者設定 + 執行階段問題（當 gateway 可達時）。
可貼上的報告（可安全分享）
```
openclaw status --all
```
唯讀診斷，包含日誌尾端（權杖已遮蔽）。
Daemon + 連接埠狀態
```
openclaw gateway status
```
顯示 supervisor 執行階段與 RPC 可達性、探測目標 URL，以及服務可能使用的設定。
深度探測
```
openclaw status --deep
```
執行即時 Gateway 健康探測，支援時也包含頻道探測（需要可達的 Gateway）。請參閱健康狀態。
追蹤最新日誌
```
openclaw logs --follow
```
如果 RPC 無法使用，請改用：
```
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
```
檔案日誌與服務日誌是分開的；請參閱日誌記錄與疑難排解。
執行 doctor（修復）
```
openclaw doctor
```
修復/遷移設定與狀態，並執行健康檢查。請參閱Doctor。

Gateway 快照

openclaw health --json
openclaw health --verbose   # shows the target URL + config path on errors

向正在執行的 Gateway 要求完整快照（僅限 WS）。請參閱健康狀態。

快速開始與首次執行設定

首次執行的問答 — 安裝、onboard、驗證路由、訂閱、初始失敗 — 位於首次執行 FAQ。

OpenClaw 是什麼？

What is OpenClaw, in one paragraph?

OpenClaw 是你在自己裝置上執行的個人 AI 助理。它會在你已經使用的通訊介面上回覆（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 這類隨附的頻道 Plugin），也能在支援的平台上使用語音 + 即時 Canvas。Gateway 是常駐的控制平面；助理本身才是產品。

Value proposition

OpenClaw 不只是「Claude 包裝器」。它是一個本機優先的控制平面，讓你能在自己的硬體上執行能力完整的助理，並從你已經使用的聊天應用程式連線使用，具備有狀態工作階段、記憶和工具，而不必把工作流程的控制權交給託管式 SaaS。重點：

你的裝置，你的資料： 在你想要的任何地方執行 Gateway（Mac、Linux、VPS），並將工作區 + 工作階段歷史保留在本機。
真實頻道，不是網頁沙盒： WhatsApp/Telegram/Slack/Discord/Signal/iMessage/等等，加上支援平台上的行動語音和 Canvas。
模型無關： 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，並可針對每個代理設定路由與容錯移轉。
僅限本機選項： 執行本機模型，因此如果你願意，所有資料都可以留在你的裝置上。
多代理路由： 依頻道、帳戶或任務分離代理，每個代理都有自己的工作區和預設值。
開源且可改造： 可以檢查、擴充並自行託管，不受供應商鎖定。

文件：Gateway、頻道、多代理、記憶。

I just set it up - what should I do first?

適合一開始做的專案：

建立網站（WordPress、Shopify，或簡單的靜態網站）。
製作行動應用程式原型（大綱、畫面、API 規劃）。
整理檔案和資料夾（清理、命名、標記）。
連接 Gmail 並自動化摘要或後續追蹤。

它可以處理大型任務，但當你把任務切分成階段，並使用子代理進行平行工作時，效果最好。

What are the top five everyday use cases for OpenClaw?

日常最有感的成果通常像這樣：

個人簡報： 摘要你關心的收件匣、行事曆和新聞。
研究與撰寫： 快速研究、摘要，以及電子郵件或文件的初稿。
提醒與後續追蹤： 由 Cron 或 Heartbeat 驅動的提醒和檢查清單。
瀏覽器自動化： 填寫表單、收集資料，以及重複執行網頁任務。
跨裝置協調： 從手機送出任務，讓 Gateway 在伺服器上執行，並在聊天中取回結果。

Can OpenClaw help with lead gen, outreach, ads, and blogs for a SaaS?

可以，用於研究、資格判定和草稿撰寫。它可以掃描網站、建立候選名單、摘要潛在客戶，並撰寫外展或廣告文案草稿。對於外展或廣告投放，請保留人工審核。避免垃圾訊息，遵循當地法律與平台政策，並在送出任何內容前先審閱。最安全的模式是讓 OpenClaw 撰寫草稿，由你核准。文件：安全性。

What are the advantages vs Claude Code for web development?

OpenClaw 是個人助理與協調層，不是 IDE 的替代品。在 repo 內需要最快的直接程式碼迭代時，請使用 Claude Code 或 Codex。當你需要持久記憶、跨裝置存取和工具協調時，請使用 OpenClaw。優勢：

跨工作階段的持久記憶 + 工作區
多平台存取（WhatsApp、Telegram、TUI、WebChat）
工具協調（瀏覽器、檔案、排程、hooks）
常駐 Gateway（在 VPS 上執行，從任何地方互動）
用於本機瀏覽器/螢幕/相機/exec 的 Node

展示：https://openclaw.ai/showcase

Skills 與自動化

How do I customize skills without keeping the repo dirty?

使用受管理的覆寫，而不是編輯 repo 內的副本。將你的變更放在 ~/.openclaw/skills/<name>/SKILL.md（或透過 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 加入資料夾）。優先順序是 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 隨附項目 → skills.load.extraDirs，因此受管理的覆寫仍會勝過隨附的 Skills，而不必碰 git。如果你需要全域安裝該 Skill，但只讓部分代理看見，請將共用副本放在 ~/.openclaw/skills，並用 agents.defaults.skills 和 agents.list[].skills 控制可見性。只有值得上游收錄的編輯才應放在 repo 中並以 PR 送出。

Can I load skills from a custom folder?

可以。透過 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 加入額外目錄（最低優先順序）。預設優先順序是 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 隨附項目 → skills.load.extraDirs。clawhub 預設會安裝到 ./skills，OpenClaw 會在下一個工作階段將其視為 <workspace>/skills。如果該 Skill 只應對特定代理可見，請搭配 agents.defaults.skills 或 agents.list[].skills。

How can I use different models for different tasks?

目前支援的模式如下：

Cron 工作：隔離工作可以針對每個工作設定 model 覆寫。
子代理：將任務路由到預設模型不同的獨立代理。
隨需切換：使用 /model 隨時切換目前工作階段模型。

請參閱 Cron 工作、多代理路由和斜線命令。

The bot freezes while doing heavy work. How do I offload that?

對於長時間或平行任務，請使用子代理。子代理會在自己的工作階段中執行，回傳摘要，並讓你的主要聊天保持回應。請要求你的機器人「為此任務產生一個子代理」，或使用 /subagents。在聊天中使用 /status 查看 Gateway 目前正在做什麼（以及是否忙碌）。權杖提示：長任務和子代理都會消耗權杖。如果你擔心成本，請透過 agents.defaults.subagents.model 為子代理設定較便宜的模型。文件：子代理、背景任務。

How do thread-bound subagent sessions work on Discord?

使用討論串繫結。你可以將 Discord 討論串繫結到子代理或工作階段目標，讓該討論串中的後續訊息留在該繫結工作階段上。基本流程：

使用 sessions_spawn 並搭配 thread: true 產生（也可選用 mode: "session" 以便持久後續追蹤）。
或使用 /focus <target> 手動繫結。
使用 /agents 檢查繫結狀態。
使用 /session idle <duration|off> 和 /session max-age <duration|off> 控制自動取消聚焦。
使用 /unfocus 分離討論串。

必要設定：

全域預設值：session.threadBindings.enabled、session.threadBindings.idleHours、session.threadBindings.maxAgeHours。
Discord 覆寫：channels.discord.threadBindings.enabled、channels.discord.threadBindings.idleHours、channels.discord.threadBindings.maxAgeHours。
產生時自動繫結：channels.discord.threadBindings.spawnSessions 預設為 true；設為 false 可停用討論串繫結的工作階段產生。

文件：子代理、Discord、設定參考、斜線命令。

A subagent finished, but the completion update went to the wrong place or never posted. What should I check?

先檢查解析後的請求者路由：

完成模式的子代理傳遞，會優先使用任何已繫結的討論串或對話路由（如果存在）。
如果完成來源只帶有頻道，OpenClaw 會退回使用請求者工作階段中儲存的路由（lastChannel / lastTo / lastAccountId），因此直接傳遞仍可能成功。
如果既沒有已繫結路由，也沒有可用的已儲存路由，直接傳遞可能失敗，結果會改為退回到排隊的工作階段傳遞，而不是立即張貼到聊天。
無效或過期的目標仍可能強制退回佇列，或導致最終傳遞失敗。
如果子項最後可見的助理回覆是精確的靜默權杖 NO_REPLY / no_reply，或精確為 ANNOUNCE_SKIP，OpenClaw 會刻意抑制公告，而不是張貼較早的過期進度。
如果子項在只有工具呼叫之後逾時，公告可能會將其摺疊成簡短的部分進度摘要，而不是重播原始工具輸出。

偵錯：

openclaw tasks show <runId-or-sessionKey>

文件：子代理、背景任務、工作階段工具。

Cron or reminders do not fire. What should I check?

Cron 在 Gateway 程序內執行。如果 Gateway 沒有持續執行，排程工作就不會執行。檢查清單：

確認 Cron 已啟用（cron.enabled），且未設定 OPENCLAW_SKIP_CRON。
檢查 Gateway 是否 24/7 執行（沒有睡眠/重新啟動）。
驗證工作的時區設定（--tz 與主機時區）。

偵錯：

openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50

文件：Cron 工作、自動化。

Cron 已觸發，但沒有傳送任何內容到頻道。為什麼？

請先檢查傳送模式：

--no-deliver / delivery.mode: "none" 表示不預期有執行器備援傳送。
缺少或無效的公告目標（channel / to）表示執行器略過了對外傳送。
頻道驗證失敗（unauthorized、Forbidden）表示執行器嘗試傳送，但認證資料阻擋了它。
靜默的隔離結果（只有 NO_REPLY / no_reply）會被視為有意不可傳送，因此執行器也會抑制佇列中的備援傳送。

對於隔離 Cron 工作，當聊天路由可用時，代理程式仍可使用 message 工具直接傳送。--announce 只控制執行器的備援路徑，用於代理程式尚未傳送的最終文字。除錯：

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

文件：Cron 工作、背景任務。

為什麼隔離 Cron 執行會切換模型或重試一次？

這通常是即時模型切換路徑，而不是重複排程。隔離 Cron 可以保留執行階段模型交接，並在作用中執行擲出 LiveSessionModelSwitchError 時重試。重試會保留切換後的 provider/model；如果切換帶有新的驗證設定檔覆寫，Cron 也會在重試前保留它。相關選擇規則：

Gmail hook 模型覆寫在適用時優先。
然後是各工作的 model。
然後是任何已儲存的 Cron 工作階段模型覆寫。
然後是一般代理程式/預設模型選擇。

重試迴圈有上限。初次嘗試加上 2 次切換重試後， Cron 會中止，而不是永遠迴圈。除錯：

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

文件：Cron 工作、Cron CLI。

如何在 Linux 上安裝 Skills？

使用原生 openclaw skills 指令，或將 Skills 放入你的工作區。macOS Skills UI 在 Linux 上不可用。可在 https://clawhub.ai 瀏覽 Skills。

openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check

原生 openclaw skills install 會寫入作用中工作區的 skills/ 目錄。只有在你想發布或同步自己的 Skills 時，才需要安裝獨立的 clawhub CLI。若要在多個代理程式之間共用安裝，請將 Skill 放在 ~/.openclaw/skills 底下，並在你想限制哪些代理程式可看見它時使用 agents.defaults.skills 或 agents.list[].skills。

OpenClaw 可以按排程或持續在背景執行任務嗎？

可以。請使用 Gateway 排程器：

Cron 工作用於排程或週期性任務（會在重新啟動後持續存在）。
Heartbeat用於「主要工作階段」的週期性檢查。
隔離工作用於會發布摘要或傳送到聊天的自主代理程式。

文件：Cron 工作、自動化、 Heartbeat。

我可以從 Linux 執行僅限 Apple macOS 的 Skills 嗎？

不能直接執行。macOS Skills 會受 metadata.openclaw.os 加上必要二進位檔的限制，而且 Skills 只有在 Gateway 主機上符合資格時，才會出現在系統提示中。在 Linux 上，除非你覆寫限制，否則僅限 darwin 的 Skills（例如 apple-notes、apple-reminders、things-mac）不會載入。你有三種受支援的模式：選項 A - 在 Mac 上執行 Gateway（最簡單）。 在 macOS 二進位檔存在的地方執行 Gateway，然後從 Linux 以遠端模式或透過 Tailscale 連線。由於 Gateway 主機是 macOS，Skills 會正常載入。選項 B - 使用 macOS Node（不需 SSH）。 在 Linux 上執行 Gateway，配對一個 macOS Node（選單列應用程式），並在 Mac 上將 Node 執行指令設為「一律詢問」或「一律允許」。當必要二進位檔存在於 Node 上時，OpenClaw 可以將僅限 macOS 的 Skills 視為符合資格。代理程式會透過 nodes 工具執行這些 Skills。如果你選擇「一律詢問」，在提示中核准「一律允許」會將該指令加入允許清單。選項 C - 透過 SSH 代理 macOS 二進位檔（進階）。 將 Gateway 保留在 Linux 上，但讓必要的 CLI 二進位檔解析為會在 Mac 上執行的 SSH 包裝器。接著覆寫 Skill 以允許 Linux，讓它維持符合資格。

為該二進位檔建立 SSH 包裝器（範例：Apple Notes 的 memo）：

#!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

將包裝器放到 Linux 主機的 PATH 上（例如 ~/bin/memo）。

覆寫 Skill 中繼資料（工作區或 ~/.openclaw/skills）以允許 Linux：

---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---

啟動新的工作階段，讓 Skills 快照重新整理。

你們有 Notion 或 HeyGen 整合嗎？

目前沒有內建。選項：

自訂 Skill / Plugin： 最適合可靠的 API 存取（Notion/HeyGen 都有 API）。
瀏覽器自動化： 不需要程式碼也能運作，但較慢且較脆弱。

如果你想依客戶保留情境（代理商工作流程），簡單模式是：

每位客戶一個 Notion 頁面（情境 + 偏好 + 進行中的工作）。
要求代理程式在工作階段開始時擷取該頁面。

如果你想要原生整合，請開啟功能請求，或建置針對那些 API 的 Skill。安裝 Skills：

openclaw skills install <skill-slug>
openclaw skills update --all

原生安裝會落在作用中工作區的 skills/ 目錄。若要在代理程式之間共用 Skills，請將它們放在 ~/.openclaw/skills/<name>/SKILL.md。如果只有部分代理程式應該看見共用安裝，請設定 agents.defaults.skills 或 agents.list[].skills。某些 Skills 預期透過 Homebrew 安裝二進位檔；在 Linux 上這表示 Linuxbrew（請參閱上方的 Homebrew Linux 常見問題項目）。請參閱 Skills、Skills 設定和 ClawHub。

如何搭配 OpenClaw 使用我現有已登入的 Chrome？

使用內建的 user 瀏覽器設定檔，它會透過 Chrome DevTools MCP 連接：

openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot

如果你想使用自訂名稱，請建立明確的 MCP 設定檔：

openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs

此路徑可以使用本機主機瀏覽器或已連線的瀏覽器 Node。如果 Gateway 在其他地方執行，請在瀏覽器所在機器上執行 Node 主機，或改用遠端 CDP。existing-session / user 的目前限制：

動作以 ref 驅動，而不是以 CSS selector 驅動
上傳需要 ref / inputRef，且目前一次支援一個檔案
responsebody、PDF 匯出、下載攔截和批次動作仍需要受管理的瀏覽器或原始 CDP 設定檔

沙箱與記憶體

有專門的沙箱文件嗎？

有。請參閱沙箱。若要查看 Docker 專用設定（Docker 中的完整 Gateway 或沙箱映像檔），請參閱 Docker。

Docker 感覺受限 - 如何啟用完整功能？

預設映像檔以安全性優先，並以 node 使用者執行，因此不包含系統套件、Homebrew 或 bundled browsers。若要使用更完整的設定：

使用 OPENCLAW_HOME_VOLUME 保留 /home/node，讓快取能持續存在。
使用 OPENCLAW_DOCKER_APT_PACKAGES 將系統相依項目烘焙進映像檔。
透過隨附 CLI 安裝 Playwright 瀏覽器： node /app/node_modules/playwright-core/cli.js install chromium
設定 PLAYWRIGHT_BROWSERS_PATH，並確保該路徑會被保留。

文件：Docker、瀏覽器。

我可以用一個代理程式讓私訊保持個人化，但讓群組公開/沙箱化嗎？

可以，如果你的私人流量是私訊，公開流量是群組。使用 agents.defaults.sandbox.mode: "non-main"，讓群組/頻道工作階段（非主要鍵）在已設定的沙箱後端中執行，而主要私訊工作階段保持在主機上。如果你沒有選擇後端，Docker 是預設後端。然後透過 tools.sandbox.tools 限制沙箱工作階段中可用的工具。設定逐步說明 + 範例設定：群組：個人私訊 + 公開群組關鍵設定參考：Gateway 設定

如何將主機資料夾繫結到沙箱？

將 agents.defaults.sandbox.docker.binds 設為 ["host:path:mode"]（例如 "/home/user/src:/src:ro"）。全域與各代理程式繫結會合併；當 scope: "shared" 時，各代理程式繫結會被忽略。對任何敏感內容使用 :ro，並記住繫結會繞過沙箱檔案系統牆。OpenClaw 會同時根據正規化路徑，以及透過最深層既有祖先解析出的標準路徑驗證繫結來源。這表示即使最後一個路徑片段尚不存在，符號連結父層逸出仍會以失敗關閉處理，而且在符號連結解析後仍會套用允許根目錄檢查。請參閱沙箱和沙箱 vs 工具政策 vs 提權，取得範例與安全注意事項。

記憶體如何運作？

OpenClaw 記憶體只是代理程式工作區中的 Markdown 檔案：

memory/YYYY-MM-DD.md 中的每日筆記
MEMORY.md 中經整理的長期筆記（僅主要/私人工作階段）

OpenClaw 也會執行靜默預先 Compaction 記憶體 flush，提醒模型在自動 Compaction 前寫入持久筆記。這只會在工作區可寫入時執行（唯讀沙箱會略過）。請參閱記憶體。

記憶體一直忘記事情。如何讓它記住？

請要求機器人將事實寫入記憶體。長期筆記應放在 MEMORY.md，短期情境則放入 memory/YYYY-MM-DD.md。這仍是我們正在改進的領域。提醒模型儲存記憶會有幫助；它會知道該怎麼做。如果它持續忘記，請確認 Gateway 在每次執行時都使用同一個工作區。文件：記憶體、代理程式工作區。

記憶體會永久保留嗎？有哪些限制？

記憶體檔案位於磁碟上，會持續存在直到你刪除它們為止。限制是你的儲存空間，而不是模型。工作階段情境仍受模型情境視窗限制，因此長對話可能會 Compaction 或截斷。這就是記憶體搜尋存在的原因 - 它只會將相關部分拉回情境中。文件：記憶體、情境。

語意記憶搜尋需要 OpenAI API key 嗎？

只有在你使用 OpenAI embeddings 時才需要。Codex OAuth 涵蓋聊天/補全，但不授予 embeddings 存取權，因此**使用 Codex 登入（OAuth 或 Codex CLI login）**對語意記憶搜尋沒有幫助。OpenAI embeddings 仍然需要真正的 API key（OPENAI_API_KEY 或 models.providers.openai.apiKey）。如果你沒有明確設定提供者，OpenClaw 會在可以解析 API key 時自動選擇提供者（auth profiles、models.providers.*.apiKey 或環境變數）。如果能解析 OpenAI key，會優先使用 OpenAI；否則如果能解析 Gemini key，則使用 Gemini，接著是 Voyage，再來是 Mistral。如果沒有可用的遠端 key，記憶搜尋會保持停用，直到你完成設定。如果你已設定且存在本機模型路徑， OpenClaw 會優先使用 local。明確設定 memorySearch.provider = "ollama" 時，支援 Ollama。如果你偏好維持本機模式，請設定 memorySearch.provider = "local"（並可選擇性設定 memorySearch.fallback = "none"）。如果你想使用 Gemini embeddings，請設定 memorySearch.provider = "gemini" 並提供 GEMINI_API_KEY（或 memorySearch.remote.apiKey）。我們支援 OpenAI、Gemini、Voyage、Mistral、Ollama 或 local embedding 模型 - 設定細節請參閱記憶。

磁碟上的位置

所有與 OpenClaw 搭配使用的資料都會儲存在本機嗎？

不會 - OpenClaw 的狀態是本機的，但外部服務仍會看到你傳送給它們的內容。

**預設為本機：**工作階段、記憶檔案、設定和工作區都位於 Gateway 主機（~/.openclaw + 你的工作區目錄）。
**必要時使用遠端：**你傳送給模型提供者（Anthropic/OpenAI/等）的訊息會送到它們的 API，而聊天平台（WhatsApp/Telegram/Slack/等）會將訊息資料儲存在它們的伺服器上。
**你控制資料足跡：**使用本機模型會讓提示留在你的機器上，但頻道流量仍會經過該頻道的伺服器。

相關：代理程式工作區、記憶。

OpenClaw 將資料儲存在哪裡？

所有內容都位於 $OPENCLAW_STATE_DIR 底下（預設：~/.openclaw）：

路徑	用途
`$OPENCLAW_STATE_DIR/openclaw.json`	主要設定（JSON5）
`$OPENCLAW_STATE_DIR/credentials/oauth.json`	舊版 OAuth 匯入（首次使用時複製到 auth profiles）
`$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json`	Auth profiles（OAuth、API keys，以及選用的 `keyRef`/`tokenRef`）
`$OPENCLAW_STATE_DIR/secrets.json`	`file` SecretRef 提供者的選用檔案後端祕密 payload
`$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json`	舊版相容性檔案（靜態 `api_key` 項目已清除）
`$OPENCLAW_STATE_DIR/credentials/`	提供者狀態（例如 `whatsapp/<accountId>/creds.json`）
`$OPENCLAW_STATE_DIR/agents/`	每個代理程式的狀態（agentDir + sessions）
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`	對話歷史與狀態（每個代理程式）
`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json`	工作階段中繼資料（每個代理程式）

舊版單一代理程式路徑：~/.openclaw/agent/*（由 openclaw doctor 遷移）。你的工作區（AGENTS.md、記憶檔案、skills 等）是分開的，並透過 agents.defaults.workspace 設定（預設：~/.openclaw/workspace）。

AGENTS.md / SOUL.md / USER.md / MEMORY.md 應該放在哪裡？

這些檔案位於代理程式工作區，不是 ~/.openclaw。

工作區（每個代理程式）：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、 MEMORY.md、memory/YYYY-MM-DD.md、選用的 HEARTBEAT.md。小寫根目錄 memory.md 僅作為舊版修復輸入；當兩個檔案同時存在時，openclaw doctor --fix 可以將它合併進 MEMORY.md。
狀態目錄（~/.openclaw）：設定、頻道/提供者狀態、auth profiles、sessions、記錄檔，以及共用 skills（~/.openclaw/skills）。

預設工作區是 ~/.openclaw/workspace，可透過以下設定：

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

如果機器人在重新啟動後「忘記」內容，請確認 Gateway 每次啟動都使用相同的工作區（並記住：遠端模式使用的是 gateway 主機的 工作區，而不是你的本機筆電）。提示：如果你想要持久的行為或偏好，請要求機器人將它寫入 AGENTS.md 或 MEMORY.md，而不是依賴聊天歷史。請參閱代理程式工作區和記憶。

建議的備份策略

將你的代理程式工作區放入私有 git repo，並備份到某個私有位置（例如 GitHub private）。這會保留記憶 + AGENTS/SOUL/USER 檔案，並讓你之後能還原助理的「心智」。不要提交 ~/.openclaw 底下的任何內容（憑證、工作階段、token 或加密祕密 payload）。如果你需要完整還原，請分別備份工作區和狀態目錄（請參閱上方的遷移問題）。文件：代理程式工作區。

如何完全解除安裝 OpenClaw？

請參閱專門指南：解除安裝。

代理程式可以在工作區之外運作嗎？

可以。工作區是預設 cwd 和記憶錨點，不是硬性沙箱。相對路徑會在工作區內解析，但除非啟用沙箱，否則絕對路徑可以存取其他主機位置。如果你需要隔離，請使用 agents.defaults.sandbox 或每個代理程式的沙箱設定。如果你想讓某個 repo 成為預設工作目錄，請將該代理程式的 workspace 指向 repo 根目錄。OpenClaw repo 只是原始碼；除非你刻意希望代理程式在其中工作，否則請將工作區分開。範例（repo 作為預設 cwd）：

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}

遠端模式：工作階段儲存區在哪裡？

工作階段狀態由 gateway 主機擁有。如果你處於遠端模式，你在意的工作階段儲存區位於遠端機器，而不是你的本機筆電。請參閱工作階段管理。

設定基礎

設定是什麼格式？在哪裡？

OpenClaw 會從 $OPENCLAW_CONFIG_PATH 讀取選用的 JSON5 設定（預設：~/.openclaw/openclaw.json）：

$OPENCLAW_CONFIG_PATH

如果檔案不存在，它會使用相對安全的預設值（包括預設工作區 ~/.openclaw/workspace）。

我設定了 gateway.bind: "lan"（或 "tailnet"），現在沒有任何東西在監聽 / UI 顯示未授權

非 loopback 綁定需要有效的 gateway 驗證路徑。實務上這表示：

shared-secret auth：token 或 password
gateway.auth.mode: "trusted-proxy" 位於正確設定的身分感知反向代理後方

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

注意：

gateway.remote.token / .password 不會自行啟用本機 gateway auth。
只有在未設定 gateway.auth.* 時，本機呼叫路徑才可以使用 gateway.remote.* 作為 fallback。
對於 password auth，請改為設定 gateway.auth.mode: "password" 加上 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
如果 gateway.auth.token / gateway.auth.password 是透過 SecretRef 明確設定且無法解析，解析會以關閉方式失敗（不會用遠端 fallback 掩蓋）。
Shared-secret 控制 UI 設定會透過 connect.params.auth.token 或 connect.params.auth.password（儲存在 app/UI 設定中）進行驗證。Tailscale Serve 或 trusted-proxy 等帶有身分的模式則使用請求標頭。避免將 shared secrets 放在 URL 中。
使用 gateway.auth.mode: "trusted-proxy" 時，同主機 loopback 反向代理需要明確設定 gateway.auth.trustedProxy.allowLoopback = true，並在 gateway.trustedProxies 中加入 loopback 項目。

為什麼現在 localhost 上需要 token？

OpenClaw 預設會強制執行 gateway auth，包括 loopback。在一般預設路徑中，這表示 token auth：如果未設定明確的 auth 路徑，gateway 啟動會解析為 token 模式，並為該次啟動產生僅限執行階段的 token，因此本機 WS 用戶端必須驗證。當用戶端需要跨重新啟動保持穩定的 secret 時，請明確設定 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。這會阻止其他本機程序呼叫 Gateway。如果你偏好不同的 auth 路徑，可以明確選擇 password 模式（或對身分感知反向代理使用 trusted-proxy）。如果你真的想要開放 loopback，請在設定中明確設定 gateway.auth.mode: "none"。Doctor 可隨時為你產生 token：openclaw doctor --generate-gateway-token。

變更設定後必須重新啟動嗎？

Gateway 會監看設定並支援 hot-reload：

gateway.reload.mode: "hybrid"（預設）：hot-apply 安全變更，針對關鍵變更重新啟動
也支援 hot、restart、off

如何停用有趣的 CLI 標語？

在設定中設定 cli.banner.taglineMode：

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

off：隱藏標語文字，但保留橫幅標題/版本列。
default：每次都使用 All your chats, one OpenClaw.。
random：輪替有趣/季節性標語（預設行為）。
如果你完全不想顯示橫幅，請設定環境變數 OPENCLAW_HIDE_BANNER=1。

如何啟用網頁搜尋（和網頁擷取）？

web_fetch 不需要 API key 即可運作。web_search 取決於你選擇的提供者：

Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 後端提供者需要其一般 API key 設定。
Ollama Web Search 不需要 key，但它使用你設定的 Ollama 主機，且需要 ollama signin。
DuckDuckGo 不需要 key，但它是非官方的 HTML 型整合。
SearXNG 不需要 key/可自架；設定 SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl。

**建議：**執行 openclaw configure --section web 並選擇提供者。環境替代方案：

Brave：BRAVE_API_KEY
Exa：EXA_API_KEY
Firecrawl：FIRECRAWL_API_KEY
Gemini：GEMINI_API_KEY
Grok：XAI_API_KEY
Kimi：KIMI_API_KEY 或 MOONSHOT_API_KEY
MiniMax Search：MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY 或 MINIMAX_API_KEY
Perplexity：PERPLEXITY_API_KEY 或 OPENROUTER_API_KEY
SearXNG：SEARXNG_BASE_URL
Tavily：TAVILY_API_KEY

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}

供應商專屬的網頁搜尋設定現在位於 plugins.entries.<plugin>.config.webSearch.* 底下。舊版 tools.web.search.* 供應商路徑仍會暫時載入以維持相容性，但不應用於新的設定。 Firecrawl 網頁擷取後援設定位於 plugins.entries.firecrawl.config.webFetch.* 底下。注意事項：

如果你使用允許清單，請加入 web_search/web_fetch/x_search 或 group:web。
web_fetch 預設為啟用（除非明確停用）。
如果省略 tools.web.fetch.provider，OpenClaw 會從可用憑證中自動偵測第一個已就緒的擷取後援供應商。目前內建的供應商是 Firecrawl。
常駐程式會從 ~/.openclaw/.env（或服務環境）讀取環境變數。

文件：Web 工具。

config.apply 清除了我的設定。我要如何復原並避免這種情況？

config.apply 會取代整份設定。如果你傳送部分物件，其他所有內容都會被移除。目前的 OpenClaw 會防止許多意外覆寫：

OpenClaw 擁有的設定寫入會在寫入前驗證完整的變更後設定。
無效或具破壞性的 OpenClaw 擁有寫入會被拒絕，並儲存為 openclaw.json.rejected.*。
如果直接編輯導致啟動或熱重新載入中斷，Gateway 會關閉失敗或略過重新載入；它不會重寫 openclaw.json。
openclaw doctor --fix 負責修復，並可在將被拒絕的檔案儲存為 openclaw.json.clobbered.* 時還原最後已知良好的設定。

復原：

檢查 openclaw logs --follow 是否有 Invalid config at、Config write rejected: 或 config reload skipped (invalid config)。
檢查有效設定旁最新的 openclaw.json.clobbered.* 或 openclaw.json.rejected.*。
執行 openclaw config validate 和 openclaw doctor --fix。
只使用 openclaw config set 或 config.patch 複製預期的鍵。
如果你沒有最後已知良好的設定或被拒絕的酬載，請從備份還原，或重新執行 openclaw doctor 並重新設定頻道/模型。
如果這不是預期行為，請回報錯誤並附上你最後已知的設定或任何備份。
本機編碼代理通常可以從日誌或歷史紀錄重建可運作的設定。

避免方式：

小幅變更請使用 openclaw config set。
互動式編輯請使用 openclaw configure。
當你不確定確切路徑或欄位形狀時，請先使用 config.schema.lookup；它會傳回淺層結構描述節點，以及用於深入查看的直接子項摘要。
部分 RPC 編輯請使用 config.patch；config.apply 只保留用於完整設定取代。
如果你在代理執行中使用僅限擁有者的 gateway 工具，它仍會拒絕寫入 tools.exec.ask / tools.exec.security（包括會正規化為相同受保護執行路徑的舊版 tools.bash.* 別名）。

文件：設定、Configure、Gateway 疑難排解、Doctor。

我要如何跨裝置執行具備專門工作者的中央 Gateway？

常見模式是一個 Gateway（例如 Raspberry Pi）加上 Node 和代理：

Gateway（中央）： 擁有頻道（Signal/WhatsApp）、路由和工作階段。
Node（裝置）： Macs/iOS/Android 會作為周邊連線，並公開本機工具（system.run、canvas、camera）。
代理（工作者）： 用於特殊角色的獨立大腦/工作區（例如「Hetzner 維運」、「個人資料」）。
子代理： 當你需要平行處理時，從主要代理產生背景工作。
TUI： 連線到 Gateway 並切換代理/工作階段。

文件：Node、遠端存取、多代理路由、子代理、TUI。

OpenClaw 瀏覽器可以以 headless 執行嗎？

可以。這是一個設定選項：

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

預設值為 false（有介面）。Headless 在某些網站上較可能觸發反機器人檢查。請參閱瀏覽器。Headless 使用相同的 Chromium 引擎，並適用於大多數自動化（表單、點擊、擷取、登入）。主要差異：

沒有可見的瀏覽器視窗（如果需要視覺內容，請使用螢幕截圖）。
某些網站對 headless 模式中的自動化限制更嚴格（CAPTCHA、反機器人）。例如，X/Twitter 經常封鎖 headless 工作階段。

我要如何使用 Brave 進行瀏覽器控制？

將 browser.executablePath 設為你的 Brave 二進位檔（或任何 Chromium 架構的瀏覽器），然後重新啟動 Gateway。請參閱瀏覽器中的完整設定範例。

遠端 Gateway 和 Node

指令如何在 Telegram、gateway 和 Node 之間傳播？

Telegram 訊息由 gateway 處理。gateway 會執行代理，且只有在需要 Node 工具時，才會透過 Gateway WebSocket 呼叫 Node：Telegram → Gateway → 代理 → node.* → Node → Gateway → TelegramNode 不會看到傳入的供應商流量；它們只會接收 Node RPC 呼叫。

如果 Gateway 託管在遠端，我的代理要如何存取我的電腦？

簡短答案：將你的電腦配對為 Node。Gateway 在其他地方執行，但它可以透過 Gateway WebSocket 在你的本機電腦上呼叫 node.* 工具（螢幕、相機、系統）。典型設定：

在永遠開機的主機（VPS/家用伺服器）上執行 Gateway。
將 Gateway 主機和你的電腦放在同一個 tailnet 上。
確保 Gateway WS 可連線（tailnet 綁定或 SSH 通道）。
在本機開啟 macOS app，並以透過 SSH 遠端模式（或直接 tailnet）連線，讓它可以註冊為 Node。

在 Gateway 上核准 Node：

openclaw devices list
openclaw devices approve <requestId>

不需要獨立的 TCP 橋接；Node 會透過 Gateway WebSocket 連線。安全提醒：配對 macOS Node 允許在該電腦上執行 system.run。只配對你信任的裝置，並查看安全性。文件：Node、Gateway 協定、macOS 遠端模式、安全性。

Tailscale 已連線，但我收不到回覆。現在該怎麼辦？

檢查基本項目：

Gateway 正在執行：openclaw gateway status
Gateway 健康狀態：openclaw status
頻道健康狀態：openclaw channels status

接著驗證驗證和路由：

如果你使用 Tailscale Serve，請確定 gateway.auth.allowTailscale 已正確設定。
如果你透過 SSH 通道連線，請確認本機通道已啟動並指向正確的連接埠。
確認你的允許清單（DM 或群組）包含你的帳號。

文件：Tailscale、遠端存取、頻道。

兩個 OpenClaw 執行個體可以彼此交談嗎（本機 + VPS）？

可以。沒有內建的「bot 對 bot」橋接，但你可以用幾種可靠方式串接：最簡單： 使用兩個 bot 都能存取的一般聊天頻道（Telegram/Slack/WhatsApp）。讓 Bot A 傳送訊息給 Bot B，然後讓 Bot B 像平常一樣回覆。CLI 橋接（通用）： 執行一個指令碼，使用 openclaw agent --message ... --deliver 呼叫另一個 Gateway，目標是另一個 bot 監聽的聊天。如果其中一個 bot 位於遠端 VPS，請透過 SSH/Tailscale 將你的 CLI 指向該遠端 Gateway （請參閱遠端存取）。範例模式（從可連到目標 Gateway 的電腦執行）：

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

提示：新增防護措施，避免兩個 bot 無限循環（僅提及、頻道允許清單，或「不要回覆 bot 訊息」規則）。文件：遠端存取、代理 CLI、代理傳送。

多個代理需要個別 VPS 嗎？

不需要。一個 Gateway 可以託管多個代理，每個代理都有自己的工作區、模型預設值和路由。這是一般設定，而且比每個代理執行一台 VPS 便宜且簡單得多。只有在你需要強隔離（安全邊界）或非常不同且不想共用的設定時，才使用個別 VPS。否則，保留一個 Gateway，並使用多個代理或子代理。

相較於從 VPS 使用 SSH，在我的個人筆電上使用 Node 有好處嗎？

有，Node 是從遠端 Gateway 連到你筆電的一等方式，而且解鎖的不只是 shell 存取。Gateway 會在 macOS/Linux（Windows 透過 WSL2）上執行，而且很輕量（小型 VPS 或 Raspberry Pi 等級的機器即可；4 GB RAM 很足夠），所以常見設定是永遠開機的主機加上作為 Node 的筆電。

不需要傳入 SSH。 Node 會向外連線到 Gateway WebSocket 並使用裝置配對。
更安全的執行控制。 system.run 會受到該筆電上的 Node 允許清單/核准把關。
更多裝置工具。 除了 system.run，Node 還會公開 canvas、camera 和 screen。
本機瀏覽器自動化。 將 Gateway 保留在 VPS 上，但透過筆電上的 Node 主機在本機執行 Chrome，或透過 Chrome MCP 附加到主機上的本機 Chrome。

SSH 適合臨時 shell 存取，但 Node 對持續的代理工作流程和裝置自動化更簡單。文件：Node、Node CLI、瀏覽器。

Node 會執行 gateway 服務嗎？

不會。除非你刻意執行隔離的設定檔（請參閱多個 gateway），否則每台主機只應執行一個 gateway。Node 是連線到 gateway 的周邊裝置（iOS/Android Node，或選單列 app 中的 macOS「Node 模式」）。關於 headless Node 主機和 CLI 控制，請參閱 Node 主機 CLI。gateway、discovery 和託管 Plugin 表面變更需要完整重新啟動。

是否有 API / RPC 方式可以套用設定？

有。

config.schema.lookup：在寫入前，檢查一個 config 子樹，以及其淺層 schema 節點、符合的 UI 提示和直接子項摘要
config.get：擷取目前的快照 + hash
config.patch：安全的局部更新（大多數 RPC 編輯的建議做法）；可行時熱重新載入，必要時重新啟動
config.apply：驗證 + 取代完整 config；可行時熱重新載入，必要時重新啟動
僅限擁有者的 gateway 執行階段工具仍會拒絕改寫 tools.exec.ask / tools.exec.security；舊版 tools.bash.* 別名會正規化為相同的受保護 exec 路徑

首次安裝的最小合理 config

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

這會設定你的 workspace，並限制誰可以觸發 bot。

如何在 VPS 上設定 Tailscale，並從我的 Mac 連線？

最小步驟：

在 VPS 上安裝 + 登入

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

在你的 Mac 上安裝 + 登入
- 使用 Tailscale app，並登入同一個 tailnet。
啟用 MagicDNS（建議）
- 在 Tailscale admin console 中啟用 MagicDNS，讓 VPS 有穩定名稱。
使用 tailnet hostname
- SSH：ssh user@your-vps.tailnet-xxxx.ts.net
- Gateway WS：ws://your-vps.tailnet-xxxx.ts.net:18789

如果你想在不使用 SSH 的情況下使用 Control UI，請在 VPS 上使用 Tailscale Serve：

openclaw gateway --tailscale serve

這會讓 gateway 綁定到 loopback，並透過 Tailscale 暴露 HTTPS。請參閱 Tailscale。

如何將 Mac node 連接到遠端 Gateway（Tailscale Serve）？

Serve 會暴露 Gateway Control UI + WS。Node 會透過同一個 Gateway WS endpoint 連線。建議設定：

確認 VPS + Mac 位於同一個 tailnet。
在 Remote mode 使用 macOS app（SSH target 可以是 tailnet hostname）。 app 會 tunnel Gateway port，並以 node 身分連線。

在 gateway 上核准 node：

openclaw devices list
openclaw devices approve <requestId>

文件：Gateway protocol、Discovery、macOS remote mode。

我應該在第二台筆電上安裝，還是只新增一個 node？

如果你只需要第二台筆電上的 local tools（screen/camera/exec），請將它新增為 node。這會保留單一 Gateway，並避免重複 config。Local node tools 目前僅支援 macOS，但我們計畫將它們擴展到其他 OS。只有在你需要 強隔離 或兩個完全分離的 bot 時，才安裝第二個 Gateway。文件：Nodes、Nodes CLI、Multiple gateways。

Env vars 與 .env 載入

OpenClaw 如何載入環境變數？

OpenClaw 會從父行程（shell、launchd/systemd、CI 等）讀取 env vars，並額外載入：

目前工作目錄中的 .env
來自 ~/.openclaw/.env 的全域 fallback .env（也就是 $OPENCLAW_STATE_DIR/.env）

這兩個 .env 檔案都不會覆寫既有的 env vars。你也可以在 config 中定義 inline env vars（只有在 process env 中缺少時才會套用）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

完整優先順序和來源請參閱 /environment。

我透過 service 啟動 Gateway，但我的 env vars 消失了。現在該怎麼辦？

兩個常見修正方式：

將缺少的 keys 放入 ~/.openclaw/.env，如此即使 service 沒有繼承你的 shell env 也能被讀取。
啟用 shell import（選擇性便利功能）：

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

這會執行你的 login shell，且只匯入缺少的預期 keys（絕不覆寫）。Env var 等效項： OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

我設定了 COPILOT_GITHUB_TOKEN，但 models status 顯示 "Shell env: off." 為什麼？

openclaw models status 回報的是 shell env import 是否已啟用。“Shell env: off” 不表示你的 env vars 缺失，這只表示 OpenClaw 不會自動載入你的 login shell。如果 Gateway 以 service（launchd/systemd）執行，它不會繼承你的 shell 環境。請用以下其中一種方式修正：

將 token 放入 ~/.openclaw/.env：
```
COPILOT_GITHUB_TOKEN=...
```
或啟用 shell import（env.shellEnv.enabled: true）。
或將它加入你的 config env block（只有在缺少時才會套用）。

然後重新啟動 gateway 並再次檢查：

openclaw models status

Copilot tokens 會從 COPILOT_GITHUB_TOKEN（也包括 GH_TOKEN / GITHUB_TOKEN）讀取。請參閱 /concepts/model-providers 和 /environment。

Sessions 與多個聊天

如何開始新的對話？

將 /new 或 /reset 作為獨立訊息傳送。請參閱 Session management。

如果我從不傳送 /new，sessions 會自動重設嗎？

Sessions 可以在 session.idleMinutes 之後到期，但這 預設停用（預設為 0）。將它設為正值即可啟用閒置到期。啟用後，閒置期間之後的 下一則 訊息會為該 chat key 啟動新的 session id。這不會刪除 transcripts，只是啟動新的 session。

{
  session: {
    idleMinutes: 240,
  },
}

有辦法建立一組 OpenClaw instances 團隊（一位 CEO 和許多 agents）嗎？

可以，透過 multi-agent routing 和 sub-agents。你可以建立一個 coordinator agent，以及多個擁有各自 workspaces 和 models 的 worker agents。不過，這最好視為一個 有趣的實驗。它會消耗大量 tokens，而且通常不如使用一個 bot 搭配獨立 sessions 有效率。我們設想的典型模型是你與一個 bot 對話，並為平行工作使用不同 sessions。該 bot 也可以在需要時產生 sub-agents。文件：Multi-agent routing、Sub-agents、Agents CLI。

為什麼 context 會在工作途中被截斷？如何避免？

Session context 受 model window 限制。長聊天、大型 tool outputs，或許多檔案都可能觸發 compaction 或 truncation。有幫助的做法：

請 bot 摘要目前狀態，並寫入檔案。
在長任務前使用 /compact，並在切換主題時使用 /new。
將重要 context 保存在 workspace 中，並請 bot 讀回。
對長時間或平行工作使用 sub-agents，讓主聊天保持較小。
如果這種情況經常發生，請選擇 context window 較大的 model。

如何完全重設 OpenClaw 但保留安裝？

使用 reset command：

openclaw reset

非互動式完整重設：

openclaw reset --scope full --yes --non-interactive

然後重新執行 setup：

openclaw onboard --install-daemon

注意：

如果 onboarding 偵測到既有 config，也會提供 Reset。請參閱 Onboarding (CLI)。
如果你使用 profiles（--profile / OPENCLAW_PROFILE），請重設每個 state dir（預設為 ~/.openclaw-<profile>）。
Dev reset：openclaw gateway --dev --reset（僅限 dev；會清除 dev config + credentials + sessions + workspace）。

我遇到 "context too large" 錯誤，該如何 reset 或 compact？

使用以下其中一種：

Compact（保留對話，但摘要較早的 turns）：
```
/compact
```
或使用 /compact <instructions> 來引導摘要。
Reset（為同一個 chat key 建立新的 session ID）：
```
/new
/reset
```

如果持續發生：

啟用或調整 session pruning（agents.defaults.contextPruning）以修剪舊 tool output。
使用 context window 較大的 model。

文件：Compaction、Session pruning、Session management。

為什麼我看到 "LLM request rejected: messages.content.tool_use.input field required"？

這是 provider validation error：model 發出了 tool_use block，但缺少必要的 input。這通常表示 session history 已過時或毀損（常見於長 threads 或 tool/schema change 之後）。修正方式：使用 /new（獨立訊息）開始新的 session。

為什麼我每 30 分鐘就收到 heartbeat 訊息？

Heartbeats 預設每 30m 執行一次（使用 OAuth auth 時為 1h）。請調整或停用它們：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}

如果 HEARTBEAT.md 存在但實際上是空的（只有空白行和 markdown headers，例如 # Heading），OpenClaw 會跳過 heartbeat run 以節省 API calls。如果檔案缺失，heartbeat 仍會執行，並由 model 決定要做什麼。Per-agent overrides 使用 agents.list[].heartbeat。文件：Heartbeat。

我需要將一個 "bot account" 加到 WhatsApp 群組嗎？

不需要。OpenClaw 會在 你自己的 account 上執行，所以如果你在群組中，OpenClaw 就能看到它。預設情況下，group replies 會被封鎖，直到你允許 senders（groupPolicy: "allowlist"）。如果你希望只有你能觸發 group replies：

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

如何取得 WhatsApp 群組的 JID？

選項 1（最快）：tail logs，並在群組中傳送測試訊息：

openclaw logs --follow --json

尋找結尾為 @g.us 的 chatId（或 from），例如： 1234567890-1234567890@g.us。選項 2（如果已設定/allowlisted）：從 config 列出 groups：

openclaw directory groups list --channel whatsapp

文件：WhatsApp、Directory、Logs。

為什麼 OpenClaw 不在群組中回覆？

兩個常見原因：

Mention gating 已開啟（預設）。你必須 @mention bot（或符合 mentionPatterns）。
你設定了 channels.whatsapp.groups，但沒有設定 "*"，且該群組未列入 allowlist。

請參閱 Groups 和 Group messages。

群組/threads 會和 DMs 共用 context 嗎？

Direct chats 預設會收斂到 main session。Groups/channels 有自己的 session keys，而 Telegram topics / Discord threads 則是獨立 sessions。請參閱 Groups 和 Group messages。

我可以建立多少個工作區與代理？

沒有硬性限制。數十個（甚至數百個）都可以，但請留意：

磁碟成長： 工作階段與逐字記錄位於 ~/.openclaw/agents/<agentId>/sessions/ 下。
Token 成本： 更多代理代表更多並行模型使用量。
營運負擔： 每個代理各自的驗證設定檔、工作區與頻道路由。

提示：

每個代理保留一個作用中工作區（agents.defaults.workspace）。
如果磁碟用量成長，請修剪舊工作階段（刪除 JSONL 或儲存項目）。
使用 openclaw doctor 找出零散工作區與設定檔不相符的問題。

我可以同時執行多個機器人或聊天（Slack）嗎？該如何設定？

可以。使用多代理路由來執行多個隔離代理，並依照頻道/帳戶/對等端路由傳入訊息。Slack 支援作為頻道，並可繫結到特定代理。瀏覽器存取功能很強大，但不是「人類能做什麼就能做什麼」；反機器人、CAPTCHA 與 MFA 仍可能阻擋自動化。若要取得最可靠的瀏覽器控制，請在主機上使用本機 Chrome MCP，或在實際執行瀏覽器的機器上使用 CDP。最佳實務設定：

常駐 Gateway 主機（VPS/Mac mini）。
每個角色一個代理（繫結）。
Slack 頻道繫結到這些代理。
需要時透過 Chrome MCP 或 Node 使用本機瀏覽器。

文件：多代理路由、Slack、瀏覽器、Nodes。

模型、故障轉移與驗證設定檔

模型問答（預設值、選擇、別名、切換、故障轉移、驗證設定檔）位於模型常見問題。

Gateway：連接埠、「已在執行」與遠端模式

Gateway 使用哪個連接埠？

gateway.port 控制 WebSocket + HTTP（控制 UI、hook 等）的單一多工連接埠。優先順序：

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

為什麼 openclaw gateway status 顯示「Runtime: running」但「Connectivity probe: failed」？

因為「running」是監督器的視角（launchd/systemd/schtasks）。連線探測則是 CLI 實際連線到 gateway WebSocket。使用 openclaw gateway status，並信任這些行：

Probe target:（探測實際使用的 URL）
Listening:（連接埠上實際繫結的內容）
Last gateway error:（程序仍在執行但連接埠未監聽時的常見根本原因）

為什麼 openclaw gateway status 顯示的「Config (cli)」與「Config (service)」不同？

你正在編輯一個設定檔，但服務正在使用另一個設定檔執行（通常是 --profile / OPENCLAW_STATE_DIR 不相符）。修正：

openclaw gateway install --force

請從你希望服務使用的相同 --profile / 環境執行該命令。

「another gateway instance is already listening」是什麼意思？

OpenClaw 會在啟動時立即繫結 WebSocket 監聽器（預設 ws://127.0.0.1:18789），以強制執行執行階段鎖定。如果繫結因 EADDRINUSE 失敗，會擲出 GatewayLockError，表示另一個執行個體已在監聽。修正：停止另一個執行個體、釋放連接埠，或使用 openclaw gateway --port <port> 執行。

如何以遠端模式執行 OpenClaw（用戶端連線到其他地方的 Gateway）？

設定 gateway.mode: "remote"，並指向遠端 WebSocket URL，可選擇搭配共享祕密遠端憑證：

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

注意：

openclaw gateway 只會在 gateway.mode 為 local 時啟動（或你傳入覆寫旗標）。
macOS app 會監看設定檔，並在這些值變更時即時切換模式。
gateway.remote.token / .password 只是用戶端遠端憑證；它們本身不會啟用本機 gateway 驗證。

控制 UI 顯示「unauthorized」（或一直重新連線）。現在該怎麼辦？

你的 gateway 驗證路徑與 UI 的驗證方法不相符。事實（來自程式碼）：

控制 UI 會將目前瀏覽器分頁工作階段與所選 gateway URL 的 token 保留在 sessionStorage 中，因此同一分頁重新整理仍可繼續運作，而不會恢復長效 localStorage token 持久化。
發生 AUTH_TOKEN_MISMATCH 時，受信任的用戶端可在 gateway 傳回重試提示（canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token）時，使用快取裝置 token 嘗試一次有界限的重試。
該快取 token 重試現在會重用與裝置 token 一起儲存的已核准快取 scope。明確 deviceToken / 明確 scopes 的呼叫者仍會保留其要求的 scope 集合，而不是繼承快取 scope。
在該重試路徑之外，連線驗證優先順序為明確共享 token/password 優先，接著是明確 deviceToken，再來是已儲存裝置 token，最後是 bootstrap token。
Bootstrap token scope 檢查會加上角色前綴。內建 bootstrap operator 允許清單只滿足 operator 要求；node 或其他非 operator 角色仍需要其自身角色前綴下的 scope。

修正：

最快方式：openclaw dashboard（列印並複製儀表板 URL、嘗試開啟；若無頭環境則顯示 SSH 提示）。
如果你還沒有 token：openclaw doctor --generate-gateway-token。
如果是遠端，請先建立隧道：ssh -N -L 18789:127.0.0.1:18789 user@host，然後開啟 http://127.0.0.1:18789/。
共享祕密模式：設定 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD，然後在控制 UI 設定中貼上相符的祕密。
Tailscale Serve 模式：確認 gateway.auth.allowTailscale 已啟用，而且你開啟的是 Serve URL，而不是會繞過 Tailscale 身分標頭的原始 loopback/tailnet URL。
受信任 Proxy 模式：確認你是透過設定好的身分感知 Proxy 進入，而不是使用原始 gateway URL。同主機 loopback Proxy 也需要 gateway.auth.trustedProxy.allowLoopback = true。
如果一次重試後仍不相符，請輪替/重新核准已配對的裝置 token：
- openclaw devices list
- openclaw devices rotate --device <id> --role operator
如果該輪替呼叫表示遭拒，請檢查兩件事：
- 已配對裝置工作階段只能輪替其自身裝置，除非它們也具備 operator.admin
- 明確 --scope 值不能超過呼叫者目前的 operator scope
仍然卡住？執行 openclaw status --all，並依照疑難排解。驗證詳細資訊請參閱儀表板。

我設定了 gateway.bind tailnet，但無法繫結，也沒有任何東西在監聽

tailnet 繫結會從你的網路介面選擇 Tailscale IP（100.64.0.0/10）。如果該機器不在 Tailscale 上（或介面已關閉），就沒有可繫結的目標。修正：

在該主機上啟動 Tailscale（讓它具有 100.x 位址），或
切換到 gateway.bind: "loopback" / "lan"。

注意：tailnet 是明確設定。auto 會偏好 loopback；當你想要僅限 tailnet 的繫結時，請使用 gateway.bind: "tailnet"。

我可以在同一台主機上執行多個 Gateway 嗎？

通常不需要；一個 Gateway 可以執行多個訊息頻道與代理。只有在需要備援（例如救援機器人）或硬隔離時，才使用多個 Gateway。可以，但你必須隔離：

OPENCLAW_CONFIG_PATH（每個執行個體的設定）
OPENCLAW_STATE_DIR（每個執行個體的狀態）
agents.defaults.workspace（工作區隔離）
gateway.port（唯一連接埠）

快速設定（建議）：

每個執行個體使用 openclaw --profile <name> ...（自動建立 ~/.openclaw-<name>）。
在每個設定檔設定中設定唯一的 gateway.port（或手動執行時傳入 --port）。
安裝每個設定檔專用服務：openclaw --profile <name> gateway install。

設定檔也會在服務名稱後加上後綴（ai.openclaw.<profile>；舊版 com.openclaw.*、openclaw-gateway-<profile>.service、OpenClaw Gateway (<profile>)）。完整指南：多個 gateway。

「invalid handshake」/ 代碼 1008 是什麼意思？

Gateway 是 WebSocket 伺服器，並預期第一則訊息必須是 connect frame。如果收到其他任何內容，就會以 代碼 1008（政策違規）關閉連線。常見原因：

你在瀏覽器中開啟了 HTTP URL（http://...），而不是使用 WS 用戶端。
你使用了錯誤的連接埠或路徑。
Proxy 或隧道移除了驗證標頭，或送出了非 Gateway 要求。

快速修正：

使用 WS URL：ws://<host>:18789（如果是 HTTPS 則用 wss://...）。
不要在一般瀏覽器分頁中開啟 WS 連接埠。
如果已啟用驗證，請在 connect frame 中包含 token/password。

如果你使用 CLI 或 TUI，URL 應該長這樣：

openclaw tui --url ws://<host>:18789 --token <token>

協定詳細資訊：Gateway 協定。

記錄與偵錯

記錄在哪裡？

檔案記錄（結構化）：

/tmp/openclaw/openclaw-YYYY-MM-DD.log

你可以透過 logging.file 設定穩定路徑。檔案記錄層級由 logging.level 控制。主控台詳細程度由 --verbose 與 logging.consoleLevel 控制。最快的記錄追蹤：

openclaw logs --follow

服務/監督器記錄（當 gateway 透過 launchd/systemd 執行時）：

macOS：$OPENCLAW_STATE_DIR/logs/gateway.log 與 gateway.err.log（預設：~/.openclaw/logs/...；設定檔使用 ~/.openclaw-<profile>/logs/...）
Linux：journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
Windows：schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

更多資訊請參閱疑難排解。

如何啟動/停止/重新啟動 Gateway 服務？

使用 gateway 輔助命令：

openclaw gateway status
openclaw gateway restart

如果你手動執行 gateway，openclaw gateway --force 可以收回連接埠。請參閱 Gateway。

我在 Windows 上關閉了終端機，該如何重新啟動 OpenClaw？

有兩種 Windows 安裝模式：1) WSL2（建議）： Gateway 在 Linux 內執行。開啟 PowerShell，進入 WSL，然後重新啟動：

wsl
openclaw gateway status
openclaw gateway restart

如果你從未安裝服務，請在前景啟動它：

openclaw gateway run

2) 原生 Windows（不建議）： Gateway 直接在 Windows 中執行。開啟 PowerShell 並執行：

openclaw gateway status
openclaw gateway restart

如果你手動執行它（沒有服務），請使用：

openclaw gateway run

文件：Windows (WSL2)、Gateway 服務操作手冊。

Gateway 已啟動，但回覆從未送達。我該檢查什麼？

先進行快速健康檢查：

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

常見原因：

Gateway 主機上未載入模型身分驗證（檢查 models status）。
頻道配對/允許清單封鎖回覆（檢查頻道設定 + 日誌）。
WebChat/Dashboard 已開啟，但沒有正確的權杖。

如果你是遠端連線，請確認通道/Tailscale 連線已啟用，且 Gateway WebSocket 可連線。文件：頻道、疑難排解、遠端存取。

"已中斷與 Gateway 的連線：沒有原因" - 現在怎麼辦？

這通常表示 UI 失去了 WebSocket 連線。請檢查：

Gateway 是否正在執行？openclaw gateway status
Gateway 是否健康？openclaw status
UI 是否有正確的權杖？openclaw dashboard
如果是遠端，通道/Tailscale 連線是否已啟用？

接著追蹤日誌：

openclaw logs --follow

文件：Dashboard、遠端存取、疑難排解。

Telegram setMyCommands 失敗。我該檢查什麼？

從日誌和頻道狀態開始：

openclaw channels status
openclaw channels logs --channel telegram

接著比對錯誤：

BOT_COMMANDS_TOO_MUCH：Telegram 選單的項目太多。OpenClaw 已經會裁減到 Telegram 限制並以較少指令重試，但某些選單項目仍需要移除。請減少 plugin/skill/自訂指令，或者如果你不需要選單，請停用 channels.telegram.commands.native。
TypeError: fetch failed、Network request for 'setMyCommands' failed!，或類似網路錯誤：如果你在 VPS 上或位於 Proxy 後方，請確認允許對外 HTTPS，且 DNS 可解析 api.telegram.org。

如果 Gateway 是遠端的，請確定你查看的是 Gateway 主機上的日誌。文件：Telegram、頻道疑難排解。

TUI 沒有顯示輸出。我該檢查什麼？

先確認 Gateway 可連線，且代理可以執行：

openclaw status
openclaw models status
openclaw logs --follow

在 TUI 中，使用 /status 查看目前狀態。如果你預期在聊天頻道中收到回覆，請確定已啟用傳送（/deliver on）。文件：TUI、斜線指令。

我要如何完全停止再啟動 Gateway？

如果你已安裝服務：

openclaw gateway stop
openclaw gateway start

這會停止/啟動受監督的服務（macOS 上的 launchd，Linux 上的 systemd）。當 Gateway 以 Daemon 形式在背景執行時，請使用這個方式。如果你是在前景執行，請用 Ctrl-C 停止，然後執行：

openclaw gateway run

文件：Gateway 服務 Runbook。

簡單說明：openclaw gateway restart 與 openclaw gateway

openclaw gateway restart：重新啟動背景服務（launchd/systemd）。
openclaw gateway：在這個終端機工作階段中以前景方式執行 gateway。

如果你已安裝服務，請使用 gateway 指令。當你想要一次性的前景執行時，使用 openclaw gateway。

發生失敗時取得更多詳細資訊的最快方式

使用 --verbose 啟動 Gateway，以取得更多主控台細節。接著檢查日誌檔案中的頻道驗證、模型路由和 RPC 錯誤。

媒體與附件

我的 Skill 產生了圖片/PDF，但沒有送出任何內容

代理的對外附件必須包含一行 MEDIA:<path-or-url>（獨立成行）。請參閱 OpenClaw 助理設定和代理傳送。CLI 傳送：

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

也請檢查：

目標頻道支援對外媒體，且未被允許清單封鎖。
檔案在提供者的大小限制內（圖片會調整為最大 2048px）。
tools.fs.workspaceOnly=true 會將本機路徑傳送限制在工作區、暫存/媒體儲存區，以及經沙盒驗證的檔案。
tools.fs.workspaceOnly=false 允許 MEDIA: 傳送代理已能讀取的主機本機檔案，但僅限媒體加上安全的文件類型（圖片、音訊、影片、PDF 和 Office 文件）。純文字和類似秘密的檔案仍會被封鎖。

請參閱圖片。

安全性與存取控制

將 OpenClaw 暴露給傳入 DM 安全嗎？

將傳入 DM 視為不受信任的輸入。預設值設計用來降低風險：

在支援 DM 的頻道上，預設行為是配對：
- 未知傳送者會收到配對碼；機器人不會處理他們的訊息。
- 使用以下指令核准：openclaw pairing approve --channel <channel> [--account <id>] <code>
- 待處理請求上限為每個頻道 3 個；如果沒有收到代碼，請檢查 openclaw pairing list --channel <channel> [--account <id>]。
公開開放 DM 需要明確選擇加入（dmPolicy: "open" 和允許清單 "*"）。

執行 openclaw doctor 以顯示有風險的 DM 政策。

提示注入只需要擔心公開機器人嗎？

不是。提示注入關乎不受信任的內容，不只是誰可以傳 DM 給機器人。如果你的助理讀取外部內容（網頁搜尋/擷取、瀏覽器頁面、電子郵件、文件、附件、貼上的日誌），該內容可能包含試圖劫持模型的指令。即使你是唯一傳送者，這也可能發生。最大的風險在於啟用工具時：模型可能被誘導外洩情境，或代表你呼叫工具。透過以下方式降低影響範圍：

使用唯讀或停用工具的「reader」代理來摘要不受信任的內容
對啟用工具的代理關閉 web_search / web_fetch / browser
也將解碼後的檔案/文件文字視為不受信任：OpenResponses input_file 和媒體附件擷取都會將擷取出的文字包在明確的外部內容邊界標記中，而不是傳遞原始檔案文字
使用沙盒和嚴格的工具允許清單

詳細資訊：安全性。

我的機器人應該有自己的電子郵件、GitHub 帳號或電話號碼嗎？

對大多數設定來說，是的。使用獨立帳號和電話號碼隔離機器人，可在出問題時降低影響範圍。這也讓你更容易輪替憑證或撤銷存取權，而不影響個人帳號。從小範圍開始。只授予你實際需要的工具和帳號存取權，之後如有需要再擴充。文件：安全性、配對。

我可以讓它自主處理我的簡訊嗎？這安全嗎？

我們不建議讓它對你的個人訊息擁有完整自主權。最安全的模式是：

將 DM 保持在配對模式或嚴格的允許清單中。
如果你想讓它代表你傳送訊息，請使用獨立號碼或帳號。
讓它先草擬，然後在傳送前核准。

如果你想實驗，請在專用帳號上進行並保持隔離。請參閱安全性。

我可以使用較便宜的模型來處理個人助理任務嗎？

可以，前提是代理僅用於聊天，且輸入受信任。較小的等級更容易受到指令劫持，因此請避免將它們用於啟用工具的代理，或在讀取不受信任內容時使用。如果你必須使用較小的模型，請鎖定工具並在沙盒內執行。請參閱安全性。

我在 Telegram 中執行 /start，但沒有收到配對碼

配對碼只有在未知傳送者傳訊給機器人，且 dmPolicy: "pairing" 已啟用時才會送出。單獨執行 /start 不會產生代碼。檢查待處理請求：

openclaw pairing list telegram

如果你想立即存取，請將你的傳送者 ID 加入允許清單，或為該帳號設定 dmPolicy: "open"。

WhatsApp：它會傳訊息給我的聯絡人嗎？配對如何運作？

不會。預設 WhatsApp DM 政策是配對。未知傳送者只會收到配對碼，而他們的訊息不會被處理。OpenClaw 只會回覆它收到的聊天，或回覆你明確觸發的傳送。使用以下指令核准配對：

openclaw pairing approve whatsapp <code>

列出待處理請求：

openclaw pairing list whatsapp

精靈電話號碼提示：它用來設定你的允許清單/擁有者，讓你自己的 DM 被允許。它不會用於自動傳送。如果你在個人 WhatsApp 號碼上執行，請使用該號碼並啟用 channels.whatsapp.selfChatMode。

聊天指令、中止任務，以及「它不會停止」

我要如何阻止內部系統訊息顯示在聊天中？

大多數內部或工具訊息只會在該工作階段啟用詳細、追蹤或推理時出現。在你看到它的聊天中修正：

/verbose off
/trace off
/reasoning off

如果仍然很吵，請在 Control UI 中檢查工作階段設定，並將 verbose 設為繼承。也請確認你沒有使用在設定中將 verboseDefault 設為 on 的機器人設定檔。文件：思考與詳細輸出、安全性。

我要如何停止/取消正在執行的任務？

將以下任一內容作為獨立訊息傳送（不要加斜線）：

stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt

這些是中止觸發詞（不是斜線指令）。對於背景程序（來自 exec 工具），你可以要求代理執行：

process action:kill sessionId:XXX

斜線指令概覽：請參閱斜線指令。大多數指令必須以 / 開頭作為獨立訊息傳送，但少數捷徑（例如 /status）也可供允許清單中的傳送者行內使用。

我要如何從 Telegram 傳送 Discord 訊息？（"跨情境訊息遭拒"）

OpenClaw 預設封鎖跨提供者訊息。如果工具呼叫綁定到 Telegram，除非你明確允許，否則它不會傳送到 Discord。為代理啟用跨提供者訊息：

{
  tools: {
    message: {
      crossContext: {
        allowAcrossProviders: true,
        marker: { enabled: true, prefix: "[from {channel}] " },
      },
    },
  },
}

編輯設定後重新啟動 gateway。

為什麼感覺機器人會「忽略」快速連續的訊息？

佇列模式控制新訊息如何與正在進行的執行互動。使用 /queue 變更模式：

steer - 將所有待處理的引導排入目前執行中的下一個模型邊界
queue - 舊版一次一個引導
followup - 一次執行一則訊息
collect - 批次收集訊息並回覆一次
steer-backlog - 立即引導，然後處理積壓訊息
interrupt - 中止目前執行並重新開始

預設模式是 steer。你可以為後續模式加入像是 debounce:0.5s cap:25 drop:summarize 的選項。請參閱命令佇列和Steering 佇列。

其他

使用 API 金鑰時，Anthropic 的預設模型是什麼？

在 OpenClaw 中，認證資訊和模型選擇是分開的。設定 ANTHROPIC_API_KEY（或在驗證設定檔中儲存 Anthropic API 金鑰）會啟用驗證，但實際的預設模型會是你在 agents.defaults.model.primary 中設定的模型（例如 anthropic/claude-sonnet-4-6 或 anthropic/claude-opus-4-6）。如果你看到 No credentials found for profile "anthropic:default"，這表示 Gateway 在執行中代理程式預期的 auth-profiles.json 中找不到 Anthropic 認證資訊。

仍然卡住嗎？請到 Discord 詢問，或開啟 GitHub 討論。

Documentation Index

​如果發生故障，前 60 秒先做這些

​快速開始與首次執行設定

​OpenClaw 是什麼？

​Skills 與自動化

​沙箱與記憶體

​磁碟上的位置

​設定基礎

​遠端 Gateway 和 Node

​Env vars 與 .env 載入

​Sessions 與多個聊天

​模型、故障轉移與驗證設定檔

​Gateway：連接埠、「已在執行」與遠端模式

​記錄與偵錯

​媒體與附件

​安全性與存取控制

​聊天指令、中止任務，以及「它不會停止」

​其他

​相關