OpenClaw 威脅模型：基於 MITRE ATLAS 的 AI 安全指南

你在開發 AI Agent 或整合各種通訊頻道時，最擔心的通常不是程式碼跑不起來，而是當你把 Agent 部署到 WhatsApp 或 Slack 後，完全不知道它的安全邊界在哪裡。傳統的 Web 安全模型沒辦法完全涵蓋 AI 模型特有的攻擊路徑，這讓你很難判斷系統是否真的安全。

這份威脅模型採用了 MITRE ATLAS 框架，專門為 AI 系統設計，幫助你釐清 OpenClaw 在運行時可能面臨的風險。

需要準備的東西

• MITRE ATLAS 框架基礎知識
• 對 OpenClaw Agent Runtime 與 Gateway 架構的理解
• 熟悉 ClawHub 技能市場的運作流程
• 參考 ATLAS Techniques 與 ATLAS Tactics

快速開始

這份威脅模型是一個持續更新的活文件，你可以透過以下 4 個步驟參與安全維護：

1. 確認範圍：檢查你的開發項目是否在 Agent Runtime、Gateway 或 MCP Servers 的涵蓋範圍內。
2. 對齊框架：參考 ATLAS Case Studies 了解現實中的 AI 攻擊案例。
3. 回報威脅：如果你發現了新的安全漏洞，請參考 CONTRIBUTING-THREAT-MODEL.md 進行回報。
4. 優化建議：針對現有的威脅描述，你可以提議更新攻擊鏈或緩解措施。

威脅模型範圍

組件	是否包含	備註
OpenClaw Agent Runtime	是	核心 Agent 執行、tool calls、sessions
Gateway	是	Authentication、routing、channel 整合
Channel Integrations	是	WhatsApp, Telegram, Discord, Signal, Slack 等
ClawHub Marketplace	是	技能發佈、審核、分發
MCP Servers	是	外部工具提供者
User Devices	部分	行動裝置 App、桌面客戶端

疑難排解

• 發現新的威脅？：請查閱 CONTRIBUTING-THREAT-MODEL.md 的準則來提交報告。
• 威脅描述過時？：你可以直接提議更新現有的威脅內容或建議新的緩解方案。

如果你在設定安全策略時遇到困難，可以詢問 AI Setup Assistant。

下一步

• 貢獻指南：威脅模型
• MITRE ATLAS GitHub 資源

開發 AI Agent 的時候，最讓人頭痛的通常不是模型夠不夠聰明，而是安全性。你可能也會擔心：萬一模型被惡意引導，會不會隨意執行指令？或者在處理外部連結時，會不會導致伺服器被攻擊？

建立一個可靠的 AI 系統，關鍵在於定義清楚「誰能信任」以及「在哪裡執行」。這份文件會帶你拆解我們的系統架構，看看我們是如何透過五層安全邊界來保護你的資料與設備。

需要準備的東西

根據源文檔，在開始探索架構前，你可能需要接觸到以下組件：

• WhatsApp, Telegram 或 Discord 等通訊 Channel
• Docker 或 Node.js 執行環境（用於 Sandbox）
• GitHub 帳號（用於 ClawHub 驗證）

Quick Start: 5 分鐘理解安全流程

要快速上手這套架構，你可以從最外層的 Gateway 開始理解：

1. 建立連線：當你從 WhatsApp 或其他 Channel 發起請求，首先會進入 Gateway。
2. 裝置配對：利用 Gateway 的 Device Pairing 功能，請注意這有 30 秒的寬限期 (grace period)。
3. 身份驗證：系統會透過 AllowFrom / AllowList 驗證，並檢查 Token、Password 或 Tailscale 狀態。
4. 進入沙箱：一旦通過驗證，Agent 的工具執行會在 Docker 或受限的 Host 環境中運行，確保安全。

2. System Architecture

2.1 Trust Boundaries (安全邊界)

我們將系統劃分為不同的信任層級，每一層都有其特定的防禦機制：

┌─────────────────────────────────────────────────────────────────┐
│                    UNTRUSTED ZONE                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  WhatsApp   │  │  Telegram   │  │   Discord   │  ...         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
└─────────┼────────────────┼────────────────┼──────────────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TRUST BOUNDARY 1: Channel Access                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                      GATEWAY                              │   │
│  │  • Device Pairing (30s grace period)                      │   │
│  │  • AllowFrom / AllowList validation                       │   │
│  │  • Token/Password/Tailscale auth                          │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TRUST BOUNDARY 2: Session Isolation              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   AGENT SESSIONS                          │   │
│  │  • Session key = agent:channel:peer                       │   │
│  │  • Tool policies per agent                                │   │
│  │  • Transcript logging                                     │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TRUST BOUNDARY 3: Tool Execution                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  EXECUTION SANDBOX                        │   │
│  │  • Docker sandbox OR Host (exec-approvals)                │   │
│  │  • Node remote execution                                  │   │
│  │  • SSRF protection (DNS pinning + IP blocking)            │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TRUST BOUNDARY 4: External Content               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              FETCHED URLs / EMAILS / WEBHOOKS             │   │
│  │  • External content wrapping (XML tags)                   │   │
│  │  • Security notice injection                              │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                 TRUST BOUNDARY 5: Supply Chain                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                      CLAWHUB                              │   │
│  │  • Skill publishing (semver, SKILL.md required)           │   │
│  │  • Pattern-based moderation flags                         │   │
│  │  • VirusTotal scanning (coming soon)                      │   │
│  │  • GitHub account age verification                        │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

2.2 Data Flows (資料流)

下表展示了資料如何在各個組件之間流動，以及我們採取的保護措施：

Flow	Source	Destination	Data	Protection
F1	Channel	Gateway	使用者訊息	TLS, AllowFrom
F2	Gateway	Agent	已路由的訊息	Session 隔離
F3	Agent	Tools	工具調用	策略強制執行
F4	Agent	External	web_fetch 請求	SSRF 阻斷
F5	ClawHub	Agent	Skill 程式碼	審核與掃描
F6	Agent	Channel	回應內容	輸出過濾

疑難排解

如果你在設定過程中遇到問題，可以參考以下來自源文檔的常見狀況：

• 配對超時：請記得 Device Pairing 有 30 秒的寬限期 (grace period)，超過時間請重新發起請求。
• 工具執行失敗：檢查 Execution Sandbox 的設定。如果使用 Host 模式，請確認 exec-approvals 是否已正確配置。
• 無法存取外部連結：系統內建 SSRF 保護（包含 DNS pinning 與 IP 阻斷），請確認你嘗試存取的網址是否被安全策略攔截。
• Skill 無法發佈：ClawHub 要求必須包含 SKILL.md 並符合 semver 版本規範，同時會檢查你的 GitHub 帳號建立時間。

如果你還有其他疑問，可以直接詢問我們的 AI Setup Assistant。

下一步

• 了解如何配置 Gateway 驗證機制
• 深入研究 Execution Sandbox 設定
• 學習如何將你的 Skill 發佈到 ClawHub
• 查看 Session 隔離策略細節

當你興沖沖地寫好一個 AI agent，接上 WhatsApp 或 Telegram 準備大展身手時，心裡總有個疙瘩：萬一有人惡搞你的機器人怎麼辦？或者更糟，有人透過它下指令刪掉你的數據？

這種擔憂不是多餘的。把 AI 暴露在公網上，就像是給了全世界一個可以對話的終端機。為了讓你睡個好覺，我們根據 ATLAS (Adversarial Threat Landscape for Artificial-Intelligence Systems) 框架，幫 OpenClaw 做了一次全面的「體檢」。這篇文章會告訴你潛在的攻擊者會怎麼玩弄你的系統，而你又該如何見招拆招。

需要準備的東西

在開始防禦之前，請確保你了解 OpenClaw 的這些核心組件：

• Gateway: 暴露在外的 API 進入點
• Channel Integrations: 像是 WhatsApp 或 Telegram 的通訊管道
• Credentials: 存放在 ~/.openclaw/credentials/ 的敏感資料
• Tools: 像是 web_fetch 或 exec 等具備執行能力的工具

Quick Start: 5 分鐘強化你的 Agent

如果你沒時間看完長篇大論，請至少先做這兩件事來應對最關鍵的風險：

1. 開啟 Docker Sandbox: 在設定中將執行環境預設為 Docker，避免攻擊者直接控制你的主機系統。
2. 縮短 Pairing Code 時效: 將配對碼的 30 秒寬限期縮短，減少被攔截的機會。

---

威脅分析詳解：ATLAS 戰術視角

我們將攻擊行為拆解為幾個階段，幫你理解攻擊者是如何一步步深入你的系統。

1. 偵察階段 (Reconnaissance)

攻擊者會先試探你的 Agent 是否存在，以及它是如何運作的。

• T-RECON-001: Agent Endpoint Discovery

  • ATLAS ID: AML.T0006 (Active Scanning)
  • 手法: 掃描 OpenClaw Gateway 終端、使用 Shodan 查詢或 DNS 列舉。
  • 影響: Gateway 與暴露的 API。
  • 建議: 使用 Tailscale 認證選項，並預設綁定到 loopback 地址。

• T-RECON-002: Channel Integration Probing

  • ATLAS ID: AML.T0006 (Active Scanning)
  • 手法: 透過發送測試訊息並觀察回應模式，判斷該帳號是否由 AI 管理。
  • 建議: 考慮將回應時間隨機化，讓它看起來更像真人。

2. 初始存取 (Initial Access)

一旦發現目標，攻擊者會嘗試取得存取權限。

• T-ACCESS-001: Pairing Code Interception

  • 手法: 在 30 秒的寬限期內，透過側錄或社交工程攔截配對碼。
  • 建議: 縮短寬限期，並增加確認步驟。

• T-ACCESS-002: AllowFrom Spoofing

  • 手法: 偽造發送者身分（如偽造電話號碼或用戶名）。
  • 建議: 針對不同 Channel 實施加密驗證。

• T-ACCESS-003: Token Theft

  • 風險: 高。目前的 Token 以明文存放在 ~/.openclaw/credentials/。
  • 建議: 實施靜態加密 (Encryption at rest) 並定期更換 Token。

3. 執行階段 (Execution)

這是最危險的階段，攻擊者會嘗試讓 Agent 執行惡意指令。

• T-EXEC-001: Direct Prompt Injection

  • 風險: 極高。攻擊者直接在訊息中夾帶指令來操控 LLM。
  • 建議: 實施多層防禦，對敏感操作必須要求人工確認。

• T-EXEC-002: Indirect Prompt Injection

  • 手法: 在網頁或 Email 中埋入指令，當 Agent 使用 web_fetch 讀取時被觸發。
  • 建議: 進行內容清洗 (Sanitization)，並將執行環境隔離。

• T-EXEC-004: Exec Approval Bypass

  • 手法: 透過混淆指令或路徑操作，繞過 exec-approvals.ts 的白名單。
  • 建議: 實施指令標準化 (Normalization) 並擴大黑名單。

4. 持續滲透 (Persistence)

攻擊者想辦法在你的系統裡留下來。

• T-PERSIST-001: Malicious Skill Installation

  • 手法: 在 ClawHub 發佈帶有隱藏惡意代碼的 Skill。
  • 建議: 整合 VirusTotal 掃描，並實施 Skill 沙盒機制。

• T-PERSIST-002: Skill Update Poisoning

  • 手法: 攻破熱門 Skill 的帳號並推送惡意更新。
  • 建議: 實施更新簽名與版本鎖定 (Version pinning)。

5. 規避防禦與數據外洩

• T-EVADE-001: Moderation Pattern Bypass: 利用 Unicode 或編碼技巧繞過 FLAG_RULES 正則表達式檢測。
• T-EXFIL-001: Data Theft via web_fetch: 誘導 Agent 將敏感數據發送到攻擊者的伺服器。建議對 URL 實施白名單管理。

---

疑難排解

如果你發現 Agent 反應異常，請參考以下常見問題：

Q: 為什麼我的 Agent 突然開始回覆奇怪的指令？

• 原因: 可能遭受了 Direct Prompt Injection。
• 解決方案: 檢查對話紀錄，並確保對敏感工具（如 exec）開啟了 ask 模式。

Q: 發現 ~/.openclaw/credentials/ 被讀取怎麼辦？

• 原因: 可能是惡意 Skill 越權存取。
• 解決方案: 立即更換所有 API Token，並檢查最近安裝的 Skill 來源。

Q: 收到大量的垃圾訊息導致 API 額度噴光？

• 原因: 遭受了 Resource Exhaustion (DoS) 攻擊。
• 建議: 目前 OpenClaw 尚未內建速率限制，建議在 Gateway 前層加上 Rate Limiting。

---

如果你對安全設定還有疑問，或者想針對你的部署環境進行更深入的排查，歡迎找我們的 AI Setup Assistant 聊聊。

下一步

• 如何設定安全沙盒 (Sandbox)
• 管理你的 API Tokens
• ClawHub Skill 審核機制

你寫好程式碼、準備整合新的功能，卻在按下部署前猶豫了：這個第三方插件真的安全嗎？在開發 AI 應用的過程中，供應鏈攻擊是每個開發者最深層的恐懼，一個惡意的 Skill 就能讓你的敏感資料付諸流水。

我們來聊聊 ClawHub 是如何拆解這些風險，以及我們目前用了哪些手段來保護你的開發環境。

需要準備的東西

在深入分析之前，請確保你了解以下基礎配置（這些是目前系統檢查的核心）：

• GitHub 帳號：系統會驗證帳號建立時間。
• SKILL.md：每個 Skill 必須包含的說明文件。
• moderation.ts：存放目前過濾規則的設定檔。
• 資料庫表結構：包含 skillReports 與 auditLogs 用於後續追蹤。

Quick Start: 5 分鐘了解防禦機制

ClawHub 目前實作了幾層基礎防護，你可以快速檢查你的 Skill 是否符合以下安全控制：

1. 帳號與檔案驗證：透過 requireGitHubAccountAge() 提高攻擊者建立新帳號的成本，並使用 sanitizePath() 防止路徑遍歷攻擊。
2. 檔案類型與大小限制：僅允許文字檔案（isTextFile()），且整個 bundle 的大小上限為 50MB，防止資源耗盡。
3. 自動化規則過濾：系統會掃描 moderation.ts 中的 FLAG_RULES。
4. 狀態標記：透過 moderationStatus 欄位進行人工審核，並使用標籤系統（如 official, deprecated）區分信任等級。

目前 moderation.ts 中的過濾模式如下：

// 已知的惡意識別碼
/(keepcold131\/ClawdAuthenticatorTool|ClawdAuthenticatorTool)/i

// 可疑關鍵字
/(malware|stealer|phish|phishing|keylogger)/i
/(api[-_ ]?key|token|password|private key|secret)/i
/(wallet|seed phrase|mnemonic|crypto)/i
/(discord\.gg|webhook|hooks\.slack)/i
/(curl[^\n]+\|\s*(sh|bash))/i
/(bit\.ly|tinyurl\.com|t\.co|goo\.gl|is\.gd)/i

風險矩陣與攻擊鏈

我們針對潛在威脅進行了評級，這能幫你決定哪些問題需要最先處理。

可能性與影響力分析

Threat ID	可能性	影響	風險等級	優先級
T-EXEC-001	High	Critical	Critical	P0
T-PERSIST-001	High	Critical	Critical	P0
T-EXFIL-003	Medium	Critical	Critical	P0
T-IMPACT-001	Medium	Critical	High	P1
T-EXEC-002	High	High	High	P1
T-EXEC-004	Medium	High	High	P1

關鍵攻擊鏈範例

了解攻擊者如何串聯漏洞非常重要：

• Skill 數據竊取鏈：發布惡意 Skill (T-PERSIST-001) → 規避審核 (T-EVADE-001) → 收集憑證 (T-EXFIL-003)。
• 從 Prompt 注入到 RCE：注入惡意指令 (T-EXEC-001) → 繞過執行確認 (T-EXEC-004) → 執行系統指令 (T-IMPACT-001)。
• 外部內容間接注入：污染 URL 內容 (T-EXEC-002) → Agent 抓取並執行指令 → 資料外傳。

改善建議

根據目前的風險評估，我們建議按照以下優先順序強化系統：

立即執行 (P0)

• 完成 VirusTotal 整合，引入 Code Insight 行為分析。
• 實作 Skill 沙盒機制 (sandboxing)。
• 針對敏感操作增加輸出驗證。

短期目標 (P1)

• 實作 Rate Limiting 頻率限制。
• 增加儲存時的 Token 加密。
• 優化執行確認 (exec approval) 的 UX 與驗證邏輯。
• 為 web_fetch 實作 URL 允許清單。

中長期規劃 (P2)

• 在可能的情況下增加加密通道驗證。
• 實作配置完整性驗證。

疑難排解

在使用或開發過程中，你可能會遇到以下限制：

• 正則表達式失效：目前的過濾規則僅檢查 slug、displayName、summary 等元數據，簡單的混淆代碼就能繞過。
• 缺乏行為分析：系統目前不會分析 Skill 的實際程式碼內容，無法偵測執行時的惡意行為。
• 社群檢舉機制不全：雖然 skillReports 資料表已存在，但前端功能尚未完全對接。
• 審核延遲：手動審核 moderationStatus 可能會導致 Skill 上架速度變慢。

想要針對你的特定環境進行安全掃描嗎？快找 AI Setup Assistant 幫你檢查。

下一步

• Skill 安全開發最佳實踐
• 配置 VirusTotal API 進行自動掃描

開發 AI 應用時，最讓人頭痛的往往不是寫程式碼，而是如何確保系統安全。你可能整晚都在擔心 Prompt Injection 或是 SSRF 漏洞會不會毀掉你的專案。

為了讓你睡個好覺，我們整理了這份附錄。它能幫你快速對齊業界的安全標準，並直接定位到程式碼中最核心的安全邏輯。

需要準備的東西

• OpenClaw 專案原始碼存取權限
• 對 TypeScript 與基本網路安全概念的理解

快速開始

1. 對齊安全威脅：參考 ATLAS 映射表，將你的威脅模型與業界標準對接。
2. 檢查核心檔案：直接進入 src/infra 和 src/gateway 等目錄，審查關鍵的安全邏輯。
3. 理解術語：快速瀏覽術語表，確保你對 Gateway 和 MCP 的理解與官方一致。
4. 回報問題：如果你發現任何安全漏洞，請直接發送郵件至 security@openclaw.ai。

ATLAS 技術映射

ATLAS 是 MITRE 針對 AI 系統制定的威脅矩陣。我們將 OpenClaw 的威脅（OpenClaw Threats）與 ATLAS 技術進行了映射，方便你進行合規性檢查：

ATLAS ID	Technique Name	OpenClaw Threats
AML.T0006	Active Scanning	T-RECON-001, T-RECON-002
AML.T0009	Collection	T-EXFIL-001, T-EXFIL-002, T-EXFIL-003
AML.T0010.001	Supply Chain: AI Software	T-PERSIST-001, T-PERSIST-002
AML.T0010.002	Supply Chain: Data	T-PERSIST-003
AML.T0031	Erode AI Model Integrity	T-IMPACT-001, T-IMPACT-002, T-IMPACT-003
AML.T0040	AI Model Inference API Access	T-ACCESS-001, T-ACCESS-002, T-ACCESS-003, T-DISC-001, T-DISC-002
AML.T0043	Craft Adversarial Data	T-EXEC-004, T-EVADE-001, T-EVADE-002
AML.T0051.000	LLM Prompt Injection: Direct	T-EXEC-001, T-EXEC-003
AML.T0051.001	LLM Prompt Injection: Indirect	T-EXEC-002

關鍵安全檔案

如果你正在進行安全審計或代碼審查，以下檔案路徑定義了 OpenClaw 的防禦邊界：

Path	Purpose	Risk Level
src/infra/exec-approvals.ts	Command approval logic	Critical
src/gateway/auth.ts	Gateway authentication	Critical
src/web/inbound/access-control.ts	Channel access control	Critical
src/infra/net/ssrf.ts	SSRF protection	Critical
src/security/external-content.ts	Prompt injection mitigation	Critical
src/agents/sandbox/tool-policy.ts	Tool policy enforcement	Critical
convex/lib/moderation.ts	ClawHub moderation	High
convex/lib/skillPublish.ts	Skill publishing flow	High
src/routing/resolve-route.ts	Session isolation	Medium

術語表

確保我們在討論同一個東西：

Term	Definition
ATLAS	MITRE’s Adversarial Threat Landscape for AI Systems
ClawHub	OpenClaw’s skill marketplace
Gateway	OpenClaw’s message routing and authentication layer
MCP	Model Context Protocol - tool provider interface
Prompt Injection	Attack where malicious instructions are embedded in input
Skill	Downloadable extension for OpenClaw agents
SSRF	Server-Side Request Forgery

疑難排解

• 發現安全漏洞？ 請勿在 GitHub Issue 公開回報。為了保護所有使用者，請私下發送郵件至 security@openclaw.ai，我們會優先處理。

• 威脅模型更新 這份威脅模型是一個持續更新的活文件。如果你發現映射關係有誤，歡迎提交 PR。

想要自動化部署或有其他疑問？試試我們的 AI Setup Assistant。

下一步

• 查看完整威脅模型
• 了解 Skill 開發規範
• Gateway 配置指南
• 加入安全討論社群