常見問題

OpenClaw 是一個在你自己的裝置上執行的個人 AI 助理。它能在你已使用的訊息平台上回覆（Discord、Google Chat、iMessage、Mattermost、Signal、Slack、Telegram、WebChat、WhatsApp，以及 QQ Bot 等隨附頻道外掛），並能在支援的平台上提供語音功能和即時 Canvas。閘道是持續運作的控制平面；助理才是產品本身。

OpenClaw 不「只是一個 Claude 包裝器」。它是本機優先的控制平面，能在你自己的硬體上執行功能強大的助理，並可從你已使用的聊天應用程式存取，具備有狀態工作階段、記憶和工具，而不必將你的工作流程交給託管式 SaaS。

• 你的裝置、你的資料：在任何你想要的位置（Mac、Linux、VPS）執行閘道，並將工作區與工作階段歷程保留在本機。
• 真正的頻道，而不是網頁沙箱：Discord/iMessage/Signal/Slack/Telegram/WhatsApp 等，以及支援平台上的行動語音功能和 Canvas。
• 不受模型限制：使用 Anthropic、MiniMax、OpenAI、OpenRouter 等，並支援依代理程式路由與容錯移轉。
• 僅限本機的選項：執行本機模型，讓所有資料都能保留在你的裝置上。
• 多代理程式路由：依頻道、帳號或工作區分代理程式，每個代理程式都有自己的工作區與預設值。
• 開放原始碼且可自由修改：無需受制於供應商，即可檢查、擴充及自行託管。

文件：閘道、頻道、多代理程式、記憶。

適合作為起點的專案：建立網站（WordPress、Shopify 或靜態網站）；製作行動應用程式原型（大綱、畫面、API 計畫）；整理檔案和資料夾；連接 Gmail 並自動產生摘要或後續追蹤。

它可以處理大型工作，但最好將工作分為多個階段，並使用子代理程式平行處理。

• 個人簡報：彙整收件匣、行事曆和你關注的新聞。
• 研究與草擬：快速研究、摘要，以及電子郵件或文件的初稿。
• 提醒與後續追蹤：由排程或心跳偵測驅動的提醒與檢查清單。
• 瀏覽器自動化：填寫表單、收集資料、重複執行網頁工作。
• 跨裝置協調：從手機傳送工作，讓閘道在伺服器上執行，再透過聊天接收結果。

可以，用於研究、資格評估與草擬：掃描網站、建立候選名單、摘要潛在客戶資訊，以及撰寫外展訊息或廣告文案草稿。

進行外展或廣告活動時，請確保有人員參與審核。避免垃圾訊息、遵守當地法律與平台政策，並在傳送任何內容前進行審閱。讓 OpenClaw 草擬；由你核准。

文件：安全性。

OpenClaw 是個人助理與協調層，而不是 IDE 的替代品。如需在儲存庫內取得最快速的直接程式設計迴圈，請使用 Claude Code 或 Codex。如需持久記憶、跨裝置存取和工具協調，請使用 OpenClaw。

• 跨工作階段持續保留的記憶與工作區。
• 多平台存取（Telegram、WhatsApp、終端介面、WebChat）。
• 工具協調（瀏覽器、檔案、排程、掛鉤）。
• 持續運作的閘道（在 VPS 上執行，並從任何地方互動）。
• 用於本機瀏覽器/螢幕/相機/執行功能的節點。

展示案例：https://openclaw.ai/showcase。

請使用受管理的覆寫，而不要編輯儲存庫中的副本。將變更放在 ~/.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。若要進行全域安裝，但只讓部分代理程式看見，請將共用副本保留在 ~/.openclaw/skills，並使用 agents.defaults.skills / agents.list[].skills 控制可見性。只有值得提交至上游的編輯，才應針對儲存庫副本提出 PR。

可以：透過 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 新增目錄（在上述順序中優先權最低）。clawhub 預設會安裝到 ./skills，OpenClaw 會在下一個工作階段將其視為 <workspace>/skills。若要限制只讓特定代理程式看見，請搭配 agents.defaults.skills 或 agents.list[].skills。

支援的模式：

• 排程工作：隔離的工作可為每項工作設定 model 覆寫。
• 代理程式：將工作路由至不同的代理程式，並設定不同的預設模型、思考層級和串流參數。
• 隨選切換：/model 可隨時切換目前工作階段的模型。

範例——相同模型，不同的代理程式個別設定：

{  agents: {    list: [      {        id: "coder",        model: "xiaomi/mimo-v2.5-pro",        thinkingDefault: "high",        params: { temperature: 0.1 },      },      {        id: "chat",        model: "xiaomi/mimo-v2.5-pro",        thinkingDefault: "off",        params: { temperature: 0.8 },      },    ],  },}

將共用的個別模型預設值放在 agents.defaults.models["provider/model"].params，再將代理程式特定的覆寫放在扁平的 agents.list[].params。請勿在巢狀的 agents.list[].models["provider/model"].params 下重複加入相同模型；該路徑用於代理程式個別的模型目錄與執行階段覆寫。

請參閱排程工作、多代理程式路由、設定、斜線命令。

對於耗時或平行工作，請使用子代理程式：它們會在自己的工作階段中執行、傳回摘要，並讓主要聊天保持可回應。要求機器人「為這項工作產生一個子代理程式」，或使用 /subagents。使用 /status 查看閘道目前是否忙碌。

長時間工作和子代理程式都會消耗權杖；如果在意成本，請透過 agents.defaults.subagents.model 為子代理程式設定較便宜的模型。

文件：子代理程式、背景工作。

將 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（預設為 24，0 會停用）、session.threadBindings.maxAgeHours（預設為 0 = 無硬性上限），以及各頻道覆寫 channels.discord.threadBindings.{enabled,idleHours,maxAgeHours}。channels.discord.threadBindings.spawnSessions 控制產生時的自動綁定（預設為 true）。

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

檢查解析後的要求者路由：

• 完成模式的子代理程式傳送會優先使用已綁定的討論串或對話路由（如果存在）。
• 如果完成來源只包含頻道，OpenClaw 會退回使用要求者工作階段已儲存的路由（lastChannel / lastTo / lastAccountId），讓直接傳送仍有機會成功。
• 沒有綁定路由，也沒有可用的已儲存路由：直接傳送可能失敗，結果會退回至佇列中的工作階段傳送，而不是立即發布。
• 無效或過時的目標也可能強制退回佇列，或導致最終傳送失敗。
• 如果子代理程式最後一則可見的助理回覆恰好是 NO_REPLY / no_reply 或 ANNOUNCE_SKIP，OpenClaw 會刻意抑制通知，以免發布先前已過時的進度。

偵錯：openclaw tasks show <lookup>，其中 <lookup> 是工作 ID、執行 ID 或工作階段金鑰。

文件：子代理程式、背景工作、工作階段工具。

排程在閘道程序內執行；如果閘道未持續運作，就不會觸發。

• 確認排程已啟用（cron.enabled），且未設定 OPENCLAW_SKIP_CRON。
• 確認閘道全天候執行（不進入睡眠／不重新啟動）。
• 確認工作時區（--tz 與主機時區）。

偵錯：

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

文件：排程工作、自動化。

檢查傳遞模式：

• --no-deliver / delivery.mode: "none"：預期不會由執行器進行備援傳送。
• 公告目標遺失或無效（channel / to）：執行器已略過對外傳遞。
• 頻道驗證失敗（unauthorized、Forbidden）：執行器嘗試傳遞，但認證資訊阻止了傳遞。
• 靜默的隔離結果（僅 NO_REPLY / no_reply）會被視為刻意不傳遞，因此也會抑制佇列中的備援傳遞。

對於隔離的排程工作，若有可用的聊天路由，代理程式仍可使用 message 工具直接傳送。--announce 只控制執行器對代理程式尚未自行傳送之最終文字的備援傳遞。

偵錯：

openclaw cron runs --id <jobId> --limit 50openclaw tasks show <lookup>

文件：排程工作、背景任務。

這是即時模型切換路徑，而不是重複排程。隔離排程會保存執行階段的模型交接，並在目前執行拋出 LiveSessionModelSwitchError 時重試；重試前會保留已切換的供應商／模型（以及任何已切換的驗證設定檔覆寫）。

模型選擇優先順序：首先是 Gmail 鉤子的模型覆寫（hooks.gmail.model），接著是每個工作的 model，再來是任何已儲存的排程工作階段模型覆寫，最後是一般代理程式／預設模型選擇。

重試迴圈的上限為初次嘗試加上 2 次切換重試；之後排程會中止，而不會無限循環。

偵錯：

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

文件：排程工作、排程命令列介面。

使用原生 openclaw skills 命令，或將 Skills 放入你的工作區；Linux 不提供 macOS Skills 使用者介面。可在 https://clawhub.ai 瀏覽 Skills。

openclaw skills search "calendar"openclaw skills search --limit 20openclaw skills install @owner/<skill-slug>openclaw skills install @owner/<skill-slug> --version <version>openclaw skills install @owner/<skill-slug> --forceopenclaw skills install @owner/<skill-slug> --globalopenclaw skills update --allopenclaw skills update --all --globalopenclaw skills list --eligibleopenclaw skills check

原生 openclaw skills install 預設會寫入目前工作區的 skills/ 目錄。加入 --global，即可安裝至供所有本機代理程式使用的共用受管理 Skills 目錄。只有在發布或同步你自己的 Skills 時，才需安裝獨立的 clawhub 命令列介面。使用 agents.defaults.skills 或 agents.list[].skills，可縮小哪些代理程式能看見共用 Skills 的範圍。

可以，透過閘道排程器：

• 排程工作用於排定或週期性任務（重新啟動後仍會保留）。
• 心跳偵測用於主要工作階段的定期檢查。
• 隔離工作用於發布摘要或傳遞至聊天的自主代理程式。

文件：排程工作、自動化、心跳偵測。

無法直接執行。macOS Skills 會受 metadata.openclaw.os 與必要二進位檔案限制，且只有符合閘道主機上的資格時才會載入。在 Linux 上，僅限 darwin 的 Skills（apple-notes、apple-reminders、things-mac）不會載入，除非你覆寫此限制。

支援三種模式：

選項 A－在 Mac 上執行閘道（最簡單）。在具備 macOS 二進位檔案的環境執行閘道，接著從 Linux 以遠端模式或透過 Tailscale 連線。由於閘道主機是 macOS，Skills 會正常載入。

選項 B－使用 macOS 節點（無需 SSH）。在 Linux 上執行閘道、配對一個 macOS 節點（選單列應用程式），然後在 Mac 上將 Node Run Commands 設為 "Always Ask" 或 "Always Allow"。當節點上具備必要的二進位檔案時，OpenClaw 會將僅限 macOS 的 Skills 視為符合資格；代理程式會透過 nodes 工具執行它們。使用 "Always Ask" 時，在提示中核准 "Always Allow" 會將該命令加入允許清單。

選項 C－透過 SSH 代理 macOS 二進位檔案（進階）。讓閘道繼續在 Linux 上執行，但使必要的命令列介面二進位檔案解析至會在 Mac 上執行的 SSH 包裝程式，然後覆寫 Skill 以允許 Linux，讓它維持符合資格。

1. 為二進位檔案建立 SSH 包裝程式（範例：Apple Notes 的 memo）：

   #!/usr/bin/env bashset -euo pipefailexec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

2. 將包裝程式放在 Linux 主機的 PATH 中（例如 ~/bin/memo）。
3. 覆寫 Skill 中繼資料（工作區或 ~/.openclaw/skills），以允許 Linux：

   ---name: apple-notesdescription: 透過 macOS 上的 memo 命令列介面管理 Apple Notes。metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }---

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

目前未內建。可選擇：

• 自訂 Skill／外掛：最適合可靠的 API 存取（兩者皆有 API）。
• 瀏覽器自動化：無需撰寫程式碼即可運作，但速度較慢且較脆弱。

若要提供代理商形式的個別客戶情境：為每位客戶保留一個 Notion 頁面（情境＋偏好設定＋進行中的工作），並要求代理程式在工作階段開始時擷取該頁面。

若需要原生整合，請提出功能要求，或使用這些 API 建置 Skill。

openclaw skills install @owner/<skill-slug>openclaw skills update --all

原生安裝會存放於目前工作區的 skills/ 目錄；使用 --global 可供所有本機代理程式使用，或設定 agents.defaults.skills / agents.list[].skills 以限制可見範圍。部分 Skills 預期使用透過 Homebrew 安裝的二進位檔案；在 Linux 上即為 Linuxbrew。

請參閱 Skills、Skills 設定、ClawHub。

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

openclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot

若要使用自訂名稱，請建立明確的 MCP 設定檔：

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

這可使用本機主機瀏覽器或已連線的瀏覽器節點。若閘道在其他位置執行，請在瀏覽器所在機器上執行節點主機，或改用遠端 CDP。

existing-session / user 設定檔相較於受管理的 openclaw 設定檔，目前有以下限制：

• click、type、hover、scrollIntoView、drag 與 select 需要快照參照，而非 CSS 選取器。
• 上傳鉤子需要 ref 或 inputRef，且一次只能處理一個檔案，不支援 CSS element。
• responsebody、PDF 匯出、下載攔截與批次操作仍需使用受管理的瀏覽器路徑。

完整比較請參閱瀏覽器。

有：沙箱。若要瞭解 Docker 專用設定（在 Docker 中執行完整閘道或使用沙箱映像檔），請參閱 Docker。

預設映像檔以安全性優先，並以 node 使用者執行，因此不包含系統套件、Homebrew 與內建瀏覽器。若要使用較完整的設定：

• 使用 OPENCLAW_HOME_VOLUME 保存 /home/node，讓快取能持續保留。
• 使用 OPENCLAW_IMAGE_APT_PACKAGES 將系統相依套件建置至映像檔中。
• 透過內建命令列介面安裝 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 限制沙箱工作階段中可用的工具。

設定逐步說明：群組：私人私訊＋公開群組。主要參考：閘道設定。

將 agents.defaults.sandbox.docker.binds 設為 ["host:container:mode"]（例如 "/home/user/src:/src:ro"）。全域與個別代理程式的繫結會合併；當 scope: "shared" 時，會忽略個別代理程式的繫結。任何敏感內容請使用 :ro；繫結會繞過沙箱檔案系統的隔離限制。

OpenClaw 會同時針對正規化路徑，以及透過最深層現有上層目錄解析出的標準路徑驗證繫結來源，因此即使最終路徑區段尚不存在，利用符號連結上層目錄逃逸的情況也會以封閉方式失敗。

請參閱沙箱與沙箱、工具原則及提升權限的比較。

OpenClaw 記憶是代理程式工作區中的 Markdown 檔案：每日筆記位於 memory/YYYY-MM-DD.md，經整理的長期筆記位於 MEMORY.md（僅限主要／私人工作階段）。

OpenClaw 也會在壓縮摘要對話前，靜默執行壓縮前記憶清理寫入，提醒模型先寫入可持續保留的筆記。這只會在工作區可寫入時執行（唯讀沙箱會略過）；可使用 agents.defaults.compaction.memoryFlush.enabled: false 停用。請參閱記憶。

要求機器人將事實寫入記憶：長期筆記存放於 MEMORY.md，短期情境存放於 memory/YYYY-MM-DD.md。提醒模型儲存記憶通常即可解決問題。若仍持續遺忘，請確認閘道每次執行時都使用相同的工作區。

文件：記憶、代理程式工作區。

記憶檔案儲存在磁碟上，並會持續保留直到遭到刪除；其限制取決於你的儲存空間，而非模型。工作階段上下文仍受模型上下文視窗限制，因此長時間的對話可能會進行壓縮或截斷——這正是記憶搜尋存在的原因，它只會將相關部分重新載入上下文。

文件：記憶、上下文。

只有在使用預設提供者 OpenAI 嵌入時才需要。Codex OAuth 涵蓋聊天／補全，但不會授予嵌入存取權，因此使用 Codex 登入（透過 OAuth 或 Codex 命令列介面登入）不會啟用語意記憶搜尋。OpenAI 嵌入仍需要真正的 API 金鑰（OPENAI_API_KEY 或 models.providers.openai.apiKey）。

若要完全在本機執行，請設定 agents.defaults.memorySearch.provider: "local"（GGUF/llama.cpp）。其他支援的提供者包括：Bedrock、DeepInfra、Gemini（GEMINI_API_KEY 或 memorySearch.remote.apiKey）、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI 相容提供者，以及 Voyage。設定詳情請參閱記憶和記憶搜尋。

不會：OpenClaw 自身的狀態儲存在本機，但外部服務仍會看到你傳送給它們的內容。

• 預設儲存在本機：工作階段、記憶檔案、設定和工作區都位於閘道主機上（~/.openclaw 加上你的工作區目錄）。
• 因運作所需而傳送至遠端：傳送給模型提供者（Anthropic/OpenAI 等）的訊息會送至其 API，而聊天平台（Slack/Telegram/WhatsApp 等）會將訊息資料儲存在其伺服器上。
• 你可以控制資料足跡：本機模型會將提示保留在你的電腦上，但頻道流量仍會經過該頻道的伺服器。

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

所有資料都位於 $OPENCLAW_STATE_DIR 下（預設：~/.openclaw）：

舊版單一代理程式路徑 ~/.openclaw/agent/* 會由 openclaw doctor 遷移。

你的工作區（AGENTS.md、記憶檔案、Skills 等）位於其他位置，透過 agents.defaults.workspace 設定（預設：~/.openclaw/workspace）。

這些檔案位於代理程式工作區，而不是 ~/.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）：設定、頻道／提供者狀態、驗證設定檔、工作階段、日誌、共用 Skills（~/.openclaw/skills）。

預設工作區為 ~/.openclaw/workspace，可以進行設定：

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

如果機器人在重新啟動後「忘記」內容，請確認閘道每次啟動時都使用相同的工作區（遠端模式使用的是閘道主機的工作區，而不是你本機筆電上的工作區）。

提示：若要持久保存行為或偏好，請要求機器人將其寫入 AGENTS.md 或 MEMORY.md，而不要依賴聊天記錄。

請參閱代理程式工作區和記憶。

可以。SOUL.md 是注入代理程式上下文的工作區啟動檔案之一。預設的單一檔案注入上限為 20000 個字元；所有檔案的啟動內容總預算為 60000 個字元。

變更共用預設值：

{  agents: {    defaults: {      bootstrapMaxChars: 50000,      bootstrapTotalMaxChars: 300000,    },  },}

或在 agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars 下覆寫單一代理程式的設定。

使用 /context 檢查原始大小與注入大小，並確認是否發生截斷。讓 SOUL.md 專注於語氣、立場和人格；將操作規則放入 AGENTS.md，並將持久資訊放入記憶。

請參閱上下文和代理程式設定。

將你的代理程式工作區放入私人 Git 儲存庫，並備份至私人位置（例如 GitHub 私人儲存庫）。這會保存記憶以及 AGENTS/SOUL/USER 檔案，讓你稍後能還原助理的「思維」。

不要提交 ~/.openclaw 下的任何內容（認證資訊、工作階段、權杖、加密的機密資料內容）。若要完整還原，請分別備份工作區和狀態目錄。

文件：代理程式工作區。

請參閱解除安裝。

可以。工作區是預設目前工作目錄和記憶錨點，不是嚴格的沙箱。相對路徑會在工作區內解析；除非已啟用沙箱，否則絕對路徑可以存取主機上的其他位置。若要隔離，請使用 agents.defaults.sandbox 或各代理程式的沙箱設定。若要將某個儲存庫設為預設工作目錄，請將該代理程式的 workspace 指向儲存庫根目錄——OpenClaw 儲存庫本身只是原始碼，因此除非你刻意要讓代理程式在其中工作，否則請將工作區分開存放。

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

工作階段狀態由閘道主機擁有。在遠端模式下，你關心的工作階段儲存區位於遠端機器，而不是你本機的筆電。請參閱工作階段管理。

OpenClaw 會從 $OPENCLAW_CONFIG_PATH（預設：~/.openclaw/openclaw.json）讀取選用的 JSON5 設定。如果檔案不存在，則會使用相對安全的預設值，包括將 ~/.openclaw/workspace 設為預設工作區。

非迴路介面繫結需要有效的閘道驗證路徑：共用機密驗證（權杖或密碼），或在已正確設定、可感知身分的反向代理後方使用 gateway.auth.mode: "trusted-proxy"。

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

• gateway.remote.token / .password 本身不會啟用本機閘道驗證；只有在未設定 gateway.auth.* 時，本機呼叫路徑才能使用 gateway.remote.* 作為備援。
• 若使用密碼驗證，請設定 gateway.auth.mode: "password" 以及 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 如果透過 SecretRef 明確設定 gateway.auth.token / .password，但無法解析，解析會以封閉方式失敗（不會以遠端備援加以掩蓋）。
• 使用共用機密的控制 UI 設定會透過 connect.params.auth.token 或 connect.params.auth.password 進行驗證（儲存在應用程式／UI 設定中）。Tailscale Serve 或 trusted-proxy 等具備身分資訊的模式則改用要求標頭——請避免將共用機密放在 URL 中。
• 使用 gateway.auth.mode: "trusted-proxy" 時，同一主機上的迴路反向代理需要明確設定 gateway.auth.trustedProxy.allowLoopback = true，並在 gateway.trustedProxies 中加入迴路項目。

OpenClaw 預設強制執行閘道驗證，包括迴路介面。如果未設定明確的驗證路徑，啟動時會解析為權杖模式，並為該次啟動產生僅限執行期間使用的權杖，因此本機 WS 用戶端必須進行驗證。這可阻止其他本機程序呼叫閘道。

當用戶端需要在重新啟動後仍維持不變的機密時，請明確設定 gateway.auth.token、gateway.auth.password、OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。你也可以選擇密碼模式，或針對可感知身分的反向代理使用 trusted-proxy。若要開放迴路介面，請明確設定 gateway.auth.mode: "none"。openclaw doctor --generate-gateway-token 可隨時產生權杖。

閘道會監看設定並支援熱重新載入：gateway.reload.mode: "hybrid"（預設值）會立即套用安全的變更，並在遇到關鍵變更時重新啟動。也支援 hot、restart 和 off。大多數 tools.*、agents.* 政策、session.* 和 messages.* 的變更都會立即生效，完全不需要重新載入；gateway.* 的繫結／連接埠變更則需要重新啟動。

設定 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 金鑰即可運作。web_search 則取決於你選擇的提供者：

Grok 也可以重複使用模型驗證中的 xAI OAuth（openclaw onboard --auth-choice xai-oauth）。

建議：openclaw configure --section web，然後選擇提供者。

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "BRAVE_API_KEY_HERE",          },        },      },    },  },  tools: {    web: {      search: {        enabled: true,        provider: "brave",        maxResults: 5,      },      fetch: {        enabled: true,        provider: "firecrawl", // 選用；省略即可自動偵測      },    },  },}

提供者專用的網頁搜尋設定位於 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（或服務環境）讀取環境變數。

文件：網頁工具。

config.apply 會取代整份設定；使用部分物件會移除其他所有內容。

目前的 OpenClaw 可防止大多數意外覆寫：

• OpenClaw 擁有的設定寫入會在寫入前驗證變更後的完整設定。
• 無效或具破壞性的 OpenClaw 設定寫入會遭到拒絕，並儲存為 openclaw.json.rejected.*。
• 若直接編輯導致啟動或熱重新載入失敗，閘道會以失敗關閉或略過重新載入；它不會重寫 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.bash.* 別名，也會拒絕重寫 tools.exec.ask / tools.exec.security。

文件：設定、設定工具、閘道疑難排解、Doctor。

常見模式：一個閘道（例如 Raspberry Pi）搭配節點和代理。

• 閘道（中央）：負責頻道（Signal/WhatsApp）、路由和工作階段。
• 節點（裝置）：Mac/iOS/Android 以周邊裝置形式連線，並提供本機工具（system.run、canvas、camera）。
• 代理（工作代理）：針對特殊角色使用不同的思考核心／工作區（例如維運與個人資料）。
• 子代理：從主要代理產生背景工作，以便平行處理。
• 終端介面：連線至閘道，並切換代理／工作階段。

文件：節點、遠端存取、多代理路由、子代理、終端介面。

可以：

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

預設為 false（有頭模式）。無頭模式在某些網站上較容易觸發反機器人檢查（X/Twitter 經常封鎖無頭工作階段）。它使用相同的 Chromium 引擎，適用於大多數自動化工作；主要差異是沒有可見的瀏覽器視窗（需要視覺內容時請使用螢幕擷取畫面）。請參閱瀏覽器。

將 browser.executablePath 設為 Brave 執行檔（或任何以 Chromium 為基礎的瀏覽器），然後重新啟動閘道。請參閱瀏覽器。

Telegram 訊息由閘道處理，閘道會執行代理，並且只有在需要節點工具時，才透過閘道 WebSocket 呼叫節點：

Telegram -> 閘道 -> 代理 -> node.* -> 節點 -> 閘道 -> Telegram

節點不會看到傳入的提供者流量；它們只會接收節點 RPC 呼叫。

將你的電腦配對為節點。閘道在其他位置執行，但可透過閘道 WebSocket 呼叫你本機上的 node.* 工具（螢幕、相機、系統）。

1. 在持續開機的主機（VPS／家用伺服器）上執行閘道。
2. 將閘道主機和你的電腦加入同一個 tailnet。
3. 確保閘道 WS 可連線（綁定 tailnet 或使用 SSH 通道）。
4. 在本機開啟 macOS 應用程式，並使用 Remote over SSH 模式（或直接透過 tailnet）連線，使其註冊為節點。
5. 核准節點：

   openclaw devices listopenclaw devices approve <requestId>

不需要額外的 TCP 橋接器；節點會透過閘道 WebSocket 連線。

安全性提醒：配對 macOS 節點會允許在該機器上使用 system.run。只配對你信任的裝置；請閱讀安全性。

文件：節點、閘道通訊協定、macOS 遠端模式、安全性。

檢查基本項目：

openclaw gateway statusopenclaw statusopenclaw channels status

接著驗證身分驗證與路由：如果使用 Tailscale Serve，請確認 gateway.auth.allowTailscale 設定正確；如果透過 SSH 通道連線，請確認通道已啟用並指向正確的連接埠；確認你的私人訊息／群組允許清單包含你的帳號。

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

可以，但目前沒有內建的機器人對機器人橋接功能。

最簡單的方式：使用兩個機器人都能存取的一般聊天頻道（Slack/Telegram/WhatsApp）。讓機器人 A 傳訊息給機器人 B，然後讓機器人 B 照常回覆。

命令列介面橋接（通用）：執行指令碼，透過 openclaw agent --message ... --deliver 呼叫另一個閘道，並指定另一個機器人正在監聽的聊天。如果其中一個機器人位於遠端 VPS，請透過 SSH/Tailscale 將命令列介面指向該遠端閘道（請參閱遠端存取）：

openclaw agent --message "來自本機機器人的問候" --deliver --channel telegram --reply-to <chat-id>

新增防護措施，避免兩個機器人無限循環（僅在提及時回覆、頻道允許清單，或「不要回覆機器人訊息」規則）。

文件：遠端存取、代理命令列介面、代理傳送。

不需要。一個閘道可託管多個代理，每個代理都有自己的工作區、模型預設值和路由；這是一般設定，比每個代理使用一台 VPS 便宜且簡單得多。只有在需要嚴格隔離（安全性邊界），或使用你不想共用的截然不同設定時，才使用不同的 VPS。

是的：節點是從遠端閘道連線至筆記型電腦的第一級方式，能提供比 shell 存取更多的功能。閘道可在 macOS/Linux（Windows 透過 WSL2）上執行，而且相當輕量（小型 VPS 或 Raspberry Pi 等級的裝置即可；4 GB RAM 已綽綽有餘），因此常見設定是使用持續開機的主機，並將筆記型電腦設為節點。

• 不需要傳入 SSH——節點會透過裝置配對，主動連線至閘道 WebSocket。
• 更安全的執行控制——system.run 會受到該筆記型電腦上的節點允許清單／核准機制限制。
• 更多裝置工具——除了 system.run 之外，節點還會提供 canvas、camera 和 screen。
• 本機瀏覽器自動化——將閘道保留在 VPS 上，但透過節點主機在本機執行 Chrome，或透過 Chrome MCP 連接本機 Chrome。

SSH 適合臨時 shell 存取；對於持續性的代理工作流程和裝置自動化，節點更為簡單。

文件：節點、節點命令列介面、瀏覽器。

不會。除非刻意執行隔離的設定檔，否則每台主機應只執行一個閘道（請參閱多個閘道）。節點是連線至閘道的周邊裝置（iOS/Android 節點，或選單列應用程式中的 macOS「節點模式」）。如需無頭節點主機與命令列介面控制，請參閱節點主機命令列介面。

gateway、discovery 和託管外掛介面變更需要完整重新啟動。

可以：

• config.schema.lookup：寫入前，檢查一個設定子樹及其淺層結構描述節點、相符的 UI 提示與直接子項摘要。
• config.get：擷取目前的快照與雜湊值。
• config.patch：安全的部分更新（大多數 RPC 編輯的首選）；可行時熱重新載入，必要時重新啟動。
• config.apply：驗證並取代完整設定；可行時熱重新載入，必要時重新啟動。
• 供代理程式使用的 gateway 執行階段工具仍拒絕重寫 tools.exec.ask / tools.exec.security；舊版 tools.bash.* 別名會正規化為相同的受保護路徑。

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

設定你的工作區，並限制可觸發機器人的使用者。

1. 在 VPS 上安裝並登入：

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

2. 使用 Tailscale 應用程式在 Mac 上安裝並登入，並使用相同的 tailnet。
3. 在 Tailscale 管理主控台中啟用 MagicDNS，讓 VPS 擁有穩定的名稱。
4. 使用 tailnet 主機名稱：SSH ssh user@your-vps.tailnet-xxxx.ts.net；閘道 WS ws://your-vps.tailnet-xxxx.ts.net:18789。

若要在不使用 SSH 的情況下存取控制 UI，請在 VPS 上使用 Tailscale Serve：

openclaw gateway --tailscale serve

這會讓閘道維持繫結至回送介面，並透過 Tailscale 公開 HTTPS。請參閱 Tailscale。

Serve 會公開閘道控制 UI + WS；節點透過相同的閘道 WS 端點連線。

1. 請確認 VPS 與 Mac 位於相同的 tailnet。
2. 以遠端模式使用 macOS 應用程式（SSH 目標可使用 tailnet 主機名稱）—它會建立閘道連接埠通道，並以節點身分連線。
3. 核准節點：

   openclaw devices listopenclaw devices approve <requestId>

文件：閘道通訊協定、探索、macOS 遠端模式。

若第二台筆記型電腦只需要本機工具（螢幕／相機／執行），請將它新增為節點——只使用一個閘道，無須複製設定。目前本機節點工具僅支援 macOS。只有在需要嚴格隔離或兩個完全獨立的機器人時，才安裝第二個閘道。

文件：節點、節點命令列介面、多個閘道。

OpenClaw 會從父程序（shell、launchd/systemd、CI 等）讀取環境變數，此外還會載入：

• 目前工作目錄中的 .env。
• 來自 ~/.openclaw/.env 的全域備援 .env（$OPENCLAW_STATE_DIR/.env）。

這兩個 .env 檔案都不會覆寫既有的環境變數。工作區 .env 中的提供者認證資訊與端點路由鍵是例外：例如 GEMINI_API_KEY、XAI_API_KEY、MISTRAL_API_KEY，或任何以 _ENDPOINT 結尾的鍵（以及其他內建提供者的驗證或端點環境變數），都會從工作區 .env 中忽略，並應放在程序環境、~/.openclaw/.env 或設定 env 中。

設定中的內嵌環境變數只會在程序環境中缺少時套用：

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

如需完整的優先順序與來源，請參閱 /environment。

有兩種修正方式：

1. 將缺少的鍵放入 ~/.openclaw/.env，如此即使服務未繼承你的 shell 環境，也能載入這些鍵。
2. 啟用 shell 匯入（選擇加入的便利功能）：

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

   這會執行你的登入 shell，且只匯入缺少的預期鍵（絕不覆寫）。對應的環境變數：OPENCLAW_LOAD_SHELL_ENV=1、OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000。

openclaw models status 會回報是否已啟用 shell 環境匯入。"Shell env: off" 不代表你的環境變數遺失——它只表示 OpenClaw 不會自動載入你的登入 shell。

若閘道以服務（launchd/systemd）執行，就不會繼承你的 shell 環境。修正方式是將權杖放入 ~/.openclaw/.env、啟用 env.shellEnv.enabled: true，或將它加入設定 env（只在缺少時套用），接著重新啟動閘道並再次檢查：

openclaw models status

Copilot 權杖會依此順序解析：OPENCLAW_GITHUB_TOKEN，接著 COPILOT_GITHUB_TOKEN，再來 GH_TOKEN，最後是 GITHUB_TOKEN。

請參閱 /concepts/model-providers 與 /environment。

將 /new 或 /reset 作為獨立訊息傳送。請參閱工作階段管理。

會。預設重設原則為每日：工作階段會依目前工作階段的開始時間，在閘道主機上所設定的當地小時（session.reset.atHour，預設 4，0-23）輪替。若要改用以閒置時間為基礎的重設，請使用 mode: "idle" 與 session.reset.idleMinutes，這會在一段時間沒有活動後讓工作階段到期（依據最後一次實際互動，而非心跳偵測／排程／執行系統事件）。

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType 支援 direct（舊版別名 dm）、group 與 thread。若未設定 session.reset/resetByType 區塊，舊版頂層 session.idleMinutes 仍可作為閒置模式預設值的相容性別名。有作用中且由提供者擁有之命令列介面工作階段的工作階段，不會被隱含的每日預設值中斷。完整生命週期請參閱工作階段管理。

可以，透過多代理程式路由與子代理程式：一個協調代理程式，加上數個各自擁有工作區與模型的工作代理程式。

最好將這視為有趣的實驗——它會大量消耗權杖，而且通常不如使用一個具有獨立工作階段的機器人有效率。典型模式是與一個機器人互動，使用不同工作階段進行平行工作，並在需要時產生子代理程式。

文件：多代理程式路由、子代理程式、代理程式命令列介面。

工作階段的內容脈絡受模型視窗限制。長篇聊天、大量工具輸出或許多檔案都可能觸發壓縮或截斷。

• 要求機器人摘要目前狀態並將其寫入檔案。
• 在長時間工作前使用 /compact，切換主題時使用 /new。
• 將重要內容脈絡保留在工作區，並要求機器人重新讀取。
• 使用子代理程式處理長時間或平行工作，讓主要聊天保持精簡。
• 如果經常發生此情況，請選擇內容脈絡視窗較大的模型。

openclaw reset

非互動式完整重設：

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

接著重新執行設定：

openclaw onboard --install-daemon

若新手引導偵測到既有設定，也會提供 重設；請參閱新手引導（命令列介面）。若使用了設定檔（--profile / OPENCLAW_PROFILE），請重設每個狀態目錄（預設為 ~/.openclaw-<profile>）。僅限開發用途的重設：openclaw gateway --dev --reset 會清除開發設定、認證資訊、工作階段與工作區。

• 壓縮（保留對話，摘要較早的對話輪次）：使用 /compact，或使用 /compact <instructions> 引導摘要。
• 重設（為相同聊天鍵建立全新的工作階段 ID）：/new 或 /reset。

如果持續發生，請調整工作階段修剪（agents.defaults.contextPruning）以移除舊工具輸出，或使用內容脈絡視窗較大的模型。

文件：壓縮、工作階段修剪、工作階段管理。

提供者驗證錯誤：模型產生了缺少必要 input 的 tool_use 區塊。通常表示工作階段歷程已過時或損毀（經常發生於長討論串或工具／結構描述變更之後）。

修正方式：以 /new（獨立訊息）開始新的工作階段。

心跳偵測預設每 30m 執行一次；若解析後的驗證模式是 Anthropic OAuth／權杖驗證（包括重複使用 Claude 命令列介面），且未設定 heartbeat.every，則為每 1h 執行一次。調整或停用方式如下：

{  agents: {    defaults: {      heartbeat: {        every: "2h", // 或設為 "0m" 以停用      },    },  },}

若 HEARTBEAT.md 存在但實際上是空的（只有空白行、Markdown/HTML 註解、ATX 標題、圍欄標記或空白清單項目殘段），OpenClaw 會略過心跳偵測執行，以節省 API 呼叫。若檔案不存在，心跳偵測仍會執行，並由模型決定該做什麼。

每個代理程式的覆寫使用 agents.list[].heartbeat。文件：心跳偵測。

不需要。OpenClaw 使用你自己的帳號執行——只要你在群組中，OpenClaw 就能看見群組內容。依預設，群組回覆會遭封鎖，直到你允許傳送者（groupPolicy: "allowlist"）。

若要將群組回覆限制為只有你：

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

最快的方式：持續查看記錄，並在群組中傳送測試訊息。

openclaw logs --follow --json

尋找以 @g.us 結尾的 chatId（或 from），例如 1234567890-1234567890@g.us。

若已完成設定／加入允許清單，請從設定中列出群組：

openclaw directory groups list --channel whatsapp

文件：WhatsApp、目錄、日誌。

兩個常見原因：提及閘門預設為啟用（你必須 @提及機器人，或符合 mentionPatterns），或是你設定了 channels.whatsapp.groups，卻未設定 "*"，而該群組不在允許清單中。

請參閱群組和群組訊息。

直接聊天預設會合併至主要工作階段。群組／頻道有各自的工作階段金鑰，而 Telegram 主題／Discord 討論串則是獨立的工作階段。請參閱群組和群組訊息。

沒有硬性限制——數十個甚至數百個都沒問題，但請注意：

• 磁碟用量成長：作用中的工作階段和對話記錄位於每個代理程式各自的 SQLite 資料庫中；舊版／封存成品仍可能在 ~/.openclaw/agents/<agentId>/sessions/ 下累積。
• 權杖成本：代理程式越多，代表同時使用模型的情況越多。
• 維運負擔：每個代理程式各自的驗證設定檔、工作區和頻道路由。

每個代理程式保留一個作用中工作區（agents.defaults.workspace）；如果磁碟用量增加，請使用 openclaw sessions cleanup 清除舊工作階段（請勿手動編輯作用中的 SQLite 狀態），並使用 openclaw doctor 找出零散的工作區和設定檔不相符的情況。

可以，透過多代理程式路由：執行多個彼此隔離的代理程式，並依頻道／帳號／對等端路由傳入訊息。Slack 支援作為頻道，且可繫結至特定代理程式。

瀏覽器存取功能很強大，但並非“人類能做什麼就能做什麼”——防機器人機制、CAPTCHA 和 MFA 仍可能阻擋自動化。若要取得最可靠的控制，請在主機上使用本機 Chrome MCP，或在實際執行瀏覽器的機器上使用 CDP。

最佳實務設定：持續運作的閘道主機（VPS／Mac mini）、每種角色一個代理程式（繫結）、將 Slack 頻道繫結至這些代理程式，並在需要時透過 Chrome MCP 或節點使用本機瀏覽器。

文件：多代理程式路由、Slack、瀏覽器、節點。

gateway.port 控制 WebSocket + HTTP（控制介面、掛鉤等）共用的單一多工連接埠。優先順序：

--port > OPENCLAW_GATEWAY_PORT > gateway.port > 預設值 18789

"Running" 是監督程式的觀點（launchd/systemd/schtasks）；連線能力探測則是命令列介面實際連線至閘道 WebSocket。請以 openclaw gateway status 中的這些行為準：Probe target:（探測使用的 URL）、Listening:（連接埠上實際繫結的項目）、Last gateway error:（程序仍在執行但連接埠未監聽時的常見根本原因）。

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

修正方式：從你希望服務使用的相同 --profile／環境中執行：

openclaw gateway install --force

OpenClaw 會在啟動時立即繫結 WebSocket 接聽程式（預設為 ws://127.0.0.1:18789），藉此強制執行執行階段鎖定。如果繫結因 EADDRINUSE 而失敗，便會擲回 GatewayLockError（"another gateway instance is already listening"）。

修正方式：停止另一個執行個體、釋放連接埠，或使用 openclaw gateway --port <port> 執行。

設定 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 應用程式會監看設定檔並即時切換模式。
• gateway.remote.token／.password 僅是用戶端的遠端認證資訊；它們本身不會啟用本機閘道驗證。

你的閘道驗證路徑與控制介面的驗證方法不相符。

事實（來自程式碼）：

• 控制介面會將權杖保留在 sessionStorage 中，其範圍限定於目前的瀏覽器分頁和選取的閘道 URL，因此重新整理同一分頁時仍可繼續運作，而不需要在 localStorage 中長期保存權杖。
• 在 AUTH_TOKEN_MISMATCH 時，如果閘道傳回重試提示（canRetryWithDeviceToken=true、recommendedNextStep=retry_with_device_token），受信任的用戶端可嘗試一次有限制的重試，並使用快取的裝置權杖。
• 該快取權杖重試會重複使用與裝置權杖一同儲存的已核准範圍；明確的 deviceToken／明確的 scopes 呼叫端會保留其要求的範圍集合，而不會繼承快取範圍。
• 在該重試路徑之外，連線驗證的優先順序為：明確的共用權杖／密碼優先，其次是明確的 deviceToken，接著是儲存的裝置權杖，最後是啟動程序權杖。
• 內建的設定代碼啟動程序會傳回具有 scopes: [] 的節點裝置權杖，以及一個供受信任行動裝置初始設定使用、有時效限制的操作員交接權杖。操作員交接可讀取設定期間的原生設定，但不會授予配對變更範圍或 operator.admin。

修正方式：

• 最快的方法：openclaw dashboard（列印並複製儀表板 URL，且嘗試開啟；若為無頭環境則顯示 SSH 提示）。
• 尚無權杖：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，然後將相符的密鑰貼到控制介面設定中。
• Tailscale Serve 模式：確認 gateway.auth.allowTailscale 已啟用，且你開啟的是 Serve URL，而非略過 Tailscale 身分標頭的原始迴路／Tailnet URL。
• 受信任 Proxy 模式：確認你是透過已設定、可感知身分的 Proxy 連入。同主機迴路 Proxy 也需要 gateway.auth.trustedProxy.allowLoopback = true。
• 一次重試後仍不相符：輪替／重新核准已配對的裝置權杖：

  openclaw devices listopenclaw devices rotate --device <id> --role operator

• 輪替遭拒：已配對裝置工作階段只能輪替其自身裝置，除非它們也具有 operator.admin；而明確的 --scope 值不得超出呼叫端目前的操作員範圍。
• 仍然卡住：openclaw status --all，再參閱疑難排解。驗證詳細資料請參閱儀表板。

tailnet 繫結會從你的網路介面中選取 Tailscale IP（100.64.0.0/10）。如果機器未連上 Tailscale（或介面已停用），閘道會回退至迴路介面，而不會公開其他網路介面。

修正方式：在該主機上啟動 Tailscale 並重新啟動閘道，或明確切換至 gateway.bind: "loopback"／"lan"。

tailnet 是明確設定；auto 偏好迴路介面。使用 gateway.bind: "tailnet" 可將非迴路公開範圍限制於 Tailnet，同時保留必要的同主機 127.0.0.1 監聽器。

通常不需要——一個閘道可以執行多個訊息頻道和代理程式。只有在需要備援（例如救援機器人）或嚴格隔離時，才使用多個閘道，並以各自的 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、agents.defaults.workspace 和唯一的 gateway.port 隔離每個閘道。

建議：每個執行個體使用 openclaw --profile <name> ...（會自動建立 ~/.openclaw-<name>）；每個設定檔組態使用唯一的 gateway.port（手動執行則使用 --port）；並搭配使用 openclaw --profile <name> gateway install 的個別設定檔服務。

設定檔也會在服務名稱加上後綴：launchd ai.openclaw.<profile>、systemd openclaw-gateway-<profile>.service、Windows OpenClaw Gateway (<profile>)。未限定名稱的 openclaw-gateway systemd 單元僅存在於預設設定檔；重新命名前的舊版 systemd 單元名稱 clawdbot-gateway 會自動遷移。

完整指南：多個閘道。

閘道是 WebSocket 伺服器，並預期第一則訊息為 connect 框架。任何其他內容都會以代碼 1008（政策違規）關閉連線。

常見原因：你在瀏覽器中開啟了 HTTP URL，而不是使用 WS 用戶端；使用了錯誤的連接埠／路徑；或 Proxy／通道移除了驗證標頭，或傳送非閘道要求。

修正方式：使用 WS URL（ws://<host>:18789，或透過 HTTPS 使用 wss://...），不要在一般瀏覽器分頁中開啟 WS 連接埠，並在啟用驗證時將權杖／密碼納入 connect 框架。命令列介面／終端介面範例：

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

通訊協定詳細資料：閘道通訊協定。

檔案日誌（結構化）：/tmp/openclaw/openclaw-YYYY-MM-DD.log。透過 logging.file 設定固定路徑；透過 logging.level 設定檔案日誌層級；透過 --verbose 和 logging.consoleLevel 設定主控台詳細程度。

最快速的追蹤方式：

openclaw logs --follow

服務／監督程式日誌（閘道透過 launchd/systemd 執行時）：

• macOS launchd 標準輸出：~/Library/Logs/openclaw/gateway.log（設定檔使用 gateway-<profile>.log；標準錯誤會被抑制）。
• Linux：journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager。
• Windows：schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST。

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

openclaw gateway statusopenclaw gateway restart

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

三種 Windows 安裝模式：

1) Windows Hub 本機設定：原生應用程式會管理由應用程式擁有的本機 WSL 閘道。從開始功能表或系統匣開啟 OpenClaw Companion，然後使用 Gateway Setup 或 Connections 分頁。

2) 手動 WSL2 閘道：閘道在 Linux 內執行。

wslopenclaw gateway statusopenclaw gateway restart

如果你從未安裝服務，請在前景啟動：openclaw gateway run。

3) 原生 Windows 命令列介面／閘道：直接在 Windows 中執行。

openclaw gateway statusopenclaw gateway restart

如果你手動執行（沒有服務）：openclaw gateway run。

文件：Windows、閘道服務操作手冊。

快速健康狀態檢查：

openclaw statusopenclaw models statusopenclaw channels statusopenclaw logs --follow

常見原因：模型驗證未載入至閘道主機（檢查 models status）、頻道配對／允許清單阻擋回覆（檢查頻道設定和日誌），或 WebChat／Dashboard 開啟時未使用正確的權杖。若為遠端環境，請確認通道／Tailscale 連線已建立，且可連線至閘道 WebSocket。

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

這通常表示 UI 失去了 WebSocket 連線。請檢查：閘道是否正在執行（openclaw gateway status）？是否健康（openclaw status）？UI 是否具有正確的權杖（openclaw dashboard）？若為遠端環境，通道／Tailscale 連線是否已建立？

接著持續查看日誌：

openclaw logs --follow

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

openclaw channels statusopenclaw channels logs --channel telegram

接著比對錯誤：

• BOT_COMMANDS_TOO_MUCH：Telegram 選單的項目過多。OpenClaw 已經會縮減至 Telegram 的限制並以較少的命令重試，但部分選單項目仍可能遭到捨棄。請減少外掛／Skill／自訂命令，或在不需要選單時停用 channels.telegram.commands.native。
• TypeError: fetch failed、Network request for 'setMyCommands' failed! 或類似的網路錯誤：若位於 VPS 或代理伺服器後方，請確認允許對外 HTTPS 連線，且 api.telegram.org 的 DNS 可正常運作。

若閘道位於遠端，請檢查閘道主機上的日誌。

文件：Telegram、頻道疑難排解。

openclaw statusopenclaw models statusopenclaw logs --follow

在終端介面中，使用 /status 查看目前狀態。如果你預期在聊天頻道中收到回覆，請確認已啟用傳送（/deliver on）。

文件：終端介面、斜線命令。

如果你已安裝服務（macOS 上的 launchd、Linux 上的 systemd）：

openclaw gateway stopopenclaw gateway start

在前景執行時，使用 Ctrl-C 停止，接著執行 openclaw gateway run。

文件：閘道服務操作手冊。

openclaw gateway restart 會重新啟動背景服務（launchd／systemd）。openclaw gateway 會在此終端機工作階段中讓閘道於前景執行。若已安裝服務，請使用 gateway 子命令；若只是單次執行，請使用不含子命令的前景執行方式。

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

代理程式傳出的附件必須使用結構化媒體欄位，例如 media、mediaUrl、path 或 filePath。請參閱 OpenClaw 助理設定和代理程式傳送。

openclaw message send --target +15555550123 --message "這是你要的內容" --media /path/to/file.png

另請檢查：目標頻道支援傳出媒體，且未遭允許清單阻擋；檔案未超過供應商的大小限制（圖片會調整為最長邊不超過 2048px）；tools.fs.workspaceOnly=true 會將本機路徑傳送限制為工作區、暫存／媒體儲存區及經沙箱驗證的檔案；tools.fs.workspaceOnly=false（預設值）允許結構化本機媒體傳送使用代理程式已可讀取的主機本機檔案，適用於媒體與安全的文件類型（圖片、音訊、影片、PDF、Office 文件，以及經驗證的文字文件，例如 Markdown／MD、TXT、JSON、YAML／YML）。這不是機密掃描器——只要副檔名與內容驗證相符，代理程式可讀取的 secret.txt 或 config.json 就能作為附件傳送。請將敏感檔案置於代理程式可讀取路徑之外，或保留 tools.fs.workspaceOnly=true，以實施更嚴格的本機路徑傳送限制。

請參閱圖片。

請將收到的私訊視為不受信任的輸入。預設值可降低風險：

• 支援私訊的頻道預設行為是配對：未知的傳送者會收到配對碼，且其訊息不會被處理。使用 openclaw pairing approve --channel <channel> [--account <id>] <code> 核准。待處理請求上限為每個頻道 3 個；若未收到配對碼，請檢查 openclaw pairing list --channel <channel> [--account <id>]。
• 公開開放私訊需要明確選擇啟用（dmPolicy: "open" 和允許清單 "*"）。

執行 openclaw doctor，以顯示有風險的私訊政策。

不是。提示注入關乎不受信任的內容，而不只是誰能向機器人傳送私訊。如果助理會讀取外部內容（網路搜尋／擷取、瀏覽器頁面、電子郵件、文件、附件、貼上的日誌），這些內容可能包含試圖劫持模型的指令——即使你是唯一的傳送者也一樣。

啟用工具時風險最大：模型可能受到誘騙而洩露上下文，或代表你呼叫工具。降低影響範圍的方法：

• 使用唯讀或停用工具的「閱讀器」代理程式，摘要不受信任的內容
• 對已啟用工具的代理程式停用 web_search／web_fetch／browser
• 也將解碼後的檔案／文件文字視為不受信任：OpenResponses input_file 和媒體附件擷取都會以明確的外部內容邊界標記包覆擷取出的文字，而非直接傳遞原始檔案文字
• 使用沙箱和嚴格的工具允許清單

詳細資訊：安全性。

程式語言和執行階段確實重要，但對個人代理程式而言並非主要風險。實際風險包括閘道曝露、誰能向機器人傳訊、提示注入、工具範圍、認證資訊處理、瀏覽器存取、執行權限，以及對第三方 Skill／外掛的信任。

Rust 和 WASM 可以為部分程式碼類別提供更強的隔離，但無法解決提示注入、不當的允許清單、公開曝露閘道、權限過廣的工具，或已登入敏感帳號的瀏覽器設定檔。請將下列項目視為主要控制措施：保持閘道私密或要求驗證、對私訊／群組使用配對和允許清單、針對不受信任的輸入拒絕高風險工具或在沙箱中執行、只安裝受信任的外掛和 Skill，並在設定變更後執行 openclaw security audit --deep。

詳細資訊：安全性、沙箱隔離。

openclaw security audit --deepopenclaw gateway status

較安全的基準：閘道繫結至 loopback，或只透過經驗證的私密存取方式曝露（tailnet、SSH 通道、權杖／密碼驗證，或正確設定的受信任代理伺服器）；私訊使用 pairing 或 allowlist 模式；除非每位成員皆受信任，否則群組應使用允許清單並要求提及後才回應；對於會讀取不受信任內容的代理程式，拒絕高風險工具（exec、browser、gateway、cron）或嚴格限制其範圍；需要縮小工具執行影響範圍時，請啟用沙箱隔離。

應優先修正的問題包括：未經驗證的公開繫結、已啟用工具的開放私訊／群組，以及曝露的瀏覽器控制。詳細資訊：openclaw security audit。

請將第三方 Skill 和外掛視為你選擇信任的程式碼。ClawHub Skill 頁面會在安裝前顯示掃描狀態，但掃描並非完整的安全邊界。OpenClaw 在安裝或更新外掛／Skill 時，不會執行內建的本機危險程式碼封鎖；請使用由操作者管理的 security.installPolicy 進行本機允許／封鎖決策。

較安全的做法：優先選擇受信任的作者和固定版本、啟用前先閱讀 Skill／外掛內容、嚴格限制外掛／Skill 允許清單、在只有最低限度工具的沙箱中執行處理不受信任輸入的工作流程，並避免授予第三方程式碼廣泛的檔案系統、執行、瀏覽器或機密存取權限。

詳細資訊：Skills、外掛、安全性。

對大多數設定而言，是。使用獨立帳號和電話號碼隔離機器人，可在發生問題時縮小影響範圍，也能更輕鬆地輪替認證資訊或撤銷存取權限，而不會影響你的個人帳號。

從小處開始：只授予實際需要的工具和帳號存取權限，之後再視需要擴充。

文件：安全性、配對。

我們不建議讓它完全自主處理你的個人訊息。最安全的做法：讓私訊維持在配對模式或使用嚴格的允許清單；如果它需要代表你傳送訊息，請使用獨立的號碼或帳號；並讓它先擬稿，由你核准後再傳送。

若要實驗，請使用專用且隔離的帳號進行。請參閱安全性。

可以，前提是代理程式僅用於聊天，且輸入受到信任。較小型級別的模型更容易遭受指令劫持，因此請避免用於啟用工具的代理程式，或用於讀取不受信任內容。如果你必須使用較小型的模型，請嚴格限制工具並在沙箱內執行。請參閱安全性。

只有在未知傳送者向機器人傳訊且已啟用 dmPolicy: "pairing" 時，才會傳送配對碼；僅執行 /start 不會產生配對碼。

檢查待處理的請求：

openclaw pairing list telegram

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

不會。WhatsApp 的預設私訊政策是配對。未知傳送者只會收到配對碼；其訊息不會被處理。OpenClaw 只會回覆收到訊息的聊天，或執行你明確觸發的傳送。

openclaw pairing approve whatsapp <code>openclaw pairing list whatsapp

精靈中的電話號碼提示會設定你的允許清單／擁有者，以允許你自己的私訊；它不會用於自動傳送。若使用你的個人 WhatsApp 號碼，請使用該號碼並啟用 channels.whatsapp.selfChatMode。

大多數內部／工具訊息只會在該工作階段啟用詳細輸出、追蹤或推理時顯示。

請在看到這些訊息的聊天中修正：

/verbose off/trace off/reasoning off

如果仍然有許多訊息：請檢查 Control UI 中的工作階段設定，並將詳細輸出設為 inherit；確認你使用的機器人設定檔中未在設定加入 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、do not do that、please stop、stop please、abort、esc、exit、interrupt、halt。常見的非英文觸發詞（法文、德文、西班牙文、中文、日文、印地文、阿拉伯文、俄文）也可使用。

若是由 exec 工具啟動的背景程序，請要求代理程式執行：

process action:kill sessionId:XXX

大多數斜線命令都必須以 / 開頭，並單獨作為一則訊息傳送；但允許清單中的傳送者也可以在行內使用少數捷徑（例如 /status）。請參閱斜線命令。

OpenClaw 預設會封鎖跨供應商傳訊。如果工具呼叫綁定至 Telegram，除非你明確允許，否則不會傳送至 Discord；此設定會立即生效，無須重新啟動閘道：

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

預設會將執行期間收到的提示引導至目前執行。使用 /queue 選擇目前執行的行為：

• steer（預設）— 在下一個模型邊界引導目前執行。
• followup — 將訊息排入佇列，並在目前執行結束後逐一執行。
• collect — 將相容的訊息排入佇列，並在目前執行結束後統一回覆一次。
• interrupt — 中止目前執行並重新開始。

可以為佇列模式新增選項，例如 debounce:0.5s cap:25 drop:summarize。請參閱命令佇列和引導佇列。

認證資訊與模型選擇彼此獨立。設定 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" 表示閘道無法在執行中代理程式預期的 auth-profiles.json 中找到 Anthropic 認證資訊。