> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 安全性 **個人助理信任模型。** 本指引假設每個閘道各有一個受信任的 操作者邊界（單一使用者、個人助理模型）。 OpenClaw **並非**供多個敵對使用者共用同一個代理程式或閘道的 敵對多租戶安全邊界。若要在混合信任或敵對使用者環境中運作， 請拆分信任邊界：使用個別的閘道與認證資訊，最好也使用個別的作業系統使用者或主機。 ## 範圍：個人助理安全模型 * 支援：每個閘道一個使用者／信任邊界（每個邊界最好使用一個作業系統使用者／主機／VPS）。 * 不支援：由互不信任或敵對的使用者共用一個閘道／代理程式。 * 敵對使用者隔離需要個別的閘道（最好也使用個別的作業系統使用者／主機）。 * 如果數名不受信任的使用者可以向同一個已啟用工具的代理程式傳送訊息，他們就會共用該代理程式獲委派的工具權限。 * 如果有人可以修改閘道主機的狀態／設定（`~/.openclaw`，包括 `openclaw.json`），請將其視為受信任的操作者。 * 在單一閘道內，已驗證的操作者存取權是受信任的控制平面角色，而不是個別使用者的租戶角色。 * `sessionKey`（工作階段 ID、標籤）是路由選擇器，不是授權權杖。 要託管多個使用者或組織嗎？請為每個租戶執行一個隔離的閘道單元，而不是共用閘道。請參閱[多租戶託管](/zh-TW/gateway/multi-tenant-hosting)。 變更遠端存取、私訊政策、反向 Proxy 或公開暴露設定前，請依照[閘道暴露操作手冊](/zh-TW/gateway/security/exposure-runbook)完成預檢／復原檢查清單。 ## `openclaw security audit` 每次變更設定後，或公開網路介面前，請執行： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw security audit openclaw security audit --deep # 嘗試即時探測閘道 openclaw security audit --fix # 套用安全的修正措施 openclaw security audit --json ``` `--fix` 的範圍刻意設得很窄：它會將開放的群組政策改為允許清單、還原 `logging.redactSensitive: "tools"`、收緊狀態／設定／引入檔案的權限（`600` 檔案、`700` 目錄），並在 Windows 上使用 ACL 重設，而不是 POSIX `chmod`。 ### 稽核檢查的項目（概略） * **輸入存取** - 私訊／群組政策、允許清單：陌生人能否觸發機器人？ * **工具影響範圍** - 高權限工具加上開放聊天室：提示詞注入是否可能轉化為 Shell／檔案／網路動作？ * **執行檔案系統偏移** - 拒絕會修改檔案系統的工具，但 `exec`/`process` 在沒有沙箱限制的情況下仍可使用。 * **執行核准偏移** - `security="full"`、`autoAllowSkills`、沒有 `strictInlineEval` 的直譯器允許清單。僅有 `security="full"` 是廣泛的安全態勢警告，並非錯誤的證據——這是受信任個人助理設定所選用的預設值；只有在你的威脅模型需要核准或允許清單防護機制時才收緊此設定。 * **網路暴露** - 閘道繫結／驗證、Tailscale Serve/Funnel、強度不足／過短的驗證權杖。 * **瀏覽器控制暴露** - 遠端節點、中繼連接埠、遠端 CDP 端點。 * **本機磁碟衛生** - 權限、符號連結、設定引入、同步資料夾路徑。 * **外掛** - 未設定明確允許清單即載入。 * **政策偏移** - 已設定沙箱 Docker 設定，但沙箱模式關閉；看似生效但只會比對確切命令 ID（例如 `system.run`），而不會比對承載資料內 Shell 文字的 `gateway.nodes.commands.deny` 項目；危險的 `gateway.nodes.commands.allow` 項目；全域 `tools.profile="minimal"` 被各代理程式的設定覆寫；外掛擁有的工具可在寬鬆政策下使用。 * **執行階段預期偏移** - 在 `tools.exec.host` 現已預設為 `auto` 時，仍假設隱含執行代表 `sandbox`；或在沙箱模式關閉時設定 `tools.exec.host="sandbox"`。 * **模型衛生** - 對已設定的舊版模型發出警告（輕度警告，而非硬性封鎖）。 每項發現都有結構化的 `checkId`（例如 `gateway.bind_no_auth`、`tools.exec.security_full_configured`）。前綴：`fs.*`（權限）、`gateway.*`（繫結／驗證／Tailscale／控制介面／受信任 Proxy）、`hooks.*`/`browser.*`/`sandbox.*`/`tools.exec.*`（各介面的強化）、`plugins.*`/`skills.*`（供應鏈）、`security.exposure.*`（存取政策 × 工具影響範圍）。包含嚴重程度與自動修正支援的完整目錄，請參閱[安全稽核檢查](/zh-TW/gateway/security/audit-checks)。另請參閱[形式驗證](/zh-TW/security/formal-verification)。 ### 分級處理發現時的優先順序 1. 任何「開放」且已啟用工具的項目：先鎖定私訊／群組（配對／允許清單），再收緊工具政策／沙箱。 2. 公開網路暴露（區域網路繫結、Funnel、缺少驗證）：立即修正。 3. 瀏覽器控制遠端暴露：視同操作者存取權處理（僅限 Tailnet、審慎配對節點、不得公開暴露）。 4. 權限：狀態／設定／認證資訊／驗證資料不得允許群組／全域讀取。 5. 外掛：只載入你明確信任的項目。 6. 模型選擇：任何使用工具的機器人都應優先選用現代且經指令強化的模型。 ## 60 秒完成強化基準設定 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { mode: "local", bind: "loopback", auth: { mode: "token", token: "replace-with-long-random-token" }, }, session: { dmScope: "per-channel-peer", }, tools: { profile: "messaging", deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"], fs: { workspaceOnly: true }, exec: { security: "deny", ask: "always" }, elevated: { enabled: false }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } }, }, } ``` 讓閘道僅限本機使用、隔離私訊，並預設停用控制平面／執行階段工具。之後再針對各受信任的代理程式選擇性地重新啟用工具。 聊天驅動代理程式回合的內建基準：無論設定為何，非擁有者傳送者都無法使用 `cron` 或 `gateway` 工具。 ### 以請求者為範圍的控制與提示詞上下文 `tools.toolsBySender`、傳送者擁有權及僅限擁有者使用的工具清單，會依據目前回合的原始請求者進行評估。它們不會驗證或清理該模型提示詞中的其他內容，包括引述文字、先前的共用聊天室歷史記錄、轉寄內容、擷取內容、附件、工具結果或其他提示詞輸入。因此，如果另一人的內容包含在由擁有者觸發的回合上下文中，該內容就可能影響該回合。 請將這些控制視為可降低請求者直接能力的縱深防禦，而不是敵對多使用者隔離。使用 `contextVisibility` 篩選支援的頻道所提供的上下文、限制工具並將代理程式置於沙箱中；當參與者彼此敵對時，請使用個別的閘道，最好也使用個別的作業系統使用者或主機。 ## 信任邊界矩陣 用於分級處理風險報告的快速模型： | 邊界或控制措施 | 含義 | 常見誤解 | | ---------------------------------------- | --------------------- | ---------------------------- | | `gateway.auth`（權杖／密碼／受信任 Proxy／裝置驗證） | 驗證閘道 API 的呼叫者 | “要確保安全，每個框架的每則訊息都需要簽章” | | `sessionKey` | 用於選擇上下文／工作階段的路由金鑰 | “工作階段金鑰是使用者驗證邊界” | | 提示詞／內容防護機制 | 降低模型遭濫用的風險 | “僅提示詞注入就足以證明驗證遭繞過” | | `canvas.eval`／瀏覽器求值 | 啟用時屬於刻意提供的操作者能力 | “在此信任模型中，任何 JS 求值原語都會自動構成漏洞” | | 本機終端介面 `!` Shell | 由操作者明確觸發的本機執行 | “本機 Shell 便利命令是遠端注入” | | 節點配對與節點命令 | 在已配對裝置上執行操作者層級的遠端操作 | “遠端裝置控制預設應視為不受信任的使用者存取” | | `gateway.nodes.pairing.autoApproveCidrs` | 選擇啟用的受信任網路節點註冊政策 | “預設停用的允許清單會自動構成配對漏洞” | | `gateway.nodes.pairing.sshVerify` | 透過操作者 SSH 進行金鑰驗證的節點註冊 | “預設啟用的自動核准會自動構成配對漏洞” | ## 依設計不屬於漏洞的項目 * 僅有提示詞注入的攻擊鏈，未繞過政策、驗證或沙箱。 * 假設在單一共用主機或設定上進行敵對多租戶操作的主張。 * 將共用閘道設定中的一般操作者讀取路徑存取（例如 `sessions.list`／`sessions.preview`／`chat.history`）歸類為 IDOR。 * 僅限 Localhost 部署的發現（例如僅限迴路閘道缺少 HSTS）。 * 針對此儲存庫中不存在之輸入路徑提出的 Discord 輸入網路鉤子簽章發現。 * 將節點配對中繼資料視為 `system.run` 每個命令的隱藏第二層核准；真正的執行邊界是閘道的全域節點命令政策，加上節點本身的執行核准。 * 因 `gateway.nodes.pairing.sshVerify` 預設啟用而將其視為漏洞。它絕不會僅根據網路位置或 SSH 可連線性進行核准：閘道會透過 SSH 回讀裝置身分（BatchMode、嚴格主機金鑰），並且只有在裝置金鑰與待處理請求完全相符時才核准；這要求連線金鑰組已存在於操作者所控制主機上的操作者帳號中。探測範圍僅限私人／CGNAT 來源位址，並採用相同的受信任 CIDR 資格下限（僅限新的無範圍 `role: node`），而 `sshVerify: false` 會關閉此功能。 * 將 `gateway.nodes.pairing.autoApproveCidrs` 本身視為漏洞。它預設停用、需要明確的 CIDR／IP 項目、僅適用於未要求任何範圍的首次 `role: node` 配對，且絕不會自動核准操作者／瀏覽器／控制介面、WebChat、角色／範圍升級、中繼資料或公開金鑰變更，亦不會自動核准同一主機上的迴路受信任 Proxy 標頭路徑（即使已啟用迴路受信任 Proxy 驗證）。 * 將 `sessionKey` 視為驗證權杖的「缺少個別使用者授權」發現。 ## 閘道與節點信任 將閘道與節點視為具有不同角色的同一個操作者信任網域： * **閘道**：控制平面與政策介面（`gateway.auth`、工具政策、路由）。 * **節點**：與該閘道配對的遠端執行介面（命令、裝置操作、主機本機功能）。 * 通過閘道驗證的呼叫者在閘道範圍內受信任；配對後，節點操作會被視為該節點上的受信任操作員操作。請參閱[操作員範圍](/zh-TW/gateway/operator-scopes)。 * 使用共用閘道權杖／密碼驗證的直接迴路後端用戶端，無須提供使用者裝置身分，即可進行內部控制平面 RPC。這並非遠端或瀏覽器配對的繞過方式——網路用戶端、節點用戶端、裝置權杖用戶端及明確的裝置身分仍須接受配對與範圍升級強制檢查。 * 執行核准（允許清單 + 詢問）是用來維護操作員意圖的防護機制，而非抵禦惡意多租戶的隔離措施。它們會繫結確切的請求情境，並盡力繫結直接的本機檔案運算元；但不會以語意方式模擬每一條執行階段／直譯器載入路徑。需要強式邊界時，請使用沙箱與主機隔離。 * 受信任單一操作員的預設值：在 `gateway`/`node` 上執行主機命令時，不會顯示核准提示（`security="full"`、`ask="off"`）。這是刻意的使用者體驗設計，本身並非漏洞。 若要隔離惡意使用者，請依作業系統使用者／主機拆分信任邊界，並執行個別閘道。 ## 威脅模型 你的 AI 助理可以執行任意 shell 命令、讀寫檔案、存取網路服務，以及向任何人傳送訊息（若已授予頻道存取權）。傳訊息給它的人可能會試圖誘騙它從事惡意行為、以社交工程手法取得你的資料存取權，或探查基礎架構詳細資訊。 這裡的大多數失敗並非罕見的漏洞利用，而是「有人傳訊息給機器人，而機器人照著對方的要求做了」。OpenClaw 的立場依序如下： 1. **身分優先**——決定誰能與機器人對話（私訊配對／允許清單／明確「開放」）。 2. **範圍其次**——決定機器人可以在哪裡操作（群組允許清單 + 提及閘門、工具、沙箱、裝置權限）。 3. **模型最後**——假設模型可能遭到操控；設計系統時，應讓操控造成的影響範圍有限。 ## 私訊存取：配對、允許清單、開放、停用 每個支援私訊的頻道都支援 `dmPolicy`（或 `*.dm.policy`），在處理訊息前先限制傳入私訊： | 政策 | 行為 | | ----------- | ------------------------------------------------------------------------------------- | | `pairing` | 預設值。未知傳送者會收到配對碼；核准前，機器人會忽略其訊息。配對碼會在 1 小時後到期；建立新請求前，重複傳送私訊不會再次傳送配對碼。每個頻道最多可有 3 個待處理請求。 | | `allowlist` | 封鎖未知傳送者，不進行配對交握。 | | `open` | 任何人都能傳送私訊（公開）。頻道允許清單必須包含 `"*"`（明確選擇啟用）。 | | `disabled` | 完全忽略傳入私訊。 | ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw pairing list openclaw pairing approve ``` 詳細資訊與磁碟上的檔案：[配對](/zh-TW/channels/pairing) 將 `dmPolicy="open"` 和 `groupPolicy="open"` 視為最後手段；除非你完全信任聊天室中的每一位成員，否則應優先使用配對 + 允許清單。 ### 允許清單（兩層） * **私訊允許清單**（`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`；舊版：`channels.discord.dm.allowFrom`、`channels.slack.dm.allowFrom`）：誰能傳送私訊給機器人。當 `dmPolicy="pairing"` 時，核准項目會寫入 `~/.openclaw/credentials/-allowFrom.json`（預設帳號）或 `--allowFrom.json`（非預設帳號），並與設定中的允許清單合併。 * **群組允許清單**（因頻道而異）：機器人會接受哪些群組／頻道／伺服器。 * `channels.whatsapp.groups`、`channels.telegram.groups`、`channels.imessage.groups`：各群組的預設值，例如 `requireMention`；設定後也會作為群組允許清單（包含 `"*"` 可維持全部允許的行為）。使用 `agents.entries.*.groupChat.mentionPatterns`（例如 `["@openclaw", "@mybot"]`）自訂提及觸發條件，讓 `requireMention` 依你自己的機器人名稱進行限制。 * `groupPolicy="allowlist"` + `groupAllowFrom`：限制誰能在群組工作階段內觸發機器人（WhatsApp/Telegram/Signal/iMessage/Microsoft Teams）。 * `channels.discord.guilds` / `channels.slack.channels`：各介面的允許清單 + 提及預設值。 * 檢查順序：先檢查 `groupPolicy`/群組允許清單，再檢查提及／回覆啟用條件。回覆機器人訊息（隱含提及）**不會**繞過 `groupAllowFrom`。 詳細資訊：[設定](/zh-TW/gateway/configuration)與[群組](/zh-TW/channels/groups) ### 私訊工作階段隔離（多使用者模式） OpenClaw 預設會將所有私訊路由至主要工作階段，以維持跨裝置的連續性。如果有多人可以傳送私訊給機器人（開放私訊或包含多人的允許清單），請隔離私訊工作階段： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { session: { dmScope: "per-channel-peer" } } ``` `session.dmScope` 值： | 值 | 範圍 | | -------------------------- | -------------------------------- | | `main`（設定預設值） | 所有私訊共用一個工作階段。 | | `per-channel-peer` | 每個頻道 + 傳送者配對都會取得隔離的私訊情境（安全私訊模式）。 | | `per-account-channel-peer` | 與上述相同，但會再依帳號拆分（多帳號頻道）。 | | `per-peer` | 每位傳送者在所有同類型頻道中共用一個工作階段。 | 本機命令列介面的新手設定會保留明確設定的 `session.dmScope`，否則不設定該值，因此會套用 `"main"` 預設值：各頻道的所有直接訊息會共用代理程式持續滾動的主要工作階段（個人代理程式的預設值）。對於共用或多使用者收件匣，請設定 `session.dmScope: "per-channel-peer"`；當 `openclaw security audit` 偵測到多使用者私訊流量時，會建議進行隔離。 這是訊息情境邊界，而非主機管理員邊界。如果使用者彼此敵對，且共用同一個閘道主機／設定，請依信任邊界執行個別閘道。 如果同一個人透過多個頻道與你聯絡，請使用 `session.identityLinks` 將這些私訊工作階段合併為一個標準身分。請參閱[工作階段管理](/zh-TW/concepts/session)與[設定](/zh-TW/gateway/configuration)。 ## 情境可見性與觸發授權 這是兩個不同的概念： * **觸發授權**：誰可以觸發代理程式（`dmPolicy`、`groupPolicy`、允許清單、提及閘門）。 * **情境可見性**：哪些補充情境會傳送給模型（回覆本文、引用文字、討論串歷史記錄、轉寄中繼資料）。 `contextVisibility` 控制第二項： * `"all"`（預設值）：依接收時的原樣保留補充情境。 * `"allowlist"`：將補充情境篩選為通過目前允許清單檢查的傳送者。 * `"allowlist_quote"`：與 `allowlist` 相同，但仍會保留一則明確引用的回覆。 可依頻道或聊天室／對話設定——請參閱[群組](/zh-TW/channels/groups#context-visibility-and-allowlists)。如果報告只顯示「模型可以看到來自不在允許清單中之傳送者的引用／歷史文字」，這屬於可透過 `contextVisibility` 處理的強化發現，本身並不構成驗證或沙箱繞過；具安全影響的報告仍須證明確實繞過了信任邊界。 ## 提示詞注入 攻擊者會設計訊息，操控模型執行不安全的操作（「忽略你的指示」、「傾印你的檔案系統」、「開啟此連結並執行命令」）。單靠系統提示詞防護**無法解決**提示詞注入——這些防護只是軟性指引；硬性強制措施來自工具政策、執行核准、沙箱及頻道允許清單（操作員仍可依設計停用這些措施）。 提示詞注入不需要公開私訊：即使只有你能傳訊息給機器人，它所讀取的任何**不受信任內容**（網路搜尋／擷取結果、瀏覽器頁面、電子郵件、文件、附件、貼上的記錄／程式碼）都可能夾帶對抗性指示。內容本身就是威脅介面，而不只是傳送者。 應視為不受信任的危險訊號： * 「讀取這個檔案／URL，並完全按照其中的指示操作。」 * 「忽略你的系統提示詞或安全規則。」 * 「揭露你的隱藏指示或工具輸出。」 * 「貼上 \~/.openclaw 或你的記錄的完整內容。」 實務上有效的做法： * 嚴格限制傳入私訊（配對／允許清單）；在群組中優先使用提及閘門；避免在公開聊天室使用永遠開啟的機器人。 * 預設將連結、附件和貼上的指示視為惡意內容。 * 在沙箱中執行敏感工具；不要將密鑰放在代理程式可存取的檔案系統中。沙箱必須明確選擇啟用：若沙箱模式關閉，隱含的 `host=auto` 會解析為閘道主機，而明確的 `host=sandbox` 仍會以關閉方式失敗（沒有可用的沙箱執行階段）。設定 `host=gateway`，即可在設定中明確指定此行為。 * 將高風險工具（`exec`、`browser`、`web_fetch`、`web_search`）限制為僅供受信任的代理程式或明確允許清單使用。 * 如果你將直譯器（`python`、`node`、`ruby`、`perl`、`php`、`lua`、`osascript`）加入允許清單，請啟用 `tools.exec.strictInlineEval`，讓行內求值形式（`-c`、`-e` 及類似形式）仍須取得明確核准。在允許清單模式下，任何 heredoc 區段（`<<`）無論如何引用，都一律需要審查者或明確核准——已列入允許清單的命令無法使用 heredoc 本文繞過允許清單審查。 * 使用唯讀或停用工具的**閱讀代理程式**摘要不受信任的內容，再將摘要傳遞給主要代理程式，以縮小影響範圍。 * 對於 Gmail 網路鉤子，內建的逐訊息工作階段會隔離對話情境，但不會移除目標代理程式的工具或工作區權限。請將不受信任的郵件路由至專用閱讀代理程式、套用[各代理程式的沙箱與工具限制](/zh-TW/tools/multi-agent-sandbox-tools)，並使用 [`tools.agentToAgent`](/zh-TW/gateway/config-tools#toolsagenttoagent) 限制任何移交給主要代理程式的內容。請參閱 [Gmail 整合](/zh-TW/gateway/configuration-reference#gmail-integration)。 * 除非有需要，否則請為已啟用工具的代理程式關閉 `web_search` / `web_fetch` / `browser`。 * 對於 OpenResponses URL 輸入（`input_file` / `input_image`），請設定嚴格的 `gateway.http.endpoints.responses.files.urlAllowlist` / `images.urlAllowlist`，並將 `maxUrlParts` 維持在較低值（空白允許清單視同未設定）。使用 `files.allowUrl: false` / `images.allowUrl: false` 可完全停用 URL 擷取。 * 不要將密鑰放入提示詞；改為透過閘道主機上的環境變數／設定傳遞。 **模型選擇很重要。** 不同模型層級的提示詞注入抵抗力並不一致——較小型／較便宜的模型在遭遇對抗性提示詞時，更容易發生工具濫用與指令劫持。 對於啟用工具或會讀取不受信任內容的代理程式，使用較舊／較小型模型的提示詞注入風險通常過高。請勿在能力較弱的模型層級上執行這些工作負載。 * 任何可執行工具或存取檔案／網路的機器人，都應使用最新世代、最高層級的模型。 * 請勿將較舊／較弱／較小型的模型層級用於啟用工具的代理程式或不受信任的收件匣。 * 如果必須使用較小型模型，請縮小影響範圍：使用唯讀工具、強式沙箱、最低限度的檔案系統存取權限，以及嚴格的允許清單。為所有工作階段啟用沙箱，並停用 `web_search`/`web_fetch`/`browser`，除非輸入受到嚴格控管。 * 對於輸入受信任且不使用工具、僅供聊天的個人助理，較小型模型通常已足夠。 ### 外部內容與不受信任輸入的包裝 即使閘道會在本機解碼 OpenResponses `input_file` 文字，它仍會以不受信任的外部內容注入——該區塊包含 `<<>>` 邊界標記與 `Source: External` 中繼資料（此路徑省略了其他位置使用的較長 `SECURITY NOTICE:` 橫幅）。媒體理解功能從附加文件擷取文字，再將其附加至媒體提示詞時，也會套用相同的標記式包裝。 OpenClaw 也會先從包裝後的外部內容與中繼資料中移除常見的自架 LLM 聊天範本特殊權杖常值（Qwen/ChatML、Llama、Gemma、Mistral、Phi、GPT-OSS 的角色／回合權杖），再將內容傳送給模型。自架的 OpenAI 相容後端（vLLM、SGLang、TGI、LM Studio、自訂 Hugging Face tokenizer 堆疊）有時會將使用者內容中的 `<|im_start|>` 或 `<|start_header_id|>` 等常值字串權杖化為結構性聊天範本權杖；若沒有此清理機制，所擷取頁面、電子郵件本文或檔案內容工具輸出中的不受信任文字，就可能偽造合成的 `assistant`/`system` 角色邊界。清理發生在外部內容包裝層，因此會一致套用至擷取／讀取工具與傳入的頻道內容。託管供應商（OpenAI、Anthropic）已套用自己的請求端清理機制；請保持啟用外部內容包裝，並在可用時優先採用會分割／逸出特殊權杖的後端設定。 傳出模型回應另有獨立的清理器，會在最終頻道傳遞邊界，從使用者可見的回覆中移除洩漏的 ``、``、``、`` 及類似的內部框架內容。 這無法取代 `dmPolicy`、允許清單、執行核准、沙箱或 `contextVisibility`——它只會封堵一種特定的 tokenizer 層繞過手法。 ### 繞過旗標（在正式環境中保持關閉） * `hooks.mappings[].allowUnsafeExternalContent` * `hooks.gmail.allowUnsafeExternalContent` * 排程承載資料欄位 `allowUnsafeExternalContent` 僅可為範圍嚴格受限的偵錯而暫時啟用；若已啟用，請隔離該代理程式（沙箱 + 最少工具 + 專用工作階段命名空間）。 即使傳遞來源是你所控制的系統，鉤子承載資料仍是不受信任的內容（郵件／文件／網頁內容可能包含提示詞注入）。較弱的模型層級會增加此風險——對於鉤子驅動的自動化，請優先採用能力強大的現代模型層級，並維持嚴格的工具原則（`tools.profile: "messaging"` 或更嚴格），同時盡可能使用沙箱。 ### 群組中的推理與詳細輸出 `/reasoning`、`/verbose` 和 `/trace` 可能會暴露不應出現在公開頻道中的內部推理、工具輸出或外掛診斷資訊——其中可能包含工具引數、URL、外掛診斷資訊，以及模型看過的資料。請在公開聊天室中保持停用；僅可在受信任的私人訊息或受到嚴格控管的聊天室中啟用。 ## 命令授權 只有獲授權傳送者的斜線命令與指令才會生效，其授權依據來自頻道允許清單／配對及 `commands.useAccessGroups`（請參閱[設定](/zh-TW/gateway/configuration)與[斜線命令](/zh-TW/tools/slash-commands)）。如果頻道允許清單為空或包含 `"*"`，該頻道的命令實際上會對所有人開放。 `/exec` 僅供獲授權操作人員在目前工作階段中便利使用——它不會寫入設定，也不會變更其他工作階段。 ## 控制平面工具 兩個內建工具仍涉及敏感的控制平面操作： * `gateway` 使用 `config.schema.lookup` / `config.get` 讀取設定。它無法寫入設定、更新 OpenClaw 或重新啟動閘道。 * `cron` 會建立排程工作，並在原始聊天／任務結束後繼續執行。 `gateway` 工具仍僅限擁有者使用，因為讀取設定可能暴露機密與主機拓撲。代理程式透過 `openclaw` 委派工具要求持久性設定或生命週期變更；OpenClaw 會將這些要求對應至型別化操作，並要求人工核准後才會套用。請參閱 [OpenClaw 設定代理程式](/zh-TW/cli/openclaw#operations-and-approval)。 對於任何處理不受信任內容的代理程式／介面，預設應拒絕這些工具： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { deny: ["gateway", "cron", "sessions_spawn", "sessions_send"], }, } ``` `commands.restart=false` 會停用 `/restart` 與外部 `SIGUSR1` 重新啟動要求。`gateway` 代理程式工具沒有重新啟動動作。 ## 節點執行（`system.run`） 如果已配對 macOS 節點，閘道可以在其上叫用 `system.run`——這代表可在該 Mac 上遠端執行程式碼。 * 需要進行節點配對（核准 + 權杖）。配對會建立節點身分／信任關係並核發權杖；它不是逐一核准命令的介面。 * 閘道會透過 `gateway.nodes.commands.allow` / `gateway.nodes.commands.deny` 套用粗粒度的全域節點命令原則。拒絕清單只會比對確切的節點命令名稱（例如 `system.run`），不會比對命令承載資料內的 shell 文字——如果閘道的全域原則與節點本身的執行核准仍會強制執行此邊界，重新連線的節點宣告不同的命令清單本身並不構成漏洞。 * 每個節點的 `system.run` 原則是節點本身的執行核准檔案（`exec.approvals.node.*`），可在 Mac 上透過 Settings -> Exec approvals（security + ask + allowlist）控制；它可以比閘道的全域命令 ID 原則更嚴格或更寬鬆。 * 執行 `security="full"` 與 `ask="off"` 的節點遵循預設的受信任操作人員模型——這是預期行為，而非錯誤，除非你的部署需要更嚴格的安全立場。 * 核准模式會繫結確切的要求情境，並在可行時繫結一個具體的本機指令碼／檔案運算元。如果 OpenClaw 無法為直譯器／執行階段命令識別出恰好一個直接本機檔案，系統會拒絕需核准的執行，而不是承諾提供完整的語意涵蓋。 * 對於 `host=node`，需核准的執行也會儲存正規化且已準備的 `systemRunPlan`；後續獲核准的轉送會重複使用該已儲存計畫，而閘道驗證會拒絕呼叫者在建立核准要求後編輯命令／cwd／工作階段情境。 * 若要完全停用遠端執行：請將安全性設為 `deny`，並移除該 Mac 的節點配對。 ## 動態 Skills（監看程式／遠端節點） OpenClaw 可以在工作階段期間重新整理 Skills 清單：當 `SKILL.md` 發生變更時，Skills 監看程式會在代理程式下一回合更新快照；連接 macOS 節點也可能使僅限 macOS 的 Skills 符合使用資格（依據二進位檔探測結果）。請將 Skills 資料夾視為受信任的程式碼，並限制可修改它們的人員。 ## 外掛 外掛會在閘道處理程序內執行——請將其視為受信任的程式碼。 * 僅從你信任的來源安裝；優先使用明確的 `plugins.allow` 允許清單；啟用前先檢查外掛設定；外掛變更後重新啟動閘道。 * 安裝／更新外掛會執行程式碼： * 安裝路徑是目前使用之外掛安裝根目錄下的各外掛目錄。 * ClawHub 套件及 OpenClaw 的內建／官方目錄都是受信任的來源。新的任意 npm、`npm-pack:`、git、本機路徑／封存檔或市集來源會在安裝前發出警告；在你檢查並信任該來源後，非互動式安裝需要 `--force`。`--force` 會確認來源並允許覆寫；它不會繞過 `security.installPolicy` 或其餘安裝安全檢查。更新會重複使用已選取的來源。 * OpenClaw 不會在安裝／更新期間執行內建的本機危險程式碼封鎖。請使用 `security.installPolicy` 進行由操作人員掌控的本機允許／封鎖決策，並使用 `openclaw security audit --deep` 進行診斷掃描。 * npm 與 git 外掛安裝只會在明確的安裝／更新流程中執行套件管理員的相依套件收斂。本機路徑與封存檔會被視為自包含套件；OpenClaw 會複製／參照它們，而不執行 `npm install`。 * 優先使用固定的確切版本（`@scope/pkg@1.2.3`），並在啟用前檢查解封裝後的程式碼。 * `--dangerously-force-unsafe-install` 已淘汰，不再變更安裝／更新行為。 * `security.installPolicy` 可讓操作人員執行受信任的本機命令，針對 Skills 與外掛安裝做出主機專屬的允許／封鎖決策。它會在來源素材暫存完成後、安裝繼續前執行，也適用於 ClawHub Skills，且無法透過已淘汰的不安全旗標繞過。 詳細資料：[外掛](/zh-TW/tools/plugin) ## 沙箱 專門文件：[沙箱](/zh-TW/gateway/sandboxing) 兩種互補的方法： * **在 Docker 中執行完整閘道**（容器邊界）：[Docker](/zh-TW/install/docker) * **工具沙箱**（`agents.defaults.sandbox`；主機閘道 + 以沙箱隔離的工具；Docker 是預設後端）：[沙箱](/zh-TW/gateway/sandboxing) 若要防止跨代理程式存取，請將 `agents.defaults.sandbox.scope` 維持為 `"agent"`（預設值），或使用 `"session"` 以提供更嚴格的逐工作階段隔離。`scope: "shared"` 會使用單一容器或工作區。 沙箱內的代理程式工作區存取權限（`agents.defaults.sandbox.workspaceAccess`）： * `"none"`（預設）：工具會看到 `~/.openclaw/sandboxes` 下的沙箱工作區；無法存取代理程式工作區。 * `"ro"`：以唯讀方式將代理程式工作區掛載至 `/agent`（停用 `write`/`edit`/`apply_patch`）。 * `"rw"`：以讀寫方式將代理程式工作區掛載至 `/workspace`。 額外的 `sandbox.docker.binds` 會根據正規化且標準化的來源路徑進行驗證。封鎖路徑拒絕清單涵蓋 `/etc`、`/private/etc`、`/proc`、`/sys`、`/dev`、`/root`、`/boot`，以及通常包含 Docker socket 或其別名的目錄（其下的 `/run`、`/var/run` 和 `docker.sock`），另包括 HOME 認證資訊子路徑（`.aws`、`.cargo`、`.config`、`.docker`、`.gnupg`、`.netrc`、`.npm`、`.ssh`）。系統會透過現有祖先路徑解析父層符號連結手法與標準化主目錄別名，並重新檢查；因此，如果它們解析至封鎖的根目錄，仍會採取封閉式失敗。 `tools.elevated` 是在沙箱外執行 exec 的全域基準逃生開關。有效主機預設為 `gateway`；如果執行目標設定為 `node`，則為 `node`。請嚴格限制 `tools.elevated.allowFrom`，且不要為陌生人啟用。可透過 `agents.entries.*.tools.elevated` 進一步限制各代理程式。請參閱[提升權限模式](/zh-TW/tools/elevated)。 ### 子代理程式委派防護措施 若允許使用工作階段工具，請將委派的子代理程式執行視為另一項邊界決策： * 除非代理程式確實需要委派，否則拒絕 `sessions_spawn`。 * 將 `agents.defaults.subagents.allowAgents` 及任何個別代理程式的 `agents.entries.*.subagents.allowAgents` 覆寫限制於已知安全的目標代理程式。 * 對於必須維持在沙箱內的工作流程，請使用 `sandbox: "require"` 呼叫 `sessions_spawn`（預設值為 `"inherit"`）；當目標子執行環境未置於沙箱中時，`"require"` 會立即失敗。 ### 唯讀模式 將 `agents.defaults.sandbox.workspaceAccess: "ro"`（或使用 `"none"` 以禁止存取工作區）與封鎖 `write`、`edit`、`apply_patch`、`exec`、`process` 等工具的允許／拒絕清單結合，以建立唯讀設定檔。 * `tools.exec.applyPatch.workspaceOnly: true`（預設）：即使關閉沙箱，也會阻止 `apply_patch` 在工作區目錄之外寫入／刪除。只有在你刻意要讓 `apply_patch` 修改工作區外的檔案時，才設定 `false`。 * `tools.fs.workspaceOnly: true`（選用）：將 `read`/`write`/`edit`/`apply_patch` 路徑與原生提示詞圖片自動載入路徑限制於工作區目錄。 * 檔案系統根目錄應維持在狹窄範圍內——避免將你的家目錄等廣泛根目錄用於代理程式／沙箱工作區，否則可能使檔案系統工具接觸敏感的本機檔案（例如 `~/.openclaw` 下的狀態／設定）。 ## 個別代理程式存取設定檔（多代理程式） 每個代理程式都可擁有自己的沙箱與工具政策：完整存取、唯讀或無存取權。優先順序規則請參閱[多代理程式沙箱與工具](/zh-TW/tools/multi-agent-sandbox-tools)。 常見模式：個人代理程式（完整存取、不使用沙箱）、家庭／工作代理程式（使用沙箱 + 唯讀工具）、公開代理程式（使用沙箱 + 無檔案系統／Shell 工具）。 ### 完整存取（不使用沙箱） ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" } }, ], }, } ``` ### 唯讀工具 + 唯讀工作區 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "family", workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" }, tools: { allow: ["read"], deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], }, }, ], }, } ``` ### 無檔案系統／Shell 存取權（允許供應商訊息傳遞） ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "public", workspace: "~/.openclaw/workspace-public", sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" }, tools: { // 工作階段工具可能會揭露逐字稿資料。預設範圍為目前工作階段 + 衍生的工作階段； // 讀取範圍也包括透過環境群組感知所監看、屬於相同代理程式的群組。 // 使用 visibility: "self" 可排除這些受監看的工作階段。 sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "discord", "slack", "telegram", "whatsapp", ], deny: [ "apply_patch", "browser", "canvas", "cron", "edit", "exec", "gateway", "image", "nodes", "process", "read", "write", ], }, }, ], }, } ``` ## 瀏覽器控制風險 啟用瀏覽器控制會讓模型取得真正的瀏覽器。若該設定檔已包含登入中的工作階段，模型便可存取這些帳號與資料——請將瀏覽器設定檔視為敏感狀態。 * 代理程式應優先使用專用設定檔（預設的 `openclaw` 設定檔）；避免使用你日常使用的個人設定檔。 * 除非你信任置於沙箱中的代理程式，否則應停用其主機瀏覽器控制。 * 獨立的回送瀏覽器控制 API 僅接受共用密鑰驗證（閘道權杖持有人驗證或閘道密碼）——不會使用受信任 Proxy 或 Tailscale Serve 身分標頭。 * 將瀏覽器下載項目視為不受信任的輸入；建議使用隔離的下載目錄。 * 若可行，請在代理程式設定檔中停用瀏覽器同步／密碼管理器。 * 對遠端閘道而言，“瀏覽器控制”等同於對該設定檔可存取之所有項目的“操作員存取權”。 * 閘道與節點主機應僅限 tailnet 存取；避免將瀏覽器控制連接埠暴露於區域網路或公用網際網路。 * 不需要時請停用瀏覽器 Proxy 路由（`gateway.nodes.browser.mode="off"`）。 * Chrome MCP 的現有工作階段模式並不“更安全”——它能以你的身分操作該主機 Chrome 設定檔可存取的任何內容。 * 當閘道與瀏覽器位於不同遠端位置時，請在瀏覽器所在機器執行**節點主機**，並讓閘道代理瀏覽器動作（請參閱[瀏覽器工具](/zh-TW/tools/browser)）；將節點配對視同管理員存取權，讓閘道與節點主機位於相同 tailnet，並避免透過區域網路、公用網際網路或 Tailscale Funnel 暴露轉送／控制連接埠。 ### 瀏覽器 SSRF 政策（預設嚴格） 除非你明確選擇允許，否則私人／內部目的地會維持封鎖。 * 預設：未設定 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，因此私人／內部／特殊用途目的地會維持封鎖。仍接受舊版別名 `allowPrivateNetwork`。 * 選擇允許：設定 `dangerouslyAllowPrivateNetwork: true` 以允許這些目的地。 * 在嚴格模式中，使用 `hostnameAllowlist`（例如 `*.example.com` 的模式）及 `allowedHostnames`（精確的主機例外，包括 `localhost` 等原本會遭封鎖的名稱）設定明確例外。 * 直接導覽要求會先經過預檢。在動作執行期間及動作後有限的寬限時間內，受防護的 Playwright 互動（點擊、座標點擊、暫留、拖曳、捲動、選取、按鍵、輸入、填寫表單及求值）會在傳送 HTTP 要求位元組之前，攔截政策所拒絕的頂層與子框架文件載入，接著盡力重新檢查最終的 `http(s)` URL。 * 每次全新啟動受管理的 Chrome 前，OpenClaw 都會盡力停用網路預測，以抑制所觀察到 Chromium 對這些遭拒載入執行的推測性預先連線。這是縱深防禦，而非政策邊界：跨控制服務重新啟動而重複使用的瀏覽器，以及其他瀏覽器後端，可能不具備相同的強化措施。頁面路由仍是要求層級的攔截，而非網路防火牆：重新導向躍點、彈出式視窗的第一個要求、Service Worker 流量、有限防護時段結束後執行的頁面程式碼，以及部分背景／子資源路徑，都可能繞過此機制。最終 URL 檢查仍屬偵測／隔離防禦；若要完全防止，必須由擁有者端實施輸出流量隔離或使用政策強制執行 Proxy。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { browser: { ssrfPolicy: { dangerouslyAllowPrivateNetwork: false, hostnameAllowlist: ["*.example.com", "example.com"], allowedHostnames: ["localhost"], }, }, } ``` ## 網路暴露 ### 繫結、連接埠、防火牆 閘道會在單一連接埠上多工處理 WebSocket + HTTP（預設為 `18789`；設定／旗標／環境變數：`gateway.port`、`--port`、`OPENCLAW_GATEWAY_PORT`）。該 HTTP 介面包括控制介面（SPA 資產，預設基底路徑為 `/`）與畫布主機（`/__openclaw__/canvas` 和 `/__openclaw__/a2ui`——任意 HTML/JS；在一般瀏覽器中載入時，請將其視為不受信任的內容；請勿向不受信任的網路／使用者公開，也不要與具特殊權限的網頁介面共用來源）。 `gateway.bind` 控制閘道的監聽位置： * `"loopback"`（預設）：只有本機用戶端能連線。 * `"lan"`、`"tailnet"`、`"custom"`：會擴大攻擊面。只有在使用閘道驗證（共用權杖／密碼，或正確設定的受信任 Proxy）及真正的防火牆時才使用。 經驗法則：優先使用 Tailscale Serve，而非區域網路繫結（Serve 會讓閘道維持在回送介面，由 Tailscale 處理存取）；若必須繫結至區域網路，請在防火牆中將該連接埠限制於嚴格的來源 IP 允許清單，而不要廣泛轉送連接埠；絕不可在 `0.0.0.0` 上公開未經驗證的閘道。 ### 使用 UFW 發布 Docker 連接埠 發布的容器連接埠（`-p HOST:CONTAINER` 或 Compose 的 `ports:`）會經由 Docker 的轉送鏈路由，而不只經過主機的 `INPUT` 規則。請在 `DOCKER-USER` 中強制執行規則（會在 Docker 自身的接受規則之前評估）；多數現代發行版使用 `iptables-nft` 前端，而該前端仍會將這些規則套用至 nftables 後端。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # /etc/ufw/after.rules（附加為獨立的 *filter 區段） *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN -A DOCKER-USER -s 127.0.0.0/8 -j RETURN -A DOCKER-USER -s 10.0.0.0/8 -j RETURN -A DOCKER-USER -s 172.16.0.0/12 -j RETURN -A DOCKER-USER -s 192.168.0.0/16 -j RETURN -A DOCKER-USER -s 100.64.0.0/10 -j RETURN -A DOCKER-USER -p tcp --dport 80 -j RETURN -A DOCKER-USER -p tcp --dport 443 -j RETURN -A DOCKER-USER -m conntrack --ctstate NEW -j DROP -A DOCKER-USER -j RETURN COMMIT ``` IPv6 使用獨立的資料表——若已啟用 Docker IPv6，請在 `/etc/ufw/after6.rules` 中新增相符的政策。請避免寫死介面名稱（`eth0`），因為不同 VPS 映像檔使用的名稱可能不同（`ens3`、`enp*` 等），名稱不符可能會讓拒絕規則在無任何警告的情況下遭到略過。 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ufw reload iptables -S DOCKER-USER ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` 預期的外部連接埠應僅包括你刻意公開的項目（對多數設定而言：SSH + 反向 Proxy 連接埠）。 ### mDNS/Bonjour 探索 啟用隨附的 `bonjour` 外掛後，閘道會透過 mDNS（`_openclaw-gw._tcp`，連接埠 5353）廣播其存在，以供本機裝置探索。完整模式包含會暴露作業細節的 TXT 記錄：`cliPath`（會揭露使用者名稱與安裝位置的檔案系統路徑）、`sshPort`（公告 SSH 可用性）、`displayName`/`lanHost`（主機名稱資訊）。廣播基礎設施細節會讓區域網路偵察更容易。 * 除非需要區域網路探索，否則應停用 Bonjour——它會在 macOS 主機上自動啟動，而在其他系統上則須選擇啟用；直接使用閘道 URL、Tailnet、SSH 或廣域 DNS-SD 可避免本機多點傳送。 * **最小模式**（啟用 Bonjour 時的預設值，建議暴露於外部的閘道使用）會省略敏感欄位： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { discovery: { mdns: { mode: "minimal" } } } ``` * **關閉**會在維持外掛啟用的同時停用本機探索： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { discovery: { mdns: { mode: "off" } } } ``` * **完整模式**（選擇啟用）包含 `cliPath` + `sshPort`： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { discovery: { mdns: { mode: "full" } } } ``` * 也可以設定 `OPENCLAW_DISABLE_BONJOUR=1`，在不變更設定的情況下停用 mDNS。 在最小模式中，閘道會廣播 `role`、`gatewayPort`、`transport`，但省略 `cliPath`/`sshPort`；需要命令列介面路徑的應用程式，可改為透過已驗證的 WebSocket 連線取得。 ### 閘道 WebSocket 驗證 預設要求閘道驗證——若未設定任何有效的驗證路徑，閘道會拒絕 WebSocket 連線（故障時關閉）。初始設定預設會產生權杖（即使使用回送介面也是如此），因此本機用戶端也必須驗證。 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { auth: { mode: "token", token: "your-token" } } } ``` `openclaw doctor --generate-gateway-token` 可為你產生權杖。 `gateway.remote.token` 和 `gateway.remote.password` 是用戶端認證資訊來源，本身無法保護本機 WS 存取。本機呼叫路徑僅在未設定 `gateway.auth.*` 時，才使用 `gateway.remote.*` 作為備援。若透過 SecretRef 明確設定 `gateway.auth.token` 或 `gateway.auth.password`，但無法解析，解析將以封閉方式失敗（不會以遠端備援掩蓋失敗）。 使用 `wss://` 時，請以 `gateway.remote.tlsFingerprint` 固定遠端 TLS。迴路、私有 IP 常值、`.local` 和 Tailnet `*.ts.net` 閘道 URL 可接受明文 `ws://`；對於其他受信任的私有 DNS 名稱，請在用戶端程序設定 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 作為緊急解鎖措施（僅限程序環境，不是 `openclaw.json` 鍵）。行動裝置配對及 Android 手動／掃描的閘道路由更為嚴格：只有迴路可使用明文，而私有 LAN、鏈路本機、`.local` 和不含點號的主機名稱都必須使用 TLS，除非你明確選擇受信任私有網路的明文路徑。 直接透過本機迴路連線時，裝置配對會自動核准（另有一條範圍狹窄的後端／容器本機自我連線路徑，供受信任的共用密鑰輔助程式流程使用）；Tailnet 和 LAN 連線（包括連至 Tailnet 位址的同主機連線）均視為遠端連線，仍需核准。解析出的 `tailnet` 位址或 `custom` 位址若不是 `127.0.0.1` 或 `0.0.0.0`，就會新增獨立的 `127.0.0.1` 接聽器；只有連至該本機接聽器的連線才會獲得迴路語意。迴路請求若有轉送標頭證據，就不再符合迴路本機性；中繼資料升級的自動核准範圍受到嚴格限制。請參閱[閘道配對](/zh-TW/gateway/pairing)。 驗證模式： * `"token"`：共用持有人權杖（建議用於大多數設定）。 * `"password"`：建議透過 `OPENCLAW_GATEWAY_PASSWORD` 設定。 * `"trusted-proxy"`：信任具身分辨識能力的反向 Proxy，由其驗證使用者並透過標頭傳遞身分。請參閱[受信任的 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。 輪替檢查清單（權杖／密碼）：產生／設定新的密鑰（`gateway.auth.token` 或 `OPENCLAW_GATEWAY_PASSWORD`）；重新啟動閘道（若由 macOS App 監督閘道，則重新啟動該 App）；更新遠端用戶端（`gateway.remote.token`/`.password`）；確認舊的認證資訊已無法使用。 ### Tailscale Serve 身分標頭 當 `gateway.auth.allowTailscale` 為 `true`（Serve 的預設值）時，OpenClaw 會接受 Tailscale Serve 身分標頭 `tailscale-user-login`，用於控制介面／WebSocket 驗證。它會透過本機 Tailscale 常駐程式（`tailscale whois`）解析 `x-forwarded-for` 位址，並將結果與標頭比對以驗證身分；這只會對帶有 Tailscale 注入的 `x-forwarded-for`、`x-forwarded-proto` 和 `x-forwarded-host` 的迴路請求觸發。對於這項非同步檢查，限制器記錄失敗前，會序列化相同 `{scope, ip}` 的失敗嘗試，因此來自同一 Serve 用戶端的並行錯誤重試，可能使第二次嘗試立即遭到鎖定。 HTTP API 端點（`/v1/*`、`/tools/invoke`、`/api/channels/*`）不使用 Tailscale 身分標頭驗證，而是遵循閘道所設定的 HTTP 驗證模式。 閘道 HTTP 持有人驗證實際上等同於全有或全無的操作員存取權。能夠呼叫 `/v1/chat/completions`、`/v1/responses`、`/api/v1/admin/rpc` 等外掛路由或 `/api/channels/*` 的認證資訊，都是該閘道具完整存取權的操作員密鑰：共用密鑰持有人驗證會還原完整的預設操作員範圍（`operator.admin`、`operator.approvals`、`operator.pairing`、`operator.read`、`operator.talk.secrets`、`operator.write`）以及代理程式輪次的擁有者語意，而範圍較窄的 `x-openclaw-scopes` 值不會縮減該共用密鑰路徑。只有當請求來自帶有身分的模式（受信任 Proxy 驗證）或明確無須驗證的私有入口時，才會套用每個請求的範圍語意；在這些模式中，省略 `x-openclaw-scopes` 時，會回復至一般操作員的預設範圍集合，而當範圍縮減時，`x-openclaw-model` 等擁有者層級標頭需要 `operator.admin`。`/tools/invoke` 和 HTTP 工作階段歷程記錄端點遵循相同的共用密鑰規則。請勿與不受信任的呼叫端共用這些認證資訊；每個信任邊界最好使用不同的閘道。 無權杖 Serve 驗證假設閘道主機本身受信任，無法防範惡意的同主機程序。若閘道主機可能執行不受信任的本機程式碼，請停用 `allowTailscale`，並要求使用明確的共用密鑰驗證（`token` 或 `password`）。 請勿從你自己的反向 Proxy 轉送這些標頭。若你在閘道前終止 TLS 或使用 Proxy，請停用 `allowTailscale`，並改用共用密鑰驗證或[受信任的 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。 請參閱 [Tailscale](/zh-TW/gateway/tailscale) 和 [Web 概觀](/zh-TW/web)。 ### 反向 Proxy 設定 在 nginx/Caddy/Traefik 等服務後方時，請設定 `gateway.trustedProxies`，以正確處理轉送的用戶端 IP。當閘道偵測到來自**不在** `trustedProxies` 中之位址的 Proxy 標頭時，不會將該連線視為本機連線；若閘道驗證已停用，該連線將遭到拒絕。這可防止經 Proxy 的連線看似來自 localhost 並自動獲得信任。 `trustedProxies` 也會提供資訊給更嚴格的 `gateway.auth.mode: "trusted-proxy"`：依預設，它會對來源為迴路的 Proxy 採取封閉式失敗。同主機迴路反向 Proxy 可使用 `trustedProxies` 進行本機用戶端偵測及轉送 IP 處理，但只有在 `gateway.auth.trustedProxy.allowLoopback = true` 時才能符合 `trusted-proxy` 驗證模式；否則請使用權杖／密碼驗證。 ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} gateway: trustedProxies: - "10.0.0.1" # 反向 Proxy IP allowRealIpFallback: false # 預設為 false；只有當你的 Proxy 無法提供 X-Forwarded-For 時才啟用 auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` 設定 `trustedProxies` 後，閘道會使用 `X-Forwarded-For` 判斷用戶端 IP；除非明確設定 `gateway.allowRealIpFallback: true`，否則會忽略 `X-Real-IP`。請確保你的 Proxy 會**覆寫** `X-Forwarded-For`/`X-Real-IP`，而不是附加內容： ```nginx theme={"theme":{"light":"min-light","dark":"min-dark"}} # 正確 proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; # 錯誤：保留／附加由不受信任用戶端提供的值 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` 受信任的 Proxy 標頭不會使節點裝置配對自動獲得信任；`gateway.nodes.pairing.autoApproveCidrs` 是另一項預設停用的操作員原則，而即使啟用迴路受信任 Proxy 驗證，來源為迴路的受信任 Proxy 標頭路徑仍不納入節點自動核准（因為本機呼叫端可偽造這些標頭）。 ### HSTS 與來源注意事項 * OpenClaw 的閘道以本機／迴路優先。若你在反向 Proxy 終止 TLS，請在該處設定 HSTS。 * 若由閘道本身終止 HTTPS，`gateway.http.securityHeaders.strictTransportSecurity` 會從 OpenClaw 回應發出 HSTS 標頭。 * 非迴路的控制介面部署依預設需要 `gateway.controlUi.allowedOrigins`；`allowedOrigins: ["*"]` 是明確允許所有來源的原則，而不是經過強化的預設值，請避免在嚴格控管的本機測試之外使用。 * 即使啟用一般迴路豁免，迴路上的瀏覽器來源驗證失敗仍會受到速率限制，但鎖定鍵會依正規化的 `Origin` 值分別設定，而不是使用單一共用 localhost 儲存區。 * `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host 標頭來源備援模式；應將其視為操作員所選的危險原則。 * 請將 DNS 重新綁定和 Proxy 主機標頭行為視為部署強化事項；嚴格限制 `trustedProxies`，並避免將閘道直接暴露於公用網際網路。 * 詳細部署指南：[受信任的 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth#tls-termination-and-hsts)。 ### 透過 HTTP 使用控制介面 控制介面需要安全內容（HTTPS 或 localhost）才能產生裝置身分。 * `gateway.controlUi.allowInsecureAuth`：本機相容性開關。在 localhost 上，當頁面透過不安全的 HTTP 載入時，允許控制介面在沒有裝置身分的情況下進行驗證。不會略過配對檢查，也不會放寬遠端（非 localhost）裝置身分要求。建議使用 HTTPS（Tailscale Serve），或在 `127.0.0.1` 開啟介面。 * `gateway.controlUi.dangerouslyDisableDeviceAuth`：已淘汰的緊急解鎖輸入。舊版設定會保留已驗證且僅限配對的控制介面存取權以進行修復，直到透過 HTTPS 或 localhost 重新開啟的瀏覽器完成有範圍限制的明確自我配對遷移；請勿將其加入目前設定。 * 除了這些旗標之外，成功的 `gateway.auth.mode: "trusted-proxy"` 可允許沒有裝置身分的**操作員**控制介面工作階段；這是刻意設計的驗證模式行為，而不是 `allowInsecureAuth` 捷徑，且不適用於節點角色的控制介面工作階段。 啟用 `allowInsecureAuth` 時，`openclaw security audit` 會發出警告。 ### 不安全／危險旗標 對每個已啟用且已知不安全／危險的偵錯開關，`openclaw security audit` 都會提出 `config.insecure_or_dangerous_flags`（每個旗標一項發現）。請勿在正式環境中設定這些旗標。若已設定稽核抑制，即使相符的發現移至 `suppressedFindings`，`security.audit.suppressions.active` 仍會保留在有效輸出中。 * `gateway.controlUi.allowInsecureAuth=true` * `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` * 從已淘汰的 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` 匯入、尚待進行的控制介面裝置驗證遷移 * `security.audit.suppressions configured ()` * `hooks.gmail.allowUnsafeExternalContent=true` * `hooks.mappings[].allowUnsafeExternalContent=true` * `tools.exec.applyPatch.workspaceOnly=false` * `plugins.entries.acpx.config.permissionMode=approve-all` 控制介面與瀏覽器： * `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` * `gateway.controlUi.dangerouslyDisableDeviceAuth`（已淘汰的升級輸入） * `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 頻道名稱比對（內建與外掛頻道；適用時也包含每個 `accounts.`）： * `channels.discord.dangerouslyAllowNameMatching` * `channels.googlechat.dangerouslyAllowNameMatching` * `channels.msteams.dangerouslyAllowNameMatching` * `channels.slack.dangerouslyAllowNameMatching` * `channels.irc.dangerouslyAllowNameMatching`（外掛頻道） * `channels.mattermost.dangerouslyAllowNameMatching`（外掛頻道） * `channels.synology-chat.dangerouslyAllowNameMatching`（外掛頻道） * `channels.synology-chat.dangerouslyAllowInheritedWebhookPath`（外掛頻道） * `channels.zalouser.dangerouslyAllowNameMatching`（外掛頻道） 網路暴露： * `channels.telegram.network.dangerouslyAllowPrivateNetwork`（也可依帳戶設定） 沙箱 Docker（預設值與每個代理程式）： * `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` * `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` * `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin` ## 部署與主機信任 * 閘道主機應啟用全磁碟加密；若主機為共用環境，建議為閘道使用專用的作業系統使用者帳號。 * 已發布套件的相依性鎖定：原始碼簽出版本使用 `pnpm-lock.yaml`；已發布的 `openclaw` npm 套件與 OpenClaw 所擁有的 npm 外掛套件包含 `npm-shrinkwrap.json`，因此安裝時會使用發布版本中經審查的遞移相依性圖，而非在安裝時重新解析相依性圖。這是供應鏈強化與發布可重現性的邊界，而非沙箱——請參閱 [npm shrinkwrap](/zh-TW/gateway/security/shrinkwrap)。 * 安全檔案操作：OpenClaw 使用 `@openclaw/fs-safe` 進行限制於根目錄內的檔案存取、不可分割寫入、封存檔解壓縮、暫存工作區及機密檔案輔助操作。選用的 POSIX Python 輔助程式預設為**關閉**；只有在你需要額外的檔案描述元相對變更強化，且能支援 Python 執行環境時，才設定 `OPENCLAW_FS_SAFE_PYTHON_MODE=auto` 或 `require`。詳細資訊：[安全檔案操作](/zh-TW/gateway/security/secure-file-operations)。 * 共用 Slack 工作區的風險：若 Slack 中的所有人都能傳訊息給機器人，核心風險在於委派的工具權限——任何獲准的傳送者都能在代理程式的政策範圍內觸發工具呼叫（`exec`、瀏覽器、網路／檔案工具）；來自某位傳送者的提示詞／內容注入可能影響共用狀態、裝置與輸出；若共用代理程式擁有敏感的認證資訊或檔案，任何獲准的傳送者都可能透過工具使用來驅動資料外洩。團隊工作流程應使用配備最少工具的獨立代理程式／閘道；處理個人資料的代理程式應保持私有。 * 公司共用代理程式（可接受的模式）：若所有使用代理程式的人都處於相同的信任邊界內（例如同一公司的團隊），且代理程式嚴格限定於業務用途，則可接受此模式。請在專用機器／虛擬機器／容器上執行，使用專用的作業系統使用者、專用瀏覽器／設定檔／帳號，且不要讓該執行環境登入個人的 Apple／Google 帳號，或使用個人的密碼管理器／瀏覽器設定檔。在同一執行環境中混用個人與公司身分，會破壞兩者之間的隔離，並增加個人資料暴露的風險。 ## 磁碟上的機密資料 假設 `~/.openclaw/`（或 `$OPENCLAW_STATE_DIR/`）下的任何內容都可能包含機密資料或私人資料： | 路徑 | 內容 | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.json` | 設定可能包含權杖（閘道、遠端閘道）、供應商設定及允許清單。 | | `credentials/**` | 頻道認證資訊（例如 WhatsApp 認證資訊）、配對允許清單、舊版 OAuth 匯入資料。 | | `state/openclaw.sqlite` | 共用執行階段狀態，包括原生 MCP OAuth 存取／重新整理權杖、動態用戶端註冊密鑰及探索狀態。 | | `agents//agent/openclaw-agent.sqlite` | 各代理程式的執行階段狀態，包括模型驗證設定檔。 | | `agents//agent/auth-profiles.json` | 舊版模型驗證遷移來源；doctor 會將支援的記錄匯入各代理程式的 SQLite 資料庫。 | | `agents//agent/codex-home/**` | 各代理程式的 Codex 應用程式伺服器帳戶、設定、Skills、外掛、原生對話串狀態、診斷資料（預設）。 | | `$CODEX_HOME/**` 或 `~/.codex/**` | 原生 Codex 執行階段狀態。一般控管框架只有在明確設定 `plugins.entries.codex.config.appServer.homeScope: "user"` 時才會存取。當個別監督連線解析出的主目錄範圍為 `"user"` 時，該連線會存取此狀態；未設定時，這是 stdio 或 Unix 的預設值。內含原生 Codex 帳戶、設定、外掛及對話串儲存區。監督功能會列出來源中繼資料，並在該連線上保留續接 Chat 的標準原生分支及後續輪次；建立分支時，會將有限範圍的持久化使用者與助理歷史記錄複製到已驗證且鎖定模型的 OpenClaw Chat。僅限由擁有者控制的閘道啟用。請參閱 [Codex 控管框架](/zh-TW/plugins/codex-harness#share-threads-with-codex-desktop-and-cli)及 [Codex 監督](/zh-TW/plugins/codex-supervision)。 | | `secrets.json`（選用） | `file` SecretRef 供應商（`secrets.providers`）使用的檔案型密鑰承載資料。 | | `agents//agent/auth.json` | 舊版相容性檔案；探索到靜態 `api_key` 項目時會將其清除。 | | `agents//agent/openclaw-agent.sqlite` | 各代理程式的執行階段狀態，包括可能含有私人訊息及工具輸出的工作階段資料列與文字記錄。 | | `agents//sessions/**` | 舊版工作階段遷移來源與封存資料，可能含有私人訊息及工具輸出。 | | 隨附的外掛套件 | 已安裝的外掛（以及其 `node_modules/`）。 | | `sandboxes/**` | 工具沙箱工作區；可能會累積在沙箱內讀取／寫入之檔案的副本。 | ### 認證資訊儲存位置對照表 也有助於制定備份策略： * WhatsApp：`~/.openclaw/credentials/whatsapp//creds.json` * Telegram Bot 權杖：設定／環境變數或 `channels.telegram.tokenFile`（僅限一般檔案；拒絕符號連結） * Discord Bot 權杖：設定／環境變數或 SecretRef（環境變數／檔案／執行提供者） * Slack 權杖：設定／環境變數（`channels.slack.*`） * 配對允許清單：`~/.openclaw/credentials/-allowFrom.json`（預設帳號）／`--allowFrom.json`（非預設帳號） * 模型驗證設定檔：`~/.openclaw/agents//agent/openclaw-agent.sqlite`（`auth_profile_store`） * MCP OAuth 工作階段：`~/.openclaw/state/openclaw.sqlite`（`mcp_oauth_stores`） * 舊版 OAuth 匯入：`~/.openclaw/credentials/oauth.json` 安全強化：嚴格限制權限（目錄使用 `700`，檔案使用 `600`）；在閘道主機上使用全磁碟加密；若主機為共用，建議使用專用的作業系統使用者帳號。 ### 檔案權限 * `~/.openclaw/openclaw.json`：`600`（僅限使用者讀取／寫入） * `~/.openclaw`：`700`（僅限使用者） `openclaw doctor` 可以發出警告，並提供收緊這些權限的選項。 ### 工作區 `.env` 檔案 OpenClaw 會為代理程式和工具載入工作區本機的 `.env` 檔案，但絕不允許這些檔案在未明示的情況下覆寫閘道執行階段控制項： * 不受信任的工作區 `.env` 檔案不得設定提供者認證資訊環境變數，例如 `GEMINI_API_KEY`、`GOOGLE_API_KEY`、`XAI_API_KEY`、`MISTRAL_API_KEY`、`GROQ_API_KEY`、`DEEPSEEK_API_KEY`、`PERPLEXITY_API_KEY`、`BRAVE_API_KEY`、`TAVILY_API_KEY`、`EXA_API_KEY`、`FIRECRAWL_API_KEY`，以及已安裝的受信任外掛所宣告的提供者驗證金鑰。請改將提供者認證資訊放在閘道程序環境、`~/.openclaw/.env`（`$OPENCLAW_STATE_DIR/.env`）、設定的 `env` 區塊，或選用的登入殼層匯入中。 * 不受信任的工作區 `.env` 檔案不得設定任何以 `OPENCLAW_` 開頭的鍵，以保留整個執行階段命名空間。如此一來，未來的 `OPENCLAW_*` 控制項預設會採取失敗即關閉機制，而不會在未明示的情況下繼承版本庫中或攻擊者提供的 `.env` 內容。 * 工作區 `.env` 也不得覆寫頻道和提供者的端點路由設定（例如 `MATRIX_HOMESERVER`、`MATTERMOST_URL`、`IRC_HOST`、`SYNOLOGY_CHAT_INCOMING_URL`、`AZURE_SPEECH_ENDPOINT`，以及其他以 `_ENDPOINT` 結尾的鍵），因此複製的工作區無法透過本機端點設定重新導向內建連接器的流量。這些設定必須來自閘道程序環境、全域執行階段 dotenv、明確設定或 `env.shellEnv`。 * 受信任的程序／作業系統環境變數、全域執行階段 dotenv、設定 `env`，以及已啟用的登入殼層匯入仍然有效；這項限制只適用於載入工作區 `.env` 檔案。 工作區 `.env` 檔案通常位於代理程式程式碼旁，可能意外提交至版本庫，或由工具寫入；禁止其中包含提供者認證資訊，可防止複製的工作區改用攻擊者控制的提供者帳號。 ### 記錄與對話逐字稿 OpenClaw 會將工作階段對話逐字稿儲存在磁碟的 `~/.openclaw/agents//sessions/*.jsonl` 下，以維持工作階段連續性及選用的記憶索引；任何具有檔案系統存取權的程序／使用者都能讀取這些內容。請將磁碟存取視為信任邊界，並嚴格限制 `~/.openclaw` 的權限；若需要更強的隔離，請讓代理程式在不同的作業系統使用者帳號或主機下執行。 閘道記錄可能包含工具摘要、錯誤和 URL；工作階段對話逐字稿可能包含貼上的機密資訊、檔案內容、命令輸出和連結。 * 保持啟用記錄／對話逐字稿遮蔽（`logging.redactSensitive: "tools"`，預設值）。 * 透過 `logging.redactPatterns` 新增適用於你的環境的自訂模式（權杖、主機名稱、內部 URL）。 * 分享診斷資訊時，建議使用 `openclaw status --all`（可直接貼上，且已遮蔽機密資訊），而非原始記錄。 * 若不需要長期保留，請清除舊的工作階段對話逐字稿和記錄檔。 詳細資訊：[記錄](/zh-TW/gateway/logging) ## 安全基準設定（複製／貼上） ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { mode: "local", bind: "loopback", port: 18789, auth: { mode: "token", token: "your-long-random-token" }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` 此設定會將閘道維持為私有、要求私訊配對，並避免群組 Bot 持續運作。若也要提高工具執行的安全性，請為任何非擁有者代理程式新增沙箱，並拒絕危險工具（請參閱上方的「每個代理程式的存取設定檔」）。 ### 使用不同號碼（WhatsApp、Signal、Telegram） 對於以電話號碼為基礎的頻道，請考慮讓助理使用與個人號碼不同的號碼，如此個人對話可保持私密，而 Bot 號碼則在自己的界線內處理自動化作業。 ## 事件應變 ### 控制影響範圍 1. 停止執行：停止 macOS App（若由其監督閘道），或終止你的 `openclaw gateway` 程序。 2. 關閉對外開放：設定 `gateway.bind: "loopback"`（或停用 Tailscale Funnel／Serve），直到釐清事發經過。 3. 凍結存取：將有風險的私訊／群組切換為 `dmPolicy: "disabled"`／要求提及，並移除所有 `"*"` 全部允許項目。 ### 輪替（若機密資訊外洩，應假設已遭入侵） 1. 輪替閘道驗證資訊（`gateway.auth.token`／`OPENCLAW_GATEWAY_PASSWORD`），然後重新啟動。 2. 在任何可呼叫閘道的電腦上輪替遠端用戶端機密資訊（`gateway.remote.token`／`.password`）。 3. 輪替提供者／API 認證資訊（WhatsApp 認證資訊、Slack／Discord 權杖、`auth-profiles.json` 中的模型／API 金鑰，以及使用加密機密資訊承載資料時的值）。 ### 稽核 1. 使用 `openclaw logs` 檢查閘道記錄（或針對具名設定檔使用 `openclaw --profile logs`）。預設路徑為 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`；除非 `logging.file` 加以覆寫，否則具名設定檔使用 `/tmp/openclaw/openclaw--YYYY-MM-DD.log`。 2. 檢閱相關對話逐字稿：`~/.openclaw/agents//sessions/*.jsonl`。 3. 檢閱近期可能擴大存取範圍的設定變更：`gateway.bind`、`gateway.auth`、私訊／群組政策、`tools.elevated`、外掛變更。 4. 重新執行 `openclaw security audit --deep`，並確認嚴重問題均已解決。 ### 蒐集報告資料 * 時間戳記、閘道主機的作業系統及 OpenClaw 版本。 * 工作階段對話逐字稿及一小段記錄尾端內容（遮蔽後）。 * 攻擊者傳送的內容，以及代理程式採取的動作。 * 閘道是否開放至回送介面以外的範圍（LAN／Tailscale Funnel／Serve）。 ## 機密資訊掃描 CI 會在版本庫上執行 pre-commit 的 `detect-private-key` 鉤子。若執行失敗，請移除或輪替已提交的金鑰資料，然後在本機重現： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} pre-commit run --all-files detect-private-key ``` ## 回報安全性問題 在 OpenClaw 中發現弱點？請負責任地回報： 1. 電子郵件：[security@openclaw.ai](mailto:security@openclaw.ai) 2. 修正前請勿公開發布。 3. 我們會將你列入致謝名單（除非你希望保持匿名）。