OpenClaw 生態系教學手冊

  • 手冊版本: 4.0.0(2026-11-08)
  • 基準版本: OpenClaw 2026.11.1(npm latest,build 4ffdd20,2026-11-05)/2026.9.36(npm extended-stable,LTS 九月線)/2026.11.5-beta.1(npm beta)
  • 最後更新: 2026 年 11 月 8 日
  • 適用對象: 企業開發團隊、DevOps 工程師、AI 架構師、資安與稽核人員
  • 授權: MIT License(治理單位:非營利的 OpenClaw Foundation)
  • 官方資源: openclaw.ai · docs.openclaw.ai · GitHub · ClawHub · Discord · Trust · DeepWiki
  • 驗證方式: 本手冊所有 openclaw.json 範例皆以 2026.11.1 的 openclaw config validate --json 實測通過;所有 CLI 範例皆比對 2026.11.1 的 630 個指令路徑;Java 範例以 Maven 實際編譯與測試;TypeScript 範例以 tsc --strict 型別檢查。詳見附錄 F。

文件總覽

本手冊是 OpenClaw 生態系的企業級教學指引,涵蓋核心概念、系統架構、安裝部署、開發實戰、企業治理、維運監控、升級策略、DevOps、資安設計、實戰案例、多人協作與分散式執行等十二大主題,並附導入檢查清單、疑難排解、名詞解釋、參考資源、升級遷移指南與驗證紀錄。內容依據 OpenClaw 官方文件(v2026.11.1 的 docs/ 原始檔)、GitHub Release Notes 與 CHANGELOG、Security Advisories 重新消化整理,以繁體中文撰寫;整合範例以 Java 21/Spring Boot 4 為主,Plugin SDK 與 Gateway Protocol 等官方以 TypeScript 定義契約之處則以 TypeScript 示範。

本手冊的寫作原則:讓你能審查 AI 的產出

AI 協助撰寫 OpenClaw 組態、技能與整合程式時,最常見的錯誤是看起來合理、實際不存在的設定鍵、指令與 API。本手冊 v4.0.0 改版時,以 2026.11.1 實測發現舊版內容中 31 個 JSON5 組態區塊有 29 個無法通過驗證、51 處 CLI 用法不存在或旗標錯誤(詳見附錄 F)。因此全書遵循三條規則:

  1. 每條指引都附可執行的範例,並標明驗證方式(指令、預期輸出)。
  2. 常見錯誤以 ❌ 標示,讓讀者能辨認 AI 的典型杜撰。
  3. 每章結尾附「本章審查與驗證清單」,可直接用於審查 AI 產出的組態、技能與程式。
你要審查的東西最可靠的驗證方式
openclaw.json 組態openclaw config validate --json(看 valid 與 warnings)
CLI 指令openclaw <指令> --help;本手冊附錄 F 的 check_cli.py
技能(SKILL.md)openclaw skills check、openclaw skills info <name>
插件/工具npm run plugin:validate、openclaw plugins inspect <id> --json
整合程式契約測試(mock)+ 對真實 Gateway 的冒煙測試(4.2、8.3)

定位提醒:OpenClaw 的原始定位是「single-operator 個人 AI 助理閘道」——由一位操作者擁有並信任的自架系統。自 v2026.8.1(OpenClaw 2.0) 起加入多使用者 Gateway、對話分享角色與 Teams 協作,v2026.9.x 起再加入共用 Gateway 的個人技能庫與 Team Server 部署模式,定位延伸為「單一信任域內的多人協作」。

但官方明確聲明:這些協作控制項不是租戶隔離,也不是安全邊界。它們限制的是「同一套受信任的 OpenClaw 安裝內部」的協作行為,而非在互不信任的租戶之間建立隔離。本手冊討論的「企業導入」,是把 OpenClaw 作為自架基礎設施元件、搭配企業自身的治理與維運框架落地,而不是官方內建的多租戶 SaaS。第十一章會完整展開。

專案沿革:2025 年 11 月以 Warelay 之名首次發布,歷經 CLAWDIS(2025-12-03)→ Clawdbot(2026-01-02)→ Moltbot(2026-01-27)→ OpenClaw(2026-01-30)。創辦人 Peter Steinberger 於 2026-02-14 宣布加入 OpenAI,同日成立非營利的 OpenClaw Foundation 接手治理;專案採 MIT 授權。版本號採日期格式 vYYYY.M.D;GitHub 星數 394,161、Fork 82,830(2026-11-08 查證)。

2.0 之後的演進(v2026.8.2 → v2026.11.1):約 40 個版本,主軸是可恢復(更新預演與自動回滾、重啟後恢復回覆、異地備份與持續複寫)、可協作(個人技能庫、Team Server、唯讀分享)、可分散(Cloud Sessions 在本機與雲端間移動)。另有數項破壞性變更:Node 22/25 不再支援(9.3)、Tasks/TaskFlow 移除(9.7)、macOS/iOS/Safari 需 26.2(10.10)。詳見 1.12 與附錄 E.5。

時程性提醒(2.0 公告的三個期限皆已過):

期限事項狀態(2026-11-08)
2026-09-01Plugin SDK 舊版 subpath 匯入關閉已過;10.1 起第三方插件須移除已退休的相容層
2026-09-18含退休設定鍵者執行 openclaw doctor --fix已過;舊組態升級時仍可由 Doctor 遷移
2026-10-12beta.5 session-store bridge 相容層失效已過
持續2026 年 6 月以前的安裝必須先升級到 2026.9.5見附錄 E.5

目錄


第一章:OpenClaw 核心概念

1.1 什麼是 OpenClaw

OpenClaw(歷經 Warelay / CLAWDIS / Clawdbot / Moltbot 等更名階段)是一個開源的個人 AI 助理框架,最初由奧地利工程師 Peter Steinberger 建立,採用 MIT 授權發布,目前由非營利的 OpenClaw Foundation 接手治理。OpenClaw 的核心定位是作為一個 single-operator AI Gateway——由單一操作者(Operator)擁有並信任、可完全自架的中繼平台,連接多種即時通訊頻道與大型語言模型(LLM),讓使用者能夠透過日常使用的通訊軟體(如 WhatsApp、Telegram、Slack、Discord 等)與 AI Agent 進行互動,同時將資料與帳號憑證留在自己掌控的基礎設施上。

名稱沿革

專案名稱在短短數月內歷經多次更迭,反映其早期爆發式的成長速度:

名稱生效日期備註
Warelay2025-11-24首次公開發布時的名稱
CLAWDIS2025-12-03第一次更名
Clawdbot2026-01-02第二次更名
Moltbot2026-01-27因 Anthropic 對「Clawd/Claude」相似性提出商標異議而改名
OpenClaw2026-01-30現行名稱,作者表示「Moltbot 唸起來不夠順口」

2026 年 2 月 14 日,Steinberger 宣布加入 OpenAI,同日成立非營利的 OpenClaw Foundation 作為專案的長期治理主體,確保專案不因創辦人職涯異動而中斷。專案原始碼與授權條款(MIT)維持不變,開發節奏由社群與基金會共同維運。

核心特色

特色描述
多頻道整合支援 30+ 通訊頻道(含插件頻道),一個 Gateway 統一管理所有連線
開源透明MIT 授權,完整原始碼公開於 GitHub,社群超過 2,513 位貢獻者
技能擴展透過 Skills 系統擴展 Agent 能力,ClawHub 市集提供社群技能
模型無關支援多種 LLM 提供者(OpenAI、Anthropic、Google、Ollama 等),內建模型失效轉移機制
自架部署可完全部署在自有基礎設施上,資料不經第三方
企業就緒支援 Docker 容器化、健康檢查、OpenTelemetry 可觀測性
語音互動Voice Wake 喚醒詞 + Talk Mode 連續語音對話(macOS/iOS/Android)
視覺工作區Live Canvas + A2UI Agent 驅動的互動式視覺工作空間
Control UI內建瀏覽器儀表板,提供聊天、組態、Session 與節點管理
技能安全與 VirusTotal 合作,提供 ClawHub 技能安全掃描機制
一鍵安裝支援跨平台一鍵安裝腳本(macOS/Linux/Windows),零門檻上手

吉祥物 🦞

OpenClaw 的吉祥物是 Molty——一隻太空龍蝦(Space Lobster)。這個有趣的吉祥物來源於龍蝦能夠不斷「蛻殼」(molting)成長的生物特性,象徵 OpenClaw 持續進化與成長的理念。

專案規模

截至 2026 年 8 月中:

  • GitHub Stars: 386,000+
  • Forks: 81,200+
  • 主要語言: TypeScript (~89.8%)、Swift (~5.0%,官方 iOS/macOS App)、Kotlin (~1.9%,官方 Android App)、JavaScript (~1.7%)、Shell (~0.6%)、CSS (~0.4%),另含少量 Python/Rust/Go 工具鏈程式碼
  • 單一版本週期貢獻規模: 以 v2026.7.1 為例,單一版本即彙整 532 位貢獻者、3,063 筆貢獻、2,018 個公開 PR,反映社群活躍度
  • 最新穩定版本: 2026.7.1-2(2026 年 8 月 4 日發布)
  • Extended-Stable 維護線: 2026.6.34(2026 年 8 月 8 日發布,僅安全性與穩定性修補,不含新功能)
  • 最新 Beta 版本: 2026.8.1-beta.2(2026 年 8 月 15 日發布)
  • 總發布版本數: 230+ 個版本(含 stable / beta / extended-stable)
  • 治理單位: OpenClaw Foundation(非營利基金會,2026 年 2 月成立)
  • 贊助商: OpenAI、GitHub、NVIDIA、Vercel、Blacksmith、Convex 等

版本線說明:OpenClaw 同時維護三條版本線——Beta(每週多次發布,含最新功能與實驗性變更)、Stable(如 2026.7.1,經過 Beta 週期驗證後的正式功能版)、Extended-Stable(如 2026.6.34,僅回補安全與穩定性修補,適合對變更敏感的正式環境採用)。企業導入建議優先評估 Extended-Stable 或已穩定運行數週的 Stable 版本,詳見第七章升級策略。

1.2 核心理念與設計哲學

OpenClaw 的設計哲學圍繞著以下核心理念:

1.2.1 個人助理優先(Personal Assistant First)

OpenClaw 採用「個人助理信任模型」,這與傳統的多租戶 SaaS 平台截然不同。每個 OpenClaw 實體由一位**操作者(Operator)**擁有並管理,Agent 的所有行為都在操作者的信任邊界內執行。

┌─────────────────────────────────────────────┐
│              信任邊界 (Trust Boundary)        │
│                                             │
│  ┌──────────┐    ┌──────────┐              │
│  │ Operator │───→│ Gateway  │              │
│  │ (擁有者)  │    │ (閘道器)  │              │
│  └──────────┘    └────┬─────┘              │
│                       │                     │
│              ┌────────┼────────┐            │
│              ↓        ↓        ↓            │
│         ┌────────┐┌────────┐┌────────┐     │
│         │ Agent 1││ Agent 2││ Agent 3│     │
│         └────────┘└────────┘└────────┘     │
│                                             │
└─────────────────────────────────────────────┘

1.2.2 頻道無關(Channel Agnostic)

OpenClaw 將「在哪裡對話」與「如何回應」完全解耦。無論訊息來自 WhatsApp、Slack 還是 Telegram,Agent 的行為邏輯保持一致。這種設計使企業可以:

  • 統一管理: 一個 Agent 定義,多個頻道部署
  • 漸進遷移: 新增頻道不需修改 Agent 邏輯
  • 一致體驗: 使用者在不同平台獲得相同品質的服務

1.2.3 技能驅動(Skill-Driven)

OpenClaw 的 Agent 能力由「技能(Skills)」定義。每個技能是一個獨立的模組,包含:

  • SKILL.md: 技能的 Prompt 定義與行為規範
  • 工具函式: 技能可使用的工具集
  • 存取規則: 哪些使用者或頻道可以觸發此技能

1.2.4 可組合架構(Composable Architecture)

graph LR
    A[使用者] --> B[通訊頻道]
    B --> C[Gateway]
    C --> D[Agent Runtime]
    D --> E[Skills]
    D --> F[Tools]
    D --> G[LLM Provider]
    E --> H[ClawHub]
    F --> I[Browser/Canvas/Cron]
    C --> J[Control UI]
    C --> K[Voice Wake / Talk]
    C --> L[Companion Apps]

OpenClaw 的架構高度可組合,每一層都可以獨立擴展或替換:

  1. 頻道層: 新增通訊頻道不影響 Agent 邏輯
  2. 閘道層: Gateway 負責連線管理與訊息路由
  3. 執行層: Agent Runtime 獨立處理業務邏輯
  4. 能力層: Skills 和 Tools 可按需啟用

1.3 Gateway 架構總覽

Gateway 是 OpenClaw 的核心守護行程(Daemon),負責管理所有外部連線與內部元件的協調。

架構圖

graph TB
    subgraph "OpenClaw Gateway (Port 18789)"
        WS[WebSocket 控制平面]
        Router[訊息路由器]
        ChannelMgr[頻道管理器]
        AgentMgr[Agent 管理器]
        ConfigMgr[組態管理器]
        HealthCheck[健康檢查]
        ControlUI[Control UI / WebChat]
        CronMgr[Cron / Webhook 管理器]
    end
    
    subgraph "外部頻道"
        WA[WhatsApp<br>Baileys]
        TG[Telegram<br>grammY]
        SL[Slack<br>Bolt]
        DC[Discord<br>discord.js]
        MS[MS Teams]
        SG[Signal<br>signal-cli]
        BB[BlueBubbles<br>iMessage]
        IRC[IRC]
        MTX[Matrix]
        MORE[22+ 其他頻道...]
    end
    
    subgraph "Agent Runtime (Pi)"
        Agent1[Agent 1]
        Agent2[Agent 2]
        Agent3[Agent 3]
    end
    
    subgraph "Companion Apps / Nodes"
        MAC[macOS Menu Bar]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    WA & TG & SL & DC & MS & SG & BB & IRC & MTX & MORE --> ChannelMgr
    ChannelMgr --> Router
    Router --> AgentMgr
    AgentMgr --> Agent1 & Agent2 & Agent3
    ConfigMgr --> WS
    HealthCheck --> WS
    ControlUI --> WS
    CronMgr --> Router
    MAC & IOS & AND -->|WebSocket| WS

關鍵特性

元件功能說明
WebSocket 控制平面即時通訊預設監聽 port 18789,提供雙向即時通訊
訊息路由器訊息分派根據頻道、使用者、訊息內容將訊息路由到對應的 Agent
頻道管理器連線管理管理所有外部頻道連線的生命週期
Agent 管理器Agent 排程管理 Agent 的啟動、停止、重啟,支援多 Agent 路由
組態管理器動態組態支援 Hot Reload,不重啟即可更新設定
健康檢查監控端點提供 /healthz、/readyz 端點供維運監控
Control UI網頁儀表板內建瀏覽器管理介面,提供聊天、組態、Session 與節點管理
Cron / Webhook自動化排程內建排程任務與外部事件觸發機制,支援 Gmail Pub/Sub

Gateway 啟動流程

sequenceDiagram
    participant CLI as openclaw CLI
    participant GW as Gateway Daemon
    participant CM as Config Manager
    participant CH as Channel Manager
    participant AM as Agent Manager

    CLI->>GW: openclaw start
    GW->>CM: 載入 openclaw.json
    CM->>CM: JSON5 解析 + 嚴格驗證
    CM-->>GW: 組態就緒
    GW->>CH: 初始化頻道連線
    CH->>CH: 連接 WhatsApp/Telegram/...
    CH-->>GW: 頻道就緒
    GW->>AM: 啟動 Agent Runtime
    AM->>AM: 載入 Skills + Tools
    AM-->>GW: Agent 就緒
    GW->>GW: 開啟 WebSocket (port 18789)
    GW-->>CLI: Gateway 啟動完成 ✓

1.4 Pi Agent 執行環境

OpenClaw 的 Agent Runtime 稱為 Pi(衍生自 pi-mono 專案),是實際處理使用者訊息並產生回應的執行環境。

核心概念

概念說明
WorkspaceAgent 的工作目錄,包含 Skills、組態、資源檔案
Bootstrap FilesAgent 啟動時載入的初始化檔案
SkillsAgent 的能力模組,定義行為與工具
Sessions對話會話管理,維護上下文與狀態
Model References模型參考設定,指定使用的 LLM

Agent 生命週期

stateDiagram-v2
    [*] --> Initializing: Gateway 啟動 Agent
    Initializing --> Loading: 載入 Bootstrap Files
    Loading --> SkillResolution: 解析 Skills
    SkillResolution --> Ready: Skills 載入完成
    Ready --> Processing: 收到使用者訊息
    Processing --> Responding: LLM 產生回應
    Responding --> Ready: 回應完成
    Ready --> Reloading: 組態變更 (Hot Reload)
    Reloading --> Ready: 重新載入完成
    Ready --> [*]: Gateway 關閉

Workspace 目錄結構

Agent 的 Workspace 是一個標準目錄結構:

~/.openclaw/
├── openclaw.json          # 主組態檔(JSON5 格式)
├── workspace/              # Agent 工作區根目錄
│   ├── AGENTS.md          # Agent 身份與行為定義
│   ├── SOUL.md            # Agent 個性與核心價值
│   ├── TOOLS.md           # 工具使用指引
│   └── skills/            # 工作區技能目錄
│       └── my-skill/
│           ├── SKILL.md   # 技能定義
│           └── tools/     # 技能工具
├── skills/                 # 管理級技能目錄
│   └── another-skill/
├── credentials/            # 頻道認證資料(如 WhatsApp 登入)
├── logs/                   # JSONL 日誌輸出
│   └── openclaw.jsonl
└── data/                   # Agent 資料存儲

Bootstrap Files: Agent 啟動時會注入 AGENTS.md、SOUL.md、TOOLS.md 等 Prompt 檔案,這些檔案定義了 Agent 的身份、個性與工具使用規範。可透過 reference/templates 查看預設範本。

Agent 的訊息處理流程

  1. 接收: Gateway 將使用者訊息傳遞給 Agent
  2. 路由: Agent 根據訊息內容與上下文判斷使用哪個 Skill
  3. 增強: Skill 將相關工具與 Prompt 注入到請求中
  4. 推論: 將增強後的請求送到 LLM 進行推論
  5. 後處理: 處理 LLM 回應,執行工具呼叫
  6. 回應: 將最終回應送回使用者

1.5 Skills 技能系統

Skills(技能)是 OpenClaw 最核心的擴展機制:一個技能就是一個資料夾,裡面放一份 SKILL.md(給模型看的操作說明)以及選用的腳本、參考資料與素材。技能不會自動帶來新權限——它只是「教 Agent 如何使用既有工具」的說明書。這一點是審查 AI 產出技能時最重要的心智模型:技能能做什麼,取決於 Agent 被允許使用哪些工具,而不是 SKILL.md 寫了什麼。

技能定義:SKILL.md

OpenClaw 遵循 AgentSkills 規範。frontmatter 只有 name 與 description 是必填;其餘為選填鍵,最常用的是 metadata.openclaw(載入閘門與環境需求):

---
name: weather-reporter
description: 查詢指定城市的即時天氣與三日預報,並以繁體中文摘要回覆
metadata:
  openclaw:
    requires:
      bins: ["curl"]
      env: ["WEATHER_API_KEY"]
    primaryEnv: WEATHER_API_KEY
---

# Weather Reporter

當使用者詢問天氣時:

1. 若地點不明確,先反問城市名稱,不要猜測。
2. 以 `exec` 工具執行 `curl -s "https://api.example-weather.com/v1/now?city=<城市>"`
   (API Key 由環境變數 `WEATHER_API_KEY` 注入,**不要**把金鑰寫進回覆或指令列)。
3. 回覆格式:溫度、體感、濕度、風速各一行;有警特報時放在第一行並加 ⚠️。
frontmatter 鍵必填用途
name✅技能識別名稱(同名時依載入優先序取勝者)
description✅模型決定是否選用此技能的主要依據,應寫「何時用、做什麼」
metadata.openclaw.requires.bins / anyBins / env / config選填載入閘門:缺少必要執行檔、環境變數或組態時不載入
metadata.openclaw.os選填平台過濾,例如 ["darwin"]、["linux"]、["win32"]
user-invocable選填(預設 true)是否同時提供為使用者可呼叫的 slash command
disable-model-invocation選填(預設 false)true 時不放入模型的常規提示,只保留 slash command
command-dispatch: tool + command-tool選填slash command 直接派送到指定工具,不經過模型

❌ 常見 AI 產出錯誤:在 frontmatter 加入 triggers:、tools:、access.channels、access.users 之類的鍵。這些不是 OpenClaw 支援的欄位,會被忽略——結果是作者以為設了存取控制,實際上完全沒有。存取控制必須放在 openclaw.json 的 Agent allowlist 與工具政策(見下方與 5.2 節)。

技能載入優先序

同名技能出現在多個來源時,優先序高者勝出(v2026.11.1 官方定義):

優先序來源路徑可見範圍
1(最高)Workspace skills<workspace>/skills僅該 Agent
2Project agent skills<workspace>/.agents/skills僅該工作區的 Agent
3Personal agent skills~/.agents/skills(僅預設 state 目錄時)使用預設 state 的 Agent
4Managed / local skills<state-dir>/skills共用同一 state 的所有 Agent
5Workshop skills<state-dir>/agents/<agentId>/agent/workshop-skills僅該 Agent(自我學習產出,見 4.3)
6Bundled / Custodian skills隨安裝套件提供所有 Agent/僅 Custodian Agent
7(最低)Extra directories 與插件技能skills.load.extraDirs + plugin skills使用該組態的所有 Agent
graph LR
    WS["1 Workspace<br/>skills/"] --> PJ["2 Project<br/>.agents/skills"] --> PS["3 Personal<br/>~/.agents/skills"] --> MG["4 Managed<br/>state-dir/skills"] --> WK["5 Workshop"] --> BD["6 Bundled"] --> EX["7 extraDirs / Plugin"]

兩件事不要混淆:「位置」決定同名時誰勝出(precedence),「allowlist」決定哪個 Agent 看得到(visibility)。若設定 OPENCLAW_STATE_DIR 指向非預設位置,~/.agents/skills 這類家目錄層級的來源會被排除。

技能啟用、金鑰注入與 Agent Allowlist

技能的組態全部集中在 skills.*(載入、安裝、個別技能開關與金鑰)與 agents.*.skills(每個 Agent 可見的技能清單):

// openclaw.json(已以 openclaw 2026.11.1 `openclaw config validate --json` 驗證通過)
{
  skills: {
    load: { extraDirs: ["~/company-skills"], watch: true },
    install: { nodeManager: "npm", allowUploadedArchives: false },
    entries: {
      "weather-reporter": {
        enabled: true,
        // 以 SecretRef 參照環境變數,避免金鑰明文出現在組態檔
        apiKey: { source: "env", provider: "default", id: "WEATHER_API_KEY" },
      },
      "legacy-report": { enabled: false },
    },
  },
  agents: {
    ownership: "explicit", // 多 Agent roster 必填:明確宣告各 Agent 的擁有關係
    defaults: { skills: ["weather-reporter", "github"] }, // 所有 Agent 的共同基準
    entries: {
      assistant: {},                         // 省略 skills → 繼承 defaults
      finance: { skills: ["finance-report"] }, // 非空清單 = 最終集合,不與 defaults 合併
      kiosk: { skills: [] },                  // 空陣列 = 不暴露任何技能
    },
  },
}

Allowlist 規則(審查重點):

  1. 省略 agents.defaults.skills → 預設不限制。
  2. 省略 agents.entries.<id>.skills → 繼承 defaults。
  3. agents.entries.<id>.skills: [] → 該 Agent 看不到任何技能。
  4. 非空清單是「最終集合」,不會與 defaults 合併——這是最常見的誤解。
  5. Allowlist 不是 Shell 授權邊界:若 Agent 可使用 exec,仍需以沙箱、exec allowlist 與最小權限憑證另行限制(見第九章)。

技能設定的驗證方式

檢查項目指令/方法預期結果
組態鍵是否存在openclaw config validate --json"valid": true;若出現 Unrecognized keys 即為 AI 杜撰鍵
技能是否實際載入openclaw skills check列出勝出來源;缺少 requires.* 時顯示未通過的閘門
同名技能由誰勝出openclaw skills info <name>顯示實際來源路徑,應符合上表優先序
frontmatter 是否只用支援的鍵人工檢視 SKILL.md不含 triggers/tools/access 等非規範鍵
金鑰未寫死grep -rnE "api[_-]?key\s*[:=]\s*['\"]\w" skills/無輸出

1.6 Tools 工具系統

Tools(工具)是 Agent 與外部世界互動的介面,OpenClaw 內建多種工具類別:

內建工具分類

工具類別功能範例用途
Browser瀏覽器控制(CDP)網頁擷取、自動化操作、截圖、座標點擊
Canvas / A2UIAgent-to-UI 渲染產生互動式 UI 元件
Nodes裝置整合相機、螢幕、定位、通知
Cron排程 & Webhook定時任務、外部事件觸發、Gmail Pub/Sub
Sessions對話管理對話狀態、歷史記錄、跨 Agent 訊息傳遞
Discord / Slack頻道動作頻道專屬操作指令
Gateway閘道控制組態管理、健康檢查、節點管理
exec / process系統執行在主機上執行指令、管理程序
code_execution程式碼執行沙箱內安全執行程式碼
web_search / web_fetch網頁搜尋與擷取即時搜尋網頁、取得 URL 內容(v2026.6.9 新增 Codex Hosted Search 無需 API Key)
read / write / edit檔案操作讀寫檔案、編輯內容
apply_patch差異套用以 patch 格式批次修改檔案
image / image_generate圖片生成與編輯透過 Provider 生成或編輯圖片
music_generate音樂生成透過 Provider 生成音樂素材
video_generate影片生成URL 資產交付、參考音訊、自適應長寬比、多 Provider 支援
tts語音合成文字轉語音,支援多 Provider(Azure Speech、ElevenLabs 等)
Dreaming記憶 Wiki 管理ChatGPT 匯入消化、Wiki 頁面編譯、Memory Palace 日記
message訊息工具傳送格式化訊息至頻道
session_status狀態查詢查詢 Session 當前狀態、Token 用量
agents_listAgent 列表列出可用 Agent 及其中繼資料
subagents子 Agent 管理建立並管理子 Agent 工作流程

工具設定檔(Tool Profiles)

tools.profile 先決定一份基準 allowlist,再疊加 tools.allow/tools.alsoAllow/tools.deny。本機 onboarding 在沒有設定 profile 時會寫入 full;既有組態不會被自動遷移。

設定檔包含(v2026.11.1)適用情境
minimalsession_status、gateway(僅 update.run)高度受限的對外 Agent
codinggroup:fs、group:runtime、group:web、group:sessions、group:memory、cron、gateway(僅更新)、goal/progress/ask_user/skill_workshop/影像與媒體生成開發輔助 Agent
messaginggroup:messaging、sessions 與 conversations 系列、subagents、session_status、gateway(僅更新)、ask_user純通訊/客服 Agent
full不做核心過濾,並選入已啟用插件的選用工具個人助理、受信任操作者

⚠️ full 只代表「選入工具」,不等於「完全存取」。工具實際能做什麼仍受對話的 Execution permissions、owner 檢查、檔案系統、沙箱與 exec 政策約束。另外 tts 不屬於任何受限 profile,需要時請加入 tools.alsoAllow。

工具群組(Tool Groups)

群組包含工具
group:runtimeexec(bash 為別名)、process、code_execution
group:fsread、write、edit、apply_patch
group:sessionssessions*、conversations_*、subagents、session_status、suggest_task、dismiss_task
group:memorymemory_search、memory_get
group:webweb_search、x_search、web_fetch
group:uibrowser、screen、theme、dashboard、terminal、portal、canvas、show_widget
group:automationheartbeat_respond、automations(cron 別名)、gateway、plugins、openclaw
group:messagingmessage
group:nodesnodes、computer
group:agentsagents_list、goal 系列、progress_card、ask_user、skill_workshop
group:mediaview_image、image_generate、music_generate、video_generate、tts、pdf
group:openclaw上述所有內建工具,但不含 read/write/edit/apply_patch/exec/process/canvas
group:plugins已載入插件擁有的工具(含透過 bundle-mcp 暴露的 MCP 伺服器)

工具存取控制透過 tools.allow/tools.alsoAllow/tools.deny 管理,也可用 tools.byProvider 與 tools.toolsBySender 依 Provider 或發送者細分。群組 deny 會覆蓋個別工具的 allow——例如 deny group:media 會一併擋掉明確 allow 的 pdf。

// 客服 Agent:以 messaging 為基準,額外允許語音,禁止所有 runtime 與檔案寫入
{
  tools: {
    profile: "messaging",
    alsoAllow: ["tts"],
    deny: ["group:runtime", "write", "edit", "apply_patch"],
    fs: { workspaceOnly: true },
  },
}

Browser 工具

Browser 工具使用 Chrome DevTools Protocol (CDP) 提供完整的瀏覽器控制能力:

// 工具呼叫示意(由模型在對話中發出,非 openclaw.json 組態)
browser → navigate { url: "https://example.com/report" }
browser → snapshot  { }            // 取得可存取性樹,供下一步點擊定位
browser → click     { ref: "e12" }

操作者也可以從 CLI 直接驅動同一個受管瀏覽器,方便重現 Agent 的行為:

openclaw browser start --headless
openclaw browser navigate https://example.com/report
openclaw browser screenshot

功能包含:

  • 導航至指定 URL
  • 擷取頁面內容(文字/截圖)
  • 填寫表單
  • 點擊按鈕
  • 執行 JavaScript

Canvas / A2UI 工具

A2UI(Agent-to-UI)是 OpenClaw 獨特的工具,允許 Agent 產生互動式 UI 元件:

使用者: 建立一個投票
Agent: [使用 Canvas 工具產生互動式投票 UI]

Cron 與 Webhook 工具

Agent 透過 automations(舊名 cron)工具建立排程;操作者則使用同名 CLI。兩者寫入的是同一份 Automations 儲存,不是 openclaw.json 組態:

# 週一至週五 09:00(台北時間)產生日報並送到 Slack #team-reports
openclaw automations add --name daily-report --cron "0 9 * * 1-5" --tz Asia/Taipei \
  --message "彙整昨日工單與部署紀錄,產出日報" --channel slack --to "#team-reports"

openclaw automations list
openclaw automations runs <job-id>     # 檢視每次執行結果

外部事件則以 Webhook 觸發;Gmail Pub/Sub 有專用的 openclaw webhooks gmail setup。一般 HTTP Webhook 的設定方式見 4.7 節。

⚠️ v2026.9.7 起 Tasks 與 TaskFlow 已移除(含面板、指令與 API)。原本的工作請改用 subagent、ACP sessions、背景程序、Automations 歷史或 Lobster pipeline;TaskFlow Webhooks 沒有對等的 HTTP 替代方案。升級後須執行 openclaw doctor --fix。

Dreaming / Memory Wiki 工具

Dreaming 是 OpenClaw v2026.4 新增的記憶管理子系統,提供 Agent 長期知識彙整能力:

  • ChatGPT 匯入消化: 可匯入既有 ChatGPT 對話歷史,透過 Imported Insights 子頁籤瀏覽
  • Wiki 頁面編譯: 將多次對話中的知識自動編譯為結構化 Wiki 頁面
  • Memory Palace 日記: Memory Palace 子頁籤提供 Agent 自主整理的記憶日記
使用者: 匯入我的 ChatGPT 對話歷史
Agent: [使用 Dreaming 工具匯入並消化對話,產出 Imported Insights 和 Wiki 頁面]

video_generate 影片生成工具

v2026.4.11 新增的影片生成工具,支援多種 Provider 的影片生成能力:

  • URL 資產交付: 生成的影片以 URL 形式交付,避免大檔案佔用記憶體
  • 參考音訊輸入: 支援提供參考音訊素材
  • 自適應長寬比: adaptive 模式自動選擇最佳畫面比例
  • 多 Provider 支援: 支援 Google Veo、OpenAI Sora 等影片生成服務

1.7 Sessions 與對話管理

Sessions 是 OpenClaw 管理對話狀態的核心機制。

Session 生命週期

stateDiagram-v2
    [*] --> Created: 新對話開始
    Created --> Active: 第一則訊息
    Active --> Active: 持續對話
    Active --> Paused: 閒置超時
    Paused --> Active: 新訊息喚醒
    Active --> Archived: 明確結束
    Paused --> Archived: 長時間閒置
    Archived --> [*]: 清理

Session 資料結構

每個 Session 包含以下資訊:

欄位類型說明
idstringSession 唯一識別碼
channelIdstring來源頻道識別碼
userIdstring使用者識別碼
agentIdstring處理此 Session 的 Agent
messagesMessage[]對話訊息歷史
contextobject上下文資料(記憶)
metadataobject中繼資料
createdAttimestamp建立時間
updatedAttimestamp最後更新時間
statusenumCreated / Active / Paused / Archived

上下文管理策略

OpenClaw 提供多種上下文管理策略防止 Token 超出限制:

  1. 滑動視窗(Sliding Window): 保留最近 N 則訊息
  2. 摘要壓縮(Summary Compression): 將較舊的訊息摘要化
  3. 優先保留(Priority Retention): 標記重要訊息永久保留
  4. 混合策略(Hybrid): 結合以上策略

Session Tools(跨 Agent 通訊)

OpenClaw 提供 sessions_* 系列工具,允許 Agent 之間跨 Session 協作:

工具功能說明
sessions_list列出 Sessions探索目前活躍的 Sessions(Agent)及其中繼資料
sessions_history讀取歷史取得指定 Session 的對話記錄
sessions_send傳送訊息向另一個 Session 傳送訊息,支援可選的回覆式 ping-pong(REPLY_SKIP、ANNOUNCE_SKIP)
sessions_spawn建立 Session建立新的 Session 並指派 Agent

使用情境: 透過 Session Tools,你可以在不同聊天介面之間協調工作。例如,在 Slack 的 DevOps Agent 可以委託 Telegram 的報表 Agent 產生報告,然後將結果傳回。詳情參考 Session tools。

Cross-channel Session Identity(v2026.6.10 新增): 當使用者從一個頻道切換到另一個頻道時(例如從 WhatsApp 轉到 Telegram),Session 的 origin 會自動重置,確保身份識別正確且避免舊頻道殘留的上下文污染新頻道。

聊天指令(Chat Commands)

使用者可在 WhatsApp / Telegram / Slack / Google Chat / Microsoft Teams / WebChat 中使用以下指令控制 Agent(群組指令僅限擁有者):

指令功能備註
/status顯示簡要 Session 狀態包含模型、Token 用量、成本
/new 或 /reset重置 Session清除上下文,開始新對話
/compact壓縮 Session 上下文產生摘要以釋放 Token 空間
/think <level>設定推理深度off | minimal | low | medium | high | xhigh(GPT-5.2 + Codex 模型)
/verbose on|off切換詳細模式顯示更多 Agent 內部處理資訊
/usage off|tokens|full設定用量頁腳每次回應後顯示的用量資訊級別
/restart重啟 Gateway僅限擁有者,群組中使用
/activation mention|always群組激活模式設定群組中需 @mention 或始終回應
/trace on|off追蹤模式開啟/關閉工具呼叫與推論過程的詳細追蹤輸出
/elevated on|off提升權限存取切換當前 Session 的主機提升權限(需預先啟用與白名單)

1.8 多頻道支援(Channels)

OpenClaw 支援 40 種以上通訊頻道(含插件頻道),涵蓋消費端通訊軟體、企業協作平台、電信簡訊、去中心化協議與 Agent 間協定。以下為完整列表:

支援頻道一覽

頻道底層函式庫狀態備註
WhatsAppBaileys✅ 穩定透過 Web API 連接
TelegramgrammY✅ 穩定Bot API,v2026.6.8 新增 Rich HTML 渲染(表格/清單/blockquote)
SlackBolt✅ 穩定Slack App
Discorddiscord.js✅ 穩定Discord Bot
Google Chat官方 API✅ 穩定Google Workspace
Signalsignal-cli✅ 穩定端對端加密
BlueBubblesBlueBubbles API✅ 穩定建議的 iMessage 整合方式
iMessageimsg (legacy)✅ 穩定需要 macOS,舊版整合
IRC原生實作✅ 穩定任何 IRC 伺服器
Microsoft TeamsBot Framework✅ 穩定Microsoft 365,支援反應、委派 OAuth、聯合認證
Matrixmatrix-js-sdk✅ 穩定開源通訊協議
LINELINE SDK✅ 穩定LINE 官方帳號
Feishu飛書 SDK✅ 穩定字節跳動飛書,支援文件評論 Session、評論反應
Mattermost插件頻道✅ 穩定自架 Slack 替代方案(extension 套件)
Nextcloud Talk官方 API✅ 穩定Nextcloud 整合
Nostr原生實作✅ 穩定去中心化協議
Synology Chat官方 API✅ 穩定Synology NAS
Tlon官方 API🔄 測試Urbit 生態
Twitchtmi.js✅ 穩定直播聊天室
QQ Bot內建插件✅ 穩定群聊支援、串流回應、媒體上傳(v2026.5.4 新增)
Yuanbao騰訊元寶插件✅ 穩定騰訊官方提供,外部插件安裝(v2026.5.4 新增)
Voice CallPlivo/Twilio 插件✅ 穩定電話語音通話,支援 Realtime Voice Loop(v2026.4.24 新增)
Google Meet內建參與者插件✅ 穩定Chrome/Twilio Realtime、出席匯出、錄製檔案(v2026.4.24 新增)
Zalo官方 API✅ 穩定越南通訊軟體(官方帳號)
Zalo Personal官方 API✅ 穩定越南通訊軟體(個人帳號)
WeChat@tencent-weixin/openclaw-weixin✅ 穩定騰訊官方插件(iLink Bot API),v2.x 需 OpenClaw ≥2026.3.22
WebChat內建✅ 穩定Gateway 內建網頁聊天介面
macOS內建✅ 穩定macOS 選單列應用(Menu Bar App)
iOS內建✅ 穩定iOS Node(Canvas、Voice Wake、相機)
Android內建✅ 穩定Android Node(Chat、Voice、Canvas、裝置指令)
SMS / MMS / RCSTwilio✅ 穩定電信簡訊與 RCS,適合無網路應用情境
WeCom(企業微信)官方 API✅ 穩定騰訊企業微信,與消費端 WeChat 為不同頻道
ClickClack官方 API✅ 穩定官方文件列為獨立頻道
Reef官方 API✅ 穩定OpenClaw 生態系內部頻道
Raft官方 API🔄 測試OpenClaw 生態系內部頻道
Buzz官方 API✅ 穩定輕量通知型頻道
A2A(Agent-to-Agent)A2A 協定✅ 穩定Agent 之間的直接訊息傳遞,非人類使用者頻道
Zalo ClawBot官方 API✅ 穩定Zalo 的 Bot 模式(與官方帳號/個人帳號並列的第三種接法)

插件頻道(Plugin Channels): OpenClaw 透過 extension 套件機制支援額外頻道整合,如 Mattermost 等。插件頻道安裝後與內建頻道行為一致。

頻道治理功能(v2026.8.1): 除頻道本身外,官方另提供跨頻道的治理機制 —— Access Groups(存取群組)、Broadcast Groups(廣播群組)、Channel Routing(頻道路由)、Bot Loop Protection(機器人迴圈防護)與 Ambient Room Events(環境房間事件)。企業部署多頻道時,這些機制比單一頻道設定更關鍵,詳見第五章 5.2 與第十一章。

WeChat 頻道安裝: WeChat 頻道由騰訊官方提供插件,安裝方式為 openclaw plugins install "@tencent-weixin/openclaw-weixin",然後執行 openclaw channels login --channel openclaw-weixin 掃描 QR Code 即可配對。目前僅支援私人聊天,需遍尋 WeChat ClawBot 插件(WeChat > 我 > 設定 > 插件)。

新增頻道的統一介面

所有頻道都實作相同的 Channel 介面:

// 頻道介面定義(TypeScript 概念說明)
interface Channel {
  id: string;
  name: string;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  sendMessage(target: string, message: Message): Promise<void>;
  onMessage(handler: MessageHandler): void;
}

1.9 與傳統 LLM 聊天機器人的比較

面向傳統 LLM 聊天機器人OpenClaw
部署模式雲端 SaaS自架或雲端皆可
頻道整合通常只有 Web UI28+ 通訊頻道原生整合(含插件頻道)
擴展機制API 呼叫 / PluginSkills + Tools 組合式架構
資料所有權平台持有使用者完全掌控
自訂程度有限(Prompt 調整)完全自訂(Skills + Tools + Agent 行為)
多 Agent通常不支援原生支援多 Agent 路由與協作
信任模型平台信任個人信任邊界 + DM Pairing 機制
可觀測性平台提供完整 OpenTelemetry 整合
成本模型按 Token / 呼叫計費自架為主,LLM API 費用可控
排程能力需額外開發內建 Cron / Webhook / Gmail Pub/Sub
語音互動多數不支援Voice Wake + Talk Mode(macOS/iOS/Android)
視覺工作區無Live Canvas + A2UI 即時渲染
遠端存取內建Tailscale Serve/Funnel 或 SSH Tunnel

1.10 OpenClaw 版本歷程

版本日期重大變更
2026.11.12026-11-05最新穩定版(本手冊基準)。可靠性為主:Mac 設定存檔失敗不再覆寫密鑰、關閉 Tailscale 暴露時保留 Gateway 驗證;Telegram/Discord/webhook 對話在請求處理結束後仍可抵達 Agent;更新器崩潰/取消後可恢復;ClickClack 與 ClawHub 拒絕導向無關私有服務的重新導向;doctor 非互動檢查不再未經同意下載插件;日誌遮罩政策格式錯誤時仍保留內建密鑰保護
2026.11.5-beta.12026-11-04下一個穩定版的 Beta(不建議用於生產)
2026.10.102026-11-034,825 commits/3,028 PR/454 位貢獻者。雲端與桌面 Session 成為一級工作流程(Session 可在本機與雲端間移動、依 Repository 組織雲端環境與 environment recipes);Windows 桌面 App 與 Tauri 可執行本機 Gateway;Gemini 4 Argon 成為預設 Gemini 模型;macOS/iOS/Safari 需 26.2 以上;Node 相容區間恢復為 >=24.16.0 <25 || >=26.1.0(24.22.1/26.12.1 改為安全建議);Codex 受管 CLI 升至 0.164.0;Git 備份涵蓋 PostgreSQL 匯出並遮罩憑證
2026.10.6〜10.92026-10-22〜10-2910.6 一度強制要求 Node 24.22.1+/26.12.1+(回應 2026 年 10 月 Node.js 憑證金鑰外洩的安全版本);10.8 安全強化(exec allowlist 對 test -v 需審批、沙箱子程序不可執行主機 CLI backend、egress proxy 拒絕不受信任的 eMudhra 憑證鏈);10.9 修補 fast-uri/nodemailer 等相依套件漏洞、tools.fs.workspaceOnly 套用至 Gateway 內建工具
2026.10.1〜10.52026-10-10〜10-18Code Mode store/load 跨 cell 保存小型值;匯入 coding-agent 逐字稿為 OpenClaw Session;異地備份(外接磁碟、NAS、Cloudflare R2);Automations 可在不執行模型下檢查條件並呼叫明確允許的 MCP;Cloud Worker 支援 GitHub Enterprise;10.5 新增 X(Twitter)頻道、語音通話報告與即時引導、Gateway 內建 ClawHub 瀏覽;10.1 第三方插件須移除已退休的相容層與整包 session-store helper(破壞性)
2026.9.33〜9.362026-10-15〜10-29Extended-Stable(LTS)九月線:九月底的 OpenClaw 加上關鍵安全、可靠性修補與新模型支援,僅提供 Gateway;目前 npm extended-stable 指向 2026.9.36
2026.9.4〜9.92026-09-11〜10-089.4 安裝/Web UI/更新流程大幅整理;9.5 為「2026 年 6 月以前安裝」的必經升級站;9.6 移除 Compaction checkpoint 還原控制(sessions.compaction.*),新增 openclaw worktrees 歸檔/還原;9.7 移除 Tasks 與 TaskFlow、Tool Search 改為 search/describe/call 三工具並移除 tool_search_code、Bun-only 安裝可自我更新
2026.9.32026-09-08破壞性:Node 需 24.16.0+(24.x)或 26.1.0+,Node 22/25 不再支援(避免 SQLite 文字截斷);Plugin SDK exec-policy/approval/SDK 別名/搜尋與目錄結果欄位多項破壞性調整;Skill Workshop 改為每個 Agent 一份可寫入的技能集合(退休 skills.workshop.allowSymlinkTargetWrites);更新前於隔離候選狀態預演(rehearse) 核心與插件變更;可分享的唯讀對話連結;會議筆記庫;選用的 Team Reports
2026.9.1〜9.22026-09-03〜09-059.1:一句話完成安裝的 quick-start(偵測既有 Claude Code/Codex 登入與 API Key)、共用 Gateway 上的個人技能庫(openclaw skills library)、openclaw update 失敗自動回滾並交給內建 triage Agent、agents.defaults.cwd/worktreeRoot、cron.skipMissedJobs、SSRF blockedHostnames、config set --dry-run 等守門旗標、openclaw memory reset、聊天中渲染 Mermaid、Anthropic Fable 5.1;9.2:GPT-6 Astra、Gateway 重啟後回覆可恢復、更多設定免重啟生效
2026.8.22026-09-01Home Agent 側邊 Dock(Cmd/Ctrl+Shift+H)、Linux 桌面 App(.deb/AppImage,簽章驗證更新)、背景 Session、openclaw update cleanup --dry-run 清理遷移原件、更安全的升級(保留較新組態、未完成遷移不宣告成功)
2026.8.33〜8.35
2026.7.35/2026.6.35
2026-09-10〜10-02八月/七月/六月 Extended-Stable 維護線的後續修補
2026.8.1
(OpenClaw 2.0)
2026-08-31專案史上最大改版(彙整逾 16,000 個 PR)。九大主軸:① 以對話為中心重建的 Control UI(Session Rail、/btw 側線對話、審批內嵌於對話)② 多人協作與分享角色(read/suggest/draft/participate、Incognito)③ Cloud Workers 與 Paired Devices 分散式執行 ④ Session 與 Transcript 改用 SQLite 儲存(含降版限制)⑤ Secret Store(Protected/Agent-readable 雙軌)⑥ Automations(cron 更名,兩套指令並存)⑦ Skill Workshop 與自我學習(off/propose/auto)⑧ Built-in Memory 取代 QMD ⑨ Code Mode 介面重寫。破壞性變更:OpenProse 插件移除、codex/* → openai/* 路由遷移、部分官方 Provider 外部化為獨立套件
2026.8.1-beta.42026-08-28⚠️ 誤植發布為 2026.9.1-beta.1,官方已聲明其實際版本為 2026.8.1-beta.4,不得視為新於 stable 2026.8.1。內容為可靠性修補:Gateway 重啟復原保留已受理回合、組態寫入於 watcher 交接期間的可靠性、Codex runtime 升至 0.150.1、Linux 安裝改用 Node 24 LTS
2026.8.1-beta.32026-08-242.0 發布前的最後一輪 Beta 驗證
2026.8.1-beta.22026-08-15Secret Egress Host Binding(跨 CLI/Gateway RPC/Control UI 綁定密鑰目的地主機)、GPT-5.6 Ultra 與 Sol/Terra/Luna 執行期切換、Channel Plugin Ingress Monitor 共用生命週期(IRC/Synology Chat/Google Chat)、openclaw backup sqlite 快照備份指令、macOS App Profile 隔離、外部插件安裝需明確 --force 確認未信任來源
2026.6.342026-08-08Extended-Stable 維護線發布,僅安全與穩定性修補(瀏覽器/網路邊界加固、Provider Fallback 更穩健、Discord Gateway 突發流量抑制),不含新功能;同時公告 Plugin SDK 舊介面(before_agent_start 等)將於 7/24 後移除
2026.7.1-2 / 2026.7.1-12026-08-04前一代穩定版的修補版。修正 Codex 進度處理、記憶體啟動問題、插件更新復原等穩定性問題
2026.7.2-beta.72026-08-02Crash-recoverable session snapshots、跨平台 durable message delivery、對話分支與回溯(conversation branching/rewinding)、MCP app hosting with ticketed sandboxes
2026.7.12026-07-13Control UI 與 Onboarding 大改版、iOS/Android/macOS 官方應用大幅更新、GPT-5.6 相容性、Tencent Hy3 完整設定流程、Meta Muse Spark 1.1、openclaw attach(外部 harness 接續既有 Gateway Session)、Gateway crash loop 修復(不再無限重啟)、排程任務按需喚醒、遠端瀏覽器分頁控制、Web/iOS/Android 受保護終端機(單一版本彙整 532 位貢獻者、3,063 筆貢獻、2,018 個公開 PR)
2026.6.102026-06-24Automatic Fast Mode(短對話自動加速)、Session Transcript SDK helpers、Cross-channel Session Identity、Trusted Tool Policy Enforcement、Trusted Package Redirects、Provider 模型目錄推理控制、StepFun Provider 安裝、DM Policy pairing 安全預設
2026.6.92026-06-17官方 Provider 外部化為獨立 npm 套件、Gateway 啟動探索已安裝 channel plugins、Codex Hosted Search、OpenTelemetry Log Export、ClawHub skill provenance 保持、Session workspace rail (Control UI)、iOS Watch 控制、安全強化(秘密編修、open-DM 工具暴露稽核)
2026.6.82026-06-14Telegram Rich HTML 渲染(表格、清單、blockquote、展開式引用)、GLM-5.2 + Claude Haiku 4.5 模型目錄、Usage Footer 原生渲染器、無 API Key 搜尋提供者明確 opt-in、WhatsApp ACP 綁定、iOS 前景 Gateway 重連、記憶體 rollback/cache recovery
2026.5.282026-05-28Claude Opus 4.8 支援、GitHub Copilot agent runtime 整合、Codex Supervisor 插件、ClawPDF 加密 PDF 抽取、Workboard 多 Agent 協調面板、Policy 合規性比對/合規確認、Plugin SDK reply payload hook、SecretRef 插件清單合約、Dreaming-tab agent 選擇器
2026.5.272026-05-27安全強化(content boundaries)、OpenAI-compatible embedding providers 核心模組、Pixverse 影片生成 Provider、DeepInfra 完整目錄更新、Skill Workshop 提案生命週期
2026.5.262026-05-26Transcript capture 核心功能、named auth profiles(多帳號驗證配置)、Activity tab UI、Rastermill 取代 Sharp 影像後端、reaction approvals(Signal/iMessage/WhatsApp)、SSRF policy for Browser、auth rate limiter、Pixverse Provider 初版、Plugin SDK reaction approval helpers
2026.5.42026-05-03iOS LAN 配對修復、fs-safe 檔案系統安全抽取、VSCode 除錯支援、Gateway 容器權限加固、Crabbox 整合簡化、Plugin SDK 子路徑匯出、WhatsApp Live QA 通道
2026.5.22026-05-01macOS appcast 更新、OpenClaw SDK 套件發布、Codex prompt snapshots、組態檔 includes 支援、Plugin 邊界修正
2026.4.272026-04-27Codex Computer Use 設定指令、DeepInfra 內建 Provider、QQBot 群聊/串流/媒體上傳、Yuanbao 頻道擴展、Manifest-first 模型目錄、Docker Sandbox GPU 直通、Outbound Proxy 路由
2026.4.262026-04-26Browser Realtime Voice (Google Live)、Cerebras 內建 Provider、Matrix E2EE (openclaw matrix encryption setup)、openclaw migrate CLI (Claude/Hermes importer)、Config Diff 面板、Compaction maxActiveTranscriptBytes
2026.4.252026-04-25TTS 大升級(Azure Speech、Xiaomi、Inworld、Volcengine、ElevenLabs v3)、PWA/Web Push、OpenTelemetry 擴展(模型呼叫、Token 用量、工具迴圈)、Prometheus 內建插件、Crestodian TUI、openclaw browser start --headless
2026.4.242026-04-24Google Meet 內建插件、DeepSeek V4 Flash/Pro、Realtime Voice Loop (Talk/Voice Call/Meet)、Codex Computer Use、Browser 座標點擊、Gradium TTS Provider
2026.4.112026-04-11Dreaming/Memory Wiki ChatGPT 匯入、Control UI 結構化聊天氣泡、video_generate 工具增強、Feishu 文件評論 Session、MS Teams 反應支援 + 委派 OAuth、Plugin 清單宣告機制
2026.4.x2026-04Ollama 快取機制、GPT-5.4 / Opus 4.6 QA 對等檢查、MiniMax OAuth 修正、WhatsApp 反應路由修正
2026.3.312026-03-31ClawFlow 執行基底、npm dist-tag mirror 修正、Session table UI 改善
2026.3.232026-03-24Tools 執行時可見性視圖、Telegram forum topic 修正
2026.3.x2026-03Control UI 改善、Skills 介面翻新、Markdown 預覽、Agent 管理、WeChat 官方插件
2026.2.122026-02版本號 bump、OpenTelemetry 深度整合、健康檢查端點強化
2026.2.x2026-02Gateway 握手逾時統一、Provider API Key 輪換機制
2026.1.x2026-01ClawHub 技能市集上線、VirusTotal 合作技能安全掃描、NVIDIA 贊助
2025.12.x2025-12Docker Compose 官方支援、Podman 安裝文件
2025.11.x〜2026.1.x2025-11 ~ 2026-01專案首次公開發布(2025-11-24,時名 Warelay)並歷經名稱沿革期:Warelay → CLAWDIS → Clawdbot → Moltbot → OpenClaw 定名,同期完成 Skills 系統與 Voice Wake + Talk Mode 等早期核心功能(完整時間軸見 1.1「名稱沿革」)

注意: OpenClaw 採用日期版本號格式 vYYYY.M.D(如 v2026.7.1)。預發布版本使用 -beta.N 後綴,穩定版偶有 -1、-2 等修補後綴(如 v2026.7.1-2),Extended-Stable(官方定位為 LTS 的等價物)以 YYYY.M.33 起跳(如 v2026.9.33〜v2026.9.36),內容是「該月月底的 OpenClaw + 關鍵安全/可靠性修補與新模型支援」,且僅提供 Gateway 套件。stable/extended-stable/beta/dev 四條版本線並行發布,以 npm dist-tag 為準(2026-11-08 查證:latest=2026.11.1、extended-stable=2026.9.36、beta=2026.11.5-beta.1),詳見 3.12 與第七章 7.1。

⚠️ 不可單憑版本號大小判斷新舊:2026-08-28 發布的套件被誤植為 2026.9.1-beta.1,但其實際內容為 2026.8.1-beta.4,比 2026-08-31 的穩定版 2026.8.1 還舊。官方已在發布說明中特別警示此事,並要求穩定版使用者直接安裝或升級至 2026.8.1。這是採用日期版本號的專案在人為誤植下會產生的典型陷阱,升級前請以官方發布說明為準,而非套件登錄的版本排序。

1.11 OpenClaw 2.0 重點導讀

v2026.8.1(OpenClaw 2.0)的變更幅度遠超一般改版,且橫跨本手冊多個章節。為方便既有讀者快速定位,下表將 2.0 的主要變更對應到本手冊的章節位置:

2.0 主題變更性質本手冊對應章節
全新 Control UI(對話為中心、Session Rail、/btw)體驗重構2.8、3.10
Session/Transcript 改用 SQLite 儲存架構變更(含降版限制)2.11、6.7、附錄 E
多人協作、分享角色、Incognito新增能力第十一章
Cloud Workers 與 Paired Devices 分散式執行新增能力第十二章
Secret Store(Protected/Agent-readable)新增能力3.11、9.2
Automations(cron 更名,指令並存)更名 + 功能擴充3.10、4.7、10.7
Skill Workshop 與自我學習(2.0 為 off/propose/auto;v2026.11.1 僅 off/auto)新增能力4.3、9.7
Built-in Memory 取代 QMD遷移(需 doctor --fix)4.6、7.5
Code Mode 介面重寫破壞性變更4.4
Plugin SDK subpath 收斂破壞性變更(2026-09-01 生效)4.9
引導式設定(偵測既有訂閱/API Key/本地模型)體驗重構3.6
Per-session 權限模式新增能力(非回溯性)5.2
Gateway 重啟復原(suspend/resume/drain)新增能力6.11
未信任外部內容標記安全強化9.1
插件能力審查與供應鏈檢查安全強化9.11

升級路徑建議:若你目前執行的是 v2026.7.x,請先閱讀 附錄 E:OpenClaw 2.0 升級遷移指南,再依第七章的升級策略執行。2.0 包含四項需要 openclaw doctor --fix 介入的遷移,以及三個有明確截止日的相容性期限。

1.12 2.x 持續演進導讀(v2026.8.2 → v2026.11.1)

2.0 發布後的兩個多月內,官方又推出了約 40 個版本(穩定版、Beta 與 Extended-Stable)。這段期間的主軸可以歸納為三個字:可恢復(更新、重啟、備份都能安全回頭)、可協作(共用 Gateway 與團隊伺服器成形)、可分散(Session 可在本機、配對裝置與雲端之間移動)。下表把重要變更對應到本手冊章節:

主題起始版本變更性質本手冊章節
一句話完成安裝的 quick-start(偵測 Claude Code/Codex 登入與 API Key)9.1體驗重構3.2
Node 需求改為 >=24.16.0 <25 || >=26.1.0,Node 22/25 不再支援9.3破壞性3.1、附錄 E.5
macOS/iOS/Safari 需 26.2 以上10.10平台需求提升3.1
四條發布通道與 Extended-Stable(LTS)月線持續營運政策3.12、7.1
openclaw update 預演、回滾、repair/recover/cleanup8.2〜10.8新增能力7.11
共用 Gateway 個人技能庫(openclaw skills library)與 Skill Workshop 改為每 Agent 一份9.1/9.3新增能力/破壞性1.5、4.13
Agent 工作目錄與 Managed Worktrees(agents.defaults.cwd、worktreeRoot、openclaw worktrees)9.1/9.6新增能力4.12
Tasks/TaskFlow 移除、Tool Search 改為三工具、Compaction checkpoint 還原移除9.6/9.7破壞性1.6、4.5、附錄 E.5
異地備份(外接磁碟、NAS、R2)、排程備份、Litestream 持續複寫10.1新增能力6.7
實驗性 PostgreSQL 儲存引擎(目前僅 Workboard)10.x實驗功能2.12
Cloud Sessions:Session 在本機與雲端間移動、environment recipes、GitHub Enterprise10.1/10.10新增能力12.7
Team Server:Cloudflare Access + trusted-proxy 驗證 + 角色9.x〜11.1企業部署模式11.7
2026-09-11 一次揭露 375 筆安全公告(150 high)9.3 修補完成資安基準9.12
發布物驗證(npm integrity、release evidence、provenance)持續供應鏈治理8.11

閱讀建議:

  • 全新導入者:依序讀 3.1 → 3.2 → 3.12 → 11.7,直接以 v2026.11.1(或 Extended-Stable 2026.9.36)為起點。
  • 既有 2.0(2026.8.x)使用者:先讀 附錄 E.5,確認 Node 版本、Tasks/TaskFlow 依賴與第三方插件相容性,再依 7.11 的流程升級。
  • 2026 年 6 月以前的安裝:官方要求必須先升級到 2026.9.5 並執行 openclaw doctor --fix,之後才能升到最新版。

1.13 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1技能 frontmatter 只用規範鍵檢視 SKILL.md;CI 以 grep -E '^(triggers|tools|access):' 擋下只有 name、description、metadata 等規範鍵
2技能實際載入來源符合優先序openclaw skills info <name>勝出來源與 1.5 的 7 層優先序一致
3Agent allowlist 理解正確openclaw config get agents --json非空清單為最終集合;[] 代表不暴露技能
4工具 profile 與 group 名稱存在openclaw config validate --jsonvalid: true,無 Unrecognized 或不合法的 enum
5版本敘述有出處比對 GitHub Release 與 npm view openclaw dist-tags版本號、日期、通道與官方一致

第二章:系統架構設計

2.1 整體架構圖

graph TB
    subgraph "使用者層"
        U1[WhatsApp 使用者]
        U2[Telegram 使用者]
        U3[Slack 使用者]
        U4[Discord 使用者]
        U5[Web 使用者]
        U6[其他頻道使用者]
    end
    
    subgraph "頻道適配層"
        C1[WhatsApp Adapter<br>Baileys]
        C2[Telegram Adapter<br>grammY]
        C3[Slack Adapter<br>Bolt]
        C4[Discord Adapter<br>discord.js]
        C5[WebChat Adapter]
        C6[其他 Adapters]
    end
    
    subgraph "Gateway 核心層"
        GW[Gateway Daemon]
        WSP[WebSocket 控制平面<br>Port 18789]
        MR[訊息路由器]
        CM[組態管理器]
        SM[Session 管理器]
        HC[健康檢查]
        DG[診斷插件]
    end
    
    subgraph "Agent Runtime 層 (Pi)"
        AR[Agent Runtime]
        SK[Skills 引擎]
        TL[Tools 引擎]
        CTX[上下文管理]
        MEM[記憶體管理]
    end
    
    subgraph "外部服務層"
        LLM[LLM Providers<br>OpenAI / Anthropic / Google]
        EXT[外部 API]
        DB[資料儲存]
        CH[ClawHub 市集]
    end
    
    subgraph "可觀測性層"
        LOG[JSONL 日誌]
        OTEL[OpenTelemetry<br>OTLP/HTTP]
        PROM[Prometheus Metrics]
        GRF[Grafana Dashboard]
    end
    
    U1 --> C1
    U2 --> C2
    U3 --> C3
    U4 --> C4
    U5 --> C5
    U6 --> C6
    
    C1 & C2 & C3 & C4 & C5 & C6 --> GW
    
    GW --> WSP
    GW --> MR
    GW --> CM
    GW --> SM
    GW --> HC
    GW --> DG
    
    MR --> AR
    AR --> SK
    AR --> TL
    AR --> CTX
    AR --> MEM
    
    SK --> CH
    TL --> LLM
    TL --> EXT
    CTX --> DB
    
    DG --> LOG
    DG --> OTEL
    OTEL --> PROM
    PROM --> GRF

2.2 Gateway 核心元件

Gateway 是 OpenClaw 的中央控制器,由以下核心模組組成:

2.2.1 WebSocket 控制平面

WebSocket 控制平面是 Gateway 的通訊骨幹,提供即時雙向通訊:

sequenceDiagram
    participant Client as 客戶端/Companion App
    participant WS as WebSocket Server (18789)
    participant GW as Gateway Core
    
    Client->>WS: 建立 WebSocket 連線
    WS->>GW: 註冊客戶端
    GW-->>WS: 連線確認
    WS-->>Client: 連線建立
    
    loop 訊息交換
        Client->>WS: 發送指令
        WS->>GW: 處理指令
        GW-->>WS: 回應結果
        WS-->>Client: 串流回應
    end
    
    Note over WS: 支援串流回應
    Note over WS: 心跳偵測
    Note over WS: 自動重連

Wire Protocol: OpenClaw 使用自定義的 Wire Protocol 在 WebSocket 上傳輸訊息,支援:

功能說明
串流(Streaming)支援 Token-by-Token 串流回應
心跳(Heartbeat)定期心跳偵測連線存活
批次(Batching)多則訊息批次傳送以提升效能
壓縮(Compression)可選的訊息壓縮

2.2.2 訊息路由器

訊息路由器負責將接收的訊息分派到正確的 Agent:

flowchart TD
    MSG[收到訊息] --> PARSE[解析訊息元資料]
    PARSE --> CHANNEL{識別頻道}
    CHANNEL --> SESSION[查詢/建立 Session]
    SESSION --> SKILL{匹配 Skill}
    SKILL -->|找到匹配| ROUTE[路由到目標 Agent]
    SKILL -->|無匹配| DEFAULT[路由到預設 Agent]
    ROUTE --> PROCESS[處理訊息]
    DEFAULT --> PROCESS

路由規則的判斷順序:

  1. DM 配對(DM Pairing): 一對一對話中,訊息直接路由到配對的 Agent
  2. Skill 觸發詞: 檢查訊息是否包含特定技能的觸發詞
  3. 上下文延續: 若存在活躍的 Session,延續上一個 Skill 的處理
  4. 預設 Agent: 以上都不匹配時,由預設 Agent 處理

2.2.3 組態管理器

組態管理器負責載入、驗證、監控 OpenClaw 的設定:

flowchart TD
    FILE[openclaw.json] --> PARSE[JSON5 解析]
    PARSE --> VALIDATE[嚴格驗證<br>Schema Validation]
    VALIDATE -->|通過| APPLY[套用組態]
    VALIDATE -->|失敗| ERROR[報告錯誤<br>拒絕載入]
    APPLY --> WATCH[監控檔案變更]
    WATCH -->|偵測變更| PARSE
    WATCH -->|Hot Reload| RELOAD{Reload 策略}
    RELOAD -->|hybrid| HYB[部分重載]
    RELOAD -->|hot| HOT[即時套用]
    RELOAD -->|restart| RST[重啟 Agent]
    RELOAD -->|off| OFF[手動重啟]

2.3 Agent Runtime 架構

Agent Runtime(Pi)是處理 AI 推論與工具呼叫的核心引擎:

架構圖

graph TB
    subgraph "Agent Runtime (Pi)"
        direction TB
        
        subgraph "請求處理層"
            RP[Request Pipeline]
            MW[Middleware Chain]
        end
        
        subgraph "Skill 引擎"
            SR[Skill Resolver]
            SL[Skill Loader]
            SG[Skill Gating]
        end
        
        subgraph "推論引擎"
            MR[Model Reference<br>Resolver]
            PC[Prompt Compiler]
            TC[Tool Caller]
            SC[Stream Controller]
        end
        
        subgraph "狀態管理"
            SM[Session Manager]
            CM[Context Manager]
            MM[Memory Manager]
        end
    end
    
    RP --> MW --> SR
    SR --> SL --> SG
    SG --> MR --> PC --> TC
    TC --> SC
    SM --> CM --> MM
    
    TC -.->|"呼叫外部 LLM"| LLM[LLM Provider]
    TC -.->|"執行工具"| TOOLS[External Tools]

請求處理管線

Agent 處理訊息的完整管線:

sequenceDiagram
    participant GW as Gateway
    participant RP as Request Pipeline
    participant SR as Skill Resolver
    participant PC as Prompt Compiler
    participant LLM as LLM Provider
    participant TC as Tool Caller
    participant SM as Session Manager

    GW->>RP: 轉發使用者訊息
    RP->>SM: 載入/建立 Session
    SM-->>RP: Session 上下文
    RP->>SR: 解析技能
    SR-->>RP: 匹配的 Skill + Tools
    RP->>PC: 編譯 Prompt
    Note over PC: 合併 Skill Prompt<br>+ 上下文 + 使用者訊息
    PC->>LLM: 推論請求
    
    loop Tool 呼叫迴圈
        LLM-->>TC: Tool 呼叫請求
        TC->>TC: 執行工具
        TC->>LLM: 工具結果
    end
    
    LLM-->>RP: 最終回應
    RP->>SM: 更新 Session
    RP->>GW: 回傳回應

2.4 訊息流程與通訊協議

完整訊息流程

以一個使用者透過 WhatsApp 詢問天氣為例的完整訊息流程:

sequenceDiagram
    actor User as 使用者 (WhatsApp)
    participant WA as WhatsApp Adapter
    participant GW as Gateway
    participant RT as Agent Runtime
    participant SK as Weather Skill
    participant LLM as LLM Provider
    participant API as 天氣 API

    User->>WA: "台北今天天氣如何?"
    WA->>GW: 標準化訊息格式
    GW->>GW: 訊息路由
    GW->>RT: 轉發至 Agent
    RT->>SK: 匹配 Weather Skill
    SK->>LLM: Prompt + 工具定義
    LLM->>SK: tool_call: get_weather("台北")
    SK->>API: HTTP GET /weather?city=taipei
    API-->>SK: {"temp": 25, "humidity": 70}
    SK->>LLM: 工具回傳結果
    LLM-->>RT: "台北目前 25°C,濕度 70%..."
    RT-->>GW: Agent 回應
    GW-->>WA: 格式化回應
    WA-->>User: "🌤️ 台北目前 25°C,濕度 70%..."

訊息格式標準化

OpenClaw 在 Gateway 層將來自不同頻道的訊息統一格式化:

{
  "id": "msg_20260305_abc123",
  "channel": {
    "type": "whatsapp",
    "id": "wa_886912345678"
  },
  "sender": {
    "id": "user_001",
    "name": "王小明",
    "role": "user"
  },
  "content": {
    "type": "text",
    "text": "台北今天天氣如何?"
  },
  "timestamp": "2026-03-05T09:30:00Z",
  "session": {
    "id": "session_xyz789",
    "messageCount": 5
  },
  "metadata": {
    "platform_specific": {}
  }
}

2.5 Skills 載入與優先序

三層技能載入架構

graph TB
    subgraph "合併結果"
        FINAL[最終 Skill 集合]
    end
    
    subgraph "層級 3 - Workspace(最高優先)"
        W1[./skills/weather]
        W2[./skills/custom-tool]
    end
    
    subgraph "層級 2 - Managed"
        M1[~/.openclaw/skills/weather]
        M2[~/.openclaw/skills/calendar]
        M3[~/.openclaw/skills/notes]
    end
    
    subgraph "層級 1 - Bundled(最低優先)"
        B1[built-in/weather]
        B2[built-in/search]
        B3[built-in/general]
    end
    
    B1 & B2 & B3 --> MERGE1[合併]
    M1 & M2 & M3 --> MERGE1
    MERGE1 --> MERGE2[合併]
    W1 & W2 --> MERGE2
    MERGE2 --> FINAL
    
    style W1 fill:#f96,stroke:#333
    style M1 fill:#f96,stroke:#333
    
    Note1[weather Skill:<br>Workspace 版本覆蓋<br>其他兩層的同名 Skill]

Skill 載入流程

flowchart TD
    START[Agent 啟動] --> SCAN1[掃描 Bundled Skills]
    SCAN1 --> LOAD1[載入內建技能]
    LOAD1 --> SCAN2[掃描 Managed Skills<br>~/.openclaw/skills/]
    SCAN2 --> LOAD2[載入管理級技能<br>同名覆蓋 Bundled]
    LOAD2 --> SCAN3[掃描 Workspace Skills<br>./skills/]
    SCAN3 --> LOAD3[載入工作區技能<br>同名覆蓋所有]
    LOAD3 --> VALIDATE[驗證所有技能]
    VALIDATE --> GATE[套用 Skill Gating 規則]
    GATE --> READY[技能集合就緒]

2.6 模型參考(Model References)

OpenClaw 透過 Model References 機制抽象化 LLM 提供者,讓 Agent 可以輕鬆切換模型:

模型參考設定

模型參考(Model Reference)一律寫成 provider/model-id 字串,例如 anthropic/claude-opus-5-5、openai/gpt-6-astra。預設模型與備援鏈放在 agents.defaults.model,別名與每模型參數放在 agents.defaults.models,自訂或自架 Provider 才需要 models.providers:

// openclaw.json(openclaw 2026.11.1 `config validate` 通過)
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-5-5",                     // 預設模型
        fallbacks: ["openai/gpt-6-astra", "google/gemini-4-argon"], // 失效轉移順序
      },
      // 為常用模型取別名(/model Sonnet)
      models: {
        "anthropic/claude-sonnet-5-5": { alias: "Sonnet" },
        "anthropic/claude-haiku-5-5": { alias: "Haiku" },
      },
      // 企業治理:只允許核准清單內的模型被選用
      // 萬用字元只能是結尾的 "provider/*";其餘須寫完整 ref 或別名
      modelPolicy: { allow: ["anthropic/*", "openai/gpt-6-astra", "google/gemini-4-argon", "vllm/*"] },
    },
  },
  models: {
    providers: {
      // 自架 vLLM(OpenAI 相容端點)
      vllm: {
        baseUrl: "http://vllm.internal:8000/v1",
        apiKey: { source: "env", provider: "default", id: "VLLM_API_KEY" },
        api: "openai-completions",
        models: [{ id: "qwen3.8-27b", name: "Qwen3.8 27B", contextWindow: 131072, maxTokens: 8192 }],
      },
    },
  },
}

❌ 舊版手冊/AI 常見錯誤寫法:agent.model、models.default、models.fast、models.reasoning。這些鍵在 2026.11.1 會被 config validate 判為 Unrecognized key。「快速模型」「推理模型」的需求應改用 agents.defaults.utilityModel、decisionModel 或別名 + /model 切換來表達。

❌ modelPolicy.allow 的萬用字元陷阱:"openai/gpt-6-*" 這種「前綴 + 星號」寫法不合法,config validate 會回報 invalid model policy ref。只接受三種形式:已設定的別名、完整的 provider/model、或結尾萬用字元 provider/*(provider/namespace/*)。

最佳實務:官方維護一份人工審核、依序排列的 Recommended models 清單(2026-11 版前五名:Claude Opus 5.5、GPT-6.1 Sol、Gemini 4 Argon、GPT-6 Astra、Claude Fable 5.1),模型選單會優先顯示該 Provider 的推薦模型。最新世代模型同時也有較低的 Prompt Injection 風險。

如何驗證:

openclaw config validate --json        # 鍵與型別正確
openclaw models status                 # 實際生效的 primary / fallbacks 與認證狀態
openclaw models fallbacks list         # 備援鏈順序

模型失效轉移(Model Failover)

OpenClaw 支援模型失效轉移機制,當主要模型不可用時自動切換到備援模型:

  • OAuth vs API Keys 輪換: 支援多種認證方式與自動切換
  • Provider 失效轉移: 當某個 Provider 回應失敗時自動嘗試下一個
  • API Key 輪換: 支援多組 API Key 自動輪換,避免單一 Key 配額耗盡

詳細設定請參考 Model failover。

支援的 LLM 提供者

OpenClaw 目前支援 50+ LLM 提供者,以下列出主要提供者(完整清單請參閱 Provider Directory):

分類提供者模型範例備註
旗艦OpenAIGPT-6.1 Sol、GPT-6 Astra、GPT-6 Luna、GPT-5.6(Sol/Terra/Luna)API Key 或 ChatGPT/Codex 帳號;GPT-6 Astra 自 v2026.9.2 起支援
AnthropicClaude Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1官方推薦清單第一名(Opus 5.5);Fable 5.1 自 v2026.9.1 起支援
GoogleGemini 4 Argon、Gemini 3.8 Flashv2026.10.10 起 Gemini 4 Argon 為預設 Gemini 模型;Veo 影片生成
雲端Azure OpenAIAzure 部署的 GPT 系列企業合規、資料落地
Amazon BedrockClaude, TitanAWS 整合,Mantle 支援
NVIDIANIM 微服務API Catalog 整合
Fireworks各類模型高速推論
Together AI各類開源模型推論即服務
GroqLlama, Mixtral硬體加速推論
新興DeepSeekV4.1 Flash、V4 Flash、V4 Pro高性價比
DeepInfra模型目錄媒體生成、TTS、Embeddings
Cerebras高速推論內建 Provider(v2026.4.26)
MiniMaxM2.5工具解析優秀,OAuth 支援
MistralMistral Large歐洲 AI
xAIGrokGrok 搜尋整合
中國Alibaba通義千問Model Studio
QwenQwen 系列阿里雲模型
GLM (Zhipu)GLM-5.3、GLM-5.3 Flash智譜 AI
MoonshotKimiKimi 搜尋整合
Volcengine豆包 Doubao字節跳動火山引擎
Tencent騰訊混元TokenHub 整合
Qianfan百度文心百度千帆
Xiaomi MiMoMiMo小米推論
本地OllamaGemma 4、Qwen3.8、gpt-oss本地執行;v2026.9.1 起本地 Ollama 路由維持可選
LM Studio各類模型桌面 LLM
vLLM各類模型高效推論引擎
SGLang各類模型結構化生成語言
媒體ElevenLabsTTS/STT語音合成
Azure SpeechTTS/STT語音服務
DeepgramSTT語音辨識
RunwayGen-3 Alpha影片生成
Fal圖片/影片模型即時 AI 媒體
ComfyUIStable Diffusion圖片生成工作流
SenseAudio音訊處理音訊 AI
閘道OpenRouter多模型路由統一 API 存取
LiteLLM多模型代理自架 Proxy
Cloudflare AIAI GatewayCDN 層級快取
Vercel AIAI GatewayEdge Runtime
GitHub CopilotGPT/ClaudeCopilot 訂閱代理
Claude MaxClaude 系列Claude Max API Proxy
其他Perplexitypplx-online搜尋增強
Hugging Face各類模型Inference API
Venice AI隱私模型去中心化 AI
Arcee AI自訂模型企業微調
GradiumTTS語音合成
Inworld角色 AI遊戲 NPC
Kilocode程式碼模型程式碼生成
Inferrs推論服務託管推論
Vydra模型服務新興 Provider
Z.AI模型服務新興 Provider
Chutes模型服務去中心化推論
StepFun階梯模型中國 AI Provider
Synthetic合成資料資料生成

模型建議: 官方建議使用最新世代最強模型以獲得最佳體驗與最低 Prompt Injection 風險。模型設定與 CLI 操作詳見 Models。

模型目錄的探索策略(v2026.8.1 變更)

2.0 之前,開啟模型選單會觸發完整的 Provider 掃描,造成明顯延遲。2.0 起改為目錄優先策略:

  • Chat 與 Models 頁面直接從 OpenClaw 已持有的目錄開啟,不等待 Provider 掃描。
  • 即時探索只在你開啟模型畫面或明確要求重新整理時執行。
  • 若探索失敗,內建項目與最後一次可用的清單仍然保留,不會變成空白。

/model 的作用域也明確化為三層,且持久性變更需要對應權限:

作用域效果權限需求
僅本對話只改變當前 Session一般使用者
單一 Agent改變該 Agent 的預設需具備變更權限
共用預設改變全域預設模型需具備變更權限

注意:清單顯示的是「OpenClaw 能辨識的模型」,但實際可用與否由 Provider、帳號、區域、端點、方案與定價共同決定。能在清單中看到,不等於該帳號有權呼叫。

脈絡窗與推理層級(v2026.8.1 更新)

2.0 對脈絡窗與推理設定做了明確化,這是企業評估成本與能力上限時的關鍵資訊:

路由標準脈絡窗可選上限說明
GPT-5.5 / GPT-5.6(一般執行)272,000 token922,000 token 輸入窗(opt-in)需明確選用,非預設
Claude 5 CLI 對話200K1M(Control UI 可選)限支援的路由與介面

推理層級(reasoning effort)在 2.0 起會跟隨所選模型與 runtime 一起保存,即使對話被還原或認證路由重建也不會遺失。各層級的可用性依 runtime 而異:

Runtime最高推理層級適用模型
Native CodexUltraSol、Terra
Native CodexMaxLuna
Embedded OpenClawUltra(對映語意不同)對映至該 Provider 支援的最高 effort

⚠️ 重要差異:Embedded OpenClaw 的 Ultra 並非等同於 Native Codex 的 Ultra。前者是「對映到該 Provider 所支援的最高 effort」並額外加上委派工作的指引,後者是 Codex 原生的推理層級。兩者行為不同,跨 runtime 比較效能或成本時不可直接對等看待。

上述脈絡窗選項僅限支援的路由、介面與帳號。同一個模型在不同 Provider 帳號或端點下,可用的上限可能不同。

Compaction 與失效轉移的行為修正

  • Compaction 改用「最新且可信的脈絡計數」,不再受累計快取計費或重複歷史影響;在支援的 Responses 檢查點會保留工具輸出,若儲存的檢查點被拒絕則回退為完整歷史。
  • 脈絡上限改為逐模型設定(原為 Provider 層級),openclaw doctor 可協助遷移綁定於明確模型項目的舊設定。
  • 多帳號失效轉移:同一 Provider 若某帳號遇到認證或配額冷卻,會依你設定的憑證順序切換到下一個授權帳號,不會改變已選定的 Provider 與模型,待其恢復後回復原偏好。未設定明確帳號清單時,環境變數金鑰仍可使用。
  • Codex 訂閱制執行不會靜默切換為按量計費的 API Key —— 這是成本治理上重要的保證。永久性的認證、模型、媒體與長視窗配額失敗會停止重試,僅暫時性速率限制與可重試的伺服器錯誤保留重試或同 Provider 授權回退行為。

2.7 ClawHub 技能市集架構

ClawHub 是 OpenClaw 的技能市集,類似 npm 之於 Node.js:

graph LR
    subgraph "開發者"
        DEV[Skill 開發者]
        PUB[發布工具]
    end
    
    subgraph "ClawHub (clawhub.ai)"
        REG[技能註冊]
        SEARCH[技能搜尋]
        VER[版本管理]
        REV[社群評價]
        VT[VirusTotal 安全掃描]
    end
    
    subgraph "使用者"
        CLI[openclaw CLI]
        GW[Gateway]
    end
    
    DEV --> PUB --> REG
    CLI --> SEARCH
    SEARCH --> CLI
    CLI --> GW
    REG --> VER
    VER --> REV
    REG --> VT

安全提示: OpenClaw 已與 VirusTotal 合作,對 ClawHub 上的技能進行安全掃描,確保技能來源安全可信。啟用 ClawHub 後,Agent 可自動搜尋並拉取所需技能,搭配 Skill Install Gating 機制進行安全審核。

ClawHub 指令

日常的搜尋、安裝與驗證走 openclaw skills;發布則使用獨立的 clawhub CLI(需先 clawhub login):

# 搜尋與安裝(技能參照格式為 @owner/slug)
openclaw skills search weather
openclaw skills install @owner/weather-reporter
openclaw skills update --all

# 安裝前先驗證來源與完整性,並產生 Skill Card 供人工審查
openclaw skills verify @owner/weather-reporter --card

# 檢視實際載入結果(權威來源)
openclaw skills list
openclaw skills check

# 發布自訂技能(ClawHub CLI,非 openclaw 子指令)
clawhub login
clawhub skill publish ./my-skill --version 1.0.0

移除技能:openclaw skills 沒有 remove 子指令。工作區或 managed 目錄的技能直接刪除資料夾即可;共用 Gateway 的個人技能庫請用 openclaw skills library remove <id>(見 4.13)。

2.8 Companion Apps 架構

OpenClaw 提供 Companion Apps 作為多平台入口。Gateway 本身即能提供完整體驗,所有 Apps 均為可選擴充:

平台技術棧功能
macOSSwift (Menu Bar App)Gateway 健康監控、Voice Wake + PTT、Talk Mode overlay、WebChat、除錯工具、遠端 Gateway 控制、Quick Chat(v2026.8.1)
iOS / iPadOSSwift (Node App)單一 Chat 介面整合打字/聽寫/語音訊息/附件/即時 Talk,Canvas、Voice Wake、相機、螢幕錄製、Bonjour + 裝置配對
Apple WatchSwift (watchOS)訊息、審批、回覆與指令,跨重啟/Gateway 變更/導航/重試仍保留並與手機對帳
AndroidKotlin (Node App)精簡 composer(聽寫/語音訊息/即時 Talk/模型與思考層級/脈絡用量/附件)、Canvas、裝置指令、Sharesheet 匯入
Wear OSKotlin (watchOS 對應)透過配對手機連線(Watch 端不儲存 Gateway 憑證)、逐字稿、回覆、停止執行、Agent Pulse(唯讀)
WindowsTypeScript (Hub App)(v2026.6.10 新增)原生 Windows 伴侶應用、Gateway 健康狀態、系統列快速存取、WebChat 內嵌
Linux 桌面TypeScript(v2026.8.1 新增)首次執行設定、系統匣與服務控制、內嵌 Control UI、深層連結、開機自啟、Quick Chat
graph TB
    subgraph "Companion Apps"
        MAC[macOS Menu Bar App<br>Swift + Quick Chat]
        IOS[iOS / iPadOS Node<br>Swift]
        WATCH[Apple Watch<br>watchOS]
        AND[Android Node<br>Kotlin]
        WEAR[Wear OS<br>經手機轉接]
        WIN[Windows Hub<br>TypeScript]
        LNX[Linux Desktop<br>TypeScript]
    end

    subgraph "Gateway"
        WS[WebSocket Server<br>Port 18789]
    end

    MAC -->|WebSocket| WS
    IOS -->|WebSocket| WS
    AND -->|WebSocket| WS
    WIN -->|WebSocket| WS
    LNX -->|WebSocket| WS
    WATCH -.->|經 iPhone| IOS
    WEAR -.->|經 Android<br>不存憑證| AND

v2026.8.1 原生應用重點變更

macOS Quick Chat 可從選單列或全域快捷鍵在當前使用中的應用之上開啟,內含最近更新的五個對話選擇器,能就地串流回覆、切換 Agent、接受聽寫並選擇模型與推理層級。兩項作業系統權限會擴充其能力:

權限解鎖能力
Screen Recording視窗或區域擷取
Accessibility讀取焦點應用的有界文字,並可將最終答案貼回原本工作處

擷取到的脈絡會在送出後或 Quick Chat 隱藏時清除。

進度卡與 Widget 的跨平台支援並不一致,這在規劃企業標準配備時必須留意:

呈現形式支援平台限制
持久化進度卡iOS、macOS、Android需連線的 Gateway 支援已儲存卡片;舊版 Gateway 只能顯示即時卡片,重啟後無法還原,Android 的回退機制偶有殘留過期完成狀態
Agent 產生的 WidgetiOS、Android、macOS、Linux Quick Chat需用戶端聲明支援;連線的 Mac 可另在原生 Canvas 面板呈現;Linux Quick Chat 使用自訂 Gateway TLS leaf pin 時僅支援純文字
可展開的檔案差異iPhone、iPad、Mac支援平台明顯較窄

Linux 桌面應用的發布狀態:官方已完成 .deb 與 AppImage 的建置與發布路徑,但發布說明載明「其作為 v2026.8.1 下載項目的可用性尚未驗證」。Summon 快捷鍵在 X11 可用,Wayland 保留系統匣項目,審批決策仍需在 Dashboard 或命令列完成。企業若規劃 Linux 桌面部署,建議先確認實際可取得的套件版本。

Plugin Manifest 機制

Plugin Manifest 機制(v2026.4.11 新增): 插件清單現可宣告激活(activation)與設定(setup)描述符,描述所需的認證、配對與組態步驟。這消除了核心程式碼中的硬編碼特殊處理,讓第三方插件的安裝設定流程更加統一。

Plugin SDK 架構(v2026.5 新增)

OpenClaw v2026.5 引入完整的 Plugin SDK,將頻道、工具與 Provider 的擴展統一為標準化插件架構:

插件分類
類型說明範例
Bundled Plugins隨 OpenClaw 安裝包內建的插件WeChat、QQ Bot、Voice Call、Google Meet
Community Plugins社群開發的第三方插件自訂頻道、工具擴展
External Plugins外部套件安裝的獨立插件@tencent-weixin/openclaw-weixin
Plugin SDK 模組
openclaw/plugin-sdk
├── sdk-overview          # SDK 總覽與 API 設計
├── sdk-setup             # 插件設定與組態
├── sdk-entrypoints       # 插件進入點定義
├── sdk-channel-plugins   # 頻道插件開發指南
├── sdk-channel-message   # 頻道訊息 API
├── sdk-channel-turn      # 頻道輪次核心
├── sdk-provider-plugins  # Provider 插件開發指南
├── sdk-agent-harness     # Agent Harness 插件
├── sdk-runtime           # 運行時輔助工具
├── sdk-subpaths          # 子路徑匯出
├── sdk-testing           # 插件測試框架
└── sdk-migration         # 舊版遷移指南
內建插件清單
插件類型功能
Voice Call頻道Plivo/Twilio 語音通話,Realtime Voice Loop
Google Meet頻道Chrome/Twilio Realtime、出席匯出、錄製檔
Webhooks自動化外部 Webhook 事件處理
Memory LanceDB記憶LanceDB 向量記憶引擎
Memory Wiki記憶Wiki 結構化記憶管理
Skill Workshop開發技能開發輔助工具
Codex Computer Use工具Codex 電腦使用整合
Codex HarnessAgentCodex Agent 執行環境
Zalo Personal頻道越南 Zalo 個人帳號頻道
插件開發範例(現行寫法)

⚠️ Breaking Change(狀態:已生效):舊版 import { defineChannelPlugin } from 'openclaw/plugin-sdk' 根路徑匯入方式,連同 before_agent_start hook、providerAuthEnvVars、channelEnvVars 等介面,已於 2026 年 7 月 24 日後移除(v2026.6.34 Extended-Stable 公告)。

v2026.8.1 進一步收斂:契約整理移除了 7 月與 8 月的已退休 SDK 路徑,並以 gateway_stop 取代 deactivate 別名。舊版 subpath 匯入的相容窗口已於 2026-09-01 關閉。新插件開發須使用細分子路徑匯入(subpath imports),例如頻道插件改從 openclaw/plugin-sdk/channel-core 匯入 defineChannelPluginEntry,並以 manifest setup descriptor 取代硬編碼的啟用/設定邏輯:

// 最小頻道插件進入點(v2026.11.1;以 tsc --strict 對 openclaw 2026.11.1 型別檢查通過)
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

// 實際的頻道實作(連線、收訊、送訊)放在 ./src/channel.ts,以 createChatChannelPlugin 等 helper 建立
declare const acmeChatPlugin: Parameters<typeof defineChannelPluginEntry>[0]["plugin"];

export default defineChannelPluginEntry({
  id: "acme-chat",
  name: "Acme Chat",
  description: "Acme Chat channel plugin",
  plugin: acmeChatPlugin,
});

❌ 舊版範例在 defineChannelPluginEntry 中直接寫 manifest、connect()、onMessage()、sendMessage();實際的 entry 只接受 id、name、description、plugin(與選用的 registerCliMetadata、registerFull),頻道行為由 plugin 物件提供。詳見官方 Channel plugins。

相關文件: Plugin SDK Overview · Building Plugins · Plugin Inventory · Plugin SDK Migration。既有插件開發者建議啟用 @typescript-eslint/no-deprecated 之類的型別感知 Lint 規則,及早攔截已標記 @deprecated 的舊版 SDK 介面呼叫。

v2026.6.9 重要變更 — Provider 外部化: 自 v2026.6.9 起,官方 Provider(如 OpenAI、Anthropic、Google 等)已從核心套件抽離為獨立 npm 套件(例如 @openclaw/provider-openai)。新安裝時 Gateway 會自動探索已安裝的 channel/provider plugin,無需手動註冊。對於現有用戶,升級時 openclaw doctor 會自動建議安裝對應套件。

2.9 高可用架構設計

設計 OpenClaw 的高可用(HA)之前,必須先接受一個官方架構事實:一個 state 目錄在任一時刻只能有一個 Gateway 擁有者。Gateway 啟動時會依序取得三層鎖——①以共享 state 資料庫路徑為鍵的行程擁有者鎖、②給舊版辨識用的相容性投影、③HTTP/WebSocket 監聽埠的獨占 bind(預設 ws://127.0.0.1:18789)。第二個想接手同一份 state 的行程會等待(最長 5 分鐘)或失敗,不存在「多個 Gateway 共用同一份 Session Store」的官方模式。

因此,OpenClaw 的 HA 不是「Active-Active 叢集」,而是以下四個層次的組合:

層次目標官方機制本手冊章節
行程韌性當機或重開機後自動回來launchd/systemd/Windows 排程工作管理的 Gateway 服務;崩潰迴圈斷路器;重啟後恢復未完成回覆3.2、6.11
資料保護主機毀損時資料不遺失openclaw backup(完整 archive、per-database SQLite snapshot、Git 備份)、排程異地備份、Litestream 持續複寫6.7、6.12
救援通道主 Gateway 壞掉時仍能修以獨立 --profile 與獨立埠執行 Rescue Gateway(獨立 bot token)本節
運算擴展長任務、重負載不拖垮 GatewayCloud Workers 與 Paired Devices:Gateway 保留逐字稿、工作區與憑證,執行移到其他機器第十二章

單機高可用(建議的生產基線)

graph TB
    subgraph "Gateway 主機"
        SVC["服務管理器<br/>systemd user service / launchd / schtasks"]
        GW["OpenClaw Gateway<br/>(唯一 state 擁有者)"]
        DB[("state/openclaw.sqlite<br/>+ 各 Agent 資料庫")]
        SVC -->|自動重啟 / 斷路器| GW
        GW --> DB
    end
    DB -->|Litestream 持續複寫| OBJ[("物件儲存<br/>S3 / R2")]
    GW -->|排程 archive<br/>openclaw backup enable| OFF[("異地備份<br/>NAS / R2")]
    MON["監控<br/>/healthz、OTel、Prometheus"] -.-> GW

Rescue Gateway(救援 Bot)

官方建議的冗餘方式是在同一台主機以獨立 profile 跑第二個 Gateway:它有自己的組態、state、工作區、服務名稱與 bot token,主 Gateway 故障時仍可透過它診斷或修改組態。

# 主 Gateway 使用預設 profile(埠 18789)
# 救援 Gateway:獨立 profile、獨立 Telegram bot、埠至少相差 120(衍生埠會用到 base+110)
openclaw --profile rescue onboard
openclaw --profile rescue gateway install --port 19789
openclaw --profile rescue gateway status --deep

冷備援(Warm/Cold Standby)

若業務要求主機層級的備援,正確做法是「備援主機待命、資料持續複寫、故障時切換擁有權」,而不是兩台同時對外:

  1. 主機以 Litestream 或排程 openclaw backup create --to offsite 持續輸出狀態。
  2. 備援主機預先安裝相同版本的 OpenClaw,但不啟動 Gateway 服務。
  3. 故障切換時:確認主機已停止(避免兩個擁有者)→ 在備援主機還原至全新 state 目錄 → openclaw doctor → 啟動服務 → 切換 DNS/Cloudflare Tunnel。

❌ 錯誤的 HA 設計(常見於 AI 產出的架構圖):負載平衡器後面放多個 Gateway,共用 Redis Session Store 或共用 PostgreSQL。OpenClaw 沒有 Redis Session Store,PostgreSQL 引擎目前也只支援 Workboard(見 2.12);多個行程搶同一份 state 會被 Gateway Lock 拒絕,或在繞過鎖時造成資料毀損。看到這類圖,應直接退回。

✅ 需要水平擴展時的正確方向:依信任邊界、團隊或環境切分成多個獨立 Gateway(各自擁有 state),把重運算交給 Cloud Workers。

如何驗證 HA 設計

檢查指令/方法預期
單一擁有者在同一 state 目錄再啟動一個 Gateway等待或明確拒絕,不會兩者同時服務
服務自動重啟kill -9 <gateway pid> 後觀察服務管理器在數秒內重啟,openclaw gateway status --deep 正常
備份可還原openclaw backup verify --from offsite --namespace gateway latest驗證通過
救援通道可用停止主 Gateway 後,從救援 bot 執行 openclaw status救援 Gateway 正常回應

2.10 企業部署拓撲

拓撲的切分依據是信任邊界,而不是使用者人數。官方明確聲明:一個 Gateway 就是一個信任域,角色與 Session 擁有權用來支援協作,不能隔離彼此不信任的使用者;互不信任的團隊必須使用不同的 Gateway、OS 使用者或主機。

小型團隊(單一信任域,1–10 人)

graph LR
    U[團隊成員] -->|HTTPS| CF["Cloudflare Access<br/>+ Tunnel"]
    CF -->|loopback| GW["Team Gateway<br/>(trusted-proxy 驗證)"]
    SLACK[Slack / Telegram] --> GW
    GW --> SBX["Docker 沙箱<br/>(非 main session)"]
    GW -.->|排程備份| OFF[("R2 / NAS")]
資源規格
CPU2–4 cores
RAM4–8 GB(大量 Agent 或本地模型另計)
儲存20–50 GB SSD(逐字稿與附件會持續成長)
網路只需對外連線;不要對外開放 18789,由 Tunnel 建立出站連線

中型組織(多個信任域,10–100 人)

graph TB
    subgraph "身分與入口"
        IDP[企業 IdP] --> ACC["Cloudflare Access / 反向代理<br/>(驗證後注入使用者標頭)"]
    end
    subgraph "協作 Gateway(研發部)"
        GWA["team-rd.example.com<br/>Gateway A"]
    end
    subgraph "協作 Gateway(業務部)"
        GWB["team-sales.example.com<br/>Gateway B"]
    end
    subgraph "發布 Gateway"
        GWR["release.example.com<br/>Gateway R(獨立憑證與更新時程)"]
    end
    subgraph "執行層"
        CW["Cloud Workers<br/>(臨時機器)"]
        PD["Paired Devices<br/>(開發者筆電)"]
    end
    subgraph "可觀測性"
        OTEL[OTel Collector] --> PROM[Prometheus] --> GRF[Grafana]
    end
    ACC --> GWA & GWB & GWR
    GWA & GWB --> CW
    GWA --> PD
    GWA & GWB & GWR --> OTEL

每個 Gateway 的建議配置:4 cores/8 GB RAM/50 GB SSD。Gateway 之間不共享 state,跨部門的唯讀分享可使用官方的「從另一個 Gateway 唯讀分享」功能(見 11.7)。

大型企業(100+ 人)

規模再擴大時,仍沿用「多個獨立 Gateway + 共用執行與觀測平台」的模式:

  • 每個信任域一個 Gateway(依事業單位、資料分級或法遵區域切分),各自擁有 state、備份與更新節奏。
  • 跨區域:以「主機 + 冷備援」方式部署於各區(見 2.9),而不是跨區共用資料庫。
  • 共用平台服務:IdP、反向代理/WAF、OTel Collector、集中日誌、物件儲存(備份)、Cloud Worker 機池。
  • 治理:以 IaC 管理每個 Gateway 的組態(openclaw config validate --json 納入 CI),版本統一走 Extended-Stable 或經驗證的 stable(見 3.12、8.1)。

⚠️ 規格數字只是起點。Gateway 的資源用量主要來自同時執行的 Agent 回合數、逐字稿大小、瀏覽器與本地模型;請以 openclaw gateway usage-cost、OTel 指標與 openclaw status 的實測值調整(見 6.8 容量規劃)。

2.11 Session 儲存架構:SQLite 遷移

v2026.8.1 最具架構影響力的變更,是將原本以檔案為後端的狀態改為 SQLite 後端儲存。這項變更影響備份策略、容器 Volume 規劃與降版可行性,是企業升級前必須理解的前提。

遷移範圍

資料類別2.0 前2.0 後
Sessions 與 Transcripts檔案式SQLite
選定的裝置與認證紀錄檔案/JSONSQLite
會議擷取(Meeting capture)檔案SQLite
Runtime journals檔案SQLite

遷移後可透過同一套工具建立、驗證與還原可攜式快照(portable snapshot),讓備份與復原在事故發生前就具備可驗證的路徑(詳見 6.7)。

架構示意

graph TB
    subgraph "Gateway Process"
        AGENT[Agent Runtime]
        SESS[Session Manager]
    end

    subgraph "State Directory 狀態目錄"
        DB[(SQLite<br/>sessions / transcripts<br/>devices / auth<br/>meetings / journals)]
        WAL[WAL 日誌]
        FILES[工作區檔案<br/>MEMORY.md / USER.md<br/>skills/]
    end

    subgraph "備份"
        SNAP[Portable Snapshot<br/>create → verify → restore]
    end

    AGENT --> SESS
    SESS --> DB
    DB --- WAL
    AGENT --> FILES
    DB --> SNAP
    FILES --> SNAP

降版限制(升級前必讀)

⚠️ 這是單向性較強的變更。官方發布說明明確警告:

  • 遷移後建立的 Session 不會出現在舊版中。
  • 若要降版到舊的檔案式版本,必須先用當前 CLI 還原已封存的舊版 transcript 產物,否則資料在舊版看不到。
  • 升級前應建立可驗證的備份(openclaw backup),而非僅複製目錄。

其他已知限制

官方載明的邊界條件,規劃維運程序時須一併納入:

項目限制
舊版儲存遷移部分舊儲存需先停止擁有該狀態的行程,openclaw doctor --fix 才能遷移
待處理的配對請求與 bootstrap 代碼不會被匯入
macOS tunnel 遷移產生的資料無法被僅支援 JSON 的舊版建置讀取
還原行為拒絕覆寫既有目標,須還原至全新目標
Node + SQLite 版本已知有漏洞的組合會在狀態開啟前擋下,並提示應升級內嵌 Node runtime 或系統共用的 SQLite 函式庫

資料安全強化:2.0 針對 SQLite 後端做了大量健全性修補,包含防止 WAL split-brain 清理損毀資料庫,以及將「已證實損毀」的判定隔離處理。即便如此,SQLite 檔案本身並未加密,其機密性仍取決於狀態目錄的檔案系統權限(與 Secret Store 相同的前提,見 3.11)。

2.12 儲存引擎與 State 擁有權

2.0 把 Session 與 Transcript 移到 SQLite(見 2.11)之後,OpenClaw 的持久化狀態可以整理成下表。企業在規劃備份、稽核與資料保存時,應以此表為準:

儲存位置(預設)引擎備註
共享狀態(使用者、技能庫中繼資料、Automations 等)<state-dir>/state/openclaw.sqliteSQLiteGateway Lock 以此路徑為擁有權鍵
各 Agent 資料庫(Session、逐字稿、記憶索引)<state-dir>/agents/<agentId>/...SQLite每個 Agent 獨立
Workboard依引擎而定SQLite(預設)或 PostgreSQL(實驗性)目前唯一支援 PostgreSQL 的儲存
技能庫不可變 bundle<state-dir>/skill-library/<id>/revisions/<hash>/檔案不要手動修改
Incognito 對話記憶體—永不落地
組態~/.openclaw/openclaw.json(可用 OPENCLAW_CONFIG_PATH 覆寫)JSON5 檔支援 includes

實驗性 PostgreSQL 引擎

// openclaw.json:Workboard 改存 PostgreSQL(需 PostgreSQL 16+、UTF8 編碼)
{
  database: {
    engine: "postgres",
    postgres: {
      // DSN 是憑證:只能用 env/file/exec SecretRef,不可用 store 型 SecretRef
      connection: { source: "env", provider: "default", id: "OPENCLAW_DATABASE_DSN" },
      schemaPrefix: "openclaw",
    },
  },
}
# 只改 engine 不會搬移既有資料:先停 Gateway,再以 port 指令搬移
openclaw gateway stop
openclaw database port --to postgres --dry-run   # 唯讀檢查前置條件
openclaw database port --to postgres             # 實際搬移,原始資料保留於 <stateDir>/recovery/database-port/
openclaw gateway start
openclaw doctor                                  # 顯示每個儲存實際使用的引擎

⚠️ 企業評估重點:

  1. PostgreSQL 引擎目前標示為 experimental,且只涵蓋 Workboard;共享狀態、Agent/Session 儲存與安全日誌仍在 SQLite。它不是多 Gateway 共用狀態的方案。
  2. 支援的儲存在 PostgreSQL 連線失敗時不會靜默退回 SQLite——這是正確的失敗模式,但代表資料庫中斷會直接影響 Workboard。
  3. 備份必須同時涵蓋 PostgreSQL schema 與對應的 SQLite anchor(openclaw backup 會處理;自行用 pg_dump 時不要遺漏 anchor)。

儲存引擎的驗證方式

openclaw config validate --json   # database.* 鍵與 SecretRef 型別
openclaw doctor                   # 每個儲存的實際引擎;PostgreSQL 會出現 experimental 警告
openclaw database preflight       # 資料庫相容性與擁有權檢查

2.13 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1架構圖沒有多 Gateway 共用 state人工審查架構圖無 Redis Session Store、無多實例共用 PostgreSQL
2模型參考格式正確openclaw config validate --jsonagents.defaults.model.primary 為 provider/model;modelPolicy 萬用字元只用 provider/*
3備援鏈可用openclaw models status、openclaw models fallbacks listprimary 與 fallbacks 皆有可用認證
4PostgreSQL 僅用於 Workboard 且標示實驗性openclaw doctor顯示各儲存的實際引擎與 experimental 警告
5救援通道存在openclaw --profile rescue gateway status --deep救援 Gateway 運作,埠至少相差 120

第三章:安裝與環境建置

3.1 系統需求

Node.js 支援政策(v2026.11.1)

package.json 的 engines 精確表達式為 >=24.16.0 <25 || >=26.1.0:

Node 版本線狀態最低版本說明
Node 26建議>=26.1.0(強烈建議 26.12.1+)Gateway 啟動較快、記憶體較省;macOS 安裝器預設提供
Node 24支援(LTS)>=24.16.0 <25(強烈建議 24.22.1+)CI 與 Linux 安裝器使用的版本線;Docker 映像內建 24.22.1
Node 25不支援—被 node:sqlite TEXT 解碼器的版本下限排除
Node 22/23不支援—自 v2026.9.3 起移除

為什麼有這些下限(審查升級計畫時要能說明理由):

  1. SQLite WAL-reset 毀損問題:實際載入的 SQLite 必須是 3.51.3+(或 3.50.7+/3.44.6+ 對應分支)。OpenClaw 會檢查實際載入的函式庫,因為部分 Node 建置連結到系統 SQLite。
  2. node:sqlite TEXT 解碼器截斷:Node 22.23.x、24.15.0、25.9.0、26.0.0 會在內嵌 NUL 字元處靜默截斷資料。
  3. 安全建議版本(24.22.1/26.12.1):會拒絕 2026 年 10 月 eMudhra 事件中外洩的憑證公鑰。v2026.10.6 一度把它列為硬性需求,10.10 起改為「強烈建議」;低於建議版本時 openclaw update 會顯示醒目警告但仍繼續。

Bun:可作為明確 opt-in 的執行環境,需 Bun 1.4.4+(WAL-reset-safe node:sqlite)。Node 仍是主要且建議的 runtime。

作業系統與平台

項目需求
macOSNode 24+ 官方二進位支援 macOS 13.5+;macOS 桌面 App、iOS App 與 Safari(Control UI)自 v2026.10.10 起需 26.2 以上
Linuxx86-64 或 64-bit ARM(沒有 ARMv7 官方 Node 建置);RPM 系發行版的安裝器會為 OpenClaw 另外佈建使用者空間 runtime,避開不安全的系統 SQLite
Windows建議使用原生 Windows Hub 桌面 App,或 PowerShell CLI 安裝器;也可採 WSL2 Gateway
FreeBSD支援 CLI 安裝(自 v2026.9.5)

硬體建議

項目個人/PoC團隊生產環境(單一 Gateway)
CPU2 cores4 cores
記憶體2–4 GB8 GB(本地模型另計)
磁碟5 GB50 GB SSD(逐字稿、附件、備份暫存會持續成長)
容器—Docker 24+ 或 rootless Podman(沙箱需要)

系統需求的驗證方式

node --version                 # 應為 v24.22.1+ 或 v26.12.1+
openclaw --version             # OpenClaw 2026.11.1 (4ffdd20)
openclaw doctor                # 會檢查實際載入的 SQLite 與 node:sqlite 行為

3.2 本地開發安裝

官方提供三種起點,依使用者類型選擇:

路徑適用對象特點
桌面 App非工程背景使用者、Windows 使用者Windows Hub(簽章安裝檔,含系統匣、聊天、node 模式)、macOS 選單列 App(.dmg)、Linux .deb/AppImage;首次設定即可佈建本機 Gateway 或連線遠端 Gateway
安裝器腳本(推薦)一般 CLI 使用者自動偵測 OS、必要時安裝 Node、安裝 OpenClaw 並啟動 onboarding
npm/pnpm/bun自行管理 Node 的團隊、CI完全掌控套件管理器與版本釘選

路徑一:官方安裝器(推薦)

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# 不立即執行 onboarding
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

若希望 OpenClaw 與 Node 都放在使用者自己的前綴目錄(不依賴系統 Node),可改用 install-cli.sh:

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

企業環境提醒:curl | bash 會直接執行遠端腳本。受控環境應先下載腳本、比對雜湊並經內部審查,或改用下方的 npm 路徑搭配內部套件鏡像與版本釘選(見 8.11 發布物驗證)。

路徑二:npm/pnpm 全域安裝

# 1. 確認 Node 版本:>=24.16.0 <25 或 >=26.1.0(建議 24.22.1+/26.12.1+)
node --version

# 2. 安裝(npm 12 或 npm 11.16+ 需明確允許 OpenClaw 的安裝腳本)
npm install -g openclaw@2026.11.1 --allow-scripts=openclaw

# 3. 初始化並安裝 Gateway 服務(launchd / systemd user service / Windows 排程工作)
openclaw onboard --install-daemon

# 4. 驗證
openclaw --version
openclaw gateway status --deep
npm 版本--allow-scripts=openclaw 的行為
npm 12必須:預設封鎖未核准的 lifecycle scripts,未加旗標會出現 blocked because they are not covered by allowScripts
npm 11.16接受此旗標;未加時只警告 not yet covered by allowScripts,腳本仍會執行
npm 11.15 以前不可加:沒有這個選項,指令須去掉旗標

⚠️ npm 11.16 提示的 npm approve-scripts openclaw 對全域安裝無效(會出現 ENOMATCH),請改用上表的旗標。另外 OpenClaw 不會替你升級 Node。

Quick-start 與 Custom setup(v2026.9.1 起)

全新安裝(包含 npx openclaw@latest)會先進入 quick-start:偵測本機既有的 Claude Code 或 Codex 登入與 API Key,即時驗證後從前景 Gateway 開啟 Web Dashboard。需要逐項設定時選 Custom setup,可走完完整精靈(Provider 登入、頻道、Gateway、工作區、技能)。

openclaw onboard                 # 引導式設定(quick-start 或 Custom setup)
openclaw setup --baseline        # 只建立基準組態、工作區與 session 目錄
openclaw configure               # 之後再調整模型、Gateway、頻道、插件、技能

啟動與日常操作

openclaw gateway status --deep         # 服務狀態(含額外服務掃描)
openclaw gateway restart               # 透過服務管理器重啟
openclaw gateway run --port 18789 --verbose   # 前景執行(除錯用)
openclaw dashboard                     # 以目前 token 開啟 Control UI(預設 http://127.0.0.1:18789)
openclaw status                        # 頻道健康與最近對象
openclaw logs --follow                 # 透過 RPC 追蹤 Gateway 檔案日誌

驗證安裝

openclaw doctor          # 組態、本機探索與遷移建議(2.0 起聚焦「壞了什麼、下一步」)
openclaw health          # 執行中 Gateway 的健康狀態
openclaw security audit  # 常見的安全誤設定

安裝出問題時:openclaw triage 會收集經過消毒的診斷資訊,並可交給本機偵測到的 coding agent(Claude Code、Codex CLI 或內建 Agent)協助修復。

3.3 Docker Compose 部署

官方映像同時發布到 GHCR(主要來源,供釘選與 provenance 驗證) 與 Docker Hub 鏡像:

映像說明
ghcr.io/openclaw/openclaw:<版本>建議生產環境釘選確切版本,例如 2026.11.1
ghcr.io/openclaw/openclaw:extended-stableExtended-Stable(LTS)月線,僅 Gateway
-slim 變體較小映像;-browser 變體內建 Chromium(給 Gateway 控制的瀏覽器使用)
openclaw/openclaw:<版本>Docker Hub 鏡像;請勿使用非官方鏡像

預設映像內建 codex 與 diagnostics-otel 插件。容器內以 node 使用者執行,state 目錄為 /home/node/.openclaw(不是 /root/.openclaw)。

建議做法:官方 setup 腳本

git clone https://github.com/openclaw/openclaw.git && cd openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.11.1"
./scripts/docker/setup.sh          # 同步 .env、修正權限、onboarding、啟動 Compose

最小可用的 docker-compose.yml(依官方 Compose 精簡)

# docker-compose.yml — 以官方 compose 為基礎精簡,保留安全相關設定
services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-ghcr.io/openclaw/openclaw:2026.11.1}
    env_file:
      - path: .env
        required: false
    environment:
      HOME: /home/node
      OPENCLAW_HOME: /home/node
      # 固定容器內路徑,避免主機路徑經由 .env 滲入容器
      OPENCLAW_STATE_DIR: /home/node/.openclaw
      OPENCLAW_CONFIG_PATH: /home/node/.openclaw/openclaw.json
      OPENCLAW_WORKSPACE_DIR: /home/node/.openclaw/workspace
      OPENCLAW_GATEWAY_PORT: "18789"
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      # OTel 為 Gateway 主動外送(OTLP/HTTP),不需要對外開埠
      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-}
      TZ: ${OPENCLAW_TZ:-Asia/Taipei}
    volumes:
      - "${OPENCLAW_CONFIG_DIR:-./data/openclaw}:/home/node/.openclaw"
      - "${OPENCLAW_WORKSPACE_DIR:-./data/openclaw/workspace}:/home/node/.openclaw/workspace"
    cap_drop:
      - NET_RAW
      - NET_ADMIN
    security_opt:
      - no-new-privileges:true
    init: true
    restart: unless-stopped
    ports:
      # 只綁本機;對外請透過反向代理或 Cloudflare Tunnel(見 11.7)
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT:-18789}:18789"
    command: ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]
    healthcheck:
      test: ["CMD", "node", "dist/docker-healthcheck.js"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s

為何容器內要 --bind lan、主機端卻只綁 127.0.0.1? 容器網路中 Gateway 必須監聽容器介面才能被 port mapping 轉發;真正的暴露面由主機端 127.0.0.1: 前綴控制。若直接寫 "18789:18789",Gateway 會暴露在主機所有網卡上。

容器的啟動與日常操作

docker compose up -d
docker compose ps                                  # healthcheck 應為 healthy
docker compose logs -f openclaw-gateway
docker compose exec openclaw-gateway node dist/index.js --version
docker compose exec openclaw-gateway node dist/index.js doctor

升級容器

容器的升級方式是換映像、重建容器並沿用同一組 state/config 掛載;容器內的 openclaw update 會回報 skipped(偵測不到套件管理器擁有者)。官方容器 entrypoint 會在啟動前自動執行必要的 Doctor 修復;自訂 entrypoint 則須自行加入 openclaw doctor --fix。

openclaw backup create --verify                   # 在容器內或主機端先備份
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.11.1"
docker compose pull && docker compose up -d

監控元件

OTel Collector、Prometheus、Grafana 應作為獨立的平台服務部署(見第六章)。注意兩點:

  • Prometheus 指標走 Gateway 既有的已驗證路由,不需要額外開埠。
  • 不需要 Redis——OpenClaw 沒有 Redis Session Store(見 2.9)。舊版手冊與網路範例中的 redis 服務應移除。

3.4 從原始碼建置

前置需求

# 啟用 corepack,依 package.json 的 packageManager 欄位取得對應版本的 pnpm(2026.11.1 為 pnpm 12.15)
corepack enable

# 確認版本
pnpm --version

建置步驟

# 1. 克隆原始碼
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安裝依賴(建議使用 pnpm)
pnpm install

# 3. 建置 UI(首次執行會自動安裝 UI 依賴)
pnpm ui:build

# 4. 建置專案
pnpm build

# 5. 從原始碼執行 onboard
pnpm openclaw onboard --install-daemon

# 5.(可選)執行測試
pnpm test

# 6.(可選)連結本地建置到全域
pnpm link --global

開發模式

# 開發模式(啟用 Gateway watch 和 hot reload)
pnpm gateway:watch

# 注意: pnpm openclaw ... 會透過 tsx 直接執行 TypeScript
# pnpm build 會產生 dist/ 用於 Node / 打包後的 openclaw 執行檔

3.5 Podman 與 Nix 安裝

Podman(rootless,官方腳本)

官方的 Podman 模型是:容器只跑 Gateway,主機上的 openclaw CLI 是控制面,state 留在主機 ~/.openclaw。日常管理用 openclaw --container <name> ...,而不是 podman exec。

# 前置:rootless Podman + catatonit(--init 需要)+ 主機已安裝 openclaw CLI
./scripts/podman/setup.sh                 # 建置 openclaw:local,或以 OPENCLAW_IMAGE 指定已發布映像
# Linux + systemd user service 可改用 Quadlet 自動啟動:
# ./scripts/podman/setup.sh --quadlet

./scripts/run-openclaw-podman.sh launch          # 以目前 uid/gid(--userns=keep-id)啟動
./scripts/run-openclaw-podman.sh launch setup    # 在容器內執行 onboarding

export OPENCLAW_CONTAINER=openclaw
openclaw gateway status --deep                   # 指令自動在容器內執行
openclaw doctor

❌ 舊版範例 podman run -v ./config:/root/.openclaw ... 的掛載路徑是錯的:官方映像以 node 使用者執行,state 在 /home/node/.openclaw;而且手動 podman run 會略過官方腳本處理的 uid 對映、權限修正與 Doctor 步驟。

Nix(nix-openclaw Home Manager 模組)

nix-openclaw 是官方第一方的宣告式安裝方式(Home Manager 模組),提供釘選版本的 Gateway、macOS App 與工具、可存活重開機的 launchd 服務,以及 home-manager switch --rollback 即時回滾:

mkdir -p ~/code/openclaw-local
git clone https://github.com/openclaw/nix-openclaw.git /tmp/nix-openclaw
cp /tmp/nix-openclaw/templates/agent-first/flake.nix ~/code/openclaw-local/flake.nix
# 填入 bot token、模型金鑰等 placeholder(可放在 ~/.secrets/)後套用
home-manager switch

參考:Nix 安裝的權威來源是 nix-openclaw repository,Nix 文件僅為概覽。以 Nix 管理時,更新也應由 Nix 處理(openclaw update 會辨識 Nix 管理的組態與憑證連結)。

3.6 初始設定與 JSON5 組態

OpenClaw 使用 JSON5 格式作為設定檔格式,JSON5 是 JSON 的超集,支援註解、尾逗號等開發友善特性。

引導式設定(v2026.8.1 重構)

2.0 將初次設定從「逐項填寫」改為「先偵測既有資源,再驗證後保存」。這對企業導入的意義在於:既有的 AI 存取權可以直接成為設定的一部分,而不是另一件要重新申請的事。

引導式設定的偵測與驗證流程:

graph LR
    A[開始設定] --> B{偵測既有 AI 存取}
    B --> C[已驗證的 Codex/<br/>ChatGPT/Claude CLI 登入]
    B --> D[API Key]
    B --> E[Provider 自身登入流程]
    B --> F[符合條件的 Ollama/<br/>LM Studio 本地模型]
    C & D & E & F --> G[實測該模型能否回答]
    G -->|通過| H[保存模型與憑證]
    G -->|未通過| B
    H --> I[交棒至 Web App 或終端機]

關鍵設計要點:

  • 驗證後才保存:系統會先證明「所選的那個確切模型」能夠回應,才會保留該模型與憑證。本地模型畫面在該選擇通過啟用測試前,不會顯示「開始聊天」。
  • OpenAI 帳號:使用該登入帳號實際可存取的模型,同時保留你自行設定的路由。
  • 本地模型:管理者可準備支援的本地模型並看到即時進度;經驗證的本地模型會**自動採用精簡工具介面(lean tool surface)**以符合其能力。
  • 設定完成後直接交棒:圖形化的 Mac/Linux/Windows 工作階段會開啟 Web App;SSH 等無頭環境則提供一組已認證的連結與 port-forward 指示,並保留終端機聊天。

組態錯誤的行為變更:2.0 起,錯誤的組態會直接停止並給出可行動的答案,而不是靜默地用別的設定啟動 OpenClaw。打包建置、CLI 檢查、服務 preflight 與 Gateway 啟動都會顯示檔案、行號、完整設定路徑、可用值(若有)以及收到內容的安全版本。格式錯誤的頂層純量檔案會 fail closed,不再載入預設值。這對生產環境是重要的可靠性提升——設定錯誤不再變成難以察覺的行為偏差。

組態檔位置

~/.openclaw/openclaw.json            # 預設;可用 OPENCLAW_CONFIG_PATH 覆寫
~/.openclaw-<profile>/openclaw.json  # 使用 --profile <name> 時

基本組態範例

最簡設定只需指定預設模型(其餘全部使用安全預設值):

// ~/.openclaw/openclaw.json(最小組態)
{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-5-5" } } },
}

團隊常用的完整組態範例(每一個鍵都已用 v2026.11.1 openclaw config validate --json 驗證):

// ~/.openclaw/openclaw.json — 團隊 Gateway 基準組態
{
  // === Agent 預設 ===
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5-5", fallbacks: ["openai/gpt-6-astra"] },
      userTimezone: "Asia/Taipei",
      // 非主 Session 一律在 Docker 沙箱中執行
      sandbox: { mode: "non-main" },
    },
  },

  // === 頻道(Token 用 ${VAR} 從環境變數帶入,不寫死在檔案)===
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+886912345678"],
      groups: { "*": { requireMention: true } },
    },
    telegram: { botToken: "${TELEGRAM_BOT_TOKEN}", dmPolicy: "pairing" },
    slack: { botToken: "${SLACK_BOT_TOKEN}", appToken: "${SLACK_APP_TOKEN}" },
    discord: { token: "${DISCORD_BOT_TOKEN}" },
  },

  // === Gateway ===
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",            // 只監聽本機;啟用 Tailscale Serve/Funnel 時必須保持 loopback
    tailscale: { mode: "off" },  // off | serve | funnel
    auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" }, // none | token | password | trusted-proxy
    reload: { mode: "hybrid" },  // 可熱套用者立即生效,其餘自動重啟
  },

  // === 工具與檔案系統 ===
  tools: { profile: "coding", fs: { workspaceOnly: true } },

  // === 日誌 ===
  logging: {
    level: "info",               // silent | fatal | error | warn | info | debug | trace
    consoleStyle: "json",        // pretty | json
  },
}

❌ 舊版範例(以及許多 AI 產出)中的錯誤鍵:agent.model(應為 agents.defaults.model.primary)、logging.format(應為 logging.consoleStyle)、gateway.tailscale.resetOnExit(已不存在)、gateway.auth.mode: "tailscale"(合法值只有 none/token/password/trusted-proxy;Tailscale identity 改以 gateway.auth.allowTailscale 控制)。

完整組態參考:所有設定鍵與預設值請參閱 官方組態參考;也可直接查詢本機 schema:openclaw config schema --json。

DM Pairing 安全機制

OpenClaw 連接的是真實的通訊平台,因此對來自陌生人的 DM 訊息預設採取安全策略。在 Telegram / WhatsApp / Signal / iMessage / Microsoft Teams / Discord / Google Chat / Slack 上的預設行為:

策略設定值說明
pairing(預設)dmPolicy="pairing"未知發送者會收到配對碼,Bot 不處理訊息
opendmPolicy="open"公開接受所有 DM(需明確啟用,並在 allowFrom 中加入 "*")
allowlistdmPolicy="allowlist"只接受 allowFrom 清單內的發送者,不發配對碼
disableddmPolicy="disabled"完全不處理 DM

管理配對的指令:

# 核准配對請求
openclaw pairing approve <channel> <code>

# 該發送者會被加入本地白名單(allowlist store)

安全提示: 使用 openclaw doctor 可檢查是否有高風險的 DM policy 設定。建議生產環境保持 pairing 模式。

Tailscale 遠端存取設定

OpenClaw 原生支援 Tailscale 以安全方式暴露 Gateway 儀表板與 WebSocket:

模式說明認證方式
off不啟用 Tailscale(預設)-
servetailnet 內 HTTPS(tailscale serve)預設使用 Tailscale identity headers
funnel公開 HTTPS(tailscale funnel)必須設定 gateway.auth.mode: "password"

注意事項:

  • 啟用 Serve/Funnel 時 gateway.bind 必須保持 loopback(OpenClaw 會強制檢查)
  • Serve 預設可用 Tailscale identity 標頭(tailscale-user-login)免 token 登入;若同主機可能執行不受信任的程式,設定 gateway.auth.allowTailscale: false 改為強制 token/password
  • Funnel 不設密碼會拒絕啟動
  • 舊版的 gateway.tailscale.resetOnExit 已移除;gateway.tailscale.preserveFunnel 僅為已棄用的遷移防護,新部署不要使用
  • v2026.11.1 修正:在 macOS 設定中關閉 Tailscale 暴露時,會保留 Gateway 驗證設定

詳見 Tailscale 指南 · Web surfaces

Remote Gateway(Linux 伺服器部署)

Gateway 可完美運行在小型 Linux 實體上,客戶端(macOS app、CLI、WebChat)透過 Tailscale 或 SSH tunnel 連線:

  • Gateway 主機:執行 exec 工具與頻道連線
  • 裝置節點:執行裝置本地動作(system.run、相機、螢幕錄製、通知)透過 node.invoke

詳見 Remote access · Nodes · Security

JSON5 vs JSON 差異

特性JSONJSON5
註解❌✅ // 單行 和 /* 多行 */
尾逗號❌✅ { "a": 1, }
單引號字串❌✅ 'hello'
多行字串❌✅ 反斜線換行
無引號 Key❌✅ { key: "value" }
十六進位❌✅ 0xFF
NaN / Infinity❌✅

3.7 環境變數與密鑰管理

支援的環境變數

環境變數說明預設值
OPENAI_API_KEYOpenAI API 金鑰-
ANTHROPIC_API_KEYAnthropic API 金鑰-
GEMINI_API_KEYGoogle Gemini API 金鑰-
TELEGRAM_BOT_TOKENTelegram Bot Token-
SLACK_BOT_TOKENSlack Bot Token-
SLACK_APP_TOKENSlack App Token-
DISCORD_BOT_TOKENDiscord Bot Token-
OPENCLAW_LOG_LEVEL日誌級別info
OPENCLAW_GATEWAY_PORTGateway 監聽埠18789
OPENCLAW_CONFIG_PATH組態檔路徑~/.openclaw/openclaw.json
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry 端點-

在組態中引用環境變數與 SecretRef

組態中任何字串值都可用 ${VAR_NAME} 帶入環境變數($${VAR} 可輸出字面的 ${VAR},也支援 "${BASE}/v1" 這種內嵌替換)。需要保護的憑證則建議使用 SecretRef 物件:它會被 openclaw secrets audit 追蹤,日誌與 Control UI 也會自動遮罩。

{
  channels: {
    telegram: { botToken: "${TELEGRAM_BOT_TOKEN}" },       // 字串替換
  },
  models: {
    providers: {
      // SecretRef:來源可為 env/file/exec,或 OpenClaw Secret Store(見 3.11)
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
}

OpenClaw 自身的常用環境變數(v2026.11.1):

環境變數用途
OPENCLAW_STATE_DIRstate 目錄(預設 ~/.openclaw)
OPENCLAW_CONFIG_PATH組態檔路徑(預設 ~/.openclaw/openclaw.json)
OPENCLAW_HOME家目錄基準(容器常設為 /home/node)
OPENCLAW_PROFILE具名 profile(等同 --profile)
OPENCLAW_GATEWAY_PORT/OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORDGateway 埠與驗證憑證
OPENCLAW_NO_AUTO_UPDATE停用自動更新(受控環境建議設定)
OPENCLAW_CONTAINER讓主機 CLI 自動在指定容器內執行
OPENCLAW_INCLUDE_ROOTS允許 $include 讀取的額外根目錄(唯讀)
OTEL_EXPORTER_OTLP_ENDPOINT 等 OTEL_*OpenTelemetry 匯出(見 6.3)

密鑰管理最佳實務

環境建議做法審查重點
個人開發~/.openclaw/.env 或 shell 環境變數.env 不可提交至版控(.gitignore)
團隊 GatewayOpenClaw Secret Store(Protected/Agent-readable,見 3.11)用 openclaw secrets audit 確認沒有明文金鑰
企業外部保管庫(1Password、HashiCorp Vault 等官方插件)透過 exec/file SecretRef 供應憑證輪替流程、存取稽核
容器Docker/Kubernetes Secret 掛載為檔案 → file SecretRef不要用 environment: 明文寫入 compose
openclaw secrets audit          # 找出組態中的明文憑證與未解析的 SecretRef
openclaw secrets configure      # 互動式設定 SecretRef
openclaw secrets reload         # 不重啟 Gateway 重新解析密鑰

3.8 多環境組態管理

OpenClaw 沒有「openclaw.<env>.json 自動疊加」的機制。多環境的正確做法有兩種,可以並用:

  1. 每個環境一個獨立 Gateway(獨立主機或獨立 --profile),各自擁有 state 與組態。
  2. 以 $include 拆分組態:共用的部分放在共同檔案,環境差異以「後者覆蓋前者」的陣列 include 或同層鍵覆蓋表達。
config/
├── openclaw.json            # 各環境的進入點(每個環境的 Gateway 各自指向自己的那一份)
├── base/
│   ├── agents.json5         # 共用 Agent 預設
│   └── tools.json5          # 共用工具政策
└── env/
    ├── dev.json5            # 開發環境差異
    └── prod.json5           # 生產環境差異

$include 規則:單一檔案取代所在物件;檔案陣列依序深度合併(後者勝出,最多 10 層);同層鍵在 include 之後合併並覆蓋;相對路徑以「發出 include 的檔案」為基準。

開發環境組態

// dev Gateway 的 openclaw.json(NOVALIDATE:含 $include,需搭配實際檔案)
{
  agents: { $include: ["./base/agents.json5", "./env/dev.json5"] },
  logging: { level: "debug", consoleStyle: "pretty" },
  gateway: { bind: "loopback", auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" } },
}

生產環境組態

// prod Gateway:直接 TLS 終結(若前方已有反向代理 / Cloudflare,改用 trusted-proxy,見 11.7)
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-5-5", fallbacks: ["openai/gpt-6-astra"] },
      sandbox: { mode: "all" },
    },
  },
  logging: { level: "warn", consoleStyle: "json" },
  gateway: {
    mode: "local",
    bind: "lan",
    port: 18789,
    auth: { mode: "password", password: { source: "env", provider: "default", id: "OPENCLAW_GATEWAY_PASSWORD" } },
    tls: {
      enabled: true,
      certPath: "/etc/openclaw/tls/fullchain.pem",
      keyPath: "/etc/openclaw/tls/privkey.pem",
    },
  },
  tools: { profile: "coding", fs: { workspaceOnly: true } },
  update: { channel: "extended-stable", checkOnStart: true },
}

❌ 舊版範例的 security.allowedUsers、security.dmPairing、gateway.host、gateway.tls.cert/key 都不是合法鍵。存取控制請改用頻道的 dmPolicy/allowFrom(3.6)、gateway.auth 與 gateway.roles(11.7);監聽介面用 gateway.bind;憑證路徑用 gateway.tls.certPath/keyPath。

3.9 Hot Reload 與組態更新

組態重載只有兩種模式(gateway.reload.mode):

模式行為適用場景
hybrid(建議)可安全熱套用的設定立即生效;需要重啟的設定自動觸發重啟一般營運
off忽略即時編輯,需手動重啟變更凍結期、批次維護

v2026.9.2 起,更多 Agent、模型、工具、頻道、瀏覽器、節點、存取與終端機設定可由其執行中的擁有者直接套用而不需重啟;仍需重啟的項目會在組態參考中標註。

{
  gateway: { reload: { mode: "hybrid" } },
}

❌ 舊版的 gateway.configReload,以及 hot/restart 兩種模式已不存在。

安全地修改組態

# 1. 先驗證(不啟動 Gateway)
openclaw config validate --json

# 2. 以「預期目前值」守門的方式修改:若目前值已被他人改動則拒絕寫入
openclaw config set gateway.port 18790 --expect-current-json 18789 --dry-run
openclaw config set gateway.port 18790 --expect-current-json 18789

# 3. 讀取與比對
openclaw config get gateway.port
openclaw config file                  # 顯示實際使用的組態檔路徑

# 4. 需要重啟的設定,透過服務擁有者重啟
openclaw gateway restart

錯誤組態的行為:2.0 起組態錯誤會直接停止並給出可行動的訊息(檔案、行號、完整設定路徑、可用值),不會靜默改用預設值;啟動遷移只會在「整份遷移後組態都通過驗證」時才寫入,並保留 .bak 輪替備份。v2026.11.1 起,舊版 binary 遇到較新組態時也會說明如何恢復。

3.10 CLI 指令參考

本節的產生方式:以 openclaw 2026.11.1 (4ffdd20) 遞迴執行每個指令的 --help(共 630 個指令路徑)建立白名單,表中每個範例都經過 check_cli.py 比對子指令與旗標(見附錄 F.2)。審查 AI 產出的指令時,最可靠的做法同樣是 openclaw <指令> --help。全域選項:--profile <name>、--dev、--container <name>、--log-level <level>、--no-color。

安裝、設定與服務

指令說明範例
openclaw onboard引導式設定(auth、模型、Gateway、工作區、頻道、技能)openclaw onboard --install-daemon
openclaw setup建立基準設定;尚未設定時進入 onboardingopenclaw setup --baseline
openclaw configure互動式調整憑證、頻道、Gateway 與 Agent 預設openclaw configure
openclaw config非互動組態操作(get/set/patch/unset/file/schema/validate)openclaw config validate --json
openclaw gateway執行、檢視與查詢 Gateway(run/start/stop/restart/status/install/probe/suspend/resume…)openclaw gateway status --deep
openclaw daemon管理 Gateway 服務(launchd/systemd/schtasks)openclaw daemon status
openclaw dashboard以目前 token 開啟 Control UIopenclaw dashboard
openclaw update更新與切換通道(status/repair/recover/cleanup/wizard)openclaw update --channel extended-stable --dry-run
openclaw reset重設本機組態/狀態(保留 CLI)openclaw reset --scope config --dry-run
openclaw uninstall移除 Gateway 服務與本機資料openclaw uninstall
openclaw migrate從其他 Agent 系統匯入狀態(Claude、Hermes 等)openclaw migrate --help

診斷與維運

指令說明範例
openclaw doctor組態與本機探索的健康檢查與快速修復openclaw doctor --fix
openclaw health從執行中的 Gateway 取得健康狀態openclaw health --json
openclaw status頻道健康與最近的 Session 對象openclaw status
openclaw logs透過 RPC 追蹤 Gateway 檔案日誌openclaw logs --follow
openclaw triage收集消毒後的診斷並交給本機 coding agent 修復openclaw triage
openclaw security稽核本機組態與狀態的常見安全誤設定openclaw security audit --deep
openclaw audit檢視活動紀錄與確切執行身分openclaw audit --help
openclaw backup建立、驗證、還原備份與 SQLite 快照;排程異地備份openclaw backup create --verify
openclaw storage列出、初始化與測試儲存位置(異地備份目的地)openclaw storage test offsite
openclaw database資料庫相容性、擁有權與 Workboard 引擎搬移openclaw database preflight
openclaw telemetry檢視與管理匿名使用遙測openclaw telemetry --help
openclaw docs搜尋線上官方文件openclaw docs "cloud worker"
openclaw completion產生 shell 自動完成腳本openclaw completion --help

頻道、裝置與使用者

指令說明範例
openclaw channels管理頻道與帳號(add/login/logout/status/logs/remove/dead-letters)openclaw channels status
openclaw pairing核准 DM 配對請求openclaw pairing approve telegram ABC123
openclaw message傳送、讀取與管理訊息openclaw message send --channel telegram --target 123456 --message "部署完成"
openclaw directory查詢聯絡人與群組 ID(self/peers/groups)openclaw directory peers --help
openclaw devices裝置配對與 auth tokenopenclaw devices --help
openclaw qr產生行動裝置配對 QR Code 與設定碼openclaw qr
openclaw nodes管理 Gateway 擁有的節點(配對、狀態、invoke、媒體)openclaw nodes --help
openclaw node執行與管理無頭 node host 服務openclaw node --help
openclaw connect把這台機器作為 node 連到某個 Gatewayopenclaw connect --help
openclaw users管理持久使用者 profile 與 email 別名(list/link-email/merge)openclaw users list

Agent、Session 與記憶

指令說明範例
openclaw agent經由 Gateway 執行一次 Agent 回合(--local 為內嵌模式)openclaw agent --help
openclaw agents管理隔離的 Agent(工作區、auth、路由)openclaw agents --help
openclaw sessionsSession 清單、匯入、匯出軌跡、壓縮、封存openclaw sessions list --all-agents
openclaw transcripts檢視儲存的逐字稿(list/show/path)openclaw transcripts list
openclaw resume在 TUI 中接續最近的 Gateway Sessionopenclaw resume
openclaw tui / chat / terminal終端機 UI(後兩者為 tui --local 別名)openclaw tui
openclaw attach讓 Claude Code 以受限 MCP 工具附掛到 Gateway Sessionopenclaw attach --help
openclaw memory搜尋、檢視、重建索引、forget、resetopenclaw memory search "季度報表"
openclaw worktrees建立、檢視、還原與清理 Managed Worktrees(見 4.12)openclaw worktrees list

模型、技能、插件與工具

指令說明範例
openclaw models模型探索、掃描與設定(list/status/set/fallbacks/aliases/auth/accounts)openclaw models status
openclaw infer / capability透過穩定 CLI 介面執行 Provider 推論(model/image/audio/tts/video/embedding/web)openclaw infer model --help
openclaw skills技能 search/install/update/verify/list/info/check/library/workshopopenclaw skills check
openclaw plugins插件 install/update/enable/disable/doctor/inspect/marketplace/validateopenclaw plugins doctor
openclaw mcp管理 mcp.servers 組態與頻道 bridgeopenclaw mcp --help
openclaw hooks管理內部 Agent hooksopenclaw hooks --help
openclaw browser管理 OpenClaw 專用瀏覽器(Chrome/Chromium)openclaw browser start --headless
openclaw sandbox管理沙箱容器(Docker 隔離)openclaw sandbox --help
openclaw approvals / exec-approvals審批政策與待處理請求(get/set/pending/resolve/allowlist/grants)openclaw approvals pending
openclaw exec-policy檢視或同步要求的 exec 政策與主機審批openclaw exec-policy --help
openclaw file-transfer檢視檔案傳輸的常設核准openclaw file-transfer --help
openclaw secrets密鑰執行期控制(audit/configure/apply/reload/store)openclaw secrets audit
openclaw proxyOpenClaw 除錯代理與流量檢視openclaw proxy --help
openclaw promos探索與領取 ClawHub 上的模型優惠openclaw promos --help

自動化、整合與分散式執行

指令說明範例
openclaw automations / cron管理 Automations(add/list/edit/run/runs/enable/disable/rm)openclaw automations list
openclaw webhooksWebhook 整合(目前為 Gmail Pub/Sub:setup/run)openclaw webhooks gmail setup --help
openclaw acp以 Gateway 為後端的 ACP bridgeopenclaw acp --help
openclaw worker執行受限的 Cloud Worker runtime(見第十二章)openclaw worker --help
openclaw dns廣域探索的 DNS 輔助(Tailscale + CoreDNS)openclaw dns setup --help
openclaw system系統工具(events、heartbeat、presence)openclaw system --help
openclaw googlemeet / teamsmeetings / zoommeetings加入與管理線上會議openclaw googlemeet --help

由官方插件提供的指令

下列指令只在對應插件啟用後出現(不在核心 --help 清單中):openclaw matrix、openclaw voicecall、openclaw wiki、openclaw workboard、openclaw policy、openclaw path、openclaw claws(實驗性)、openclaw vault、openclaw onepassword、openclaw team-reports、openclaw codex 等。

❌ 舊版手冊中已不存在或從未存在的指令(AI 產出時常見):openclaw start/restart/reload(請用 openclaw gateway start|restart)、openclaw config show/config migrate(請用 config get/config file、doctor --fix)、openclaw tasks(9.7 起移除)、openclaw fleet、openclaw skills publish/skills remove(發布用 clawhub skill publish;技能庫移除用 skills library remove)、openclaw channels test、openclaw models test、openclaw secrets set、openclaw proxy set、openclaw logs -f(應為 --follow)、openclaw message send --to(應為 --target)、openclaw health --deep(--deep 屬於 gateway status/security audit)。

診斷分工:doctor、health、plugins doctor

指令檢查對象何時用
openclaw doctor本機探索與組態(含 SQLite/Node 能力、遷移建議);--fix 套用修復,--json 唯讀輸出升級後、組態變更後、啟動失敗時
openclaw health執行中 Gateway 的健康狀態服務已啟動但行為異常
openclaw gateway status --deep服務管理器、監聽埠、額外服務掃描確認服務層面是否正常
openclaw plugins doctor本機插件探索與組態插件載入失敗

v2026.11.1 起,非互動式 doctor 在沒有修復同意的情況下不會下載插件——CI 中執行 openclaw doctor --json 是安全的唯讀檢查。

聊天指令(Chat Commands)

在 WhatsApp/Telegram/Slack/WebChat 等頻道中可直接使用(節錄常用者;完整清單見 /commands 或 Slash commands):

指令說明
/status、/status plugins執行狀態、Gateway 運行時間、插件健康與 Provider 用量
/new [model]、/reset [soft]封存並開新 Session/原地重置(soft 保留逐字稿)
/compact [instructions]壓縮 Session 脈絡
/stop中止目前執行
/think <level|default>設定思考層級(別名 /t)
/model <name> -s|-a|-g切換模型:-s 僅本 Session;-a 更新 Agent 預設、-g 全域(需 owner/admin)
/steer <message>對進行中的執行注入引導(別名 /tell)
/btw <question>不改變 Session 脈絡的側問(別名 /side)
/goal ...管理本 Session 的持久目標
/learn [request]透過 Skill Workshop 從本次對話草擬一個待審技能
/loop [interval] <prompt>(owner)在此對話週期性重複一個提示;/loop status、/loop stop
/approve <id> <decision>回應 exec、插件或 OpenClaw 變更的審批
/usage off|tokens|full|cost每則回覆的用量頁尾
/elevated on|off|ask|full切換提升權限模式(需授權)
/restart、/update(owner)重啟/依設定通道更新 OpenClaw
/activation mention|always群組啟動模式

⚠️ /reasoning、/verbose、/trace 在群組中可能洩漏內部推理或插件診斷,群組環境請保持關閉。/bash 需要 commands.bash: true,生產環境不建議開啟。


3.11 Secret Store 與密鑰治理(v2026.8.1 新增)

2.0 引入 團隊範圍的本地 Secret Store,將密鑰明確分為兩類。這個區分是整套密鑰治理的核心,混淆兩者會直接造成外洩。

兩類密鑰的本質差異

類別用途模型可見性風險特性
Protected(受保護值)注入 Gateway 託管的 HTTPS 請求不進入模型可見文字可保持不出現在明文組態與對話脈絡中
Agent-readable(Agent 可讀環境值)提供給 Gateway 託管的指令使用模型與指令可讀接收它的指令仍可將其印出或傳送出去

⚠️ 這是兩種不同的授權,不是同一機制的兩種強度。將本應為 Protected 的憑證放入 Agent-readable,等同於直接交給模型與其呼叫的任何指令。

保護機制

Protected 值可透過三種方式在不落入明文的前提下抵達目的地:

  1. 遮罩式請求(masked request)——以遮罩提示向使用者索取憑證,值不會出現在聊天中。
  2. Vault 或 1Password 參照——組態中只存放參照,不存放值本身。
  3. 目的地綁定替換(destination-bound substitution)——將值綁定至特定目的地後再替換,避免被導向他處。

實作:寫入 Secret Store、以 SecretRef 引用、綁定目的地

兩類密鑰在儲存層的對應是 kind:Protected = kind: "secret"(寫入後即不可讀回,沒有 reveal RPC)、Agent-readable = kind: "env"(管理者可讀,會以明文加入 Gateway 託管的指令環境)。

# 1. Protected 密鑰:從檔案或 stdin 寫入,避免出現在 shell history;綁定唯一允許替換的 HTTPS 主機
printf '%s' "$PAYMENT_TOKEN" | openclaw secrets store set PAYMENT_API_TOKEN --kind secret --value-file - --allow-host api.payment.example.com

# 2. Agent-readable 值:只放可以承受被讀取的設定
openclaw secrets store set REPORT_OUTPUT_DIR --kind env --value /var/openclaw/reports

# 3. 檢視(secret 類只會列出名稱與中繼資料,不會顯示值)
openclaw secrets store list

# 4. 啟用預設關閉的 secret egress proxy,然後重啟
openclaw config set secrets.egressProxy.enabled true --strict-json
openclaw gateway restart
// openclaw.json:組態中只存「參照」,不存值
{
  models: {
    providers: {
      // store:OpenClaw Secret Store;env/file/exec:外部來源(例如 1Password、Vault 插件的 exec 供應器)
      openai: { apiKey: { source: "store", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  secrets: {
    egressProxy: {
      enabled: true,
      allowedHosts: ["api.openai.com", "api.payment.example.com"],
    },
  },
}

啟用 egress proxy 後,Gateway 託管的子行程拿到的 $PAYMENT_API_TOKEN 只是一個 oc-sent-v2...end 哨兵值;proxy 只會在請求目標完全符合綁定主機時,才把哨兵替換成真實值。送往其他主機的請求會被拒絕,並在錯誤訊息中提示需要執行的 store set ... --allow-host ... 指令。

❌ 舊版範例錯誤:secrets.protected、secrets.agentReadable 這兩個組態鍵並不存在;vault://、op:// 也不是 OpenClaw 的 SecretRef 語法。Vault/1Password 是透過官方插件提供 exec 型 SecretRef,或以 file 型 SecretRef 讀取掛載檔案。

⚠️ 主機名稱比對規則:小寫 ASCII/punycode 精確比對,不支援萬用字元、後綴比對與連接埠。沒有綁定任何主機的 secret,egress proxy 一律不替換。

必須理解的限制(官方明確揭露)

⚠️ Secret Store 並非加密保險庫。官方載明以下邊界,企業在做風險評估時不可忽略:

限制說明
非靜態加密Secret Store 的值未於靜態加密,其機密性完全取決於 OpenClaw 狀態目錄的檔案系統權限
目的地綁定的適用範圍僅適用於 Gateway 託管的 HTTPS 指令,且該子行程需遵循其 proxy 設定
不在保護範圍內的路徑raw socket、容器、遠端節點、Provider 原生 harness、純 HTTP、WebSocket 皆在此路徑之外

換言之:若你的威脅模型包含「取得主機檔案系統存取權的攻擊者」,Secret Store 本身不構成防線,必須另外以作業系統層級的權限控制、磁碟加密與最小權限原則補足。真正的高價值憑證應存放於 Vault/1Password 並以參照方式引用,讓 OpenClaw 僅持有參照而非值。

連帶的編修(redaction)強化

2.0 同時擴大了自動編修的覆蓋範圍:

  • 常見的憑證與簽章參數樣式,會在日誌、診斷、Agent 錯誤訊息與 Control UI 失敗訊息中被編修。
  • 聊天歷史會移除內嵌媒體位元組、本地路徑、私有 shell 列、複製的提示脈絡,以及傳遞失敗的酬載。

仍需明確選擇的遙測項目:額外的功能統計、Android 已安裝應用程式明細、iOS 健康摘要都需要明確選擇啟用(健康資料另有兩道預設關閉的關卡)。更新檢查預設開啟(可停用);約略的 Activity 位置對可路由位址預設啟用,且首次使用時可能下載本地城市資料庫——這兩項預設值在隱私敏感的環境中應主動檢視。

3.12 發布通道與版本選擇

OpenClaw 同時維護四條更新通道,npm dist-tag 是唯一的真實來源:

通道npm dist-tag2026-11-08 指向語意企業建議用途
stablelatest2026.11.1大多數使用者的建議通道;通常先在 beta 驗證後「不改版號」直接升為 latest一般團隊 Gateway
extended-stableextended-stable2026.9.36LTS 等價物:上個月月底的版本 + 關鍵安全/可靠性修補與新模型支援;僅套件、僅前景安裝、永不自動套用(只會在 update.checkOnStart 啟用時提示)受控生產環境、變更窗口嚴格的組織
betabeta(若較舊則退回 latest)2026.11.5-beta.1預覽下一個穩定版;舊 beta 永遠不會取代較新的 stable預備(staging)環境的相容性驗證
devGit main移動中開發中的 head,可能包含未完成功能或破壞性變更不可用於生產 Gateway
openclaw update status                            # 目前通道、版本與可用更新
openclaw update --channel extended-stable --dry-run
openclaw update --channel extended-stable         # 成功後寫入 update.channel
openclaw update --tag 2026.11.1 --dry-run         # 釘選特定版本
// 生產 Gateway:鎖定 LTS 通道、只提示不自動更新
{
  update: { channel: "extended-stable", checkOnStart: true },
}

選型決策

graph TD
    A[新部署或年度規劃] --> B{是否有正式變更管理<br/>與固定維護窗口?}
    B -->|是| C["extended-stable<br/>每月評估一次"]
    B -->|否| D{是否需要最新功能<br/>例如 Cloud Sessions?}
    D -->|是| E["stable(latest)<br/>先在 beta 預備環境驗證"]
    D -->|否| C
    C --> F[以 IaC 釘選確切版本<br/>例如 openclaw@2026.9.36]
    E --> F

⚠️ 注意事項:

  1. extended-stable 通道只支援套件安裝;Git checkout 安裝切到此通道時,OpenClaw 會保持 checkout 不變並要求改用套件安裝。
  2. 對 extended-stable 的更新會先解析 npm selector、驗證確切套件後才安裝;驗證失敗會停止,不會退回 latest/beta/dev。
  3. 容器部署不使用通道切換,而是換映像 tag(ghcr.io/openclaw/openclaw:extended-stable 或確切版本)。
  4. 日期版本號不能單憑大小判斷新舊(例如 2026.9.36 是 LTS 線,比 2026.10.x 舊);以 dist-tag 與發布說明為準。

3.13 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1Node 版本符合node --version>=24.16.0 <25 或 >=26.1.0,建議 24.22.1+/26.12.1+
2組態檔合法openclaw config validate --jsonvalid: true 且 warnings: []
3所有 CLI 指令存在openclaw <cmd> --help 或附錄 F 的 check_cli.py沒有 unknown command/unknown flag
4Docker 部署路徑與暴露面檢視 compose:state 掛載 /home/node/.openclaw、埠帶 127.0.0.1: 前綴、無 redis 服務符合 3.3
5憑證未寫死openclaw secrets audit無明文憑證;SecretRef 皆可解析
6通道與版本釘選openclaw update status --json通道符合企業政策;映像以確切版本或 digest 釘選

第四章:開發實戰教學

4.1 第一個 OpenClaw Agent

本節用最短路徑做出一個「Java 教學助理」,並說明每一步該如何驗證。重點在建立正確的心智模型:行為寫在工作區的 Markdown 檔,連線與政策寫在 openclaw.json,能力來自技能 + 工具政策。

步驟 1:建立工作區

# 預設工作區為 ~/.openclaw/workspace;此處指定專案目錄作為工作區
mkdir -p ~/agents/java-tutor
openclaw onboard --workspace ~/agents/java-tutor

onboarding 會在工作區建立缺少的啟動檔(bootstrap files):

~/agents/java-tutor/
├── AGENTS.md        # 操作規則與優先順序(每個 Session 開始時載入);其中「## Tools」段落只是使用慣例,不控制工具權限
├── SOUL.md          # 人格、語氣與邊界
├── IDENTITY.md      # 名稱、風格、emoji(首次執行儀式中建立)
├── USER.md          # (選用)使用者偏好,獨立 4,000 字元預算
├── BOOTSTRAP.md     # 一次性的首次執行儀式,完成後可刪除
├── MEMORY.md        # (選用)精選長期記憶
├── memory/          # 每日記憶日誌 memory/YYYY-MM-DD.md
└── skills/          # 工作區技能(最高優先序)

❌ 常見錯誤:把系統提示寫成 openclaw.json 裡的 agent.systemPrompt。OpenClaw 沒有這個鍵;Agent 的行為與人格是由 AGENTS.md、SOUL.md 等工作區檔案組成,可在 Control UI 的 Settings → Agents → Files 編輯(單檔上限 2 MiB)。

步驟 2:撰寫行為規則(AGENTS.md)

# 操作規則

- 你是 Java 程式設計教學助理,一律以繁體中文回覆。
- 先解釋概念,再提供可編譯的完整範例(含 import 與 main 方法)。
- 不確定 API 行為時,明說不確定並建議使用者以 `javac`/`java` 實測,不要杜撰。
- 回覆保持簡潔,使用 Markdown。

## Tools

- 需要示範執行結果時,使用沙箱中的 code_execution,不要在主機執行。

步驟 3:連線與模型(openclaw.json)

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-5-5" },
      workspace: "~/agents/java-tutor",
      sandbox: { mode: "non-main" },
    },
  },
  channels: {
    telegram: { botToken: "${TELEGRAM_BOT_TOKEN}", dmPolicy: "pairing" },
  },
  tools: { profile: "coding", fs: { workspaceOnly: true } },
}

步驟 4:建立第一個 Skill

建立 ~/agents/java-tutor/skills/java-tutor/SKILL.md:

---
name: java-tutor
description: 當使用者詢問 Java 語法、標準函式庫或物件導向設計時,提供概念說明與可編譯的完整範例
---

# Java 教學技能

1. 先用三到五句話解釋概念。
2. 提供完整範例:import、JavaDoc 註解、main 方法、以註解標示預期輸出。
3. 指出一個常見錯誤與修正方式。
4. 範例需符合 Java 21 語法;使用 record、switch pattern 等新語法時要標註最低版本。

步驟 5:啟動、配對並測試

openclaw gateway restart                  # 讓服務載入新組態(或 openclaw gateway run 前景執行)
openclaw skills check                     # 確認 java-tutor 已載入且來源為工作區
openclaw pairing approve telegram <配對碼>  # 第一次 DM 會收到配對碼

# 不經過頻道,直接從 CLI 跑一個回合驗證行為
openclaw agent --message "請用 Java Stream API 示範分組計數"

第一個 Agent 的驗證方式

檢查方法預期
組態合法openclaw config validate --jsonvalid: true
技能已載入openclaw skills checkjava-tutor 出現且來源為 <workspace>/skills
行為符合規則以 openclaw agent --message 測試 3 個問題皆為繁體中文、含完整可編譯範例
範例可編譯將回覆中的程式碼存檔後執行 javac Main.java && java Main編譯成功,輸出與註解一致
DM 安全用未配對帳號傳訊收到配對碼,Agent 不處理訊息

4.2 Java 整合 OpenClaw API

Java 後端整合 OpenClaw 有三條官方路徑,依需求選擇:

路徑協定適用情境本手冊
OpenAI 相容 HTTP APIPOST /v1/chat/completions(另有 /v1/responses)後端服務呼叫 Agent、批次作業、內部系統整合(Java 首選)本節、4.10
Gateway WebSocket Protocolreq/res/event frame + connect.challenge 握手 + 裝置配對自建 operator 介面、需要即時事件串流與審批 UI4.11
Tools Invoke HTTP APIPOST 直接呼叫單一工具不需要模型推理、只要執行某個工具官方 Tools invoke

❌ 舊版範例的錯誤:以 Java-WebSocket 送出 {"type":"message.send", ...} 與 heartbeat.pong。Gateway WebSocket 協定沒有這些訊息型別;它要求先完成 connect.challenge → connect(含角色、scope 與裝置證明)→ hello-ok 握手,之後才能以 {"type":"req","method":"chat.send",...} 呼叫方法。Java 沒有官方 WebSocket 參考用戶端,後端整合請優先使用 HTTP API。

步驟 1:在 Gateway 啟用 HTTP 端點

// openclaw.json(預設關閉)
{
  gateway: {
    auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" },
    http: { endpoints: { chatCompletions: { enabled: true } } },
  },
}

⚠️ 安全邊界:此端點的 token/password 等同 operator 完整權限,請求會以一般 Agent 執行,若 Agent 政策允許敏感工具,透過此端點也能使用。只能開放在 loopback、tailnet 或內部 ingress,絕不可暴露到公網;呼叫端只能是受信任的後端服務。

model 欄位在 OpenClaw 代表Agent 目標而非供應商模型:

model 值路由到
openclaw 或 openclaw/default預設 Agent(後者是穩定別名,可安全寫死)
openclaw/<agentId>指定 Agent

Session 行為:預設每次請求都是新 Session;若帶 OpenAI 的 user 欄位,Gateway 會據此衍生固定 session key,讓同一對話共用 Session。

步驟 2:Maven 專案(Spring Boot 4.1.2、Java 21、Jackson 3)

OpenClawClient 本身只使用 JDK java.net.http 與 Jackson;Spring Boot 只在 4.10 的 REST 包裝時需要。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.2</version>
        <relativePath/>
    </parent>

    <groupId>com.tutorial</groupId>
    <artifactId>openclaw-java-integration</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <!-- REST 控制器(4.10);OpenClawClient 本身只依賴 JDK HttpClient 與 Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

步驟 3:OpenClawClient

package com.tutorial.openclaw;

import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.node.ArrayNode;
import tools.jackson.databind.node.ObjectNode;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpTimeoutException;
import java.time.Duration;
import java.util.Objects;

/**
 * OpenClaw Gateway 的 Java 用戶端(OpenAI 相容 HTTP API)。
 *
 * <p>呼叫 Gateway 的 {@code POST /v1/chat/completions}。此端點預設關閉,需在
 * {@code openclaw.json} 設定 {@code gateway.http.endpoints.chatCompletions.enabled: true}。
 * 請求會以一般 Agent 執行(與 {@code openclaw agent} 相同路徑),因此路由、權限與組態
 * 都與 Gateway 一致。</p>
 *
 * <p><b>安全邊界</b>:持有 Gateway token/password 等同於 operator 權限,
 * 本用戶端只應部署在可信任的後端服務中,且 Gateway 端點只開放於 loopback/內網。</p>
 *
 * <pre>{@code
 * OpenClawClient client = OpenClawClient.builder(URI.create("http://127.0.0.1:18789"))
 *         .token(System.getenv("OPENCLAW_GATEWAY_TOKEN"))
 *         .agent("assistant")
 *         .build();
 * String reply = client.sendMessage("ticket-4711", "幫我摘要這張工單");
 * }</pre>
 */
public final class OpenClawClient implements AutoCloseable {

    private static final JsonMapper JSON = JsonMapper.builder().build();

    private final URI gatewayUri;
    private final String token;
    private final String agentTarget;
    private final Duration requestTimeout;
    private final int maxAttempts;
    private final Duration initialBackoff;
    private final HttpClient http;

    private OpenClawClient(Builder b) {
        this.gatewayUri = Objects.requireNonNull(b.gatewayUri, "gatewayUri");
        this.token = Objects.requireNonNull(b.token, "token(OPENCLAW_GATEWAY_TOKEN)不可為空");
        this.agentTarget = b.agentId == null ? "openclaw/default" : "openclaw/" + b.agentId;
        this.requestTimeout = b.requestTimeout;
        this.maxAttempts = b.maxAttempts;
        this.initialBackoff = b.initialBackoff;
        // 必須固定 HTTP/1.1:JDK HttpClient 對 http:// 預設會送出 "Upgrade: h2c" 嘗試升級 HTTP/2,
        // Gateway 會把 Upgrade 標頭當成 WebSocket 升級處理,回 400(GET)或 405(POST)。
        this.http = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_1_1)
                .connectTimeout(b.connectTimeout)
                .build();
    }

    public static Builder builder(URI gatewayUri) {
        return new Builder(gatewayUri);
    }

    /** 無狀態呼叫:每次請求都是新的 Session。 */
    public String sendMessage(String content) {
        return sendMessage(null, content);
    }

    /**
     * 以穩定的對話識別碼呼叫 Agent。
     *
     * <p>OpenAI 的 {@code user} 欄位會被 Gateway 用來衍生固定的 session key,
     * 同一個 {@code conversationId} 的多次呼叫會共用同一個 Agent Session。
     * 請用「對話/工單」層級的識別碼,不要用帳號層級的識別碼。</p>
     *
     * @param conversationId 對話識別碼;{@code null} 表示無狀態
     * @param content        使用者訊息
     * @return Agent 的最終回覆文字
     * @throws OpenClawException 認證失敗、請求被拒或重試後仍失敗
     */
    public String sendMessage(String conversationId, String content) {
        if (content == null || content.isBlank()) {
            throw new IllegalArgumentException("content 不可為空");
        }
        ObjectNode body = JSON.createObjectNode();
        body.put("model", agentTarget);
        ArrayNode messages = body.putArray("messages");
        messages.addObject().put("role", "user").put("content", content);
        if (conversationId != null) {
            body.put("user", conversationId);
        }

        HttpRequest request = HttpRequest.newBuilder(gatewayUri.resolve("/v1/chat/completions"))
                .timeout(requestTimeout)
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(JSON.writeValueAsString(body)))
                .build();

        HttpResponse<String> response = sendWithRetry(request);
        JsonNode json = JSON.readTree(response.body());
        JsonNode text = json.path("choices").path(0).path("message").path("content");
        if (text.isMissingNode() || text.isNull()) {
            throw new OpenClawException("回應中沒有 choices[0].message.content", response.statusCode());
        }
        return text.asString();
    }

    /**
     * 呼叫 {@code GET /readyz}:Gateway 啟動完成、未在 drain、必要資料庫與頻道就緒。
     *
     * <p><b>必須檢查 JSON 本文的 {@code ready: true},不能只看狀態碼</b>:Control UI 對未知路徑
     * 一律回 200,若映像版本沒有這個路由,只看狀態碼的檢查會永遠通過(官方 Kubernetes probe
     * 也是同樣做法)。</p>
     */
    public boolean isReady() {
        HttpRequest request = HttpRequest.newBuilder(gatewayUri.resolve("/readyz"))
                .timeout(Duration.ofSeconds(5))
                .GET()
                .build();
        try {
            HttpResponse<String> res = http.send(request, HttpResponse.BodyHandlers.ofString());
            if (res.statusCode() >= 400) {
                return false;
            }
            return JSON.readTree(res.body()).path("ready").asBoolean(false);
        } catch (RuntimeException e) {
            return false; // 非 JSON 本文(例如 Control UI 的 HTML)
        } catch (IOException e) {
            return false;
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return false;
        }
    }

    public URI getGatewayUri() {
        return gatewayUri;
    }

    private HttpResponse<String> sendWithRetry(HttpRequest request) {
        Duration backoff = initialBackoff;
        OpenClawException last = null;
        for (int attempt = 1; attempt <= maxAttempts; attempt++) {
            try {
                HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
                int status = response.statusCode();
                if (status == 200) {
                    return response;
                }
                // 4xx(429 除外)是呼叫端問題,重試沒有意義:直接失敗
                if (status != 429 && status < 500) {
                    throw new OpenClawException(errorMessage(response), status);
                }
                last = new OpenClawException(errorMessage(response), status);
                // 429 時尊重 Retry-After
                backoff = response.headers().firstValue("Retry-After")
                        .map(OpenClawClient::parseRetryAfter).orElse(backoff);
            } catch (HttpTimeoutException e) {
                last = new OpenClawException("請求逾時(" + requestTimeout + ")", -1, e);
            } catch (IOException e) {
                last = new OpenClawException("無法連線至 Gateway: " + e.getMessage(), -1, e);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new OpenClawException("呼叫被中斷", -1, e);
            }
            if (attempt < maxAttempts) {
                sleep(backoff);
                backoff = backoff.multipliedBy(2);
            }
        }
        throw last;
    }

    private static String errorMessage(HttpResponse<String> response) {
        try {
            JsonNode err = JSON.readTree(response.body()).path("error");
            String msg = err.path("message").asString("");
            if (!msg.isEmpty()) {
                return "Gateway 回應 " + response.statusCode() + ": " + msg;
            }
        } catch (RuntimeException ignored) {
            // 非 JSON 錯誤本文
        }
        return "Gateway 回應 " + response.statusCode();
    }

    private static Duration parseRetryAfter(String value) {
        try {
            return Duration.ofSeconds(Math.min(Long.parseLong(value.trim()), 60));
        } catch (NumberFormatException e) {
            return Duration.ofSeconds(1);
        }
    }

    private static void sleep(Duration d) {
        try {
            Thread.sleep(d.toMillis());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new OpenClawException("重試等待被中斷", -1, e);
        }
    }

    @Override
    public void close() {
        http.close();
    }

    /** 建構器:所有逾時與重試參數都有保守的預設值。 */
    public static final class Builder {
        private final URI gatewayUri;
        private String token;
        private String agentId;
        private Duration connectTimeout = Duration.ofSeconds(5);
        private Duration requestTimeout = Duration.ofMinutes(2);
        private int maxAttempts = 3;
        private Duration initialBackoff = Duration.ofMillis(500);

        private Builder(URI gatewayUri) {
            this.gatewayUri = gatewayUri;
        }

        public Builder token(String token) { this.token = token; return this; }
        public Builder agent(String agentId) { this.agentId = agentId; return this; }
        public Builder connectTimeout(Duration d) { this.connectTimeout = d; return this; }
        public Builder requestTimeout(Duration d) { this.requestTimeout = d; return this; }
        public Builder maxAttempts(int n) { this.maxAttempts = Math.max(1, n); return this; }
        public Builder initialBackoff(Duration d) { this.initialBackoff = d; return this; }

        public OpenClawClient build() {
            return new OpenClawClient(this);
        }
    }
}
package com.tutorial.openclaw;

/** 呼叫 OpenClaw Gateway 失敗;{@link #getStatus()} 為 HTTP 狀態碼,連線層錯誤為 -1。 */
public class OpenClawException extends RuntimeException {

    private final int status;

    public OpenClawException(String message, int status) {
        super(message);
        this.status = status;
    }

    public OpenClawException(String message, int status, Throwable cause) {
        super(message, cause);
        this.status = status;
    }

    public int getStatus() {
        return status;
    }

    /** 401/403:憑證錯誤或權限不足,不應重試。 */
    public boolean isAuthError() {
        return status == 401 || status == 403;
    }
}

設計重點(Review 時逐項確認):

  1. 重試只針對可恢復錯誤:5xx、429、逾時與連線錯誤會指數退避重試;401/403 等 4xx 立即失敗,避免以錯誤憑證反覆嘗試觸發 Gateway 的 auth.rateLimit。
  2. 尊重 Retry-After:Gateway 在認證失敗過多時回 429 並附 Retry-After。
  3. 逾時有上限:連線 5 秒、請求預設 2 分鐘;Agent 回合可能很長,但不能無限等待。
  4. 固定 HTTP/1.1:JDK HttpClient 對 http:// 預設會帶 Upgrade: h2c 嘗試升級 HTTP/2,Gateway 會把 Upgrade 標頭當成 WebSocket 升級,GET 回 400 Invalid Upgrade header、POST 回 405 Invalid HTTP method。這個問題只有對真實 Gateway 測試才會出現(mock 伺服器會忽略該標頭),本範例是在實跑冒煙測試時發現並修正的;測試 neverSendsHttp2UpgradeHeader 用來防止退化。
  5. 401 有兩種來源:Gateway token 錯誤({"error":{"message":"Unauthorized","type":"unauthorized"}}),或 Agent 執行時上游 Provider 沒有可用憑證(例如 No API key found for provider "anthropic")。兩者都不應重試,但告警與排查方向不同,應記錄 error.message。
  6. 對話識別碼用對話層級:user 欄位決定 Session 共用範圍,用帳號 ID 會讓不同對話混在一起。
  7. readiness 用 /readyz,而且要檢查 JSON 本文:/healthz 只代表 HTTP 存活;/readyz 才代表啟動完成、未在 drain、必要資料庫與頻道就緒。Control UI 對未知路徑一律回 200,所以只看狀態碼的檢查在映像缺少該路由時會永遠通過——必須確認本文是 {"ready": true}(官方 Kubernetes probe 也這樣做,見 8.5)。

步驟 4:以模擬 Gateway 進行單元測試

測試不需要真的 Gateway:用 JDK HttpServer 模擬 /v1/chat/completions 與 /readyz,依序回放預設回應並記錄收到的請求。

package com.tutorial.openclaw;

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.ArrayDeque;
import java.util.Deque;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;

/** 以 JDK HttpServer 模擬 Gateway 的 /v1/chat/completions 與 /readyz。 */
final class MockGateway implements AutoCloseable {

    record Reply(int status, String body, Map<String, String> headers, long delayMs) {
        static Reply ok(String text) {
            return new Reply(200, """
                    {"id":"chatcmpl-1","object":"chat.completion","model":"openclaw/assistant",
                     "choices":[{"index":0,"message":{"role":"assistant","content":%s},"finish_reason":"stop"}]}
                    """.formatted(quote(text)), Map.of(), 0);
        }

        static Reply error(int status, String message) {
            return new Reply(status, "{\"error\":{\"message\":" + quote(message) + ",\"type\":\"error\"}}", Map.of(), 0);
        }
    }

    record Received(String method, String path, String authorization, String upgrade, String body) {
    }

    private final HttpServer server;
    private final Deque<Reply> replies = new ArrayDeque<>();
    final List<Received> received = new CopyOnWriteArrayList<>();
    volatile int readyStatus = 200;
    volatile String readyBody = "{\"ready\":true}";

    MockGateway() throws IOException {
        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        server.createContext("/v1/chat/completions", this::chat);
        server.createContext("/readyz", ex -> respond(ex, readyStatus, readyBody, Map.of()));
        server.start();
    }

    URI uri() {
        return URI.create("http://127.0.0.1:" + server.getAddress().getPort());
    }

    MockGateway enqueue(Reply... rs) {
        synchronized (replies) {
            replies.addAll(List.of(rs));
        }
        return this;
    }

    private void chat(HttpExchange ex) throws IOException {
        String body = new String(ex.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
        received.add(new Received(ex.getRequestMethod(), ex.getRequestURI().getPath(),
                ex.getRequestHeaders().getFirst("Authorization"),
                ex.getRequestHeaders().getFirst("Upgrade"), body));
        Reply r;
        synchronized (replies) {
            r = replies.isEmpty() ? Reply.error(500, "no reply queued") : replies.poll();
        }
        if (r.delayMs() > 0) {
            try {
                Thread.sleep(r.delayMs());
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
        respond(ex, r.status(), r.body(), r.headers());
    }

    private static void respond(HttpExchange ex, int status, String body, Map<String, String> headers)
            throws IOException {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        ex.getResponseHeaders().add("Content-Type", "application/json");
        headers.forEach((k, v) -> ex.getResponseHeaders().add(k, v));
        try {
            ex.sendResponseHeaders(status, bytes.length);
            ex.getResponseBody().write(bytes);
        } catch (IOException ignored) {
            // 用戶端已逾時斷線
        } finally {
            ex.close();
        }
    }

    private static String quote(String s) {
        return "\"" + s.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
    }

    @Override
    public void close() {
        server.stop(0);
    }
}
package com.tutorial.openclaw;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;

import java.time.Duration;
import java.util.Map;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

class OpenClawClientTest {

    private MockGateway gw;
    private OpenClawClient client;

    @BeforeEach
    void setUp() throws Exception {
        gw = new MockGateway();
        client = OpenClawClient.builder(gw.uri())
                .token("test-token")
                .agent("assistant")
                .requestTimeout(Duration.ofSeconds(2))
                .initialBackoff(Duration.ofMillis(10))
                .maxAttempts(3)
                .build();
    }

    @AfterEach
    void tearDown() {
        client.close();
        gw.close();
    }

    @Test
    void sendsAgentTargetUserAndBearerToken() {
        gw.enqueue(MockGateway.Reply.ok("報表已產生"));

        String reply = client.sendMessage("ticket-4711", "產生今日報表");

        assertThat(reply).isEqualTo("報表已產生");
        MockGateway.Received req = gw.received.getFirst();
        assertThat(req.path()).isEqualTo("/v1/chat/completions");
        assertThat(req.authorization()).isEqualTo("Bearer test-token");
        JsonNode body = JsonMapper.builder().build().readTree(req.body());
        assertThat(body.path("model").asString()).isEqualTo("openclaw/assistant");
        assertThat(body.path("user").asString()).isEqualTo("ticket-4711");
        assertThat(body.path("messages").path(0).path("content").asString()).isEqualTo("產生今日報表");
    }

    @Test
    void neverSendsHttp2UpgradeHeader() {
        // 真實 Gateway 收到 "Upgrade: h2c" 會回 400/405(2026.11.1 實測)
        gw.enqueue(MockGateway.Reply.ok("ok"));
        client.sendMessage("x");
        assertThat(gw.received.getFirst().upgrade()).isNull();
    }

    @Test
    void statelessCallOmitsUserField() {
        gw.enqueue(MockGateway.Reply.ok("ok"));
        client.sendMessage("hi");
        JsonNode body = JsonMapper.builder().build().readTree(gw.received.getFirst().body());
        assertThat(body.has("user")).isFalse();
    }

    @Test
    void authErrorIsNotRetried() {
        gw.enqueue(MockGateway.Reply.error(401, "unauthorized"), MockGateway.Reply.ok("should not be used"));

        assertThatThrownBy(() -> client.sendMessage("x"))
                .isInstanceOf(OpenClawException.class)
                .satisfies(e -> assertThat(((OpenClawException) e).isAuthError()).isTrue())
                .hasMessageContaining("unauthorized");
        assertThat(gw.received).hasSize(1);
    }

    @Test
    void serverErrorIsRetriedThenSucceeds() {
        gw.enqueue(MockGateway.Reply.error(503, "draining"), MockGateway.Reply.ok("recovered"));

        assertThat(client.sendMessage("x")).isEqualTo("recovered");
        assertThat(gw.received).hasSize(2);
    }

    @Test
    void rateLimitHonoursRetryAfterAndGivesUpAfterMaxAttempts() {
        var limited = new MockGateway.Reply(429, "{\"error\":{\"message\":\"slow down\"}}", Map.of("Retry-After", "0"), 0);
        gw.enqueue(limited, limited, limited);

        assertThatThrownBy(() -> client.sendMessage("x"))
                .isInstanceOf(OpenClawException.class)
                .satisfies(e -> assertThat(((OpenClawException) e).getStatus()).isEqualTo(429));
        assertThat(gw.received).hasSize(3);
    }

    @Test
    void timeoutIsReportedAsOpenClawException() {
        var slow = new MockGateway.Reply(200, "{}", Map.of(), 3_000);
        gw.enqueue(slow, slow, slow);
        OpenClawClient fast = OpenClawClient.builder(gw.uri()).token("t")
                .requestTimeout(Duration.ofMillis(300)).maxAttempts(1).build();

        assertThatThrownBy(() -> fast.sendMessage("x"))
                .isInstanceOf(OpenClawException.class)
                .hasMessageContaining("逾時");
        fast.close();
    }

    @Test
    void readinessFollowsReadyz() {
        assertThat(client.isReady()).isTrue();
        gw.readyStatus = 503;
        assertThat(client.isReady()).isFalse();
    }

    @Test
    void readinessRequiresJsonReadyTrueNotJustStatus200() {
        // 模擬「映像沒有 /readyz 路由,Control UI 回 200 + HTML」的情況
        gw.readyBody = "<!doctype html><title>OpenClaw</title>";
        assertThat(client.isReady()).isFalse();
        gw.readyBody = "{\"ready\":false}";
        assertThat(client.isReady()).isFalse();
    }

    @Test
    void rejectsBlankInputBeforeCallingGateway() {
        assertThatThrownBy(() -> client.sendMessage("  ")).isInstanceOf(IllegalArgumentException.class);
        assertThat(gw.received).isEmpty();
    }
}
mvn -B test
# [INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0 -- in com.tutorial.openclaw.OpenClawClientTest
# [INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.tutorial.openclaw.spring.OpenClawControllerTest
# [INFO] BUILD SUCCESS

驗證測試本身有效(突變測試):暫時把 if (status != 429 && status < 500) 改成 if (false)(也就是讓 401 也重試),authErrorIsNotRetried 會失敗——證明這組測試真的守住了「認證錯誤不重試」這條規則。審查 AI 產生的測試時,也應以同樣方式抽查。

步驟 5:對真實 Gateway 做冒煙測試

mock 測試證明「邏輯正確」,但無法證明「與真實 Gateway 相容」——上面的 HTTP/1.1 問題就是例子。以環境變數控制、預設略過的冒煙測試:

package com.tutorial.openclaw;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;

import java.net.URI;
import java.time.Duration;

import static org.assertj.core.api.Assertions.assertThat;

/**
 * 對「真實」Gateway 的冒煙測試:只有在設定 OPENCLAW_GATEWAY_URL 與 OPENCLAW_GATEWAY_TOKEN 時才執行
 * (CI 的預備環境 job 設定這兩個變數;開發機與單元測試 job 會自動略過)。
 */
@Tag("live")
@EnabledIfEnvironmentVariable(named = "OPENCLAW_GATEWAY_URL", matches = "https?://.+")
@EnabledIfEnvironmentVariable(named = "OPENCLAW_GATEWAY_TOKEN", matches = ".+")
class LiveGatewaySmokeTest {

    private OpenClawClient client() {
        return OpenClawClient.builder(URI.create(System.getenv("OPENCLAW_GATEWAY_URL")))
                .token(System.getenv("OPENCLAW_GATEWAY_TOKEN"))
                .requestTimeout(Duration.ofMinutes(2))
                .build();
    }

    @Test
    void gatewayIsReady() {
        try (OpenClawClient c = client()) {
            assertThat(c.isReady()).as("/readyz 應回 ready: true").isTrue();
        }
    }

    @Test
    void agentAnswersADeterministicPrompt() {
        try (OpenClawClient c = client()) {
            String reply = c.sendMessage("smoke-" + System.currentTimeMillis(), "只回覆 OK 兩個字,不要加其他文字");
            assertThat(reply).containsIgnoringCase("ok");
        }
    }
}
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 OPENCLAW_GATEWAY_TOKEN=... mvn -B test -Dtest=LiveGatewaySmokeTest

也可以直接用 curl 確認端點:

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"openclaw/default","messages":[{"role":"user","content":"回覆 OK 兩個字"}]}'

4.3 自訂 Skill 開發

Skill 完整結構

技能資料夾遵循 AgentSkills 規範:SKILL.md 是唯一必要檔案,其他支援檔依用途放在慣例目錄,並在 SKILL.md 中以 {baseDir} 引用(OpenClaw 會替換成技能資料夾的實際路徑):

skills/
└── enterprise-reporter/
    ├── SKILL.md                 # 技能說明(必要)
    ├── scripts/
    │   └── fetch_metrics.sh     # Agent 透過 exec 執行的輔助腳本
    ├── references/
    │   └── report-style.md      # 需要時才讀取的長篇參考資料(不佔用常駐提示)
    └── assets/
        ├── daily_report.md      # 報表模板
        └── weekly_summary.md

為什麼要分 references/assets:SKILL.md 的內容會進入模型提示;把長篇規範放在 references/,讓模型在需要時才讀取,可以控制 token 成本(見 tools/skills 文件的 Token impact)。

SKILL.md 完整範例

---
name: enterprise-reporter
description: 產生企業日報、週報、月報。當使用者要求「報表」「日報」「週報」「月報」或彙整營運指標時使用
metadata:
  openclaw:
    requires:
      bins: ["curl", "jq"]
      env: ["METRICS_API_TOKEN"]
    primaryEnv: METRICS_API_TOKEN
    os: ["linux", "darwin"]
---

# 企業報表技能

## 報表類型

| 類型 | 資料範圍 | 模板 |
| --- | --- | --- |
| 日報 | 前一個工作日 00:00–24:00 | `{baseDir}/assets/daily_report.md` |
| 週報 | 上週一到週日 | `{baseDir}/assets/weekly_summary.md` |
| 月報 | 上個自然月 | 依週報模板,加上月度趨勢 |

## 步驟

1. 確認報表類型與期間;期間不明確時先反問,不要假設。
2. 執行 `{baseDir}/scripts/fetch_metrics.sh <起日> <迄日>` 取得指標 JSON。
3. 依對應模板填寫;數字一律取自腳本輸出,**不可推估或捏造**。
4. 數據缺漏時,在報表開頭標示「資料不完整」並列出缺少的項目。
5. 撰寫風格依 `{baseDir}/references/report-style.md`。

## 禁止事項

- 不在報表中顯示 API Token、內部主機名稱或個人聯絡資訊。
- 不自行寄送報表;寄送須由使用者明確要求,並使用 message 工具。
#!/usr/bin/env bash
# scripts/fetch_metrics.sh — 以唯讀 API 取得指標;Token 由環境變數注入
set -euo pipefail
from="${1:?usage: fetch_metrics.sh <from> <to>}"; to="${2:?usage: fetch_metrics.sh <from> <to>}"
curl -fsS --max-time 20 \
  -H "Authorization: Bearer ${METRICS_API_TOKEN}" \
  "https://metrics.internal.example.com/api/v1/summary?from=${from}&to=${to}" | jq '{orders, revenue, incidents, sla}'

金鑰怎麼給腳本:在 skills.entries.enterprise-reporter.apiKey 設定 SecretRef(見 1.5);若啟用 secret egress proxy(3.11),腳本拿到的是只對 metrics.internal.example.com 有效的哨兵值,外洩到其他主機也無法使用。

驗證技能(Review Checklist)

檢查指令/方法預期
載入閘門未設定 METRICS_API_TOKEN 時執行 openclaw skills check顯示 enterprise-reporter 因缺少 env 未通過閘門
來源與優先序openclaw skills info enterprise-reporter來源為工作區 skills/
腳本可獨立執行bash scripts/fetch_metrics.sh 2026-11-01 2026-11-07輸出 JSON,且不印出 Token
沒有杜撰欄位檢視 frontmatter只有 name、description、metadata 等規範鍵
防捏造規則讓腳本回傳空資料再請 Agent 產報表報表標示「資料不完整」而非自行補數字

Skill 生命週期與 Skill Workshop(v2026.8.1)

2.0 將原本零散的技能操作,連成一條完整且可稽核的路徑:

graph LR
    A[建立技能<br/>引導式流程] --> B[驗證<br/>openclaw skills check]
    B --> C[安裝/發現<br/>ClawHub 或本地]
    C --> D[在對話中使用<br/>$skill-name]
    D --> E[Skill Workshop<br/>審閱提案]
    E -->|套用| F[已套用修訂版<br/>依技能分組的歷史]
    E -->|拒絕| G[退回]
    E -->|隔離| H[Quarantine]
建立與驗證

建立技能現在是一條引導式路徑:從選擇調用方式開始,經過加入支援檔案、儲存,到驗證結果。檢查器理解調用中繼資料,能在寫入任何東西之前就抓出「描述過長」這類問題。

技能載入的錯誤處理也更精細:格式錯誤的中繼資料、無法讀取的檔案、過大的指令、被遮蔽的副本,都會歸咎到造成問題的那個技能,其餘有效技能照常載入,不會因一個壞技能而讓整個目錄不可用。

持久性 Gateway Session 中的熱更新:對正規技能與 managed-worktree 技能的編輯,會在下一個回合生效;必要的技能指令會被完整讀取。但進行中的對話會維持它載入時的版本,直到下一個回合為止。

在對話中調用技能
方式說明
聊天中的技能選擇器將參照加入草稿而不送出
$skill-name直接指名,單次最多 8 個,含被隱藏於模型自動選用之外的技能
Code Mode可在既有沙箱與允許清單範圍內列出並讀取符合條件的技能

⚠️ 大型技能目錄會被壓縮:模型可見的目錄在數量龐大時可能被壓縮,因此 openclaw skills check 才是完整清單的權威來源。做技能盤點與稽核時,不要以模型看到的清單為準。

Skill Workshop:提案審閱

Skill Workshop 將提案、檢查、決策與已套用歷史整合為單一工作流。你可以檢視提案的指令與支援檔案、查看插件提供的掃描器/基準測試/評分器結果、修訂提案,然後套用、拒絕或隔離它。

治理上的關鍵保證:

保證說明
提案綁定確切修訂版每個決策都綁定你所審閱的那個確切修訂版;後續修訂會重新回到審閱流程
注入攻擊阻擋關鍵等級的 prompt-injection 發現會直接阻擋套用
中斷可復原中斷的套用可以復原,且不會覆寫已在他處變更的目標
遠端 Gateway 為權威明確選定的遠端 Gateway 是該變更的權威來源
掃描不改動線上技能過往工作掃描只產生待審提案,不會直接編輯線上技能
自我學習(Self-learning)

OpenClaw 可將實質性的工作與持續性的糾正,轉化為可重用的技能。v2026.11.1 的背景學習模式(skills.workshop.autonomous.mode)只有兩種:

模式行為
off停用背景學習;仍可用 /learn 主動起草一個待審技能
auto(預設)大量工作後自動儲存或更新 Workshop 擁有的技能,並封存 30 天未使用的技能;每項變更都有紀錄且可用 /learn undo <id> 復原

⚠️ 與 2.0 的差異:2.0 時期的 propose(排入審閱佇列)模式已不存在,config validate 只接受 off/auto。有治理要求的企業應在部署基準中明確設定 off,以 /learn 起草後經人工審查再發布,並用 openclaw skills workshop changes 檢視變更紀錄。自 v2026.9.3 起,Workshop 技能改為每個 Agent 一份可寫入的集合(<state-dir>/agents/<agentId>/agent/workshop-skills),且退休了 skills.workshop.allowSymlinkTargetWrites。

所有權界線是這套機制最重要的保護:

你自己撰寫的技能,以及所有權在他處的共享技能,仍然屬於原擁有者。自動學習可以對它們提出改善建議,但不能自行改寫或移除。明確的 /learn 或過往工作掃描,同樣只會產生待審提案。

在支援的 Agent runtime 上,選用的背景審查會獨立執行,不會打斷對話或發文至聊天中。當學習模式與排程工作設定都允許時,一個可見的每週工作會審查技能集合、記錄使用情況與結果、保留特化技能,並建立可復原的備份(還原備份始終是明確的選擇,不會自動發生)。

4.4 自訂 Tool 開發

自訂工具的三條官方路徑

OpenClaw 沒有「在 openclaw.json 宣告一個 HTTP endpoint 就變成工具」的機制。要給 Agent 新工具,有三條官方路徑:

路徑適用情境優點注意
技能 + 腳本(4.3)包裝既有 CLI 或 curl 呼叫最簡單,不需寫程式依賴 exec 工具與主機環境;需沙箱與 exec 政策約束
MCP Server既有系統已有或易於提供 MCP 介面(任何語言,包括 Java)語言中立、可跨 Agent 平台重用透過 bundle-mcp 暴露;沙箱 Session 需另外放行
Native Tool Plugin(defineToolPlugin)需要型別化參數、結構化輸出、與 OpenClaw 深度整合參數與輸出 schema 驗證、可被 Code Mode/Tool Search 使用TypeScript;需處理插件發布與供應鏈審查

❌ 舊版範例的錯誤:"tools": [{ "name": ..., "endpoint": "http://localhost:8090/tools/generate_report", ... }]。tools 是工具政策物件(profile/allow/deny…),不是工具定義陣列;config validate 會回報 tools: Invalid input: expected object, received array。

路徑一:接入 MCP Server(Java 團隊的首選)

// openclaw.json:以 streamable-http 連接內部 ERP 的唯讀 MCP Server
{
  mcp: {
    servers: {
      "erp-readonly": {
        url: "https://mcp.erp.internal.example.com/mcp",
        transport: "streamable-http",
        enabled: true,
        connectionTimeoutMs: 5000,
        requestTimeoutMs: 20000,
        // 只暴露必要的工具;以白名單而非黑名單管理
        toolFilter: { include: ["search_*", "get_*"] },
      },
    },
  },
}

⚠️ 沙箱 Session 的額外閘門:agents.defaults.sandbox.mode 為 "all" 或 "non-main" 時,MCP 工具還必須出現在 tools.sandbox.tools 的允許清單中(bundle-mcp、group:plugins,或精確的 erp-readonly__* 這類 server glob),否則沙箱內看不到這些工具。server glob 會使用「provider-safe」前綴:非 [A-Za-z0-9_-] 的字元會被轉成 -。

openclaw mcp --help            # 管理 mcp.servers 與頻道 bridge
openclaw config validate --json

路徑二:Native Tool Plugin(defineToolPlugin)

以下範例是一個唯讀的工單查詢工具,已在 OpenClaw 2026.11.1 實際走完 plugins init → build → validate → test → install:

openclaw plugins init ticket-lookup --name "Ticket Lookup"
cd ticket-lookup
npm install
npm run plugin:build       # tsc + openclaw plugins build(產生 openclaw.plugin.json)
npm run plugin:validate    # 輸出:Plugin ticket-lookup is valid.
npm test                   # vitest

src/index.ts:

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

/**
 * 唯讀查詢內部工單系統。
 * - API 位址與金鑰來自插件組態(plugins.entries.ticket-lookup.config),金鑰請用 SecretRef。
 * - 只提供查詢,不提供修改:寫入動作應另做工具並設為 optional(需明確 allowlist)。
 */
export default defineToolPlugin({
  id: "ticket-lookup",
  name: "Ticket Lookup",
  description: "Read-only lookup of internal service-desk tickets.",
  configSchema: Type.Object({
    baseUrl: Type.String({ description: "Service desk API base URL." }),
    apiToken: Type.Optional(Type.String({ description: "Bearer token for the service desk API." })),
  }),
  tools: (tool) => [
    tool({
      name: "ticket_lookup",
      label: "Ticket Lookup",
      description: "依工單編號(例如 OPS-4711)查詢狀態、負責人與最後更新時間。唯讀。",
      workspaceAccess: false,
      parameters: Type.Object({
        ticketId: Type.String({ pattern: "^[A-Z]{2,5}-[0-9]{1,8}$", description: "工單編號,例如 OPS-4711" }),
      }),
      outputSchema: Type.Object(
        {
          ticketId: Type.String(),
          status: Type.String(),
          assignee: Type.String(),
          updatedAt: Type.String(),
        },
        { additionalProperties: false },
      ),
      async execute({ ticketId }, config, context) {
        context.signal?.throwIfAborted();
        const res = await fetch(`${config.baseUrl}/api/tickets/${encodeURIComponent(ticketId)}`, {
          headers: config.apiToken ? { Authorization: `Bearer ${config.apiToken}` } : {},
          signal: context.signal ?? AbortSignal.timeout(10_000),
        });
        if (!res.ok) {
          throw new Error(`service desk returned HTTP ${res.status} for ${ticketId}`);
        }
        const t = (await res.json()) as { status: string; assignee: string; updatedAt: string };
        return { ticketId, status: t.status, assignee: t.assignee, updatedAt: t.updatedAt };
      },
    }),
  ],
});

src/index.test.ts:以假的 plugin api 呼叫 register(),取得真正註冊的工具並執行,驗證 URL、Bearer token 與錯誤處理:

import { afterEach, describe, expect, it, vi } from "vitest";
import entry from "./index.js";
import { getToolPluginMetadata } from "openclaw/plugin-sdk/tool-plugin";

type RegisteredTool = {
  name: string;
  execute: (id: string, params: unknown, signal?: AbortSignal) => Promise<{ details?: unknown }>;
};

/** 以假的 plugin api 執行 register(),取得實際註冊的工具。 */
function loadTool(pluginConfig: Record<string, unknown>): RegisteredTool {
  const registered: RegisteredTool[] = [];
  const api = { pluginConfig, registerTool: (t: RegisteredTool) => registered.push(t) };
  (entry as unknown as { register: (a: unknown) => void }).register(api);
  expect(registered).toHaveLength(1);
  return registered[0]!;
}

describe("ticket-lookup", () => {
  afterEach(() => vi.unstubAllGlobals());

  it("declares exactly one read-only tool with a strict output schema", () => {
    const meta = getToolPluginMetadata(entry);
    expect(meta?.tools.map((t) => t.name)).toEqual(["ticket_lookup"]);
    const tool = meta!.tools[0]!;
    expect(tool.workspaceAccess).toBe(false);
    expect(tool.outputSchema).toMatchObject({ additionalProperties: false });
    expect(JSON.stringify(tool.parameters)).toContain("^[A-Z]{2,5}-[0-9]{1,8}$");
  });

  it("calls the service desk API with the bearer token and returns structured details", async () => {
    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
      new Response(JSON.stringify({ status: "In Progress", assignee: "alice", updatedAt: "2026-11-08T09:00:00Z" }), { status: 200 }),
    );
    vi.stubGlobal("fetch", fetchMock);
    const tool = loadTool({ baseUrl: "https://sd.example.com", apiToken: "t0k" });

    const result = await tool.execute("call-1", { ticketId: "OPS-4711" });

    expect(fetchMock).toHaveBeenCalledOnce();
    const [url, init] = fetchMock.mock.calls[0]!;
    expect(url).toBe("https://sd.example.com/api/tickets/OPS-4711");
    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer t0k");
    expect(result.details).toEqual({ ticketId: "OPS-4711", status: "In Progress", assignee: "alice", updatedAt: "2026-11-08T09:00:00Z" });
  });

  it("surfaces upstream HTTP errors instead of inventing data", async () => {
    vi.stubGlobal("fetch", vi.fn(async () => new Response("nope", { status: 404 })));
    const tool = loadTool({ baseUrl: "https://sd.example.com" });
    await expect(tool.execute("call-2", { ticketId: "OPS-1" })).rejects.toThrow("HTTP 404");
  });
});
 ✓ src/index.test.ts (3 tests)
 Test Files  1 passed (1)
      Tests  3 passed (3)

openclaw plugins build 產生的 manifest(contracts.tools 讓 OpenClaw 不必載入插件程式碼就能知道工具歸屬):

{
  "id": "ticket-lookup",
  "name": "Ticket Lookup",
  "description": "Read-only lookup of internal service-desk tickets.",
  "version": "0.1.0",
  "configSchema": {
    "type": "object",
    "required": [
      "baseUrl"
    ],
    "properties": {
      "baseUrl": {
        "type": "string",
        "description": "Service desk API base URL."
      },
      "apiToken": {
        "type": "string",
        "description": "Bearer token for the service desk API."
      }
    }
  },
  "activation": {
    "onStartup": true
  },
  "contracts": {
    "tools": [
      "ticket_lookup"
    ]
  }
}

安裝與啟用(兩道供應鏈關卡)

# 本地或非 ClawHub 來源:必須在審查後明確 --force;宣告的能力需明確同意
openclaw plugins install ./ticket-lookup --force --accept-capabilities
openclaw plugins list
openclaw plugins inspect ticket-lookup --json

實測時,未加 --force 會顯示「This source is outside ClawHub review and trust metadata」並取消安裝;未加 --accept-capabilities 則顯示「requires capability consent. The plugin was not installed」。這兩道關卡是刻意的設計,CI 腳本不應無條件加上這兩個旗標,而應在審查後才加入。

// openclaw.json:允許並設定插件;工具名稱加入 alsoAllow(受限 profile 時)
{
  plugins: {
    allow: ["ticket-lookup"],
    entries: {
      "ticket-lookup": {
        enabled: true,
        config: { baseUrl: "https://servicedesk.internal.example.com", apiToken: "${TICKET_API_TOKEN}" },
      },
    },
  },
  tools: { alsoAllow: ["ticket_lookup"] },
}

審查 AI 產出的工具(Review Checklist)

檢查方法預期
工具定義能被 OpenClaw 接受npm run plugin:validatePlugin <id> is valid.
參數有嚴格 schema檢視 parameters有 pattern/enum/長度限制,而非只有 Type.String()
輸出有結構化 schema檢視 outputSchemaadditionalProperties: false
錯誤不被吞掉或捏造測試上游 4xx/5xx拋出錯誤或回傳明確失敗,不回假資料
唯讀與寫入分離檢視工具清單寫入類工具設 optional: true,需明確 allowlist
憑證來源檢視 config 與程式碼金鑰來自插件組態/SecretRef,未寫死
安裝後狀態openclaw plugins list、config validate --jsonenabled,且 warnings: []

⚠️ Code Mode 破壞性變更(v2026.8.1)

這是 2.0 中對開發者影響最直接的破壞性變更,升級前必須確認你的 Code Mode 程式碼已完成遷移。

Code Mode 現在將授權的工具視為一般的非同步函式,讓 Agent 能在單一程式中組合來自對話、檔案與 Session 的可信結果,或並行執行彼此獨立的呼叫。官方明確聲明:這是最終介面,而非疊加在舊介面旁的另一層。

因此以下四項舊介面已經移除:

已移除項目說明
tools 物件舊的工具集合存取物件
ALL_TOOLS全部工具的匯出常數
exact-ID 呼叫以確切工具 ID 進行呼叫的方式
raw call envelope原始呼叫封包格式
Code Mode 的實際寫法(guest JavaScript)

Code Mode 讓模型撰寫一段 guest JavaScript 在受限執行器中執行(不是你的 Java/TypeScript 服務程式碼)。每個有效的非 MCP 工具都會以工具本身的名稱安裝成 async 全域函式;不在快速索引中的工具用 catalog.search(...) 找到後直接呼叫:

// ❌ 舊寫法(v2026.8.1 起移除):tools.call({ id: 'web.fetch', ... })、ALL_TOOLS
// ✅ 新寫法:工具即 async function,彼此獨立的呼叫可並行
const [page, notes] = await Promise.all([
  web_fetch({ url: "https://example.com/report" }),
  memory_search({ query: "季度營收" }),
]);

// 快速索引沒列出的工具:以 catalog.search 取得可呼叫的函式
const [shipmentTool] = await catalog.search("list shipments");
const shipments = await shipmentTool({});

// 跨 cell/跨回覆保存小型值(v2026.10.1 起)
await store("unpaidCount", shipments.filter((s) => !s.paid).length);
return { pageLength: page.length, notes, unpaid: await load("unpaidCount") };

審查 Code Mode 程式時的三個重點:

  1. 輸出形狀未知(-> ?)時不要猜欄位:先原樣回傳或 await results.save(value) 取得預覽,下一個 exec 再處理。
  2. 每個 exec 都是全新的 JavaScript context:變數不會跨 cell 保留,需要保留的小型值用 store/load。
  3. 沒有檔案系統、模組或網路存取:所有外部動作都必須經過授權的工具呼叫,因此工具政策(tools.*)仍是安全邊界。
// 相關組態(openclaw.json)
{
  tools: {
    codeMode: { enabled: true, timeoutMs: 120000, maxOutputBytes: 200000 },
  },
}

Tool Search(v2026.9.7 改為三工具結構)

當可用工具很多時,OpenClaw embedded 與 Copilot runs 在 tools.toolSearch 未設定時會自動使用結構化 Tool Search:模型收到一份依脈絡窗大小縮放的工具目錄,加上 tool_search、tool_describe、dispatch_action 三個控制工具,延後載入完整 schema 以節省 token。

變更說明
移除 tool_search_code舊的 JavaScript 工具已移除;需要 JavaScript 編排請改用 Code Mode
自動遷移一般更新會遷移退休設定;手動升級後須先執行 openclaw doctor --fix,否則舊設定會阻止啟動
停用方式tools.toolSearch: false 恢復直接提供 schema;已停用者升級後維持停用

限制:Tool Search 仍標示為 experimental;政策隱藏的工具不會出現在搜尋結果中,沒有合適工具時可能回傳空結果。

4.5 工作流程編排

多步驟工作流程設計

flowchart TD
    START[開始:使用者請求「產生月報」] --> FETCH[Step 1: 擷取資料]
    FETCH --> ANALYZE[Step 2: 分析資料]
    ANALYZE --> GENERATE[Step 3: 生成報表]
    GENERATE --> REVIEW{Step 4: 需要審核?}
    REVIEW -->|是| NOTIFY_REVIEWER[通知審核者]
    NOTIFY_REVIEWER --> WAIT[等待審核]
    WAIT --> APPROVED{審核通過?}
    APPROVED -->|是| DISTRIBUTE[Step 5: 分發報表]
    APPROVED -->|否| REVISE[修訂報表]
    REVISE --> REVIEW
    REVIEW -->|否| DISTRIBUTE
    DISTRIBUTE --> END[完成:通知使用者]

先確認是否需要自建編排器:OpenClaw 已內建多種編排方式——Agent 自行拆解工作並以 subagents 委派、Lobster 管線(取代已移除的 TaskFlow)、Automations 的條件檢查與排程,以及 Code Mode 在單一程式中組合工具呼叫(4.4)。只有在流程必須由企業既有系統掌控(例如需要 BPM 稽核軌跡、跨系統交易補償)時,才需要像下面這樣以 Java 自建外部編排器,並透過 4.2 的 HTTP API 逐步呼叫 Agent。

Java 工作流程引擎(外部編排器)

package com.tutorial.openclaw.workflow;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.*;
import java.util.concurrent.CompletableFuture;
import java.util.function.Function;

/**
 * OpenClaw 工作流程引擎。
 *
 * <p>提供多步驟工作流程的編排與執行能力,
 * 支援條件分支、平行執行、錯誤處理等特性。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class WorkflowEngine {

    private static final Logger logger = LogManager.getLogger(WorkflowEngine.class);

    /**
     * 工作流程步驟定義。
     */
    public record Step(
            String name,
            Function<Map<String, Object>, Map<String, Object>> action,
            String onSuccess,
            String onFailure
    ) {}

    /** 步驟映射表 */
    private final Map<String, Step> steps = new LinkedHashMap<>();

    /** 起始步驟名稱 */
    private String startStep;

    /**
     * 新增工作流程步驟。
     *
     * @param step 步驟定義
     * @return 此引擎實體(支援鏈式呼叫)
     */
    public WorkflowEngine addStep(Step step) {
        steps.put(step.name(), step);
        if (startStep == null) {
            startStep = step.name();
        }
        return this;
    }

    /**
     * 執行工作流程。
     *
     * @param initialContext 初始上下文
     * @return 工作流程執行結果
     */
    public Map<String, Object> execute(Map<String, Object> initialContext) {
        Map<String, Object> context = new HashMap<>(initialContext);
        String currentStep = startStep;
        List<String> executionPath = new ArrayList<>();

        logger.info("開始執行工作流程,起始步驟: {}", currentStep);

        while (currentStep != null) {
            Step step = steps.get(currentStep);
            if (step == null) {
                logger.error("找不到步驟: {}", currentStep);
                break;
            }

            executionPath.add(currentStep);
            logger.info("執行步驟: {}", currentStep);

            try {
                Map<String, Object> result = step.action().apply(context);
                context.putAll(result);
                currentStep = step.onSuccess();
                logger.info("步驟 {} 成功完成", step.name());
            } catch (Exception e) {
                logger.error("步驟 {} 執行失敗: {}", step.name(), e.getMessage());
                context.put("error", e.getMessage());
                currentStep = step.onFailure();
            }
        }

        context.put("_executionPath", executionPath);
        logger.info("工作流程完成,路徑: {}", executionPath);
        return context;
    }

    /**
     * 工作流程建構範例。
     *
     * @return 建構好的報表工作流程
     */
    public static WorkflowEngine createReportWorkflow() {
        WorkflowEngine engine = new WorkflowEngine();

        engine.addStep(new Step(
                "fetch_data",
                ctx -> {
                    // 模擬資料擷取
                    ctx.put("rawData", List.of(95.2, 97.1, 93.8, 98.5, 96.0));
                    return ctx;
                },
                "analyze_data",
                "handle_error"
        ));

        engine.addStep(new Step(
                "analyze_data",
                ctx -> {
                    @SuppressWarnings("unchecked")
                    List<Double> data = (List<Double>) ctx.get("rawData");
                    double avg = data.stream()
                            .mapToDouble(Double::doubleValue)
                            .average()
                            .orElse(0.0);
                    ctx.put("averageScore", avg);
                    ctx.put("trend", avg > 95 ? "positive" : "negative");
                    return ctx;
                },
                "generate_report",
                "handle_error"
        ));

        engine.addStep(new Step(
                "generate_report",
                ctx -> {
                    String report = String.format(
                            "# 分析報表\n\n平均分數: %.2f\n趨勢: %s",
                            ctx.get("averageScore"),
                            ctx.get("trend")
                    );
                    ctx.put("report", report);
                    return ctx;
                },
                "distribute",
                "handle_error"
        ));

        engine.addStep(new Step(
                "distribute",
                ctx -> {
                    logger.info("分發報表至指定頻道");
                    ctx.put("distributed", true);
                    return ctx;
                },
                null,  // 工作流程結束
                "handle_error"
        ));

        engine.addStep(new Step(
                "handle_error",
                ctx -> {
                    logger.error("工作流程發生錯誤: {}", ctx.get("error"));
                    ctx.put("status", "failed");
                    return ctx;
                },
                null,
                null
        ));

        return engine;
    }
}

4.6 記憶體與上下文管理

Built-in Memory 取代 QMD(v2026.8.1 遷移)

2.0 起,Built-in Memory 擁有核心的搜尋與回想路徑。原本使用 QMD 的安裝需執行遷移:

# 移除已退休的 QMD 設定並重建索引
openclaw doctor --fix

doctor --fix 在此遷移中會:移除已退休的 QMD 設定、延續你明確啟用的額外路徑與 Session 索引、保留 Agent 資料庫中已相容的資料列,並從正規的 Markdown 重建索引。

⚠️ 遷移會退休三項 QMD 專屬能力:由於資料被帶入不同的核心,QMD 專屬的 reranking、query expansion、跨 Agent 逐字稿搜尋將不再提供。格式錯誤的結構、不相容的向量維度,以及沒有安全歸屬的資料會被停下待修復,不會靜默丟棄。若你的工作流程依賴上述三項能力,升級前須先規劃替代方案。

各記憶元件在 2.0 後的分工:

元件角色
Built-in Memory核心搜尋與回想路徑
LanceDB向量儲存外掛
Memory Wiki人工維護的筆記(匯入時會被保留)
外部 embedding 服務選用的向量化來源
MEMORY.md可整併的觀察結果
USER.md持久性指令

跨對話回想與其邊界

在符合條件的個人安裝上,Agent 預設可從同一個 Agent 的其他私人對話中回想相關脈絡,包含「重置 Session 前那一刻重要的內容」。

回想的邊界(不可誤解為全域搜尋):回想僅限於該 Agent 的私人對話。以下一律排除在外:

  • 群組、頻道、共享別名
  • 其他 Agent 的對話
  • 已刪除的歷史
  • 被政策封鎖的來源

此外,明確的 direct-message 隔離設定永遠優先(會覆蓋回想行為)。

搜尋能力與 Session 生命週期變更

  • 內建搜尋現在理解檔名、完整與部分的 Unicode 路徑,以及設定的額外路徑;會擴展過於嚴格而結果稀少的比對;在選用的 embedding provider 無法啟動時,仍保留關鍵字結果。搜尋始終限縮在設定的根目錄與 Agent 邊界內,而必要的 embedding provider 則 fail closed。
  • Session 預設行為變更:未設定重置政策的 Session 會跨日保持開啟(2.0 之前會自動重置)。持久性的重置或壓縮標記會說明可見的歷史變化。這項預設變更會影響長期執行的 Agent 的脈絡成本,升級後應重新檢視。
  • 對話分支與回溯:Web、macOS、iOS、Android 上以 SQLite 為後端的聊天,可回溯至某則使用者訊息、分叉對話,並在保留的分支之間切換。

⚠️ 回溯只改變逐字稿分支,不會回復副作用。它不會復原檔案、已送出的訊息,或其他工具產生的外部影響。把它理解為「對話歷史的版本控制」,而非「操作的復原鍵」。

記憶的來源標記與清除

自動記憶維持有界且經來源把關(provenance-gated):來自網路或受限 Session 的內容會保留「未信任來源」標記,不會進入自動脈絡,但明確的搜尋仍可將其帶出。

此保護僅適用於新追蹤的素材;較舊、未被追蹤的檔案維持其既有分類。這代表升級後既有的記憶並不會自動獲得來源標記保護。

清除衍生記憶:

# 先預覽:可依 session、hook 來源或參與者篩選
openclaw memory forget --session <session-id> --dry-run

# 確認後執行
openclaw memory forget --session <session-id>

⚠️ memory forget 的清除範圍有限。它依照記錄的 provenance 執行,因此以下內容可能仍然存在:原始逐字稿、較舊且無血緣資訊的筆記、其他 Agent 的儲存、直接或外部的寫入、匯出檔案與備份。套用前務必先檢視預覽結果——若你的目的是符合資料刪除的法遵要求,這個指令本身並不足以構成完整證據,需搭配備份與匯出的清理程序。

上下文管理器

package com.tutorial.openclaw.context;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.Instant;
import java.util.*;
import java.util.concurrent.ConcurrentLinkedDeque;

/**
 * OpenClaw 對話上下文管理器。
 *
 * <p>管理 Agent 與使用者之間的對話歷史與上下文,
 * 實作滑動視窗和摘要壓縮策略以控制 Token 用量。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class ContextManager {

    private static final Logger logger = LogManager.getLogger(ContextManager.class);

    /** 對話訊息記錄 */
    public record Message(
            String role,
            String content,
            Instant timestamp,
            boolean pinned
    ) {}

    /** 最大保留訊息數 */
    private final int maxMessages;

    /** 最大 Token 數估計 */
    private final int maxTokenEstimate;

    /** 訊息佇列 */
    private final Deque<Message> messages;

    /** 摘要文字 */
    private String summary;

    /** 使用者偏好 */
    private final Map<String, String> userPreferences;

    /**
     * 建立上下文管理器。
     *
     * @param maxMessages     最大保留訊息數
     * @param maxTokenEstimate 最大 Token 數估計值
     */
    public ContextManager(int maxMessages, int maxTokenEstimate) {
        this.maxMessages = maxMessages;
        this.maxTokenEstimate = maxTokenEstimate;
        this.messages = new ConcurrentLinkedDeque<>();
        this.summary = "";
        this.userPreferences = new HashMap<>();
    }

    /**
     * 新增訊息至上下文。
     *
     * @param role    訊息角色(user/assistant/system)
     * @param content 訊息內容
     */
    public void addMessage(String role, String content) {
        addMessage(role, content, false);
    }

    /**
     * 新增訊息至上下文,可選是否釘選。
     *
     * @param role    訊息角色
     * @param content 訊息內容
     * @param pinned  是否釘選(釘選的訊息不會被移除)
     */
    public void addMessage(String role, String content, boolean pinned) {
        messages.addLast(new Message(role, content, Instant.now(), pinned));
        logger.debug("新增訊息 [role={}, pinned={}, length={}]",
                role, pinned, content.length());
        trimIfNeeded();
    }

    /**
     * 取得用於 LLM 的完整上下文。
     *
     * @return 格式化的上下文訊息列表
     */
    public List<Map<String, String>> getContextForLLM() {
        List<Map<String, String>> context = new ArrayList<>();

        // 加入摘要(如果有的話)
        if (!summary.isEmpty()) {
            context.add(Map.of(
                    "role", "system",
                    "content", "以下是之前對話的摘要:\n" + summary
            ));
        }

        // 加入訊息歷史
        for (Message msg : messages) {
            context.add(Map.of(
                    "role", msg.role(),
                    "content", msg.content()
            ));
        }

        return Collections.unmodifiableList(context);
    }

    /**
     * 設定使用者偏好。
     *
     * @param key   偏好鍵
     * @param value 偏好值
     */
    public void setPreference(String key, String value) {
        userPreferences.put(key, value);
        logger.debug("設定使用者偏好: {} = {}", key, value);
    }

    /**
     * 取得使用者偏好。
     *
     * @param key 偏好鍵
     * @return 偏好值,若不存在則回傳 null
     */
    public String getPreference(String key) {
        return userPreferences.get(key);
    }

    /**
     * 若超出限制則裁剪上下文。
     */
    private void trimIfNeeded() {
        while (messages.size() > maxMessages) {
            // 找到第一個未釘選的訊息移除
            Iterator<Message> iter = messages.iterator();
            boolean removed = false;
            while (iter.hasNext()) {
                Message msg = iter.next();
                if (!msg.pinned()) {
                    // 將被移除的訊息加入摘要
                    appendToSummary(msg);
                    iter.remove();
                    removed = true;
                    logger.debug("移除舊訊息並加入摘要 [role={}]", msg.role());
                    break;
                }
            }
            if (!removed) {
                break; // 所有訊息都被釘選
            }
        }
    }

    /**
     * 將訊息摘要化並加入到摘要中。
     */
    private void appendToSummary(Message msg) {
        String summaryEntry = String.format("[%s] %s: %s",
                msg.timestamp().toString().substring(0, 19),
                msg.role(),
                msg.content().length() > 100
                        ? msg.content().substring(0, 100) + "..."
                        : msg.content()
        );
        if (summary.isEmpty()) {
            summary = summaryEntry;
        } else {
            summary += "\n" + summaryEntry;
        }
    }

    /**
     * 取得目前上下文統計資訊。
     *
     * @return 統計資訊映射
     */
    public Map<String, Object> getStats() {
        int estimatedTokens = messages.stream()
                .mapToInt(m -> m.content().length() / 4) // 粗略估算
                .sum();
        return Map.of(
                "messageCount", messages.size(),
                "pinnedCount", messages.stream().filter(Message::pinned).count(),
                "estimatedTokens", estimatedTokens,
                "hasSummary", !summary.isEmpty(),
                "preferencesCount", userPreferences.size()
        );
    }

    /**
     * 清除所有上下文。
     */
    public void clear() {
        messages.clear();
        summary = "";
        userPreferences.clear();
        logger.info("上下文已清除");
    }
}

4.7 Webhook 與排程任務

Automations:Cron 的新名稱(v2026.8.1)

2.0 將排程工作統一命名為 Automations,橫跨 Agent 工具、Control UI、命令列、文件與原生應用。

這是更名,不是取代。官方明確保證向下相容:openclaw automations 與 openclaw cron 提供同一組指令族,而舊的 /cron 路由、cron.* 設定與 RPC 名稱、排程運算式、識別碼與已儲存的工作全部繼續運作。既有自動化不需要因為更名而修改。

# 以下兩者等價
openclaw automations list
openclaw cron list

各介面的能力並不對等,規劃維運分工時須留意:

介面能力
Control UI最完整:搜尋、篩選、建立、複製、檢視、編輯、執行、暫停、移除,含進階傳遞與失敗路由
iOS / Android各自支援的欄位與動作;Android 的變更需管理員範圍,唯讀連線僅能檢視
無法替換酬載的用戶端腳本型自動化可見但唯讀

條件式與事件串流觸發

自動化不再限於時間排程,可等待條件或受監控的事件串流:

觸發類型建立方式Control UI 支援限制
條件(Condition)Control UI 可建立、篩選、編輯、檢視完整檢查間隔至少 30 秒;儲存前會先驗證;記錄檢查與命中但不為每次未命中建立執行
串流排程(Stream)僅命令列或 Agent唯讀有界緩衝、批次處理與重啟退避

觸發機制可以完全停用。條件間隔的 30 秒下限是硬性限制,設計高頻監控時需改用其他機制。

執行、傳遞與完成是三件獨立的事

這是 2.0 在自動化可觀測性上最重要的改變,也是排錯時最容易誤判的地方:

graph LR
    A[自動化觸發] --> B[執行工作]
    B -->|成功| C[產生結果]
    C --> D{傳遞結果}
    D -->|成功| E[完成]
    D -->|失敗| F["狀態:not-delivered<br/>(工作本身已成功)"]
事實意義
是否執行工作本身是否跑完
是否傳遞結果是否成功送達目的地
整個請求是否完成兩者皆成立

關鍵解讀:一個工作可以執行成功、卻仍標示為 not-delivered(當預設的 announce 傳遞失敗時)。反之,明確要求傳遞時可能讓 cron run --wait 失敗,但不會重跑已經完成的工作。刻意的抑制不算失敗。

失敗告警與自動停用

機制預設值
路由型失敗告警連續 2 次失敗觸發,冷卻 1 小時
週期性 cron / every 工作自動停用連續 10 次執行失敗後停用,並說明如何重新啟用

僅傳遞失敗不會累計該連續次數;一次成功執行或手動重新啟用即可重置計數。

其他重要變更

  • HEARTBEAT.md 已停止在 runtime 讀取。既有使用該檔案的安裝必須執行 openclaw doctor --fix 才能遷移有效的工作(見 7.5)。
  • 統一容量限制:週期性排程、一次性工作、手動啟動、佇列工作、重啟補跑、結束時工作、指令與有界腳本,現在共用同一個設定的容量上限。等待中的工作會在有空間時開始。
  • 腳本仍有限制:時間、工具呼叫次數、節奏與狀態皆有上限,且可以完全停用。成功的腳本可保留少量狀態、通知目的地、喚醒主對話,或要求稍後再檢查一次。
  • 時區處理:時區感知的排程會略過本地時間中不存在的時刻,在本地時間重複時選擇第一個真實發生的時刻,並在重啟後繼續遵守明確的位移設定。

原生 Webhook Ingress(hooks.*)

多數「外部事件觸發 Agent」的需求,不需要自建 HTTP 服務:Gateway 本身就能在獨立子路徑接收 Webhook,並依 hooks.mappings 轉成 Agent 回合或喚醒動作。

// openclaw.json
{
  hooks: {
    enabled: true,
    path: "/hooks",                          // 不可為 "/"
    token: "${OPENCLAW_HOOKS_TOKEN}",        // 專用 token,不可重用 Gateway 驗證密鑰
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        // POST /hooks/github → 交給 devops Agent,於隔離 Session 執行,不主動對外發送
        match: { path: "github" },
        action: "agent",
        agentId: "devops",
        sessionMode: "isolated",
        deliver: false,
      },
    ],
  },
}
# 冒煙測試:先打內建的 /hooks/agent(Idempotency-Key 防止重送造成重複執行)
curl --include http://127.0.0.1:18789/hooks/agent \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webhook-smoke-001' \
  --data '{"message":"摘要這個測試事件:匯入完成。","name":"Webhook smoke test","agentId":"devops","deliver":false}'
# 預期 HTTP 200:{ "ok": true, "runId": "..." }(代表已受理,不代表已完成)
回應排查方向
401檢查 hook token(不是 Gateway token),以及反向代理是否轉送 Authorization 標頭
404hooks.enabled、hooks.path 或 mapping 的 match.path
400JSON 格式、Agent 選擇、Session 政策或投遞目的地不合法

⚠️ 安全規則:Webhook 內容一律視為不受信任的輸入;驗證只接受標頭(Authorization: Bearer 或 x-openclaw-token),查詢字串中的 token 會被拒絕;保持 allowUnsafeExternalContent 關閉;開啟 allowRequestSessionKey 時必須同時以 allowedSessionKeyPrefixes 限制範圍;hook 驅動的 Agent 應使用嚴格工具政策(例如 messaging profile + 沙箱)。

自建 Webhook 中介層(需要驗簽或格式轉換時)

當來源系統需要驗證簽章(例如 GitHub 的 X-Hub-Signature-256、Jira 的共用密鑰)、或需要先做格式轉換再交給 Agent 時,才需要下面這種自建處理器;處理完成後,再呼叫 Gateway 的 /hooks/<name> 或 4.2 的 HTTP API。

package com.tutorial.openclaw.webhook;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Consumer;

/**
 * OpenClaw Webhook 處理伺服器。
 *
 * <p>接收外部 Webhook 事件並轉發給 OpenClaw Agent 處理,
 * 支援 GitHub、GitLab、Jira 等常見服務的 Webhook。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class WebhookServer {

    private static final Logger logger = LogManager.getLogger(WebhookServer.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();

    private final HttpServer server;
    private final Map<String, Consumer<JsonNode>> handlers;
    private final OpenClawNotifier notifier;

    /**
     * 建立 Webhook 伺服器。
     *
     * @param port         監聽埠
     * @param gatewayUri   OpenClaw Gateway WebSocket URI
     * @throws IOException 若伺服器建立失敗
     */
    public WebhookServer(int port, String gatewayUri) throws IOException {
        this.server = HttpServer.create(new InetSocketAddress(port), 0);
        this.handlers = new ConcurrentHashMap<>();
        this.notifier = new OpenClawNotifier(gatewayUri);

        // 註冊 Webhook 端點
        server.createContext("/webhook", this::handleWebhook);
        server.createContext("/health", this::handleHealth);

        // 註冊預設處理器
        registerDefaultHandlers();
    }

    /**
     * 啟動伺服器。
     */
    public void start() {
        server.start();
        logger.info("Webhook 伺服器已啟動於 port {}",
                server.getAddress().getPort());
    }

    /**
     * 註冊 Webhook 事件處理器。
     *
     * @param eventType 事件類型
     * @param handler   處理函式
     */
    public void registerHandler(String eventType, Consumer<JsonNode> handler) {
        handlers.put(eventType, handler);
        logger.info("已註冊 Webhook 處理器: {}", eventType);
    }

    /**
     * 處理 Webhook 請求。
     */
    private void handleWebhook(HttpExchange exchange) throws IOException {
        if (!"POST".equals(exchange.getRequestMethod())) {
            sendResponse(exchange, 405, "Method not allowed");
            return;
        }

        try {
            String body = new String(
                    exchange.getRequestBody().readAllBytes(),
                    StandardCharsets.UTF_8);
            JsonNode payload = MAPPER.readTree(body);

            // 判斷事件來源和類型
            String source = detectSource(exchange, payload);
            String eventType = detectEventType(exchange, payload);
            String fullEventKey = source + "." + eventType;

            logger.info("收到 Webhook [source={}, event={}]", source, eventType);

            // 執行處理器
            Consumer<JsonNode> handler = handlers.get(fullEventKey);
            if (handler != null) {
                handler.accept(payload);
            } else {
                logger.warn("無處理器: {}", fullEventKey);
            }

            sendResponse(exchange, 200, "{\"status\": \"received\"}");

        } catch (Exception e) {
            logger.error("Webhook 處理失敗", e);
            sendResponse(exchange, 500,
                    "{\"error\": \"" + e.getMessage() + "\"}");
        }
    }

    /**
     * 偵測 Webhook 來源。
     */
    private String detectSource(HttpExchange exchange, JsonNode payload) {
        // GitHub: X-GitHub-Event header
        String githubEvent = exchange.getRequestHeaders()
                .getFirst("X-GitHub-Event");
        if (githubEvent != null) return "github";

        // GitLab: X-Gitlab-Event header
        String gitlabEvent = exchange.getRequestHeaders()
                .getFirst("X-Gitlab-Event");
        if (gitlabEvent != null) return "gitlab";

        // Jira
        if (payload.has("webhookEvent")) return "jira";

        return "unknown";
    }

    /**
     * 偵測事件類型。
     */
    private String detectEventType(HttpExchange exchange, JsonNode payload) {
        String githubEvent = exchange.getRequestHeaders()
                .getFirst("X-GitHub-Event");
        if (githubEvent != null) return githubEvent;

        String gitlabEvent = exchange.getRequestHeaders()
                .getFirst("X-Gitlab-Event");
        if (gitlabEvent != null) return gitlabEvent.replace(" ", "_").toLowerCase();

        if (payload.has("webhookEvent")) {
            return payload.get("webhookEvent").asText();
        }

        return "unknown";
    }

    /**
     * 註冊預設 Webhook 處理器。
     */
    private void registerDefaultHandlers() {
        // GitHub Push 事件
        registerHandler("github.push", payload -> {
            String repo = payload.path("repository").path("full_name").asText();
            String pusher = payload.path("pusher").path("name").asText();
            int commitCount = payload.path("commits").size();

            String message = String.format(
                    "🔔 GitHub Push\n倉庫: %s\n推送者: %s\n提交數: %d",
                    repo, pusher, commitCount);

            notifier.notify(message);
            logger.info("GitHub push: {} by {} ({} commits)",
                    repo, pusher, commitCount);
        });

        // GitHub Pull Request 事件
        registerHandler("github.pull_request", payload -> {
            String action = payload.path("action").asText();
            String title = payload.path("pull_request").path("title").asText();
            String author = payload.path("pull_request").path("user")
                    .path("login").asText();
            String repo = payload.path("repository").path("full_name").asText();

            String message = String.format(
                    "🔀 GitHub PR %s\n倉庫: %s\n標題: %s\n作者: %s",
                    action, repo, title, author);

            notifier.notify(message);
        });

        // GitHub Issue 事件
        registerHandler("github.issues", payload -> {
            String action = payload.path("action").asText();
            String title = payload.path("issue").path("title").asText();
            int number = payload.path("issue").path("number").asInt();

            String message = String.format(
                    "📋 GitHub Issue #%d %s\n標題: %s",
                    number, action, title);

            notifier.notify(message);
        });
    }

    /**
     * 健康檢查端點。
     */
    private void handleHealth(HttpExchange exchange) throws IOException {
        sendResponse(exchange, 200,
                "{\"status\": \"healthy\", \"handlers\": " +
                        handlers.size() + "}");
    }

    /**
     * 發送 HTTP 回應。
     */
    private void sendResponse(HttpExchange exchange, int statusCode, String body)
            throws IOException {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().set("Content-Type",
                "application/json; charset=utf-8");
        exchange.sendResponseHeaders(statusCode, bytes.length);
        try (OutputStream os = exchange.getResponseBody()) {
            os.write(bytes);
        }
    }

    /**
     * OpenClaw 通知發送器(簡化版)。
     */
    static class OpenClawNotifier {
        private final String gatewayUri;

        OpenClawNotifier(String gatewayUri) {
            this.gatewayUri = gatewayUri;
        }

        void notify(String message) {
            // 透過 Gateway API 發送通知
            // 實際實作會使用 WebSocket 客戶端
            LogManager.getLogger(OpenClawNotifier.class)
                    .info("通知已送出: {}", message);
        }
    }
}

4.8 多 Agent 協作開發

多 Agent 架構設計

graph TB
    subgraph "Orchestrator Agent"
        ORC[協調者 Agent]
    end
    
    subgraph "專業 Agent 群"
        CODE[程式碼 Agent]
        REVIEW[審查 Agent]
        TEST[測試 Agent]
        DOC[文件 Agent]
    end
    
    subgraph "共享資源"
        CTX[共享上下文]
        QUEUE[工作佇列]
    end
    
    ORC -->|分派任務| CODE
    ORC -->|分派任務| REVIEW
    ORC -->|分派任務| TEST
    ORC -->|分派任務| DOC
    
    CODE & REVIEW & TEST & DOC --> CTX
    CODE & REVIEW & TEST & DOC --> QUEUE
    
    CODE -->|完成| ORC
    REVIEW -->|完成| ORC
    TEST -->|完成| ORC
    DOC -->|完成| ORC

Java 多 Agent 協調器

package com.tutorial.openclaw.multiagent;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.*;
import java.util.concurrent.*;

/**
 * 多 Agent 協調器。
 *
 * <p>管理多個 OpenClaw Agent 之間的協作,
 * 實作任務分派、結果聚合、衝突解決等功能。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class MultiAgentOrchestrator {

    private static final Logger logger = LogManager.getLogger(
            MultiAgentOrchestrator.class);

    /**
     * Agent 定義。
     */
    public record AgentDef(
            String id,
            String name,
            String role,
            String skill
    ) {}

    /**
     * 任務定義。
     */
    public record Task(
            String id,
            String description,
            String assignedAgent,
            Map<String, Object> parameters,
            TaskStatus status
    ) {}

    /**
     * 任務狀態。
     */
    public enum TaskStatus {
        PENDING, IN_PROGRESS, COMPLETED, FAILED
    }

    private final Map<String, AgentDef> agents;
    private final ExecutorService executor;
    private final ConcurrentLinkedQueue<Task> taskQueue;
    private final Map<String, Object> sharedContext;

    /**
     * 建立協調器。
     */
    public MultiAgentOrchestrator() {
        this.agents = new ConcurrentHashMap<>();
        this.executor = Executors.newFixedThreadPool(4);
        this.taskQueue = new ConcurrentLinkedQueue<>();
        this.sharedContext = new ConcurrentHashMap<>();
    }

    /**
     * 註冊 Agent。
     *
     * @param agent Agent 定義
     */
    public void registerAgent(AgentDef agent) {
        agents.put(agent.id(), agent);
        logger.info("已註冊 Agent: {} ({})", agent.name(), agent.role());
    }

    /**
     * 提交複合任務並協調多個 Agent 處理。
     *
     * @param description 任務描述
     * @return 所有子任務的結果
     */
    public CompletableFuture<Map<String, Object>> submitCompositeTask(
            String description) {
        logger.info("收到複合任務: {}", description);

        // 步驟 1: 任務分解
        List<Task> subTasks = decomposeTask(description);
        logger.info("分解為 {} 個子任務", subTasks.size());

        // 步驟 2: 平行執行子任務
        List<CompletableFuture<Map.Entry<String, Object>>> futures =
                subTasks.stream()
                        .map(task -> CompletableFuture.supplyAsync(() -> {
                            logger.info("Agent {} 開始處理: {}",
                                    task.assignedAgent(), task.description());
                            // 模擬 Agent 處理
                            Map<String, Object> result = processTask(task);
                            return Map.entry(task.id(), (Object) result);
                        }, executor))
                        .toList();

        // 步驟 3: 聚合結果
        return CompletableFuture.allOf(
                        futures.toArray(new CompletableFuture[0]))
                .thenApply(v -> {
                    Map<String, Object> results = new HashMap<>();
                    futures.forEach(f -> {
                        Map.Entry<String, Object> entry = f.join();
                        results.put(entry.getKey(), entry.getValue());
                    });
                    logger.info("所有子任務完成,聚合結果");
                    return results;
                });
    }

    /**
     * 將複合任務分解為子任務。
     */
    private List<Task> decomposeTask(String description) {
        List<Task> tasks = new ArrayList<>();

        // 根據任務描述分配給不同 Agent
        if (description.contains("程式碼") || description.contains("開發")) {
            tasks.add(new Task(
                    UUID.randomUUID().toString(),
                    "撰寫程式碼",
                    "code-agent",
                    Map.of("type", "implementation"),
                    TaskStatus.PENDING
            ));
        }
        if (description.contains("審查") || description.contains("review")) {
            tasks.add(new Task(
                    UUID.randomUUID().toString(),
                    "程式碼審查",
                    "review-agent",
                    Map.of("type", "review"),
                    TaskStatus.PENDING
            ));
        }
        if (description.contains("測試") || description.contains("test")) {
            tasks.add(new Task(
                    UUID.randomUUID().toString(),
                    "撰寫測試",
                    "test-agent",
                    Map.of("type", "testing"),
                    TaskStatus.PENDING
            ));
        }
        if (description.contains("文件") || description.contains("文檔")) {
            tasks.add(new Task(
                    UUID.randomUUID().toString(),
                    "撰寫文件",
                    "doc-agent",
                    Map.of("type", "documentation"),
                    TaskStatus.PENDING
            ));
        }

        // 若無特定匹配,建立通用任務
        if (tasks.isEmpty()) {
            tasks.add(new Task(
                    UUID.randomUUID().toString(),
                    description,
                    "default-agent",
                    Map.of("type", "general"),
                    TaskStatus.PENDING
            ));
        }

        return tasks;
    }

    /**
     * 處理單一任務(模擬)。
     */
    private Map<String, Object> processTask(Task task) {
        try {
            // 模擬處理時間
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return Map.of(
                "taskId", task.id(),
                "agent", task.assignedAgent(),
                "status", "completed",
                "result", "任務完成: " + task.description()
        );
    }

    /**
     * 關閉協調器。
     */
    public void shutdown() {
        executor.shutdown();
        try {
            if (!executor.awaitTermination(30, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
        }
        logger.info("協調器已關閉");
    }
}

4.9 錯誤處理與重試機制

Agent-to-Agent 通訊: OpenClaw 內建 sessions_* 工具用於跨 Session 的 Agent 間通訊,無需自行實作協調邏輯:

工具說明
sessions_list列出活躍 Session(Agent)及其中繼資料
sessions_history取得指定 Session 的對話記錄
sessions_send向另一個 Session 發送訊息,支援 reply-back 乒乓
sessions_spawn生成新的 Agent Session

詳見 Session 工具文件。

統一錯誤處理框架

package com.tutorial.openclaw.resilience;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.Duration;
import java.util.concurrent.Callable;
import java.util.function.Predicate;

/**
 * 彈性重試機制。
 *
 * <p>為 OpenClaw 相關操作提供指數退避重試策略,
 * 防止因網路波動或 LLM API 暫時性錯誤導致的失敗。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class RetryPolicy<T> {

    private static final Logger logger = LogManager.getLogger(RetryPolicy.class);

    private final int maxAttempts;
    private final Duration initialDelay;
    private final double backoffMultiplier;
    private final Duration maxDelay;
    private final Predicate<Exception> retryableCheck;

    /**
     * 建立重試策略。
     */
    private RetryPolicy(Builder<T> builder) {
        this.maxAttempts = builder.maxAttempts;
        this.initialDelay = builder.initialDelay;
        this.backoffMultiplier = builder.backoffMultiplier;
        this.maxDelay = builder.maxDelay;
        this.retryableCheck = builder.retryableCheck;
    }

    /**
     * 以重試策略執行操作。
     *
     * @param operation 要執行的操作
     * @return 操作結果
     * @throws Exception 若所有重試都失敗
     */
    public T execute(Callable<T> operation) throws Exception {
        Exception lastException = null;
        Duration currentDelay = initialDelay;

        for (int attempt = 1; attempt <= maxAttempts; attempt++) {
            try {
                T result = operation.call();
                if (attempt > 1) {
                    logger.info("操作在第 {} 次嘗試成功", attempt);
                }
                return result;

            } catch (Exception e) {
                lastException = e;

                if (!retryableCheck.test(e)) {
                    logger.error("不可重試的錯誤,立即失敗: {}", e.getMessage());
                    throw e;
                }

                if (attempt < maxAttempts) {
                    logger.warn("嘗試 {}/{} 失敗: {},等待 {}ms 後重試",
                            attempt, maxAttempts, e.getMessage(),
                            currentDelay.toMillis());
                    Thread.sleep(currentDelay.toMillis());

                    // 指數退避
                    long nextDelayMs = (long) (currentDelay.toMillis()
                            * backoffMultiplier);
                    currentDelay = Duration.ofMillis(
                            Math.min(nextDelayMs, maxDelay.toMillis()));
                } else {
                    logger.error("所有 {} 次嘗試均失敗", maxAttempts);
                }
            }
        }

        throw lastException;
    }

    /**
     * 建立預設的 OpenClaw API 重試策略。
     *
     * @return 適用於 OpenClaw API 呼叫的重試策略
     */
    public static <T> RetryPolicy<T> forOpenClawApi() {
        return new Builder<T>()
                .maxAttempts(3)
                .initialDelay(Duration.ofSeconds(1))
                .backoffMultiplier(2.0)
                .maxDelay(Duration.ofSeconds(30))
                .retryOn(e ->
                        e.getMessage() != null && (
                                e.getMessage().contains("timeout") ||
                                e.getMessage().contains("rate limit") ||
                                e.getMessage().contains("503") ||
                                e.getMessage().contains("429")
                        ))
                .build();
    }

    /**
     * 建立適用於 LLM 呼叫的重試策略。
     *
     * @return 適用於 LLM API 呼叫的重試策略
     */
    public static <T> RetryPolicy<T> forLLMCall() {
        return new Builder<T>()
                .maxAttempts(5)
                .initialDelay(Duration.ofSeconds(2))
                .backoffMultiplier(2.0)
                .maxDelay(Duration.ofMinutes(1))
                .retryOn(e ->
                        e.getMessage() != null && (
                                e.getMessage().contains("rate_limit") ||
                                e.getMessage().contains("overloaded") ||
                                e.getMessage().contains("timeout") ||
                                e.getMessage().contains("500") ||
                                e.getMessage().contains("502") ||
                                e.getMessage().contains("503")
                        ))
                .build();
    }

    /**
     * 重試策略建構器。
     */
    public static class Builder<T> {
        private int maxAttempts = 3;
        private Duration initialDelay = Duration.ofSeconds(1);
        private double backoffMultiplier = 2.0;
        private Duration maxDelay = Duration.ofSeconds(30);
        private Predicate<Exception> retryableCheck = e -> true;

        public Builder<T> maxAttempts(int maxAttempts) {
            this.maxAttempts = maxAttempts;
            return this;
        }

        public Builder<T> initialDelay(Duration initialDelay) {
            this.initialDelay = initialDelay;
            return this;
        }

        public Builder<T> backoffMultiplier(double multiplier) {
            this.backoffMultiplier = multiplier;
            return this;
        }

        public Builder<T> maxDelay(Duration maxDelay) {
            this.maxDelay = maxDelay;
            return this;
        }

        public Builder<T> retryOn(Predicate<Exception> check) {
            this.retryableCheck = check;
            return this;
        }

        public RetryPolicy<T> build() {
            return new RetryPolicy<>(this);
        }
    }
}

使用範例

// 使用重試策略調用 OpenClaw API
RetryPolicy<String> retryPolicy = RetryPolicy.forOpenClawApi();

// 4.2 的 OpenClawClient 內建重試;外層已有 RetryPolicy 時把 maxAttempts 設為 1,避免重試次數相乘
try (OpenClawClient client = OpenClawClient.builder(URI.create("http://127.0.0.1:18789"))
        .token(System.getenv("OPENCLAW_GATEWAY_TOKEN"))
        .maxAttempts(1)
        .build()) {
    String response = retryPolicy.execute(() -> client.sendMessage("report-2026-11-08", "生成今日報表"));
}

Plugin SDK 匯入路徑遷移對照(v2026.8.1)

舊版的粗粒度 subpath 已收斂為聚焦命名空間。以下為官方公告的對照關係:

舊版 subpath遷移目標
plugin-sdk-config-runtime-subpathapi.pluginConfig 與對應的聚焦匯入
plugin-sdk-channel-*-subpathopenclaw/plugin-sdk/channel-outbound 及相關命名空間
plugin-sdk-infra-runtime-subpath聚焦匯入:例如 SSRF 防護改由 openclaw/plugin-sdk/ssrf-runtime(fetchWithSsrFGuard)與 openclaw/plugin-sdk/ssrf-policy 提供;完整清單見官方 SDK subpaths
deactivate(別名)gateway_stop
// ❌ 舊寫法(已移除;tsc 對 2026.11.1 實測:Cannot find module 'openclaw/plugin-sdk'、'openclaw/plugin-sdk/infra-runtime')
import { registerChannel } from "openclaw/plugin-sdk";
import { fetchWithSsrfGuard } from "openclaw/plugin-sdk/infra-runtime";

export function deactivate() { /* ... */ }
// ✅ 現行寫法:從聚焦的子路徑匯入(以 tsc 對 openclaw 2026.11.1 驗證)
import { fetchWithSsrFGuard, SsrFBlockedError } from "openclaw/plugin-sdk/ssrf-runtime";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export { fetchWithSsrFGuard, SsrFBlockedError, defineChannelPluginEntry };

❌ 連舊版手冊的「新寫法」也有錯:openclaw/plugin-sdk/ssrf 子路徑不存在、registerOutboundChannel 不是 channel-outbound 的匯出、函式名稱是 fetchWithSsrFGuard(F 大寫)。插件程式碼請一律以 tsc --strict 對目標 OpenClaw 版本的型別檢查。

其他需同步遷移的項目:

  • 使用 v2026.7.2 beta 的 question、worker 或 session-catalog 形狀的用戶端,需改用更名並扁平化後的契約。
  • 自訂的 agents.defaults.cliBackends 指令、參數、環境變數、別名與解析器,現在必須放進 backend plugin,且該執行檔需可被 OpenClaw 服務存取。
  • beta.5 session-store bridge 仍可使用至 2026-10-12。

Hook 政策的位階:Hook 政策位於頻道准入、沙箱、審批、owner-only 工具等主機政策之下。換言之,插件 hook 無法繞過主機層級的安全控制。另外,Codex hook 轉接的 timeout 清理僅適用於 POSIX 主機,不含 Windows。

插件更新與執行期世代

2.0 讓插件更新保留一個 runtime 世代給已在進行中的工作:已受理的訊息、完成項目與 worker 會以它們啟動時的插件版本執行完畢,後續工作只在替換版本成功載入後才會移轉過去。若熱重載失敗,OpenClaw 會還原最後一組有效的指令、Provider、hook、記憶體與其他註冊項目。

失敗隔離:已知的插件自身失敗可被隔離(quarantine),不會拖垮健康的插件或整個 OpenClaw。但無效的組態、失敗的遷移、歸屬不明與無法驗證的狀態,仍會阻止啟用。

Context-engine 插件:可在長 Session 中推進持久狀態,方法是將限制套用於已受理的回合而非全部累計歷史。既有的 v1 引擎在採用新介面前維持其完整歷史契約;單一受理回合超過 8 MiB 或 20,000 events 仍會停止。

4.10 Java Spring Boot 整合範例

本節把 4.2 的 OpenClawClient 包成 Spring Boot 4 服務,讓內部前端或其他微服務以一般 REST 呼叫 Agent,而不需要持有 Gateway token。這也是企業最常見的整合模式:Gateway token 只存在於這個後端服務中。

graph LR
    FE[內部前端 / 微服務] -->|POST /api/openclaw/chat<br/>企業 SSO| SB[Spring Boot 服務]
    SB -->|Bearer OPENCLAW_GATEWAY_TOKEN<br/>POST /v1/chat/completions| GW[OpenClaw Gateway<br/>loopback / 內網]
    SB -->|GET /readyz| GW

應用程式

package com.tutorial.openclaw.spring;

import com.tutorial.openclaw.OpenClawClient;
import com.tutorial.openclaw.OpenClawException;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.net.URI;
import java.time.Duration;
import java.util.Map;

/** Spring Boot 4 整合 OpenClaw Gateway 的範例應用程式。 */
@SpringBootApplication
public class OpenClawSpringApp {
    public static void main(String[] args) {
        SpringApplication.run(OpenClawSpringApp.class, args);
    }
}

/**
 * 組態綁定(application.yml 的 openclaw.*)。token 一律從環境變數帶入,不寫在檔案中。
 */
@ConfigurationProperties(prefix = "openclaw")
record OpenClawProperties(URI gatewayUri, String token, String agent,
                          Duration requestTimeout, int maxAttempts) {
}

@Configuration
@EnableConfigurationProperties(OpenClawProperties.class)
class OpenClawConfig {

    @Bean(destroyMethod = "close")
    OpenClawClient openClawClient(OpenClawProperties p) {
        return OpenClawClient.builder(p.gatewayUri())
                .token(p.token())
                .agent(p.agent())
                .requestTimeout(p.requestTimeout() == null ? Duration.ofMinutes(2) : p.requestTimeout())
                .maxAttempts(p.maxAttempts() <= 0 ? 3 : p.maxAttempts())
                .build();
    }
}

/** 請求本文:以 Bean Validation 限制輸入,避免把任意大小的文字轉送給 Agent。 */
record ChatRequest(@NotBlank @Size(max = 64) String conversationId,
                   @NotBlank @Size(max = 8000) String message) {
}

@RestController
@RequestMapping("/api/openclaw")
class OpenClawController {

    private static final Logger log = LoggerFactory.getLogger(OpenClawController.class);
    private final OpenClawClient client;

    OpenClawController(OpenClawClient client) {
        this.client = client;
    }

    @PostMapping("/chat")
    Map<String, Object> chat(@Valid @RequestBody ChatRequest request) {
        // 只記錄識別碼與長度,不記錄訊息內容(可能含個資)
        log.info("chat conversation={} length={}", request.conversationId(), request.message().length());
        String reply = client.sendMessage(request.conversationId(), request.message());
        return Map.of("conversationId", request.conversationId(), "reply", reply);
    }

    @GetMapping("/health")
    ResponseEntity<Map<String, Object>> health() {
        boolean ready = client.isReady();
        return ResponseEntity.status(ready ? HttpStatus.OK : HttpStatus.SERVICE_UNAVAILABLE)
                .body(Map.of("gateway", client.getGatewayUri().toString(), "ready", ready));
    }

    /** 對外不洩漏內部錯誤細節;認證錯誤回 502(是本服務設定問題,不是呼叫者的錯)。 */
    @ExceptionHandler(OpenClawException.class)
    ResponseEntity<Map<String, Object>> onGatewayError(OpenClawException e) {
        log.warn("OpenClaw call failed status={} message={}", e.getStatus(), e.getMessage());
        HttpStatus status = e.getStatus() == 429 ? HttpStatus.TOO_MANY_REQUESTS : HttpStatus.BAD_GATEWAY;
        return ResponseEntity.status(status).body(Map.of("error", "openclaw_unavailable"));
    }
}

組態

server:
  port: 8080

openclaw:
  gateway-uri: http://127.0.0.1:18789
  token: ${OPENCLAW_GATEWAY_TOKEN}
  agent: assistant
  request-timeout: 2m
  max-attempts: 3

logging:
  level:
    com.tutorial.openclaw: INFO

端到端測試

package com.tutorial.openclaw.spring;

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;

import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

import static org.assertj.core.api.Assertions.assertThat;

/** 端到端:Spring REST → OpenClawClient → 模擬 Gateway。 */
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OpenClawControllerTest {

    static final HttpServer GATEWAY = startGateway();

    @LocalServerPort
    int port;

    static HttpServer startGateway() {
        try {
            HttpServer s = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
            s.createContext("/v1/chat/completions", ex -> {
                byte[] b = """
                        {"choices":[{"index":0,"message":{"role":"assistant","content":"摘要完成"}}]}
                        """.getBytes(StandardCharsets.UTF_8);
                ex.sendResponseHeaders(200, b.length);
                ex.getResponseBody().write(b);
                ex.close();
            });
            s.createContext("/readyz", ex -> {
                ex.sendResponseHeaders(503, -1);
                ex.close();
            });
            s.start();
            return s;
        } catch (IOException e) {
            throw new IllegalStateException(e);
        }
    }

    @DynamicPropertySource
    static void props(DynamicPropertyRegistry r) {
        r.add("openclaw.gateway-uri", () -> "http://127.0.0.1:" + GATEWAY.getAddress().getPort());
        r.add("openclaw.token", () -> "it-token");
    }

    @AfterAll
    static void stop() {
        GATEWAY.stop(0);
    }

    private HttpResponse<String> post(String json) throws Exception {
        return HttpClient.newHttpClient().send(HttpRequest.newBuilder(
                        URI.create("http://127.0.0.1:" + port + "/api/openclaw/chat"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json)).build(), HttpResponse.BodyHandlers.ofString());
    }

    @Test
    void chatIsForwardedToGateway() throws Exception {
        HttpResponse<String> res = post("{\"conversationId\":\"t-1\",\"message\":\"請摘要工單\"}");
        assertThat(res.statusCode()).isEqualTo(200);
        assertThat(res.body()).contains("摘要完成").contains("t-1");
    }

    @Test
    void blankMessageIsRejectedWith400() throws Exception {
        assertThat(post("{\"conversationId\":\"t-1\",\"message\":\"\"}").statusCode()).isEqualTo(400);
    }

    @Test
    void healthReflectsGatewayReadiness() throws Exception {
        HttpResponse<String> res = HttpClient.newHttpClient().send(HttpRequest.newBuilder(
                URI.create("http://127.0.0.1:" + port + "/api/openclaw/health")).build(), HttpResponse.BodyHandlers.ofString());
        assertThat(res.statusCode()).isEqualTo(503);
        assertThat(res.body()).contains("\"ready\":false");
    }
}

Review Checklist(審查 AI 產出的整合服務)

檢查項目為什麼本範例的做法
Token 不出現在程式碼或 yml 明文operator 等級憑證${OPENCLAW_GATEWAY_TOKEN} 環境變數
輸入長度與必填驗證避免把任意大小的輸入轉給 Agent@NotBlank @Size + @Valid
不記錄訊息內容訊息可能含個資只記錄 conversationId 與長度
錯誤不外洩內部細節避免暴露 Gateway 位址與錯誤訊息@ExceptionHandler 統一回 openclaw_unavailable
健康檢查反映 Gateway readiness讓負載平衡器正確摘除/readyz → 200/503
對話層級的 Session避免不同使用者共用 SessionconversationId → OpenAI user 欄位
本服務自身有存取控制Gateway 端點等同 operator 權限部署時置於企業 SSO/API Gateway 之後(本範例未示範)

4.11 Gateway Protocol Client 開發

需要自建 operator 介面(即時串流、審批卡片、Session 清單訂閱)時,才需要直接使用 Gateway WebSocket 協定。官方提供兩個跟隨發布列車版號的 npm 套件:

套件內容
@openclaw/gateway-protocolschema、執行期驗證器、TypeScript 型別、client identity 與 capability 登錄表、結構化錯誤讀取器、協定版本常數;tarball 內含 protocol.schema.json
@openclaw/gateway-client參考連線實作;套件根目錄為 Node 用戶端(內含 ws 傳輸),@openclaw/gateway-client/browser 為瀏覽器版
# 套件版本與 Gateway 版本、wire protocol 版本是三件事:務必精確釘選並一起測試
npm install --save-exact @openclaw/gateway-client@2026.11.1 @openclaw/gateway-protocol@2026.11.1

連線生命週期(必須理解的五步)

sequenceDiagram
    participant C as Client
    participant G as Gateway
    C->>G: WebSocket 連線
    G-->>C: event connect.challenge(含 nonce 與 ts)
    C->>G: req connect(role、scopes、caps、bootstrap token/password、Ed25519 裝置證明)
    alt 裝置尚未配對
        G-->>C: res error PAIRING_REQUIRED(requestId)
        G->>G: 管理者執行 openclaw devices approve(requestId)
        C->>G: 重新連線並 connect
    end
    G-->>C: res hello-ok(protocol、policy、auth.deviceToken)
    C->>G: req chat.send(sessionKey、message、idempotencyKey)
    G-->>C: res(受理)
    G-->>C: event chat/agent/tool(需宣告對應 caps)
  1. 裝置身分:用戶端持久保存一組 Ed25519 金鑰;不要手動編輯 openclaw.json 產生每個用戶端的 token。
  2. Bootstrap 驗證:首次連線以共用 Gateway token/password 證明身分,取得配對後改用 hello-ok.auth.deviceToken。
  3. 最小 scope:互動聊天只需 operator.read + operator.write;顯示審批卡片再加 operator.approvals;operator.admin 只給管理工具。scope 升級會產生新的配對請求。
  4. Capabilities 不是授權:caps 只宣告用戶端能處理的事件;例如沒宣告 tool-events 就收不到工具串流,且握手不會報錯。
  5. 重連即重建投影:每次重連都要重新 sessions.subscribe、重抓 chat.history,並接手 inFlightRun。

TypeScript 範例(以 tsc --strict 對 2026.11.1 型別檢查通過)

import { randomUUID } from "node:crypto";
import { GatewayClient, GatewayClientRequestError } from "@openclaw/gateway-client";
import { GATEWAY_CLIENT_CAPS, GATEWAY_CLIENT_IDS, GATEWAY_CLIENT_MODES } from "@openclaw/gateway-protocol/client-info";

const sessionKey = "agent:assistant:ops-daily-report";

const client = new GatewayClient({
  url: "wss://gateway.internal.example.com",
  // 首次連線以共用 Gateway token 做 bootstrap 驗證;配對核准後改用 hello-ok 回傳的 device token
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
  clientName: GATEWAY_CLIENT_IDS.GATEWAY_CLIENT,
  clientDisplayName: "ops-report-bot",
  mode: GATEWAY_CLIENT_MODES.BACKEND,
  role: "operator",
  // 只要求實際需要的 scope:讀歷史 + 送訊息
  scopes: ["operator.read", "operator.write"],
  caps: [GATEWAY_CLIENT_CAPS.TOOL_EVENTS],
  requestTimeoutMs: 120_000,
  onHelloOk: (hello) => {
    console.log("connected, protocol", hello.protocol);
  },
  onEvent: (evt) => {
    if (evt.event === "chat") console.log("chat event", evt.payload);
  },
  onConnectError: (err) => console.error("connect failed:", err.message),
});

client.start();

try {
  // chat.send:sessionKey、message 與 idempotencyKey 為必填;重送時沿用同一 idempotencyKey 可避免重複執行
  const ack = await client.request("chat.send", {
    sessionKey,
    message: "生成今日維運報表",
    idempotencyKey: randomUUID(),
  });
  console.log("accepted:", ack);
} catch (err) {
  if (err instanceof GatewayClientRequestError) {
    console.error("gateway rejected request:", err.message);
  } else {
    throw err;
  }
} finally {
  await client.stopAndWait({ timeoutMs: 5_000 });
}

❌ 舊版範例的錯誤:import { createGatewayClient } from '@openclaw/gateway-client' 搭配 validate: 'strict'、client.ready()、client.sendMessage()。實測 tsc 會回報 has no exported member named 'createGatewayClient'. Did you mean 'GatewayClient'?——這是典型的 AI 杜撰 API,一定要用編譯器驗證。

Java 怎麼辦?

Java 沒有官方 WebSocket 參考用戶端;若自行實作,需完整處理 challenge 簽章、裝置配對、序號缺口(onGap)、重連後的狀態重建與 schema 驗證,成本很高。建議:

  • 一般後端整合:使用 4.2 的 HTTP API。
  • 需要即時事件:以 Node.js 執行官方 @openclaw/gateway-client 作為 sidecar,再以內部 API 或訊息佇列轉給 Java 服務。
  • 必須自行實作:以 protocol.schema.json 產生 Java 型別並在 CI 中驗證 frame,並以官方 Gateway protocol 的 wire-version 規則管理相容性。

為什麼 readiness 很重要:Gateway 重啟後,健康檢查、Agent 清單與核心控制項會先可用,catalog、插件與遷移工作則延後(見 6.11)。用戶端應在 hello-ok 之後才送出請求,並處理 startup-unavailable、restart-unavailable 這類結構化錯誤,而不是把「WebSocket 已連線」當成可用。

4.12 Managed Worktrees 與 Agent 工作目錄

讓 Agent 改程式碼時,最怕的是它直接在你的工作目錄上動手。v2026.9.x 起,OpenClaw 提供兩個互補的機制:

機制用途設定
Agent 工作目錄(cwd)讓 Agent 回合在指定目錄執行(與存放 AGENTS.md、記憶的工作區分開)agents.defaults.cwd、agents.entries.<id>.cwd(需非沙箱執行)
Managed Worktrees每個任務一條獨立 Git 分支與 checkout,不在原始 repo 中留下暫存目錄;OpenClaw 會記錄並快照worktreeRoot、worktreeMaxCount、openclaw worktrees
// openclaw.json
{
  // 新的 managed worktree 存放位置(Windows 建議放在 ReFS 磁碟以啟用 block cloning)
  worktreeRoot: "/mnt/workspaces/openclaw-worktrees",
  // 所有 Agent/repo 共用的上限(預設 4096);超過時先淘汰已合併的分支,再淘汰最舊的閒置 worktree
  worktreeMaxCount: 200,
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",   // 指令、人格與記憶
      cwd: "~/src/payments-service",        // Agent 回合實際執行的目錄
    },
  },
}
openclaw worktrees create ~/src/payments-service --name fix-refund-rounding --base-ref main
openclaw worktrees list
openclaw worktrees remove <id> --if-lossless   # 只有在不會遺失資料時才移除
openclaw worktrees restore <id>                # 從快照還原已移除的 worktree
openclaw worktrees gc                          # 清理過期的快照與模板

在 Control UI 開新對話時選 Worktree,即可讓該任務在 managed worktree 中進行;對話中可檢視 diff、執行測試,並以 Publish PR(需先確認 GitHub 發布身分,見 11.7)發出 Pull Request。

⚠️ 審查重點:

  1. 淘汰會發生:worktreeMaxCount 調低時,會立即對既有 checkout 套用淘汰政策。OpenClaw 會先快照,但仍建議把 worktrees restore 的演練納入維運手冊。
  2. cwd 與沙箱互斥:與工作區不同的 cwd 需要非沙箱執行;生產環境若要求沙箱,請改用 managed worktree(沙箱 Session 會使用私有 Git checkout 投影)。
  3. 「裝置上的既有資料夾」不是 managed worktree:在配對裝置上直接指定的資料夾,OpenClaw 不會 clone、快照或清理。

4.13 共用 Gateway 上的個人技能庫

在團隊共用的 Gateway 上,v2026.9.1 起每位經驗證的使用者可以維護自己的技能庫,不需要取得修改工作區技能或 Gateway 組態的權限。

概念說明
擁有權新技能屬於建立者;Share with team 讓其他人可用但不可編輯;管理者可 transfer to team
不可變版本(revision)每次儲存都發布一個完整版本(SKILL.md + 所有支援檔),雜湊涵蓋路徑、內容、大小與執行權限;舊版本保留供回滾
Session 鎖定版本Session 會記住它選用的技能與版本;其他人加入不會改變選擇。新版本只套用到新 Session,舊 Session 需明確 refresh
限制新 Session 最多選用 64 個技能;單一 bundle 最多 256 個檔案、單檔 1 MiB、總計 8 MiB
儲存位置中繼資料在 state/openclaw.sqlite,bundle 在 <state-dir>/skill-library/<id>/revisions/<hash>/——不要手動修改
openclaw skills library list
openclaw skills library import ./release-notes-skill.zip   # 匯入 SKILL.md 或 ZIP bundle
openclaw skills library share <skill-id>                   # 分享給團隊(唯讀)
openclaw skills library rollback <skill-id> --help         # 回滾到保留的版本
openclaw skills library remove <skill-id>                  # 不影響已選用該版本的既有 Session

⚠️ 信任邊界提醒:共用 Gateway 仍是單一信任域。技能庫的擁有權只管理「誰能編輯與發現」,不會授予新工具、憑證或主機安裝權限,也不會把技能與 Gateway 操作者隔離。不要把任何憑證寫進技能內容。共用 token 無法識別個人,個人技能庫需要經驗證的 Gateway profile(例如 11.7 的 trusted-proxy 登入)。

4.14 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1Java 整合使用 HTTP API 且固定 HTTP/1.1檢視 HttpClient.newBuilder();執行 neverSendsHttp2UpgradeHeader 測試.version(HttpClient.Version.HTTP_1_1),測試通過
2readiness 檢查 JSON 本文執行 readinessRequiresJsonReadyTrueNotJustStatus200 測試/readyz 需 ready: true 才算就緒
3契約測試與冒煙測試皆通過mvn -B test;預備環境再跑 LiveGatewaySmokeTest全部通過(無環境變數時 live 測試 Skipped)
4TypeScript 用戶端 API 存在npx tsc --noEmit --strict0 錯誤;沒有 createGatewayClient 等杜撰 API
5插件可被 OpenClaw 接受npm run plugin:validate、openclaw plugins inspect <id> --jsonPlugin <id> is valid.;安裝後為 enabled
6Webhook 使用原生 ingress 與專用 tokenopenclaw config get hooks --jsonhooks.token 與 Gateway token 不同;path 不是 /
7Code Mode 程式不猜欄位人工審查 guest JavaScript未知輸出先 results.save 或原樣回傳

第五章:企業最佳實務

5.1 技能模組化設計

技能分層架構

graph TB
    subgraph "層級 3:業務技能"
        BIZ1[報表生成]
        BIZ2[客戶服務]
        BIZ3[專案管理]
    end
    
    subgraph "層級 2:通用技能"
        UTIL1[搜尋引擎]
        UTIL2[資料轉換]
        UTIL3[通知發送]
    end
    
    subgraph "層級 1:基礎技能"
        BASE1[文字處理]
        BASE2[日期計算]
        BASE3[格式驗證]
    end
    
    BIZ1 --> UTIL1 & UTIL2 & UTIL3
    BIZ2 --> UTIL1 & UTIL3
    BIZ3 --> UTIL2 & UTIL3
    
    UTIL1 & UTIL2 & UTIL3 --> BASE1 & BASE2 & BASE3

技能設計原則

原則說明範例
單一職責每個 Skill 只負責一個領域✅ weather-skill, ❌ everything-skill
明確觸發觸發詞精確,避免衝突✅ ["天氣", "氣象"], ❌ ["查"]
最小權限工具只授予必要權限✅ 只允許讀取 API, ❌ 全部 CRUD
可組合技能之間可以互相協作報表 Skill 呼叫資料 Skill
版本管理使用語意化版本號1.0.0 → 1.1.0 → 2.0.0
文件完整README + SKILL.md 完整說明包含使用範例、限制說明

5.2 權限與存取控制

Per-Session 權限模式(v2026.8.1 新增)

2.0 讓每個 Session 各自選擇權限姿態,取代過去只能全域設定的模式。這是企業落地時最實用的控制點之一。

模式存取範圍
read-only唯讀,不可變更
guarded受保護的有限操作
workspace限於工作區範圍
full完整存取,僅限管理員

在用戶端有暴露對應控制項時,各 Session 還可個別覆寫 MCP 伺服器、技能或網頁搜尋的可用性。

⚠️ 這項設定是非回溯性的(nonretroactive)。官方明確載明:尚未設定權限模式的既有 Session,會維持先前的全域姿態。這代表升級到 2.0 之後,你不會自動獲得更嚴格的保護——既有 Session 仍沿用舊行為。企業若要落實最小權限,必須主動為既有 Session 指定模式,或建立新 Session。

⚠️ 另一項必須理解的邊界:官方聲明這些是「選用的角色(opt-in roles),用來限制單一受信任 OpenClaw 安裝內部的協作」,而不是在互相敵對的租戶之間建立隔離。詳見第十一章。

可重用的指令權限綁定

可重用的指令權限現在能綁定到確切的參數與工作目錄;腳本型指令會在執行前重新檢查當初被審閱過的位元組。

綁定的覆蓋範圍與其缺口:

  • ✅ 綁定涵蓋:已審閱的指令本身與腳本位元組。
  • ⚠️ 不涵蓋:直譯器與變動中的相依套件可能引入獨立的行為。
  • ⚠️ 不透明的包裝程式(opaque wrapper)與可能啟動其他程式的指令可能會再次詢問。

換言之,這個機制防的是「同一指令被悄悄換成不同參數」,而不是「指令所呼叫的下游相依套件被替換」。供應鏈風險需另以 9.11 的機制處理。

委派與排程工作的政策繼承

  • 排程與委派的工作會保留其發起時的政策,不會因執行環境而放寬。
  • 來自另一台機器的不確定結果會回報為 unknown,而非以猜測重試——這對稽核完整性很重要,避免把「不知道」記錄成「成功」。

DM 配對與 Agent 路由

OpenClaw 沒有全域的 security.allowedUsers。存取控制分成兩層,分別設定:

  1. 誰能跟 Bot 說話:每個頻道各自的 dmPolicy(pairing/allowlist/open/disabled)與 allowFrom,群組另有 groupPolicy 與群組設定。
  2. 訊息交給哪個 Agent:頂層 bindings[] 依頻道、帳號、群組(guild/team)、對象或角色把訊息路由到指定 Agent。
{
  channels: {
    slack: {
      botToken: "${SLACK_BOT_TOKEN}",
      appToken: "${SLACK_APP_TOKEN}",
      dmPolicy: "allowlist",
      allowFrom: ["U01ADMIN", "U02OPS"],      // Slack 使用者 ID,而非 email
    },
    telegram: { botToken: "${TELEGRAM_BOT_TOKEN}", dmPolicy: "pairing" },
  },
  agents: {
    ownership: "explicit",
    entries: {
      "admin-agent": { workspace: "~/.openclaw/workspace-admin" },
      "general-agent": { workspace: "~/.openclaw/workspace-general" },
    },
  },
  bindings: [
    // Slack 的訊息交給 admin-agent;其他頻道交給 general-agent
    { agentId: "admin-agent", match: { channel: "slack" } },
    { agentId: "general-agent", match: { channel: "telegram" } },
  ],
}

❌ 舊版範例的錯誤:security.dmPairing、security.allowedUsers(含 *@dev-team.company.com 萬用字元)、security.agentAccess。這些鍵都不存在。另外要注意:多數頻道的 allowFrom 使用平台使用者 ID(Slack U...、Telegram 數字 ID、WhatsApp 電話號碼),不是 email;以顯示名稱比對需明確開啟 dangerouslyAllowNameMatching,不建議使用。

openclaw directory peers --help    # 查詢平台使用者/群組 ID
openclaw pairing approve telegram <code>
openclaw config validate --json

權限層級設計

graph TB
    subgraph "操作者 (Operator)"
        OP[完全控制權]
    end
    
    subgraph "管理員 (Admin)"
        ADM[管理 Skills/Agents<br>檢視日誌<br>設定變更]
    end
    
    subgraph "一般使用者 (User)"
        USR[使用 Agent<br>基本對話]
    end
    
    subgraph "訪客 (Guest)"
        GST[限定 Skill<br>唯讀操作]
    end
    
    OP --> ADM --> USR --> GST

5.3 多 Agent 治理架構

Agent 命名規範

層級格式範例
組織{org}.{team}.{function}acme.devops.monitor
環境{function}-{env}monitor-prod, monitor-dev
版本{function}@{version}monitor@1.2.0

治理規則:對應到實際可設定的控制項

「治理」在 OpenClaw 中不是一個獨立的組態區塊,而是由多個子系統的政策組合而成。下表把常見的治理需求對應到真實的設定:

治理需求OpenClaw 控制項驗證方式
多 Agent 必須有明確擁有者agents.ownership: "explicit"config validate:多 Agent roster 缺少時直接報錯
只允許核准的模型agents.defaults.modelPolicy.allow/model 選不到清單外模型
每個 Agent 可見的技能agents.defaults.skills、agents.entries.<id>.skillsopenclaw skills check
技能/插件安裝需經審查security.installPolicy(以外部指令審核 skill/plugin 安裝)安裝未經核准的來源會被拒絕
只允許核准的插件plugins.allow/plugins.denyopenclaw plugins list
自我學習是否開啟skills.workshop.autonomous.mode: "off" | "auto"Workshop 變更紀錄(openclaw skills workshop changes)
工具最小權限tools.profile + allow/deny + tools.fs.workspaceOnly/tools 指令列出實際可用工具
成本掌握用量統計與告警(無內建「每日 token 上限」)openclaw gateway usage-cost --days 7
// 企業治理基準(openclaw 2026.11.1 config validate 通過)
{
  agents: {
    ownership: "explicit",
    defaults: {
      model: { primary: "anthropic/claude-opus-5-5" },
      modelPolicy: { allow: ["anthropic/*", "openai/gpt-6-astra"] },
      skills: ["github", "enterprise-reporter"],
    },
    entries: {
      assistant: {},
      "finance-bot": { skills: ["finance-report"] },
    },
  },
  skills: {
    workshop: { autonomous: { mode: "off" } },   // 受管環境:關閉背景自我學習,改由人工 /learn 起草再審查
  },
  plugins: { allow: ["ticket-lookup", "diagnostics-otel"] },
  tools: { profile: "coding", deny: ["group:nodes"], fs: { workspaceOnly: true } },
}

❌ 舊版範例的錯誤:頂層 governance 區塊(maxAgentsPerWorkspace、requireReview、maxTokenBudgetDaily 等)並不存在;config validate 會回報 Unrecognized key: "governance"。像命名規則、必填中繼資料這類 OpenClaw 不支援的規範,應改在 CI 中以自訂檢查落實(例如對 openclaw.json 跑 lint,或以 openclaw config get agents.entries --json 取出後驗證)。

⚠️ 自我學習模式只有 off 與 auto:2.0 時期的 propose 模式已不存在。auto 會在大量工作後自動儲存或更新 Workshop 技能,並封存 30 天未使用的技能;每一項變更都有紀錄且可復原(/learn undo <id>)。需要人工審查時,請設為 off 並以 /learn 主動起草待審技能。

5.4 安全強化策略

Sandbox 沙箱機制

OpenClaw 的安全模型預設信任主 Session(操作者本人),但對群組/頻道 Session 可啟用沙箱隔離:

模式說明適用場景
off所有 Session 直接在主機執行個人使用(預設)
non-main非主 Session 在 Docker 沙箱中執行群組/頻道使用(建議)
all所有 Session 都在沙箱中執行最高安全需求
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
      },
    },
  },
}

審批請求的權威性綁定(v2026.8.1)

2.0 讓每個審批請求擁有單一持久紀錄,由已授權的瀏覽器與支援的行動裝置共用。這解決了過去多裝置環境下審批狀態不一致的問題:

保證說明
首個有效回覆定案第一個有效答覆即決定結果,避免重複審批
重連無法復活已完成請求斷線重連不會讓已決定的請求重新出現
被放棄的請求會被取消不會無限期懸置
中止執行會清除其待處理審批避免遺留孤兒請求
30 天滾動歷史供事後追溯查閱

審批請求會出現在觸發它的那個對話中,其他對話則顯示安靜的提示指標。關閉審批佇列會讓請求維持待處理,而不會意外核准或拒絕——這個預設行為對避免誤操作很重要。

沙箱預設工具白名單: bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn

沙箱預設工具黑名單: browser、canvas、nodes、cron、discord、gateway

工具政策與 exec 安全模式

「限制 Agent 能用哪些工具」與「限制 shell 指令能做什麼」是兩層不同的控制,生產環境兩者都要設:

{
  tools: {
    profile: "coding",
    deny: ["browser", "gateway", "group:nodes"],   // 群組 deny 會覆蓋個別 allow
    fs: { workspaceOnly: true },
    exec: {
      host: "sandbox",        // auto | sandbox | gateway | node
      security: "allowlist",  // deny | allowlist | full
      ask: "on-miss",         // off | on-miss | always:不在 allowlist 時要求人工審批
    },
  },
  approvals: { exec: { enabled: true } },
}
設定作用常見誤用
tools.profile + allow/deny決定模型看得到哪些工具以為 full 等於完全授權(其實只是選入工具)
tools.exec.security決定 shell 指令的授權模式生產環境設成 full
tools.exec.askallowlist 未命中時是否詢問人設成 off 又搭配 allowlist,導致未列入的指令一律失敗而改用其他工具繞過
tools.fs.workspaceOnly檔案工具限縮在工作區(v2026.10.9 起也套用到 Gateway 內建工具)未開啟,Agent 可讀寫家目錄

❌ 舊版範例的錯誤:agents.defaults.trustedTools(mode: "allowlist")並不存在。「Trusted Tool Policy」是插件層級的能力(插件以 api.registerTrustedToolPolicy(...) 註冊,且需在 manifest 的 contracts.trustedToolPolicies 宣告),不是一個可直接寫在 openclaw.json 的白名單。

Session Transcript SDK(v2026.6.10 新增)

插件可透過 Plugin SDK 的 runtime 介面存取 Session 逐字稿(v2026.11.1):

  • openclaw/plugin-sdk/agent-sessions:載入既有的 SQLite 逐字稿(hydration),並以 reloadPersistedTranscriptAsync(signal?) 重新載入
  • Awaited transcript mutations:寫入逐字稿的操作需 await 完成持久化(舊的同步寫法已標示 deprecated,見官方 SDK migration「await session transcript persistence」)
  • openclaw/plugin-sdk/session-transcript-runtime 的 publishSessionTranscriptUpdateByIdentity:發布逐字稿更新通知

⚠️ 舊版手冊的 transcript.read()/append()/publish() 與 manifest permissions: ["transcript:read"] 不是實際的 SDK 介面。逐字稿 API 屬於 api.runtime 的 agent/session 介面,詳見 Plugin runtime — Agent and sessions。Incognito Session 的逐字稿不會落地。

Secret Egress Host Binding(v2026.8.1 新增)

為防止密鑰(Secret)被惡意插件或 Prompt Injection 誘導外洩至非預期目的地,v2026.8.1 引入密鑰目的地主機綁定機制:每個共用密鑰儲存區(shared secret store)中的密鑰,須明確綁定至允許存取的確切 HTTPS 目的地主機,跨 CLI、Gateway RPC、Control UI 三個介面一致強制執行。未綁定的 sentinel 替換請求會在密鑰明文外洩前直接失敗(fail closed),而非預設放行。企業導入時建議搭配 5.2 節的 Agent 存取控制與 9.2 節的 API Key 管理策略一併設定。

詳見 Security guide · Sandbox config

安全強化清單

flowchart TD
    subgraph "網路層"
        N1[TLS 加密傳輸]
        N2[防火牆規則]
        N3[VPN/零信任]
        N4[Tailscale Serve/Funnel]
    end
    
    subgraph "應用層"
        A1[API Key 輪替]
        A2[DM 配對白名單]
        A3[Skill 存取控制]
        A4[Sandbox 模式]
    end
    
    subgraph "資料層"
        D1[日誌脫敏]
        D2[密鑰加密儲存]
        D3[資料保留策略]
    end
    
    subgraph "容器層"
        C1[非 root 執行]
        C2[唯讀檔案系統]
        C3[資源限制]
    end
    
    N1 & N2 & N3 --> A1 & A2 & A3
    A1 & A2 & A3 --> D1 & D2 & D3
    D1 & D2 & D3 --> C1 & C2 & C3

Docker 安全強化範例

# docker-compose.secure.yml
services:
  openclaw:
    image: openclaw/openclaw:2026.7.1
    # 非 root 使用者
    user: "1000:1000"
    # 唯讀根檔案系統
    read_only: true
    # 臨時檔案系統
    tmpfs:
      - /tmp:noexec,nosuid,size=100m
    # 安全選項
    security_opt:
      - no-new-privileges:true
    # 資源限制
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G
          pids: 100
    # 網路隔離
    networks:
      - openclaw-internal
    # 最小化掛載
    volumes:
      - ./config:/home/openclaw/.openclaw:ro  # 唯讀設定
      - openclaw-data:/data                     # 寫入僅限資料

💡 Tailscale 整合建議 OpenClaw 原生支援 Tailscale,可透過 Tailscale Serve 在 tailnet 內安全暴露 Gateway,或透過 Tailscale Funnel 將服務公開到網際網路(自動取得 HTTPS 憑證),免去手動設定反向代理與 TLS 的複雜度。詳見第九章安全設計。

5.5 Prompt 工程最佳實務

System Prompt 結構化模板

# Agent 身份定義

你是「企業智慧助理」,專為 {company} 提供服務。

## 核心原則

1. **精確性**: 所有數據引用必須有來源
2. **安全性**: 不處理/回應密碼、金鑰等敏感資訊
3. **專業性**: 使用繁體中文,語氣專業但友善
4. **邊界**: 超出能力範圍的請求,明確告知並建議替代方案

## 回應格式

- 簡要回答置於最前
- 詳細說明使用 Markdown 格式
- 程式碼使用正確的語言標記
- 數據使用表格呈現

## 禁止事項

- 不模擬其他 AI 系統
- 不提供醫療/法律/財務建議
- 不存取或回傳使用者的敏感個人資訊
- 不執行未經授權的系統操作

Prompt 版本管理

skills/
└── enterprise-assistant/
    ├── SKILL.md               # 目前版本
    ├── SKILL.md.v1            # 版本 1 備份
    ├── SKILL.md.v2            # 版本 2 備份
    └── CHANGELOG.md           # 變更記錄

5.6 可觀測性策略

三支柱整合

graph LR
    subgraph "可觀測性三支柱"
        direction TB
        LOGS[日誌 Logs<br>JSONL + ELK]
        METRICS[指標 Metrics<br>Prometheus + Grafana]
        TRACES[追蹤 Traces<br>OpenTelemetry + Jaeger]
    end
    
    OC[OpenClaw Gateway] --> LOGS
    OC --> METRICS
    OC --> TRACES
    
    LOGS --> DASH[統一儀表板]
    METRICS --> DASH
    TRACES --> DASH

5.7 效能調校指引

關鍵效能指標

指標目標值調校方向
首次回應時間 (TTFR)< 2sLLM 模型選擇、Prompt 長度
完整回應時間< 30s串流回應、工具呼叫並行
WebSocket 延遲< 100ms網路架構、地理位置
記憶體使用< 2GB / Agent上下文裁剪、Session 清理
CPU 使用率< 70%Agent 數量、並行限制
錯誤率< 0.1%重試策略、Circuit Breaker

效能相關設定(實際可用的鍵)

{
  agents: {
    defaults: {
      // 輕量工作(命名、摘要、分類)交給較快、較便宜的模型
      utilityModel: "anthropic/claude-haiku-5-5",
      maxConcurrent: 4,          // 同時執行的 Agent 回合上限
      timeoutSeconds: 600,       // 單一回合逾時
      // 依快取 TTL 修剪舊的工具結果,降低重送的 token
      contextPruning: { mode: "cache-ttl" },
      // safeguard(預設)保留最近脈絡;可指定較便宜的模型做壓縮
      compaction: { mode: "safeguard", keepRecentTokens: 20000 },
    },
  },
  session: {
    reset: { mode: "idle", idleMinutes: 240 },     // 長時間閒置的 Session 自動重置,避免脈絡無限增長
    maintenance: { mode: "enforce", pruneAfter: "30d", maxEntries: 5000, maxDiskBytes: "10gb" },
  },
}
需求設定說明
降低簡單查詢成本agents.defaults.utilityModel背景與輔助工作改用較小模型
控制併發agents.defaults.maxConcurrent依 CPU/記憶體與 Provider 速率限制調整
控制脈絡成本contextPruning、compaction、session.reset預設 session.reset.mode 為 none,長期執行的 Agent 建議設定
控制磁碟session.maintenance先用 mode: "warn" 觀察,確認後改 enforce
降低感知延遲頻道串流設定(例如 channels.<id>.streaming)依頻道而定

❌ 舊版範例的錯誤:頂層 performance 區塊(routeSimpleQueries、context.maxMessages、tools.parallelExecution 等)並不存在。工具呼叫的並行是由模型與 runtime 決定(Code Mode 可在單一程式中以 Promise.all 並行,見 4.4),不是全域開關。

openclaw gateway usage-cost --days 7    # 用量與成本
openclaw status                          # Gateway 與頻道狀態
openclaw sessions list --all-agents --active 60

5.8 成本最佳化

LLM 成本控制策略

flowchart TD
    MSG[收到訊息] --> CLASSIFY{訊息分類}
    CLASSIFY -->|簡單查詢| FAST[使用 Claude Haiku 4.5<br>成本低]
    CLASSIFY -->|複雜推論| FULL[使用 GPT-5.6<br>成本中]
    CLASSIFY -->|程式碼生成| REASON[使用 Claude Opus 4.8<br>成本高]
    
    FAST --> CACHE{快取命中?}
    FULL --> CACHE
    REASON --> CACHE
    
    CACHE -->|是| RETURN[直接回傳快取]
    CACHE -->|否| LLM[呼叫 LLM]
    LLM --> STORE[儲存快取]
    STORE --> RETURN

成本計算範例

⚠️ 費率僅為相對量級示意:以下數字為說明「混合路由可顯著降低成本」的相對比例範例,並非官方牌價。LLM 定價變動頻繁,實際費用請以各 Provider 官方定價頁面(OpenAI、Anthropic、Zhipu 等)與 OpenClaw openclaw gateway usage-cost --days 30、openclaw models status 的實測用量為準。

模型(示意)1K 次對話/月相對成本策略
GPT-5.6高複雜任務使用
Claude Haiku 4.5低日常查詢使用
Claude Opus 4.8最高最複雜推論
GLM-5.2(開源權重)中低程式碼/長上下文,Anthropic 相容端點可直連
MiniMax M2.5低輕量級本地/雲端
Ollama / vLLM(本地)僅硬體成本隱私敏感場景
混合策略中低(顯著低於全用旗艦模型)智慧路由(推薦)

OAuth 訂閱模式: 若使用 OpenAI ChatGPT/Codex 的 OAuth 訂閱,可降低 API Key 費用。配合 OpenClaw 的 Model Failover 機制自動在 OAuth 與 API Key 間切換。

Automatic Fast Mode(v2026.6.10 新增): 短對話(少於 3 輪交互)自動使用快速模型(如 Claude Haiku 4.5)以降低成本與延遲,當對話複雜度增加時自動升級為完整模型。可透過 agentConfig.fastMode 設定啟用/停用。

Per-agent Usage-cost Reporting(v2026.6.10 新增): 每個 Agent 現可獲取獨立的 Token 使用量與費用報告,方便企業按團隊/專案分攤成本。

5.9 合規與稽核

資料保留與稽核(實際可用的鍵)

{
  logging: {
    level: "info",
    consoleStyle: "json",
    // 自訂遮罩規則會「取代」預設字串清單;內建的表單本文、結構化驗證與 AWS key 保護永遠生效
    // JSON5 字串中的反斜線要寫成 \\("\\b" 才是正規式的字邊界;"\b" 會變成 backspace 字元)
    redactPatterns: ["\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b", "\\b09\\d{8}\\b"],
    audit: {
      enabled: true,             // 記錄 run、tool 與(若啟用)訊息生命週期事件;預設 true
      executionIdentity: true,   // 保留確切執行身分,供 openclaw audit --explain 檢視
      messages: "direct",        // off | direct | all:只記錄 metadata,不記錄內容
    },
  },
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "90d",              // 超過 90 天的對話封存(可還原)
      resetArchiveRetention: "180d",  // 封存逐字稿依時間刪除(預設只依磁碟預算淘汰)
    },
  },
}
# 稽核查詢:依 Agent、時間、種類與狀態篩選(最多 500 筆一頁,可用 cursor 續查)
openclaw audit --agent finance-bot --kind tool_action --after 2026-11-01 --json
openclaw audit --execution <execution-id> --explain

⚠️ 兩個必須寫進法遵文件的限制:

  1. logging.redactPatterns 只作用於日誌與診斷;工具參數、工具結果與 Session 逐字稿不會被遮罩。個資保護需在資料進入 Agent 之前處理,或限制可存取個資的工具。
  2. 封存(archive)不是刪除:封存的對話可還原,且備份中仍有副本。完整刪除需同時處理封存、備份與 4.6 的記憶清除。

⚠️ 遮罩規則的兩個陷阱(實測):

  1. config validate 不檢查正規式本身是否合法。例如 "(?i)\\bsecret\\b" 能通過驗證,但 OpenClaw 執行於 Node.js,JavaScript 正規式不支援開頭的 (?i) 內嵌旗標(node -e "new RegExp('(?i)x')" 會拋出 Invalid group)。v2026.11.1 起無效規則會被回報且不影響其他規則,但它不會生效。
  2. JSON5 字串中的反斜線必須寫成 \\;寫成 "\b" 會得到 backspace 字元而非字邊界。

驗證方式:node -e "for (const p of ['\\\\b09\\\\d{8}\\\\b']) console.log(new RegExp(p).test('0912345678'))",並在測試環境送一則含假 email 的訊息,確認日誌中已被遮罩。

❌ 舊版範例的錯誤:頂層 compliance 區塊(dataRetention、pii.maskInLogs、audit.events)並不存在;請使用上方的 logging.* 與 session.maintenance.*。

Incognito 模式的合規邊界(v2026.8.1)

2.0 引入 Incognito 對話。它預設關閉,且範圍刻意設計得比一般理解的「無痕」更窄。在法遵評估時,必須以「它不保證什麼」為準,而非以名稱推測。

Incognito 確實做到Incognito 不會做到
對話保存在行程記憶體中❌ Model Provider 仍然收到訊息
不寫入一般逐字稿❌ 工具仍可寫入檔案或影響外部服務
不寫入自動的 OpenClaw 記憶到磁碟❌ 不含內容的稽核 metadata 仍會保留
Gateway 重啟後即消失❌ 操作 Gateway 的人仍可看到進行中的工作

⚠️ 對合規的意涵:Incognito 不能被當作「資料不出境」「不留痕跡」或「符合特定資料刪除要求」的技術控制。它降低的是本機持久化的範圍,而非資料處理者的接觸範圍。若你的法遵要求涵蓋 Model Provider 端的資料處理,Incognito 完全不影響該面向——那需要透過 Provider 選擇、資料處理協議與部署位置來處理。

記憶清除與可稽核性的落差

在設計資料刪除流程時,需理解 openclaw memory forget 的能力邊界(詳見 4.6)。它依 provenance 清除可歸屬的衍生記憶,但原始逐字稿、無血緣資訊的舊筆記、其他 Agent 的儲存、直接或外部寫入、匯出與備份可能仍然存在。

企業建議:將「記憶清除」與「備份與匯出清理」視為兩道必須分別執行的程序。僅執行前者不足以構成完整的刪除證據。

5.10 團隊協作規範

Git 分支策略

main           ─── 正式環境組態
├── develop    ─── 開發環境組態
│   ├── feature/new-skill-weather    ─── 新技能開發
│   ├── feature/improve-prompt       ─── Prompt 改善
│   └── fix/timeout-issue            ─── 問題修復
├── staging    ─── 預備環境組態
└── release/v2.1.0   ─── 發布版本

Code Review 檢查項

  • SKILL.md 格式正確且包含所有必要欄位
  • 觸發詞不與現有 Skill 衝突
  • 工具定義包含完整的參數描述
  • 存取控制設定符合最小權限原則
  • Prompt 不包含硬編碼的敏感資訊
  • 已新增對應的測試案例
  • README.md 已更新使用說明
  • CHANGELOG.md 已記錄變更

5.11 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1沒有杜撰的治理區塊openclaw config validate --json無 governance、performance、compliance、security.allowedUsers 等鍵
2DM 與路由政策檢視 channels.*.dmPolicy、allowFrom、bindingsallowFrom 使用平台使用者 ID;路由規則可追溯
3exec 與檔案政策請 Agent 執行未列入 allowlist 的指令、讀取 ~/.ssh前者觸發審批,後者被拒
4自我學習模式明確設定openclaw config get skills.workshop.autonomous.mode受管環境為 off
5稽核可查openclaw audit --kind tool_action --limit 20 --json看得到工具呼叫事件與執行身分
6保存政策與法遵說法一致比對 session.maintenance、logging.redactPatterns 與法遵文件不宣稱逐字稿已遮罩;封存不等於刪除

第六章:系統維運與監控

6.1 健康檢查機制

OpenClaw 提供多層級健康檢查端點:

端點說明

端點方法說明回應碼
/healthzGET基本存活檢查(Liveness)200 / 503
/readyzGET就緒檢查(Readiness)200 / 503
openclaw doctorCLI一站式環境診斷(推薦)-
openclaw doctor --deepCLI深度診斷(含網路延遲與模型測試)-
openclaw healthCLI完整健康檢查-
openclaw statusCLI運行狀態-
/metricsHTTPPrometheus 指標端點(v2026.4.25 新增)200
/statusChat在對話中查詢系統狀態-

健康檢查回應格式

{
  "status": "healthy",
  "version": "2026.7.1",
  "uptime": "3d 14h 22m",
  "checks": {
    "gateway": {
      "status": "healthy",
      "port": 18789,
      "connections": 3
    },
    "agentRuntime": {
      "status": "healthy",
      "agentCount": 2,
      "activeSkills": 8
    },
    "channels": {
      "whatsapp": {"status": "connected", "latency": "45ms"},
      "telegram": {"status": "connected", "latency": "32ms"},
      "slack": {"status": "disconnected", "error": "token expired"}
    },
    "models": {
      "default": {"status": "reachable", "latency": "120ms"},
      "fast": {"status": "reachable", "latency": "85ms"}
    }
  },
  "timestamp": "2026-03-05T10:30:00Z"
}

Java 健康檢查客戶端

package com.tutorial.openclaw.health;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

/**
 * OpenClaw 健康檢查客戶端。
 *
 * <p>定期檢查 OpenClaw Gateway 的健康狀態,
 * 並在異常時觸發告警。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class HealthChecker {

    private static final Logger logger = LogManager.getLogger(HealthChecker.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();

    private final HttpClient httpClient;
    private final String baseUrl;

    /**
     * 建立健康檢查器。
     *
     * @param gatewayHost OpenClaw Gateway 主機(例如 localhost)
     * @param gatewayPort OpenClaw Gateway 埠(預設 18789)
     */
    public HealthChecker(String gatewayHost, int gatewayPort) {
        this.baseUrl = String.format("http://%s:%d", gatewayHost, gatewayPort);
        this.httpClient = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();
    }

    /**
     * 執行存活檢查(Liveness Check)。
     *
     * @return true 如果 Gateway 存活
     */
    public boolean isAlive() {
        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(baseUrl + "/healthz"))
                    .timeout(Duration.ofSeconds(5))
                    .GET()
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());
            boolean alive = response.statusCode() == 200;
            logger.debug("Liveness check: {}", alive ? "PASS" : "FAIL");
            return alive;
        } catch (Exception e) {
            logger.warn("Liveness check 失敗: {}", e.getMessage());
            return false;
        }
    }

    /**
     * 執行就緒檢查(Readiness Check)。
     *
     * @return true 如果 Gateway 就緒
     */
    public boolean isReady() {
        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(baseUrl + "/readyz"))
                    .timeout(Duration.ofSeconds(5))
                    .GET()
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());
            boolean ready = response.statusCode() == 200;
            logger.debug("Readiness check: {}", ready ? "PASS" : "FAIL");
            return ready;
        } catch (Exception e) {
            logger.warn("Readiness check 失敗: {}", e.getMessage());
            return false;
        }
    }

    /**
     * 執行深度健康檢查。
     *
     * @return 詳細的健康狀態資訊
     */
    public Map<String, Object> deepCheck() {
        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(baseUrl + "/healthz"))
                    .timeout(Duration.ofSeconds(10))
                    .GET()
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());
            JsonNode json = MAPPER.readTree(response.body());

            return Map.of(
                    "status", json.path("status").asText(),
                    "version", json.path("version").asText(),
                    "uptime", json.path("uptime").asText(),
                    "httpStatus", response.statusCode(),
                    "checks", MAPPER.convertValue(
                            json.path("checks"), Map.class)
            );
        } catch (Exception e) {
            logger.error("深度健康檢查失敗", e);
            return Map.of(
                    "status", "unreachable",
                    "error", e.getMessage()
            );
        }
    }
}

6.2 結構化日誌系統

OpenClaw 使用 JSONL(JSON Lines)格式輸出結構化日誌。

日誌格式

{"level":"info","ts":"2026-04-12T10:30:00.123Z","msg":"Gateway 已啟動","port":18789,"version":"2026.4.11"}
{"level":"info","ts":"2026-03-05T10:30:01.456Z","msg":"頻道已連線","channel":"whatsapp","latency_ms":45}
{"level":"info","ts":"2026-03-05T10:30:05.789Z","msg":"收到訊息","channel":"telegram","user":"user123","session":"sess_abc"}
{"level":"debug","ts":"2026-03-05T10:30:06.012Z","msg":"Skill 匹配","skill":"weather","confidence":0.95}
{"level":"info","ts":"2026-03-05T10:30:08.345Z","msg":"LLM 呼叫完成","model":"gpt-5.6","tokens_in":250,"tokens_out":180,"latency_ms":2341}
{"level":"info","ts":"2026-03-05T10:30:08.567Z","msg":"回應已傳送","channel":"telegram","user":"user123","latency_ms":2562}

日誌級別

級別說明使用場景
trace最詳細除錯 Wire Protocol
debug除錯資訊開發環境除錯
info一般資訊生產環境預設
warn警告非致命錯誤
error錯誤需要關注的問題

日誌組態

{
  logging: {
    level: "info",                              // 檔案與主要輸出門檻:silent | fatal | error | warn | info | debug | trace
    consoleLevel: "warn",                       // 主控台可另設較高門檻
    consoleStyle: "json",                       // pretty | json(機器解析用 json)
    file: "~/.openclaw/logs/openclaw.jsonl",
    maxFileBytes: 104857600,                    // 單檔上限(100 MiB)
  },
}

❌ 舊版範例的錯誤:logging.format、logging.console、logging.rotation(maxSize/maxFiles/compress)都不存在。長期保存與輪替請交給外部的日誌收集(OTel logs 匯出,或 logrotate/Fluent Bit 收集 JSONL 檔),見 6.3 與 6.9。

openclaw logs --follow --json      # 透過 Gateway RPC 追蹤日誌
openclaw logs --limit 200 --plain

6.3 OpenTelemetry 整合

OpenClaw 透過官方 diagnostics-otel 插件(官方 Docker 映像已內建)以 OTLP/HTTP 主動外送 traces、metrics 與 logs;另有 diagnostics-prometheus 插件提供受驗證保護的 Prometheus 端點(見 6.4)。

OTEL 組態

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",      // 未設定時退回 OTEL_SERVICE_NAME,再退回 "openclaw"
      headers: { "x-collector-token": "${OTEL_COLLECTOR_TOKEN}" },
      traces: true,
      metrics: true,
      logs: true,
      logsExporter: "otlp",                 // otlp | stdout | both
      sampleRate: 0.2,                      // root span 取樣率 0.0–1.0
      flushIntervalMs: 60000,               // metrics 匯出間隔(最小 1000 ms)
      captureContent: false,                // 不要把訊息內容送進遙測(個資)
    },
  },
}

❌ 舊版範例的錯誤:telemetry.exporter、telemetry.serviceName、telemetry.resource 並不存在——telemetry 是匿名使用遙測的同意設定(enabled、consentedAt),與 OpenTelemetry 無關。OTel 一律設定在 diagnostics.otel。

⚠️ captureContent 保持 false:開啟後 span 會帶上訊息與工具內容,等同把對話資料複製到觀測平台。

OpenTelemetry Collector 組態

# otel-config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"
      grpc:
        endpoint: "0.0.0.0:4317"

processors:
  batch:
    timeout: 10s
    send_batch_size: 1024
  
  memory_limiter:
    check_interval: 1s
    limit_mib: 512

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    namespace: "openclaw"
  
  otlp/jaeger:
    endpoint: "jaeger:4317"
    tls:
      insecure: true
  
  # 舊版的 logging exporter 已自 Collector 移除,改用 debug exporter
  debug:
    verbosity: basic

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp/jaeger]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

6.4 Metrics 指標監控

關鍵指標(diagnostics-prometheus 匯出,節錄)

指標名稱類型用途
openclaw_message_received_total/openclaw_message_processed_totalCounter進線與處理完成的訊息數
openclaw_message_processed_duration_secondsHistogram訊息處理時間
openclaw_model_call_total/openclaw_model_call_duration_secondsCounter/Histogram模型呼叫次數與延遲
openclaw_model_tokens_total/openclaw_model_cost_usd_totalCounterToken 用量與估算成本
openclaw_model_failover_totalCounter模型失效轉移次數(Provider 健康的先行指標)
openclaw_tool_execution_total/openclaw_tool_execution_duration_secondsCounter/Histogram工具執行次數與時間
openclaw_tool_execution_blocked_totalCounter被政策擋下的工具呼叫(資安訊號)
openclaw_sessions_active/openclaw_session_stuck_totalGauge/Counter活躍 Session 與卡住的 Session
openclaw_gateway_event_loop_delay_max_secondsGaugeGateway 事件迴圈延遲(回應變慢的根因之一)
openclaw_secret_egress_requests_totalCountersecret egress proxy 請求(含被拒絕者)
openclaw_webhook_received_total/openclaw_webhook_error_totalCounterWebhook ingress 健康度
openclaw_gateway_build_infoGauge執行中的版本(升級稽核)

完整清單見官方 Prometheus metrics。

啟用與 Prometheus 抓取組態

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
openclaw plugins enable diagnostics-prometheus
openclaw gateway restart

# 端點需要 Gateway 驗證,且呼叫者需具備 operator.read
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" http://127.0.0.1:18789/api/diagnostics/prometheus | head
# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]

❌ 舊版範例的錯誤:metrics_path: "/metrics",以及 openclaw_messages_by_channel、openclaw_llm_cost_usd、openclaw_active_sessions 等指標名稱。OpenClaw 的 Prometheus 路由是 /api/diagnostics/prometheus,而且需要驗證;未帶 token 的 scrape 會失敗。

驗證要分兩層:promtool check config prometheus.yml 只驗證語法——實測舊版 metrics_path: "/metrics" 的設定檔同樣會顯示 SUCCESS。路徑與驗證是否正確,必須再以上面的 curl 實際抓一次,並在 Prometheus 的 Targets 頁面確認狀態為 UP。

6.5 分散式追蹤

追蹤流程

sequenceDiagram
    participant User
    participant GW as Gateway
    participant SK as Skill Engine
    participant LLM as LLM Provider
    participant Tool as Tool Service

    Note over GW: Trace ID: abc-123
    User->>GW: 發送訊息
    Note over GW: Span: gateway.receive
    GW->>SK: 路由到 Skill
    Note over SK: Span: skill.resolve
    SK->>LLM: 呼叫 LLM
    Note over LLM: Span: llm.inference
    LLM-->>SK: tool_call
    SK->>Tool: 執行工具
    Note over Tool: Span: tool.execute
    Tool-->>SK: 工具結果
    SK->>LLM: 送回結果
    LLM-->>SK: 最終回應
    SK-->>GW: Agent 回應
    Note over GW: Span: gateway.respond
    GW-->>User: 回傳訊息
    Note over GW: Trace 完成

6.6 告警策略設計

告警規則

# alerting-rules.yml
groups:
  - name: openclaw-alerts
    rules:
      # 高錯誤率告警
      - alert: HighErrorRate
        expr: |
          rate(openclaw_errors_total[5m]) /
          rate(openclaw_messages_total[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "OpenClaw 錯誤率過高"
          description: "過去 5 分鐘錯誤率超過 5%"

      # 高延遲告警
      - alert: HighResponseLatency
        expr: |
          histogram_quantile(0.95,
            rate(openclaw_response_duration_seconds_bucket[5m]))
          > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "OpenClaw 回應延遲過高"
          description: "P95 回應時間超過 10 秒"

      # 頻道斷線告警
      - alert: ChannelDisconnected
        expr: openclaw_channel_connections == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "OpenClaw 頻道已斷線"

      # LLM 成本超標
      - alert: HighLLMCost
        expr: |
          increase(openclaw_llm_cost_usd[24h]) > 100
        labels:
          severity: warning
        annotations:
          summary: "OpenClaw 24 小時 LLM 成本超過 $100"

      # Gateway 無回應
      - alert: GatewayDown
        expr: up{job="openclaw"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "OpenClaw Gateway 無回應"

6.7 備份與災難復原

Session 與 Transcript 改存 SQLite(見 2.11)之後,直接複製目錄已不是可靠的備份方式(可能拿到 WAL 尚未合併的不一致狀態)。v2026.11.1 的官方備份工具鏈依需求分成五條路徑:

需求指令/工具RPO(可接受資料遺失)說明
一次性完整備份(state + 工作區)openclaw backup create上次備份時間點升級前必做
單一資料庫、壓縮且驗證openclaw backup sqlite create上次快照針對特定 Agent 資料庫
版本化、依內容增量openclaw backup git create上次提交可推送到私有 Git(推送時會遮罩憑證)
定期異地備份openclaw backup enable --to <location>排程間隔外接磁碟、NAS、Cloudflare R2(v2026.10.1 起)
持續複寫(秒級)Litestream(外部常駐程式)數秒只複寫資料庫;組態、憑證檔與工作區仍需上面的檔案型路徑

建立、驗證、還原

openclaw backup create --verify                    # 建立並立即驗證
openclaw backup list
openclaw backup verify <archive>
openclaw backup restore <archive> --target /srv/openclaw-restore   # 只能還原到全新目錄

還原的安全預設:restore 拒絕覆寫既有目標。災難復原程序必須規劃「乾淨的還原目的地」,而不是就地覆蓋;還原後再切換服務指向新目錄。

異地備份與排程(v2026.10.1 起)

// openclaw.json:命名儲存位置(filesystem 為內建;R2 由 Cloudflare 插件提供)
{
  storage: {
    locations: {
      offsite: {
        provider: "filesystem",
        settings: { path: "/mnt/nas/openclaw-backups" },
        // 上傳內容加密;passphrase 用 SecretRef,遺失 passphrase 等於遺失備份
        encryption: { passphrase: { source: "env", provider: "default", id: "OPENCLAW_STORAGE_PASSPHRASE" } },
      },
    },
  },
}
openclaw storage init offsite            # 明確初始化目的地(runtime 備份永遠不會自動初始化)
openclaw storage test offsite
openclaw backup create --to offsite --namespace gateway-prod --keep-daily 7 --keep-weekly 4 --keep-monthly 12
openclaw backup enable --to offsite --namespace gateway-prod --every 24h --keep-daily 7 --keep-weekly 4 --keep-monthly 12
openclaw backup verify --from offsite --namespace gateway-prod latest
openclaw status                           # 顯示最近一次備份與異地結果;超過三個排程週期未成功會標示

⚠️ 兩個常被忽略的細節:

  1. 命名空間:多台 Gateway 共用同一個目的地時,每台都要指定不同的 --namespace(預設為主機名稱)。
  2. 本地副本是明文:加上 --output 保留的本地 .tar.gz 即使目的地有加密,本身仍是明文,兩邊都要保護。

持續複寫(Litestream)

# litestream.yml — 複寫控制面資料庫與一個 Agent 資料庫到 S3 相容儲存
dbs:
  - path: /home/openclaw/.openclaw/state/openclaw.sqlite
    replicas:
      - url: s3://openclaw-backups/state
  - path: /home/openclaw/.openclaw/agents/main/agent/openclaw-agent.sqlite
    replicas:
      - url: s3://openclaw-backups/agents/main
litestream replicate -config /etc/litestream.yml        # 由 systemd 等服務管理器常駐
litestream restore -o ./restored-openclaw.sqlite s3://openclaw-backups/state

Litestream 唯一的硬性需求是 WAL 模式:OpenClaw 在本機檔案系統上使用 WAL,但在 NFS/SMB 等網路儲存上會退回 rollback journal,請先以 PRAGMA journal_mode; 確認。

備份不涵蓋的範圍

項目處理方式
受管理的 dev/ checkout、本地原始碼修改另行以 Git 推送或檔案備份
Managed worktree 中未提交的變更OpenClaw 會快照,但仍建議定期推送分支(4.12)
外部系統(Provider 端資料、頻道平台的訊息)依各平台的保存政策
PostgreSQL 引擎的 Workboardopenclaw backup 會處理 schema 與 SQLite anchor;自行 pg_dump 時不可遺漏 anchor(2.12)

重設與解除安裝的保護機制

openclaw reset 與 openclaw uninstall 拒絕在下列條件成立前移除資料:①Gateway 服務已被拆除;②OpenClaw 能確認沒有其他行程擁有該狀態。檢查失敗時狀態會原地保留;僅移除狀態的解除安裝不會動到已設定的工作區。先用 openclaw reset --dry-run 預覽影響範圍。

復原流程與演練

flowchart TD
    START[偵測到故障] --> ASSESS[評估損害範圍]
    ASSESS --> STOP["停止 Gateway<br/>openclaw gateway stop"]
    STOP --> RESTORE{選擇復原來源}
    RESTORE -->|組態損壞| CONFIG["config 的 .bak 輪替備份<br/>或 Git 備份"]
    RESTORE -->|資料庫毀損| SNAP["backup sqlite restore<br/>或 litestream restore"]
    RESTORE -->|主機毀損| FULL["backup restore --target 全新目錄<br/>(備援主機)"]
    CONFIG & SNAP & FULL --> VALIDATE["openclaw config validate --json<br/>openclaw doctor"]
    VALIDATE --> RESTART["openclaw gateway start"]
    RESTART --> VERIFY["/readyz 200、openclaw status、<br/>抽查 3 個 Session 歷史"]
    VERIFY -->|通過| DONE[復原完成,記錄 RTO/RPO]
    VERIFY -->|失敗| ASSESS

演練要求:至少每季在備援環境做一次完整還原,記錄實際 RTO(恢復時間)與 RPO(資料遺失量)。沒有演練過的備份,不能算是備份。

6.8 容量規劃

資源需求計算

維度計算公式範例
記憶體基礎(512MB) + 每Agent(256MB) × Agent數2 Agent = 1GB
CPU基礎(0.5核) + 每Agent(0.25核) × Agent數2 Agent = 1核
磁碟基礎(1GB) + 日誌速率 × 保留天數10MB/天 × 90天 = ~2GB
網路每訊息(~2KB) × 日訊息數 × 2(雙向)1000 msg/天 = ~4MB/天
LLM Token每訊息平均Token × 日訊息數500 token × 1000 = 500K/天

6.9 日誌聚合與分析

ELK Stack 整合

# filebeat.yml - 收集 OpenClaw JSONL 日誌
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /root/.openclaw/logs/openclaw.jsonl
    json.keys_under_root: true
    json.overwrite_keys: true
    json.add_error_key: true
    json.expand_keys: true

output.elasticsearch:
  hosts: ["elasticsearch:9200"]
  index: "openclaw-%{+yyyy.MM.dd}"

setup.kibana:
  host: "kibana:5601"

6.10 Grafana 儀表板範例

主要面板

{
  "dashboard": {
    "title": "OpenClaw Gateway 監控",
    "panels": [
      {
        "title": "訊息吞吐量",
        "type": "timeseries",
        "targets": [{
          "expr": "rate(openclaw_messages_total[5m])"
        }]
      },
      {
        "title": "回應時間 P50/P95/P99",
        "type": "timeseries",
        "targets": [
          {"expr": "histogram_quantile(0.50, rate(openclaw_response_duration_seconds_bucket[5m]))"},
          {"expr": "histogram_quantile(0.95, rate(openclaw_response_duration_seconds_bucket[5m]))"},
          {"expr": "histogram_quantile(0.99, rate(openclaw_response_duration_seconds_bucket[5m]))"}
        ]
      },
      {
        "title": "頻道連線狀態",
        "type": "stat",
        "targets": [{
          "expr": "openclaw_channel_connections"
        }]
      },
      {
        "title": "LLM Token 使用量",
        "type": "timeseries",
        "targets": [{
          "expr": "increase(openclaw_llm_tokens_total[1h])"
        }]
      },
      {
        "title": "活躍 Session 數",
        "type": "gauge",
        "targets": [{
          "expr": "openclaw_active_sessions"
        }]
      },
      {
        "title": "錯誤率",
        "type": "stat",
        "targets": [{
          "expr": "rate(openclaw_errors_total[5m]) / rate(openclaw_messages_total[5m]) * 100"
        }]
      }
    ]
  }
}

6.11 Gateway 重啟復原(v2026.8.1 新增)

2.0 為 Gateway 重啟建立了明確的復原契約。理解它保證什麼、以及邊界在哪裡,是規劃維護窗口的前提。

Suspend / Resume 與 Drain

在支援的快照或目標式重啟之前,Gateway 的 suspend 與 resume 可以:

  1. 暫停新的一般工作;
  2. 回報阻礙項目(blockers);
  3. 排空(drain)OpenClaw 已追蹤的:Agent 執行、傳遞、排程工作、佇列、Session 與背景指令。
sequenceDiagram
    participant OP as 維運人員
    participant GW as Gateway
    participant W as 進行中工作

    OP->>GW: suspend
    GW-->>OP: 回報 blockers
    GW->>W: 停止受理新工作
    W-->>GW: 已追蹤工作陸續完成(drain)
    OP->>GW: 重啟
    GW-->>OP: 健康檢查/Agent 清單/核心控制項先可用
    Note over GW: catalog/plugin/migration 延後執行
    GW->>W: 恢復受理

其他保證:

  • 失敗的組態重載會保留先前的一致狀態(不會半套用)。
  • 快速連續的組態寫入會保留待處理的重啟意圖,不會被丟棄。

重啟後的可用性順序

重啟之後,健康檢查、Agent 清單與核心控制項會先變為可用,而選用的 catalog、插件與遷移工作則延後而非移除。

實務影響:因為 catalog 工作被延後,第一個明確的 catalog 請求仍可能耗時較久。監控告警的門檻設定應考慮這段暖機期,否則會產生假警報。用戶端則應明確等待 readiness 訊號(見 4.11)。

⚠️ 復原邊界之外的項目(規劃維護窗口時必讀)

官方明確載明,上述等待僅涵蓋 OpenClaw 所追蹤的工作。以下項目不在復原邊界內:

不在復原範圍內意涵
新的頻道或外部 ingress重啟期間抵達的外部請求不受保護
既有的插件連線需自行重新建立
未註冊的背景工作OpenClaw 不知道它的存在,無法排空
傳入訊息的持久化收訖(durable receipt)不保證重啟期間的訊息不遺失
外部監管的安裝必須自行消費交接訊號並完成其重啟

對高可用設計的意涵:若你的場景不能容許重啟期間的訊息遺失,必須在 OpenClaw 之外建立訊息緩衝層(例如訊息佇列),而不能依賴 Gateway 的重啟復原機制。這是 2.9 高可用架構設計中最容易被高估的一環。

自動化的重啟復原

自動化排程有其獨立的復原邏輯,會區分「真正錯過的工作」與「已完成或已不屬於當前自動化的工作」:

會恢復不會恢復(維持退休)
佇列中與延後的執行已完成的時段
重新排程的一次性提醒已刪除或已退休的工作
重啟或時鐘變更期間錯過的排程時間舊的排程、來自已被替換的排程器的工作

⚠️ exactly-once 不在保證範圍內:舊版的執行中標記會維持中斷狀態,因為系統無法確認外部副作用是否已經發生。官方明確聲明「外部系統中的 exactly-once 執行仍在排程器的復原邊界之外」。若自動化會觸發不可重複的外部操作(付款、發信、建立資源),冪等性必須由你的外部系統自行保證。

6.12 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1日誌與 OTel 鍵正確openclaw config validate --json使用 logging.consoleStyle、diagnostics.otel.*
2Prometheus 抓得到資料帶 token 對 /api/diagnostics/prometheus 執行 curl;檢查 Prometheus Targets回傳 openclaw_* 指標;Target 為 UP
3prometheus.yml 語法與語意promtool check config 加上實際 curl語法 SUCCESS,且路徑為 /api/diagnostics/prometheus
4備份可驗證openclaw backup verify --from offsite --namespace <ns> latest驗證通過
5還原演練在備援環境 openclaw backup restore <archive> --target <新目錄> 並啟動記錄 RTO/RPO;抽查 Session 歷史正確
6probe 不被 catch-all 騙過對 /no-such-route 執行 probe 腳本probe 回報失敗

第七章:系統升級策略

7.1 版本命名規則

OpenClaw 採用 日曆版本號(CalVer)格式,Git tag 帶有 v 前綴:

vYYYY.M.D
vYYYY.M.D-<patch>      # 同日修補時附加後綴
欄位說明範例
v版本前綴v
YYYY年份2026
M月份(無前導零)3
D日期23
patch同日修補後綴(選用)1, 2, …

完整版本範例:v2026.7.1(2026 年 7 月 13 日發布) 同日修補範例:v2026.7.1-2(同日第 2 次修補)

發布頻道

OpenClaw 實際提供四個發布頻道(Development Channels),較早期文件常見的「stable/beta/dev 三頻道」說法已不完整——v2026.6 起新增 extended-stable 頻道:

頻道說明適用場景
stable正式穩定版(預設),經 beta 週期驗證後發布一般生產環境
extended-stable每月一條的 LTS 等價線:版本號以 YYYY.M.33 起跳,內容是「該月月底的 OpenClaw + 關鍵安全、可靠性與效能修補,以及新模型支援」,僅提供 Gateway 套件、只能前景安裝、永不自動套用。2026-11-08 的 extended-stable 指向 2026.9.36(九月線)對變更敏感、追求最大穩定性的正式環境
beta公開測試版,每週多次發布Staging / 搶先預覽新功能
devmain 分支開發版(含未完成功能與可能的破壞性變更)開發者測試、貢獻者
# 切換頻道
openclaw update --channel stable
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev

# 預覽將執行的更新動作(不實際套用)
openclaw update --dry-run

# 查看目前頻道與可用版本狀態
openclaw update status --json

# 查看當前版本
openclaw --version

企業建議:一般正式環境建議採用 extended-stable 頻道,兼顧安全修補即時性與功能變更的最小化;若需要最新功能且能承受較高變更頻率,可評估 stable 頻道並搭配第 7.2~7.3 節的升級前評估與滾動升級流程。

版本生命週期

graph LR
    DEV[dev<br/>main 分支] --> BETA[beta<br/>預覽與驗證]
    BETA -->|不改版號直接升格| STABLE[stable<br/>npm latest]
    STABLE -->|每月月底快照| EXT["extended-stable<br/>YYYY.M.33+<br/>(僅 Gateway)"]
    EXT -->|安全/可靠性回補<br/>與新模型支援| EXT

⚠️ 官方沒有公布固定的支援終止期限(例如「下一版後 3 個月」)。企業應以 extended-stable dist-tag 實際指向的月線為準,並追蹤官方 Extended-Stable 公告 與安全公告(9.12)。

7.2 升級前評估

相容性檢查矩陣

元件向後相容向前相容注意事項
openclaw.json5✅⚠️新欄位被舊版忽略
SKILL.md✅✅AgentSkills 規格穩定
WebSocket API✅❌主版號升級可能不相容
CLI 指令✅⚠️旗標可能新增或棄用
頻道連接器✅❌依賴第三方 API 變更

升級前檢查清單

# 1. 目前版本、通道與可用更新
openclaw --version
openclaw update status --json

# 2. 閱讀目標版本的發布說明(人讀)與 changelog(給 AI/工具讀的純文字)
#    https://docs.openclaw.ai/releases/<版本>
#    https://raw.githubusercontent.com/openclaw/openclaw/main/CHANGELOG/<版本>.md

# 3. 建立並驗證備份(不要用 cp -r 複製 ~/.openclaw)
openclaw backup create --verify

# 4. 預覽升級路徑:不改變組態、交接、清理或重啟狀態
openclaw update --tag 2026.11.1 --dry-run --json

# 5. 在測試環境以相同組態驗證(容器映像精確釘選版本)
docker run --rm -v "$PWD/config:/home/node/.openclaw:ro" \
  ghcr.io/openclaw/openclaw:2026.11.1 node dist/index.js config validate --json

7.3 升級的停機時間與「滾動升級」的真相

由於一個 state 目錄同一時間只能有一個 Gateway 擁有者(2.9),單一 Gateway 無法做到傳統意義的零停機滾動升級。正確的期待與做法如下:

你以為的實際上建議做法
多個實例輪流升級同一份 state 不能同時被兩個 Gateway 擁有單一 Gateway:安排維護窗口;多個獨立 Gateway:一個一個升級
升級時對話會中斷Gateway 會 drain 進行中的工作,重啟後恢復已受理的回覆升級前用 openclaw gateway suspend --wait 主動暫停並等待排空
失敗就要手動回滾openclaw update 會先在隔離的候選狀態預演,Doctor 失敗會自動回滾讓官方更新器處理;只在它回報無法自動恢復時才介入(7.4)

單一 Gateway(npm/套件安裝)

openclaw backup create --verify
openclaw gateway suspend --wait --json            # 暫停受理新工作並等待排空;記下回傳的 suspensionId
openclaw update --tag 2026.11.1 --yes             # 預演 → 啟用 → Doctor 驗證;失敗會自動回滾
openclaw gateway status --deep                    # 確認服務已回到運作狀態
openclaw doctor                                   # 檢查遷移與殘留問題

容器部署

openclaw backup create --verify                   # 或以 docker compose exec 在容器內執行
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.11.1"
docker compose pull openclaw-gateway
docker compose up -d openclaw-gateway             # 官方 entrypoint 會在啟動前執行必要的 Doctor 修復
until curl -sf http://127.0.0.1:18789/readyz; do sleep 2; done   # 用 readyz 而非 healthz 判斷可用
docker compose exec openclaw-gateway node dist/index.js --version

多個獨立 Gateway 的分階段升級

flowchart TD
    START[新版發布] --> BETA["預備環境 Gateway<br/>(beta 或目標版本)"]
    BETA --> V1{"config validate、doctor、<br/>回歸對話測試通過?"}
    V1 -->|否| HOLD[暫緩並回報]
    V1 -->|是| PILOT["試點 Gateway<br/>(一個部門)"]
    PILOT --> MON["觀察 24–72 小時<br/>錯誤率、model_failover、session_stuck"]
    MON --> V2{指標正常?}
    V2 -->|否| ROLLBACK["回滾該 Gateway(7.4)"]
    V2 -->|是| REST["依序升級其餘 Gateway<br/>一次一個"]
    REST --> DONE[完成並記錄]

傳統的「Canary 10% 流量」在 OpenClaw 中以 Gateway 為單位實現:挑一個信任域(例如一個部門的 Gateway)先升級,而不是把同一批使用者的流量切分到兩個版本。

7.4 回滾策略

回滾分三個層級,由淺到深:

層級情境做法
1. 自動回滾更新後 Doctor 驗證失敗openclaw update 會自動回滾並保留組態與密鑰參照;npm 回滾在 Windows 也會重試暫時性拒絕
2. 修復未完成的更新更新器崩潰、取消、主機重開機openclaw update recover、openclaw update repair;之後 openclaw doctor --fix
3. 降版新版有無法接受的行為受 SQLite schema 遷移限制,必須從遷移前的備份還原到全新目錄(見附錄 E.3)
# 層級 2:恢復被中斷的更新
openclaw update status
openclaw update recover --json
openclaw update repair --yes
openclaw doctor --fix

# 層級 3:降版(npm 安裝)
openclaw gateway stop
npm install -g openclaw@2026.9.36 --allow-scripts=openclaw     # 例如退回 extended-stable
openclaw backup restore <遷移前的備份> --target /srv/openclaw-state-rollback
OPENCLAW_STATE_DIR=/srv/openclaw-state-rollback openclaw gateway install --force
openclaw gateway start

# 容器:把 OPENCLAW_IMAGE 改回原版本,並掛載還原後的 state 目錄

⚠️ 不要在新版改過的資料庫上直接跑舊版 binary。v2026.11.1 起,舊版 binary 遇到較新的組態會說明恢復方式;但資料庫 schema 已前進時,唯一安全的路徑是「相容的備份 + 全新目錄」。v2026.8.2 的 openclaw update cleanup 會永久刪除遷移原件——執行前先 --dry-run,並確認已有可還原的備份。

7.5 組態遷移

自動遷移

❌ OpenClaw 沒有 openclaw config migrate 指令。組態遷移由 Doctor 統一處理:一般的 openclaw update 會自動執行;手動替換安裝(例如直接 npm install -g)或自訂容器 entrypoint 則必須自己執行:

openclaw config validate --json     # 先看哪些鍵已退休或不合法
openclaw doctor --fix               # 套用遷移(只有整份遷移後組態都通過驗證才會寫入,並保留 .bak)
openclaw config validate --json     # 再驗證一次

v2026.8.1 的四項 Doctor 遷移

升級至 OpenClaw 2.0 時,有四項遷移由 openclaw doctor --fix 統一處理。建議在升級後、正式使用前一次執行完畢:

openclaw doctor --fix
#遷移項目若不執行的後果
1OpenProse 插件移除插件已從產品移除,殘留設定會造成啟動問題;另需依上游的 Agent Skill 遷移指引處理
2codex/* 與 openai-codex/* → openai/* 路由舊的模型參照無法解析到正確路由
3QMD → Built-in Memory記憶搜尋與回想無法運作(詳見 4.6,注意三項 QMD 專屬能力會退休)
4HEARTBEAT.md 停止在 runtime 讀取既有的 heartbeat 工作不會執行,必須遷移才能保留有效工作

⚠️ 執行期限:2026-09-18。官方載明「若你升級的組態仍含已退休的設定鍵,請在 2026 年 9 月 18 日前執行 openclaw doctor --fix」。

Doctor 的遷移行為:當新舊設定鍵衝突時,保留正規值;移除已不具作用的設定。但請注意——已明確退休的調校值會回到內建預設值,若你原先依賴這些調校,升級後效能特性可能改變,需重新驗證。

服務目標的保護

Gateway 服務修復現在會保留已安裝的狀態目錄、組態路徑、port、受管理環境與符合條件的檔案式憑證,不會靜默地重新指向服務目標。

# 若確實要變更上述目標,必須明確指定 --force
openclaw gateway install --force

Linux 額外保護:服務指令會拒絕相互衝突的 user unit 與 system unit,並顯示哪一個 unit 擁有該 Gateway。這解決了過去雙 unit 並存導致的難以診斷問題。

手動遷移範例

以本手冊舊版的模型設定為例(config validate 會判為 Unrecognized key):

// ❌ 舊寫法(NOVALIDATE:示範錯誤用法)
{
  agent: { model: "anthropic/claude-opus-4-8" },
  models: { default: { provider: "openai", model: "gpt-5.6" } },
}
// ✅ v2026.11.1 寫法
{
  agents: {
    defaults: {
      model: { primary: "openai/gpt-6-astra", fallbacks: ["anthropic/claude-opus-5-5"] },
    },
  },
}

審查 AI 產生的遷移:要求 AI 同時附上遷移前後的 openclaw config validate --json 輸出;遷移後必須是 "valid": true 且沒有非預期的 warnings。

7.6 多環境升級協調

環境升級時機驗證項目負責人
Dev新版發布後 1 天基本功能測試開發團隊
StagingDev 驗證後整合測試、效能測試QA 團隊
ProductionStaging 驗證後 1 週全面回歸測試營運團隊

7.7 破壞性變更處理

識別破壞性變更

# 查看 CHANGELOG 中的 BREAKING CHANGES
curl -s https://api.github.com/repos/openclaw/openclaw/releases/latest | \
  jq -r '.body' | grep -A5 "BREAKING"

常見破壞性變更處理模式

變更類型處理方式
API 端點變更更新客戶端 URI,設定臨時重定向
組態格式變更openclaw config validate --json 找出退休鍵 → openclaw doctor --fix
頻道驅動升級更新對應的第三方 API Token
棄用功能移除提前遷移到替代功能

v2026.8.1(OpenClaw 2.0)破壞性變更完整清單

#破壞性變更影響對象處理方式章節
1OpenProse 插件移除使用該插件者openclaw doctor --fix + 上游 Agent Skill 遷移7.5
2codex/*、openai-codex/* → openai/* 路由使用 Codex 模型參照者openclaw doctor --fix7.5
3Plugin SDK 舊 subpath 匯入移除插件開發者改用 openclaw/plugin-sdk/* 聚焦命名空間4.9
4deactivate → gateway_stop插件開發者更名匯出函式4.9
5Code Mode 介面重寫Code Mode 使用者移除 tools 物件、ALL_TOOLS、exact-ID 呼叫、raw call envelope4.4
6Session/Transcript 改用 SQLite所有使用者升級前建立可驗證備份;降版須先還原舊版逐字稿產物2.11、附錄 E
7QMD 記憶退休使用 QMD 者doctor --fix;reranking/query expansion/跨 Agent 逐字稿搜尋將失去4.6
8HEARTBEAT.md 停止 runtime 讀取使用 heartbeat 者doctor --fix 遷移4.7、7.5
9官方 Provider 外部化為獨立套件使用相關 Provider 者新設定需安裝對應套件並重啟下方說明
10agents.defaults.cliBackends 自訂項目自訂 CLI backend 者須移入 backend plugin4.9
11v2026.7.2 beta 契約形狀變更使用該 beta 契約的用戶端改用更名並扁平化後的契約4.9
12Canvas 範圍收斂Canvas 使用者聚焦 macOS presenter 與 session-board A2UI;獨立工作區、eval/snapshot 介面、原生 push/reset 指令,以及 iOS/Android/Linux 用戶端已移除—
13Managed worktree 抑制 Git hooks依賴隱含 hooks 的儲存庫須將設定移入明確路徑(管理員另跑設定腳本)9.9
外部化為獨立套件的官方 Provider

以下 Provider 與整合現在需個別安裝:

Cohere、Meta、BytePlus、ComfyUI、OpenCode、Voyage、Vydra、Volcengine、Mistral、NovitaAI、Teams meetings、Zoom meetings

新設定:安裝對應套件後重啟 OpenClaw。 既有已啟用的設定:會在外部產物可用時自行重新定位。 例外:OpenCode Go 仍為內建,因其外部佔位套件不可用。

三個相容期限總表

期限事項逾期後果
2026-09-01Plugin SDK 舊 subpath 匯入關閉插件無法載入
2026-09-18含已退休設定鍵者須執行 doctor --fix組態可能無法通過驗證
2026-10-12beta.5 session-store bridge 相容層失效依賴該 bridge 的用戶端中斷

7.8 自動化升級管線

GitHub Actions 自動升級

# .github/workflows/openclaw-upgrade.yml
name: OpenClaw 自動升級檢查

on:
  schedule:
    - cron: "0 9 * * 1"  # 每週一早上 9 點
  workflow_dispatch:

jobs:
  check-upgrade:
    runs-on: ubuntu-latest
    steps:
      - name: 檢查最新版本
        id: check
        run: |
          CURRENT=$(cat .openclaw-version)
          LATEST=$(npm view openclaw version)
          echo "current=$CURRENT" >> $GITHUB_OUTPUT
          echo "latest=$LATEST" >> $GITHUB_OUTPUT
          if [ "$CURRENT" != "$LATEST" ]; then
            echo "needs_upgrade=true" >> $GITHUB_OUTPUT
          fi

      - name: 在測試環境驗證
        if: steps.check.outputs.needs_upgrade == 'true'
        run: |
          # 唯讀檢查:不需要啟動 Gateway;容器內 state 目錄為 /home/node/.openclaw
          docker run --rm \
            -v $PWD/config:/home/node/.openclaw:ro \
            ghcr.io/openclaw/openclaw:${{ steps.check.outputs.latest }} \
            node dist/index.js config validate --json

      - name: 建立升級 PR
        if: steps.check.outputs.needs_upgrade == 'true'
        uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: 升級 OpenClaw 至 ${{ steps.check.outputs.latest }}"
          body: |
            ## OpenClaw 版本升級
            - 當前版本: `${{ steps.check.outputs.current }}`
            - 目標版本: `${{ steps.check.outputs.latest }}`
            
            ### 驗證結果
            - [x] 新版本 `config validate --json` 通過
            - [ ] 預備環境 Gateway 回歸測試(人工確認後勾選)
          branch: "chore/upgrade-openclaw-${{ steps.check.outputs.latest }}"

7.9 升級監控儀表板

升級後關鍵監控指標

指標正常範圍異常門檻動作
錯誤率< 0.1%> 1%立即回滾
P95 延遲< 5s> 15s調查原因
記憶體使用< 2GB持續增長檢查記憶體洩漏
頻道連線全部連線有斷線檢查頻道組態
LLM 成功率> 99%< 95%檢查 API Key

7.10 版本鎖定與固定

鎖定版本

{
  "devDependencies": {
    "openclaw": "2026.11.1"
  }
}

package.json 是標準 JSON,不能加註解;請使用精確版本(不要 ^、~ 或 latest),並搭配 lockfile 與 npm ci。

# docker-compose.yml - 使用精確標籤
services:
  openclaw-gateway:
    # ✅ 使用精確版本(或 extended-stable 月線的確切版本,例如 2026.9.36)
    image: ghcr.io/openclaw/openclaw:2026.11.1
    # ❌ 避免使用 latest:無法重現、也無法回滾到「上一個 latest」

更嚴格的做法:以映像 digest 釘選(ghcr.io/openclaw/openclaw@sha256:...),並在 CI 中驗證 provenance(見 8.11)。

7.11 安全更新管線:預演、啟用、驗證與恢復

v2026.8.2 到 v2026.11.1 之間,openclaw update 幾乎每個版本都在強化「更新失敗也能回到可用狀態」。理解它的內部階段,才能判斷什麼時候該讓它自己處理、什麼時候該介入。

flowchart LR
    A["Admission<br/>檢查 Node/服務擁有者/<br/>組態是否有效"] --> B["Rehearsal<br/>在隔離候選狀態預演<br/>核心與插件變更(9.3)"]
    B --> C["Activation<br/>替換套件、<br/>重新整理服務定義"]
    C --> D["Post-update Doctor<br/>遷移與驗證"]
    D -->|通過| E[重啟並驗證 readiness]
    D -->|失敗| F["自動回滾<br/>保留組態與密鑰參照(9.1)"]
    F --> G["Triage<br/>交給內建或本機 coding agent 診斷"]
階段會擋下更新的常見原因你該做的事
AdmissionNode 低於 >=24.16.0(低於 24.22.1/26.12.1 只會警告)、組態無效(invalid-config)、Windows 排程工作需要提升權限(windows-task-elevation-required)、偵測到同一安裝的 Gateway 仍在執行(gateway-stop-unverified)依錯誤代碼處理後重跑;不要強行繞過
Rehearsal插件不相容、遷移無法在候選狀態完成先升級或停用該插件
Post-update Doctor遺留設定鍵、資料庫遷移鎖通常會自動回滾;回滾後看 openclaw update status
系統套件管理器擁有的安裝pacman、FreeBSD pkg 等OpenClaw 會跳過更新並提示改用該套件管理器
容器偵測不到套件擁有者記為 skipped;請改為更換映像(3.3)
openclaw update --dry-run --json      # 預覽(JSON 的 notes 欄位會保留診斷建議)
openclaw update --yes                 # 非互動執行;失敗時收集診斷並印出交接指令
openclaw update status                # 最近一次更新結果與歷史
openclaw update recover               # 更新器崩潰或取消後恢復
openclaw update repair                # 依目前通道修復安裝
openclaw update cleanup --dry-run     # 預覽可清除的遷移原件(清除後無法再回滾到那些原件)

特殊升級路徑

起點規則
2026 年 6 月以前的安裝必須先升級到 2026.9.5,在該版本執行 openclaw doctor --fix 並解決匯入問題,再升到最新版;使用同一個帳號、profile 與安裝路徑
Bun-only 安裝2026.9.6 以前的更新器第一次 Bun-only 升級需依官方 workaround;之後可自行更新
使用私有 npm 鏡像的無頭節點Bun 的版本探索會直接連 public npm;若必須走鏡像,關閉 nodeHost.autoUpdate.enabled 並以既有流程更新
手動替換安裝或自訂容器 entrypoint啟動前必須執行 openclaw doctor --fix(官方 entrypoint 會自動處理)

自動更新的治理

// 生產 Gateway:不自動更新,只在啟動時提示
{
  update: { channel: "extended-stable", checkOnStart: true, auto: { enabled: false } },
}

CI 中的更新驗證:在預備環境執行 openclaw update --tag <目標> --dry-run --json,把 JSON 結果存成 CI artifact;正式升級的變更單應附上這份輸出、config validate --json 與 doctor --json 的結果,作為審查依據。

7.12 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1升級前有可驗證備份openclaw backup create --verify成功並記錄 archive 名稱
2升級路徑預覽openclaw update --tag <ver> --dry-run --json無阻擋性 admission 錯誤;JSON 存為 CI artifact
3沒有使用不存在的指令附錄 F 的 check_cli.py❌ 沒有 config migrate、openclaw restart 等不存在的指令
4Kubernetes/容器升級方式檢視 Deployment strategy 與映像 tagRecreate、確切版本;不使用 latest
5升級後驗證openclaw --version、openclaw doctor、openclaw config validate --json、/readyz版本正確、無錯誤、ready: true
6回滾程序可執行演練 openclaw update recover 與從備份還原到新目錄能在維護窗口內恢復服務

第八章:DevOps 整合

8.1 CI/CD 管線設計

完整 CI/CD 流程

flowchart LR
    subgraph "CI 階段"
        LINT[Lint<br>組態驗證] --> TEST[Test<br>技能測試]
        TEST --> BUILD[Build<br>映像建構]
    end
    
    subgraph "CD 階段"
        BUILD --> DEV[Dev<br>自動部署]
        DEV --> STG[Staging<br>自動部署]
        STG --> APPROVE{人工審批}
        APPROVE --> PROD[Production<br>Canary 部署]
    end
    
    PROD --> MONITOR[監控<br>30 分鐘]
    MONITOR --> FULL[全面部署]

8.2 GitHub Actions 完整管線

# .github/workflows/openclaw-ci.yml
name: OpenClaw CI/CD

on:
  push:
    branches: [main, develop]
    paths:
      - "openclaw/**"
      - "skills/**"
      - ".github/workflows/openclaw-ci.yml"
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}/openclaw

jobs:
  lint:
    name: 組態驗證
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: 安裝 OpenClaw(精確版本,與正式環境一致)
        run: npm install -g openclaw@2026.11.1 --allow-scripts=openclaw

      - name: 驗證組態(validate 沒有 --config 旗標,以環境變數指定檔案)
        env:
          OPENCLAW_CONFIG_PATH: ${{ github.workspace }}/openclaw/openclaw.json
          OPENCLAW_STATE_DIR: ${{ runner.temp }}/openclaw-state
        run: |
          openclaw config validate --json | tee config-validate.json
          jq -e '.valid == true and ((.warnings // []) | length == 0)' config-validate.json

      - name: 驗證 Skill 格式
        run: |
          for skill_dir in skills/*/; do
            if [ -f "$skill_dir/SKILL.md" ]; then
              echo "驗證: $skill_dir"
              grep -q "^name:" "$skill_dir/SKILL.md" || \
                (echo "❌ $skill_dir 缺少 name 欄位" && exit 1)
              grep -q "^description:" "$skill_dir/SKILL.md" || \
                (echo "❌ $skill_dir 缺少 description 欄位" && exit 1)
              # 擋下非規範的 frontmatter 鍵(常見的 AI 杜撰欄位)
              if grep -qE "^(triggers|tools|access):" "$skill_dir/SKILL.md"; then
                echo "❌ $skill_dir 含非規範 frontmatter 鍵" && exit 1
              fi
            fi
          done

  test:
    name: 整合與冒煙測試
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4

      - name: Java 契約測試(mock Gateway,見 4.2)
        run: mvn -B test

      - name: 對預備環境 Gateway 冒煙測試
        if: ${{ vars.OPENCLAW_STAGING_URL != '' }}
        env:
          OPENCLAW_GATEWAY_URL: ${{ vars.OPENCLAW_STAGING_URL }}
          OPENCLAW_GATEWAY_TOKEN: ${{ secrets.OPENCLAW_STAGING_TOKEN }}
        run: |
          # readyz 必須檢查 JSON 本文,不能只看狀態碼
          curl -sf "$OPENCLAW_GATEWAY_URL/readyz" | jq -e '.ready == true'
          mvn -B test -Dtest=LiveGatewaySmokeTest

  build:
    name: 建構映像
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      
      - name: 登入 Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      - name: 建構並推送映像
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

  deploy-staging:
    name: 部署到 Staging
    runs-on: ubuntu-latest
    needs: build
    environment: staging
    steps:
      - name: 部署到 Staging
        run: |
          echo "部署映像至 Staging 環境"
          # kubectl set image deployment/openclaw \
          #   openclaw=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

  deploy-production:
    name: 部署到 Production
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment: production
    steps:
      - name: Canary 部署
        run: |
          echo "Canary 部署至 Production (10%)"
          # istioctl set ... 設定流量比例

      - name: 監控 Canary
        run: |
          echo "監控 30 分鐘..."
          sleep 60  # 簡化示範

      - name: 全面部署
        run: |
          echo "擴展到 100% 流量"

8.3 測試策略

測試金字塔

graph TB
    subgraph "E2E 測試 (少量)"
        E2E[完整對話流測試]
    end
    
    subgraph "整合測試 (中量)"
        INT1[頻道連接測試]
        INT2[Skill 載入測試]
        INT3[工具呼叫測試]
    end
    
    subgraph "單元測試 (大量)"
        UNIT1[組態解析測試]
        UNIT2[訊息路由測試]
        UNIT3[上下文管理測試]
        UNIT4[工具實作測試]
    end
    
    E2E --> INT1 & INT2 & INT3
    INT1 & INT2 & INT3 --> UNIT1 & UNIT2 & UNIT3 & UNIT4

Java 測試的兩個層次

層次目的何時執行本手冊範例
契約測試(mock Gateway)驗證重試、逾時、錯誤分類、請求格式等邏輯每次提交(不需 Gateway)4.2 OpenClawClientTest(10 個案例)
冒煙測試(真實 Gateway)驗證與實際 Gateway 版本的相容性預備環境部署後、升級前後4.2 LiveGatewaySmokeTest(無環境變數時自動略過)

為什麼兩層都要:本手冊的 Java 範例在 mock 測試全部通過後,第一次對真實 Gateway 執行冒煙測試就失敗了——JDK HttpClient 預設送出 Upgrade: h2c,Gateway 回 405。這類「協定層」問題 mock 永遠測不出來。反過來,真實 Gateway 也很難穩定重現 429、逾時、5xx,這些只能靠契約測試。

mvn -B test                                         # 契約測試;LiveGatewaySmokeTest 會顯示 Skipped
OPENCLAW_GATEWAY_URL=https://gw-staging.internal OPENCLAW_GATEWAY_TOKEN=... \
  mvn -B test -Dtest=LiveGatewaySmokeTest           # 冒煙測試

Agent 行為的回歸測試

Agent 的回覆不是確定性的,不適合用字串完全比對。建議的做法:

  1. 固定一組「黃金問題」(20–50 題),每題定義可客觀檢查的條件(必須包含的關鍵字、不得出現的內容、必須呼叫或不得呼叫的工具)。
  2. 在預備環境透過 HTTP API 執行,結果以 openclaw audit --kind tool_action --json 交叉比對實際的工具呼叫。
  3. 升級前後各跑一次,比較通過率;通過率下降即阻擋升級。

8.4 容器化最佳實務

自訂 Dockerfile

# Dockerfile — 以官方映像為基礎,只加入組織的技能
FROM ghcr.io/openclaw/openclaw:2026.11.1

LABEL org.opencontainers.image.source="https://git.company.internal/platform/openclaw-image"
LABEL org.opencontainers.image.description="企業自訂 OpenClaw Gateway"

# 官方映像以 node 使用者執行,state 目錄為 /home/node/.openclaw
# 技能放在 managed skills 目錄(所有 Agent 共用);組態請以掛載或 ConfigMap 提供,不要燒進映像
COPY --chown=node:node skills/ /home/node/.openclaw/skills/

# 沿用官方的健康檢查與啟動方式(映像不保證有 curl)
HEALTHCHECK --interval=30s --timeout=5s --retries=5 --start-period=20s \
    CMD ["node", "dist/docker-healthcheck.js"]

USER node
CMD ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]
原則說明
精確釘選基底映像2026.11.1 或 digest;不要 latest
不把密鑰與組態燒進映像組態用 ConfigMap/掛載;憑證用 Secret → SecretRef
以官方 healthcheck 為準node dist/docker-healthcheck.js 會檢查回應內容,而不只是 HTTP 狀態
唯讀根檔案系統僅 /home/node/.openclaw 與 /tmp 可寫(見 8.5)

❌ 舊版範例的錯誤:FROM openclaw/openclaw:2026.7.1、路徑 /home/openclaw/.openclaw、CMD ["openclaw", "start"](不存在的指令)、curl healthcheck(映像不一定有 curl,且只看狀態碼會被 Control UI 的 catch-all 200 騙過——2026.11.1 實測未知路徑回 200 text/html)。

8.5 Kubernetes 部署

官方以 Kustomize 提供起始 manifest(scripts/k8s/),並明確說明不提供 Helm chart:OpenClaw 是單一容器,真正需要客製的是 Agent 內容(Markdown、技能、組態),而不是基礎設施模板。官方也強調這是起點而非可直接上線的部署。

export ANTHROPIC_API_KEY="..."
./scripts/k8s/deploy.sh                       # 建立 namespace、Secret(含自動產生的 Gateway token)並部署
kubectl port-forward svc/openclaw 18789:18789 -n openclaw
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d

部署的資源:

Namespace: openclaw
├── Deployment/openclaw        # 單一 Pod:init container(首次植入組態)+ gateway
├── Service/openclaw           # ClusterIP 18789
├── PersistentVolumeClaim      # 10Gi,存放 Agent state 與組態
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Gateway token + Provider API key

Gateway 容器的關鍵設定(依官方 manifest 精簡,映像版本已更新)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: openclaw
  namespace: openclaw
spec:
  replicas: 1                  # 一份 state 只能有一個擁有者:不可水平擴展
  strategy:
    type: Recreate             # 不可用 RollingUpdate:新舊 Pod 會同時搶同一個 PVC 的 state
  selector:
    matchLabels: { app: openclaw }
  template:
    metadata:
      labels: { app: openclaw }
    spec:
      containers:
        - name: gateway
          image: ghcr.io/openclaw/openclaw:2026.11.1-slim
          command: ["node", "/app/dist/index.js", "gateway", "run"]
          ports:
            - { name: gateway, containerPort: 18789, protocol: TCP }
          env:
            - { name: HOME, value: /home/node }
            - { name: OPENCLAW_CONFIG_DIR, value: /home/node/.openclaw }
            - { name: XDG_CACHE_HOME, value: /home/node/.openclaw/.cache }
            - name: OPENCLAW_GATEWAY_TOKEN
              valueFrom: { secretKeyRef: { name: openclaw-secrets, key: OPENCLAW_GATEWAY_TOKEN } }
          resources:
            requests: { memory: 512Mi, cpu: 250m }
            limits: { memory: 2Gi, cpu: "1" }
          # probe 必須檢查 JSON 本文:Control UI 對未知路徑一律回 200
          startupProbe:
            exec:
              command:
                - node
                - -e
                - "require('http').get('http://127.0.0.1:18789/readyz', r => { let b = ''; r.on('data', d => b += d); r.on('end', () => { try { process.exit(r.statusCode < 400 && JSON.parse(b).ready === true ? 0 : 1); } catch { process.exit(1); } }); }).on('error', () => process.exit(1))"
            periodSeconds: 10
            failureThreshold: 30
          livenessProbe:
            exec:
              command:
                - node
                - -e
                - "require('http').get('http://127.0.0.1:18789/healthz', r => { let b = ''; r.on('data', d => b += d); r.on('end', () => { try { process.exit(r.statusCode < 400 && JSON.parse(b).ok === true ? 0 : 1); } catch { process.exit(1); } }); }).on('error', () => process.exit(1))"
            initialDelaySeconds: 60
            periodSeconds: 30
          volumeMounts:
            - { name: openclaw-home, mountPath: /home/node/.openclaw }
            - { name: tmp-volume, mountPath: /tmp }
          securityContext:
            runAsNonRoot: true
            runAsUser: 1000
            runAsGroup: 1000
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities: { drop: ["ALL"] }
      volumes:
        - name: openclaw-home
          persistentVolumeClaim: { claimName: openclaw-home-pvc }
        - name: tmp-volume
          emptyDir: {}

實測回應格式(OpenClaw 2026.11.1 本機 Gateway):

GET /healthz        → 200 {"ok":true,"status":"live"}
GET /readyz         → 200 {"ready":true,"coreReady":true,"failing":[],...}
GET /startupz       → 200 {"ok":true,"status":"started","version":"2026.11.1",...}
GET /no-such-route  → 200 <!doctype html>...(Control UI catch-all)

⚠️ 三個最常見的錯誤:

  1. replicas > 1 或 RollingUpdate:新舊 Pod 同時掛載同一份 state,第二個 Gateway 會被 Gateway Lock 擋下或卡住,最壞情況造成資料毀損。
  2. 只看 HTTP 狀態碼的 probe:如上實測,未知路徑也回 200,probe 會永遠通過。
  3. 以為 ConfigMap 更新就會生效:init container 只在 PVC 上沒有 openclaw.json 時才植入;首次啟動後,PVC 上的副本才是真實來源。要套用新版 ConfigMap,需刪除 PVC 上的檔案再 kubectl rollout restart。

/startupz 只看啟動完成、不受頻道健康影響,比 /readyz 更適合作為流量准入:一個頻道帳號壞掉不會讓整個 Gateway 被從 Service endpoints 移除。

kubectl apply --dry-run=client -k scripts/k8s/manifests      # 離線驗證 manifest
kubectl -n openclaw exec deploy/openclaw -- node /app/dist/index.js gateway status --deep

8.6 Infrastructure as Code

Terraform 範例

# terraform/main.tf
terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

resource "docker_network" "openclaw" {
  name = "openclaw-network"
}

resource "docker_image" "openclaw" {
  name         = "ghcr.io/openclaw/openclaw:2026.11.1"
  keep_locally = true
}

resource "docker_container" "openclaw" {
  name  = "openclaw-gateway"
  image = docker_image.openclaw.image_id

  ports {
    internal = 18789
    external = 18789
  }

  networks_advanced {
    name = docker_network.openclaw.name
  }

  volumes {
    host_path      = abspath("./openclaw-state")
    container_path = "/home/node/.openclaw"   # 官方映像的 state 目錄;必須可寫(不可 read_only)
  }

  healthcheck {
    test         = ["CMD", "node", "dist/docker-healthcheck.js"]
    interval     = "30s"
    timeout      = "5s"
    retries      = 5
    start_period = "20s"
  }

  restart = "unless-stopped"
}

8.7 GitOps 工作流程

Flux CD:以 Kustomize 部署(官方未提供 Helm chart)

# gitops/openclaw-kustomization.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: openclaw
  namespace: flux-system
spec:
  interval: 10m
  path: ./deploy/openclaw          # 內含官方 scripts/k8s/manifests 的副本與組織的 overlay
  prune: true
  sourceRef:
    kind: GitRepository
    name: platform-config
  targetNamespace: openclaw
  images:
    - name: ghcr.io/openclaw/openclaw
      newTag: "2026.11.1-slim"      # 升級 = 透過 PR 修改這一行

GitOps 的升級流程:PR 修改映像 tag → CI 執行 kubectl apply --dry-run 與 config validate → 合併 → Flux 套用(Recreate)→ 冒煙測試。

⚠️ 組態的真實來源要想清楚:GitOps 管理的 ConfigMap 只在首次啟動時植入(8.5)。若要求「Git 即真實來源」,需在 overlay 中改為每次啟動都以 ConfigMap 覆寫組態,並停用透過 Control UI/config set 的線上修改,否則兩邊會互相覆蓋。

❌ 舊版範例的 HelmRelease(chart: openclaw)引用了不存在的官方 chart。

8.8 藍綠部署

藍綠部署在 OpenClaw 中只能以「整個 Gateway + 它自己的 state」為單位進行,不能讓藍綠兩個版本同時服務同一份 state:

flowchart LR
    subgraph "切換前"
        DNS1["DNS/Tunnel"] --> BLUE["🔵 Blue Gateway<br/>v2026.9.36<br/>state-blue"]
        GREEN["🟢 Green Gateway<br/>v2026.11.1<br/>state-green(由 Blue 備份還原)"]
    end
    subgraph "切換後"
        DNS2["DNS/Tunnel"] --> GREEN2["🟢 Green Gateway<br/>v2026.11.1"]
        BLUE2["🔵 Blue(停止,保留供回滾)"]
    end
  1. Blue 執行 openclaw gateway suspend --wait,再 openclaw backup create --verify。
  2. 以該備份在 Green 主機還原到全新目錄,安裝新版並執行 openclaw doctor。
  3. Green 通過冒煙測試後切換 DNS/Cloudflare Tunnel,同時停止 Blue(避免兩邊都在接收頻道訊息)。
  4. 回滾:停止 Green,以 openclaw gateway resume <suspensionId> 恢復 Blue。Green 期間產生的新對話不會回到 Blue,這是必須事先告知使用者的取捨。

⚠️ 頻道連線(Telegram bot、Slack app 等)同一時間只能由一個 Gateway 持有;切換時要確認舊 Gateway 已完全停止。

8.9 Canary 部署

OpenClaw 沒有「同一批使用者 10% 流量導到新版」的機制;Canary 應以信任域/部門為單位:

做法說明
試點 Gateway選一個影響範圍小的部門 Gateway 先升級(見 7.3 流程圖)
觀察指標openclaw_model_failover_total、openclaw_session_stuck_total、openclaw_tool_execution_blocked_total、錯誤率(6.4)
晉升條件24–72 小時內指標無異常,黃金問題回歸通過率不下降(8.3)

❌ 舊版範例以 Istio VirtualService 對同一個 OpenClaw 服務做 90/10 權重切分;這會讓同一位使用者的連線在兩個版本、兩份 state 之間跳動,對話脈絡會分裂。

反例:以流量權重切分同一個 Gateway(不要這樣做)

# ❌ 反例:istio/openclaw-canary.yaml(反例)
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: openclaw
spec:
  hosts:
    - openclaw.company.internal
  http:
    - route:
        - destination:
            host: openclaw-stable
            port:
              number: 18789
          weight: 90
        - destination:
            host: openclaw-canary
            port:
              number: 18789
          weight: 10

8.10 監控即程式碼

Grafana Dashboard as Code

# monitoring/grafana-dashboard.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: openclaw-dashboard
  labels:
    grafana_dashboard: "true"
data:
  openclaw.json: |
    {
      "dashboard": {
        "title": "OpenClaw 運營儀表板",
        "uid": "openclaw-ops",
        "refresh": "30s",
        "time": { "from": "now-6h", "to": "now" },
        "panels": [
          {
            "title": "訊息吞吐量",
            "type": "timeseries",
            "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0},
            "targets": [
              {
                "expr": "sum(rate(openclaw_messages_total[5m])) by (channel)",
                "legendFormat": "{{channel}}"
              }
            ]
          },
          {
            "title": "回應時間分佈",
            "type": "heatmap",
            "gridPos": {"h": 8, "w": 12, "x": 12, "y": 0},
            "targets": [
              {
                "expr": "rate(openclaw_response_duration_seconds_bucket[5m])"
              }
            ]
          }
        ]
      }
    }

8.11 發布物驗證(供應鏈)

每個 OpenClaw 正式版的 GitHub Release 都附有 Release verification 區塊:npm 套件頁、registry tarball、integrity(sha512)、release commit SHA、完整 release CI 報告與各 publish workflow 的執行連結。企業在把新版本放進內部鏡像或映像倉庫前,應把下列檢查自動化:

檢查方法2026.11.1 實測結果
tarball 完整性npm view openclaw@<版本> dist.integrity 與 Release 頁的 integrity 比對一致(sha512-2pSbt/taBKM/...)
registry 簽章npm audit signatures(於已安裝的專案內)508 packages have verified registry signatures
建置來源(provenance)npm view openclaw@<版本> dist.attestations附 SLSA provenance v1;151 packages have verified attestations
原始碼對應Release 的 release SHA 與 Git tag 指向的 commit 比對4ffdd20(亦即 openclaw --version 顯示的 build)
容器映像只用 ghcr.io/openclaw/openclaw(主要來源)或 openclaw/openclaw;以 digest 釘選GHCR 為 release 自動化與 provenance 檢查的主要來源
VER=2026.11.1
# 1) integrity 與 Release 說明比對
npm view openclaw@$VER dist.integrity
gh release view v$VER -R openclaw/openclaw --json body --jq .body | grep -E '^- integrity:'

# 2) 簽章與 provenance(在固定版本的隔離專案中)
mkdir -p /tmp/oc-verify && cd /tmp/oc-verify && npm init -y >/dev/null
npm install --save-exact openclaw@$VER --allow-scripts=openclaw
npm audit signatures

# 3) 版本與 build
npx openclaw --version      # OpenClaw 2026.11.1 (4ffdd20)

Plugin 與 Skill 也是供應鏈:同一份 Release 會發布官方插件(npm 與 ClawHub)。第三方插件則必須經過 4.4 所示的兩道關卡(--force 與 --accept-capabilities),並可透過 security.installPolicy 把審核交給外部指令(5.3、9.11);ClawHub 技能用 openclaw skills verify @owner/slug --card 產生 Skill Card 供人工審查。

8.12 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1CI 中的組態驗證檢視 workflow以 OPENCLAW_CONFIG_PATH + config validate --json 並以 jq 斷言 valid
2Dockerfile 正確docker build 後以 docker inspect 檢查基底為 ghcr.io/openclaw/openclaw:<確切版本>、USER node、官方 healthcheck
3Kubernetes manifestkubectl apply --dry-run=client -k ...replicas: 1、Recreate、JSON probe、唯讀 rootfs
4沒有虛構的 Helm chart檢視 GitOps 設定使用 Kustomize(官方未提供 chart)
5發布物完整性比對 npm view openclaw@<ver> dist.integrity 與 Release 頁;執行 npm audit signaturesintegrity 一致;簽章與 attestation 驗證通過
6藍綠/Canary 以 Gateway 為單位審查部署計畫沒有對同一份 state 做流量權重切分

第九章:安全設計

9.1 信任模型

OpenClaw 採用 個人助理信任模型(Personal Assistant Trust Model),核心概念是:一個操作者(Operator)擁有完整控制權。

信任邊界

graph TB
    subgraph "完全信任區"
        OP[操作者<br>Operator]
        GW[Gateway<br>守護程序]
        AGENT[Pi Agent<br>執行環境]
    end
    
    subgraph "授權信任區"
        SKILL[受管理 Skills]
        TOOL[工具 Bridge]
    end
    
    subgraph "有限信任區"
        CHANNEL[頻道接口]
        USER[外部使用者]
    end
    
    subgraph "不信任區"
        EXT[外部 API]
        LLM[LLM Provider]
    end
    
    OP -->|完全控制| GW
    GW -->|受控執行| AGENT
    AGENT -->|受限呼叫| SKILL
    SKILL -->|白名單| TOOL
    CHANNEL -->|DM配對| GW
    GW -->|加密傳輸| LLM
    GW -->|加密傳輸| EXT

信任原則

原則說明
單一操作者每個 Gateway 實例由一個人控制
最小曝露Gateway 預設綁定 loopback,不公開到網際網路
DM 配對使用者必須透過 DM 配對才能互動
技能隔離每個 Skill 在獨立上下文中執行
資料在地所有對話資料留在本地
沙箱隔離非主 Session 可選在 Docker 沙箱中執行

DM 配對機制(DM Pairing)

OpenClaw 預設在 Telegram / WhatsApp / Signal / iMessage / Microsoft Teams / Discord / Google Chat / Slack 等頻道上啟用 DM 配對,防止未授權使用者存取 Agent:

sequenceDiagram
    actor Unknown as 未知使用者
    participant GW as Gateway
    actor Owner as 操作者

    Unknown->>GW: 發送訊息
    GW->>GW: dmPolicy="pairing"
    GW-->>Unknown: 回傳配對碼 (ABC123)
    GW->>GW: 不處理訊息
    
    Note over Owner: 收到配對請求通知
    Owner->>GW: openclaw pairing approve telegram ABC123
    GW->>GW: 將使用者加入允許清單
    
    Unknown->>GW: 再次發送訊息
    GW->>GW: 使用者已授權
    GW-->>Unknown: Agent 正常回應

DM Policy 設定選項:

策略說明
pairing(預設)未知使用者收到配對碼,需操作者核准
open開放所有 DM(需搭配 allowFrom: ["*"])

安全提示: 開放 DM 需明確設定 dmPolicy="open" 並在 allowFrom 中包含 "*"。執行 openclaw doctor 可偵測危險的 DM 設定。

沙箱模式(Sandbox Mode)

對於群組和非主 Session,OpenClaw 支援在 Docker 沙箱中隔離執行:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",        // off | non-main | all
        scope: "session",        // session | agent | shared:沙箱容器的共用範圍
        workspaceAccess: "ro",   // none | ro | rw:沙箱對工作區的存取
        docker: { network: "none", readOnlyRoot: true, memory: "1g", pidsLimit: 256 },
      },
    },
  },
  tools: {
    // 沙箱 Session 額外的工具閘門(在一般工具政策之上再過濾一次)
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send"],
        deny: ["browser", "canvas", "nodes", "cron", "gateway"],
      },
    },
  },
}

❌ 舊版範例的錯誤:把 allow/deny 寫在 agents.defaults.sandbox 底下。沙箱的工具過濾在 tools.sandbox.tools.allow/deny;agents.defaults.sandbox 只管「怎麼建沙箱」(模式、範圍、工作區存取、Docker 參數)。

  • 主 Session(main): 一對一直接對話,工具在主機上執行,完整存取權限
  • 非主 Session(non-main): 群組/頻道對話,bash 在 Docker 容器中執行

未信任外部內容的標記(v2026.8.1)

2.0 對「模型會讀到什麼」建立了明確的邊界。來自 search、fetch、MCP、插件、Browser 以及其他網路支援工具的回傳文字,在進入模型之前會被:

  1. 設限(bounded)——限制長度與規模;
  2. 正規化(normalized)——統一格式;
  3. 標記為未信任外部內容(untrusted external content)。

⚠️ 這項機制的真實效力必須被正確理解。官方的措辭極為誠實:「這讓來源與邊界變得明確,但模型仍然可能被它所讀到的惡意素材影響」。

換言之,這是縱深防禦的一層,而非 Prompt Injection 的解方。它讓模型(與稽核者)知道「這段內容來自外部且不可信」,但並不能阻止模型被說服。9.7 的防禦措施仍然全部必要。

其他同步強化的注入面向:

面向強化內容
終端機與 CSV 輸出中和已涵蓋的控制序列與公式注入形式
組態拒絕會造成 prototype pollution 的路徑
Browser 與 MCP App瀏覽器參照、可執行等待、導覽與 MCP App 授權,會針對產生它們的文件與即時權限重新檢查

⚠️ 瀏覽器導覽強制的覆蓋範圍有缺口:強制機制涵蓋「受管理動作期間所選頁面的文件流量」與一段有界的寬限期。但彈出視窗、Service Worker、背景請求、部分重新導向與遠端後端,都在該邊界之外。若你的威脅模型包含惡意網頁主動發起的側通道,這些缺口需另行處理。

網路政策強化

項目2.0 行為
NAT64 目標預設封鎖未指定與 local-use 的 NAT64 目標
重新導向驗證受保護的重新導向與無認證的瀏覽器來源
遙測 Proxy設定的 proxy 無效時停止遙測,而非繞過它
私有自動化 Webhook 目的地需明確的主機例外,或啟用較寬鬆的私有網路開關

⚠️ 私有網路開關的副作用:較寬鬆的那個設定會將信任範圍擴大到每一個已設定的 cron webhook,而非僅限你當下想開放的那一個。企業環境應優先使用精確的主機例外。

9.2 API Key 管理

安全儲存策略

// openclaw.json — 組態中只放參照,不放金鑰
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },   // ✅ SecretRef
      // openai: { apiKey: "sk-xxx..." }                                                  // ❌ 絕對禁止
    },
  },
  channels: {
    telegram: { botToken: "${TELEGRAM_BOT_TOKEN}" },   // ✅ 環境變數替換
  },
}
openclaw secrets audit     # 掃描組態中的明文憑證與無法解析的參照

密鑰輪替策略

flowchart TD
    START[排程觸發<br>每 90 天] --> GEN[產生新 API Key]
    GEN --> STORE[儲存到密鑰管理服務<br>Vault / AWS Secrets Manager]
    STORE --> DEPLOY[更新環境變數]
    DEPLOY --> RELOAD[OpenClaw Hot Reload<br>重新載入組態]
    RELOAD --> VERIFY[驗證新 Key 可用]
    VERIFY -->|成功| REVOKE[撤銷舊 Key]
    VERIFY -->|失敗| ROLLBACK[回復為舊 Key]
    REVOKE --> LOG[記錄稽核日誌]

Java 密鑰管理範例

package com.tutorial.openclaw.security;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/**
 * API Key 管理器。
 *
 * <p>管理 OpenClaw 相關的 API Key 生命週期,
 * 包含建立、輪替、撤銷、過期檢查等功能。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class ApiKeyManager {

    private static final Logger logger = LogManager.getLogger(ApiKeyManager.class);

    /** Key 記錄 */
    public record KeyRecord(
            String keyId,
            String provider,
            Instant createdAt,
            Instant expiresAt,
            boolean active
    ) {}

    private final Map<String, KeyRecord> keys = new ConcurrentHashMap<>();

    /**
     * 檢查是否有即將過期的 Key。
     *
     * @param warningDays 提前幾天警告
     * @return 即將過期的 Key 列表
     */
    public java.util.List<KeyRecord> getExpiringKeys(int warningDays) {
        Instant threshold = Instant.now().plus(warningDays, ChronoUnit.DAYS);
        return keys.values().stream()
                .filter(KeyRecord::active)
                .filter(k -> k.expiresAt().isBefore(threshold))
                .toList();
    }

    /**
     * 執行 Key 輪替。
     *
     * @param provider 提供者名稱
     * @param newKeyId 新的 Key ID
     */
    public void rotateKey(String provider, String newKeyId) {
        // 停用舊 Key
        keys.values().stream()
                .filter(k -> k.provider().equals(provider) && k.active())
                .forEach(k -> {
                    keys.put(k.keyId(), new KeyRecord(
                            k.keyId(), k.provider(), k.createdAt(),
                            k.expiresAt(), false));
                    logger.info("已停用舊 Key: {} ({})", k.keyId(), provider);
                });

        // 啟用新 Key
        KeyRecord newKey = new KeyRecord(
                newKeyId, provider, Instant.now(),
                Instant.now().plus(90, ChronoUnit.DAYS), true);
        keys.put(newKeyId, newKey);
        logger.info("已啟用新 Key: {} ({})", newKeyId, provider);
    }
}

9.3 Agent 隔離策略

隔離層級

層級隔離方式適用場景
L1: 邏輯隔離不同 Skill 組態同 Gateway 多用途
L2: 處理程序隔離不同 Agent 實例不同信任等級
L3: 容器隔離Docker / Crabbox 容器不同團隊/專案
L4: 主機隔離不同 VM/主機高機密環境

沙箱架構(Sandboxing)

OpenClaw v2026.5 引入完整的沙箱架構,支援三種後端:

後端說明適用場景
Docker預設沙箱後端,容器隔離一般多使用者環境
SSH透過 SSH 連線到遠端主機執行遠端沙箱、跳板機
OpenShell輕量級 shell 隔離低資源環境
// 沙箱組態範例(backend 依已安裝的沙箱插件,常見為 docker、ssh、openshell)
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        backend: "docker",
        workspaceAccess: "ro",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
        deny: ["browser", "canvas", "nodes", "cron", "gateway"],
      },
    },
  },
}

Sandbox vs Tool Policy vs Elevated: OpenClaw 提供三層工具存取控制:

  1. Sandbox: 完全隔離,非主 Session 在容器內執行
  2. Tool Policy: 透過 tools.allow / tools.deny 精細控制工具存取
  3. Elevated Mode: 臨時提升權限,用於需要特殊存取的操作

詳見 Sandbox vs Tool Policy vs Elevated。

插件供應鏈安全(Plugin Provenance,v2026.8.1 新增)

延續 9.6 節 OWASP LLM05(供應鏈攻擊)的防護,v2026.8.1 起 CLI 與聊天介面安裝任意可執行檔的第三方插件時,須明確加上 --force 旗標確認已知悉風險來源;來自 ClawHub、Bundled、官方目錄與既有追蹤更新的信任來源則維持原有免確認流程,避免影響日常維運效率。企業導入建議在插件治理規範中明訂:非官方目錄插件一律須經安全審查後才可加註 --force 安裝,並保留審查紀錄以利稽核(見 9.8 節)。

v2026.11.1 的兩道安裝關卡(實測):

關卡未通過時的訊息放行方式
來源信任This source is outside ClawHub review and trust metadata ... Install cancelled; rerun with --force after reviewing the source.審查後加 --force
能力同意Plugin "<id>" requires capability consent. The plugin was not installed.檢視宣告的能力後加 --accept-capabilities

進一步可設定 security.installPolicy,以外部審核指令(例如呼叫內部的軟體成分分析服務)決定 skill/plugin 是否允許安裝,讓審查紀錄自動化。

DM 配對安全(DM Pairing)

OpenClaw 預設對所有頻道的私訊實施配對驗證:

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing"  // pairing(預設)| open
    }
  }
}
  • pairing(預設): 未知發送者收到配對碼,需操作者核准
  • open: 接受所有私訊(需顯式啟用,搭配 allowFrom: ["*"])
  • 核准指令:openclaw pairing approve <channel> <code>
  • 安全檢查:openclaw doctor 可偵測風險/錯誤配置的 DM Policy

9.4 網路安全

防火牆規則

# 只允許內部網路存取 Gateway
iptables -A INPUT -p tcp --dport 18789 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 18789 -j DROP

# 允許 Gateway 連出到 LLM API
iptables -A OUTPUT -p tcp --dport 443 -d api.openai.com -j ACCEPT
iptables -A OUTPUT -p tcp --dport 443 -d api.anthropic.com -j ACCEPT

TLS/SSL 設定

// Gateway 直接終結 TLS(若前方已有反向代理/Cloudflare Tunnel,改由代理終結並保持 bind: "loopback")
{
  gateway: {
    bind: "lan",
    tls: {
      enabled: true,
      certPath: "/etc/openclaw/tls/fullchain.pem",
      keyPath: "/etc/openclaw/tls/privkey.pem",
      caPath: "/etc/openclaw/tls/ca.pem",   // 選用:自訂 CA 鏈
    },
  },
}

❌ 舊版的 security.tls(含 minVersion)並不存在;TLS 設定在 gateway.tls。最低 TLS 版本、加密套件等更細的政策,請在反向代理層統一管理。

9.5 資料加密

靜態加密(Encryption at Rest)

OpenClaw 本身不對 state 做靜態加密。官方明確說明:Secret Store 的值以未加密方式存在共享狀態資料庫 state/openclaw.sqlite,僅靠 0600 檔案與 0700 目錄權限保護。因此靜態加密必須在 OpenClaw 之外完成:

資產建議做法
state 目錄(SQLite、逐字稿、Secret Store)作業系統層級的磁碟加密(LUKS、BitLocker、FileVault)或雲端的加密磁碟/加密 PV
異地備份storage.locations.<name>.encryption.passphrase(SecretRef),見 6.7
高價值憑證放在外部保管庫(1Password、Vault 插件),OpenClaw 只持有參照
Litestream 複寫物件儲存的伺服器端加密 + 嚴格的 bucket 存取政策
// 備份目的地的內容加密(這是 OpenClaw 唯一內建的「靜態加密」設定)
{
  storage: {
    locations: {
      offsite: {
        provider: "filesystem",
        settings: { path: "/mnt/nas/openclaw-backups" },
        encryption: { passphrase: { source: "env", provider: "default", id: "OPENCLAW_STORAGE_PASSPHRASE" } },
      },
    },
  },
}

❌ 舊版範例的 security.encryption.atRest(AES-256-GCM、keySource: "vault")並不存在。在資安審查文件中宣稱「OpenClaw 已啟用 AES-256 靜態加密」是錯誤陳述。

傳輸加密(Encryption in Transit)

通訊路徑加密方式備註
Client ↔ GatewayWSS (TLS 1.3)必須啟用
Gateway ↔ LLM APIHTTPS (TLS 1.3)預設加密
Gateway ↔ Channel APIHTTPS (TLS 1.2+)依頻道支援
Gateway ↔ Tool BridgeHTTPS 建議內網可免

9.6 OWASP LLM Top 10 防護

風險說明OpenClaw 防護
LLM01: Prompt Injection惡意 Prompt 注入輸入清理、Skill 隔離
LLM02: Insecure Output不安全的輸出處理輸出過濾、內容安全檢查
LLM03: Training Data Poisoning訓練資料污染N/A(使用外部模型)
LLM04: Model DoS模型拒絕服務Token 限制、速率限制
LLM05: Supply Chain供應鏈攻擊技能審核、來源驗證
LLM06: Sensitive Info敏感資訊洩露日誌脫敏、PII 過濾
LLM07: Insecure Plugin不安全的外掛工具白名單、權限控制
LLM08: Excessive Agency過度代理權最小權限、確認機制
LLM09: Overreliance過度依賴非技術措施(訓練、流程)
LLM10: Model Theft模型竊取N/A(使用 API)

9.7 Prompt Injection 防禦

真實案例警示:2026 年 2 月,社群曾回報一起 Agent 在缺乏適當工具邊界與核准機制的情況下,遭間接 Prompt Injection 誘導、未經使用者明確同意即自行在外部服務建立交友檔案的事件。此事件凸顯 Excessive Agency(OWASP LLM08,見 9.6 節)與工具白名單/Trusted Tool Policy(見 5.4 節)等控制措施並非「可選強化」,而是 Agent 一旦擁有瀏覽器、表單填寫等高影響力工具時的必要防線。企業導入時應將「高風險工具需人工核准」列為預設值,而非事後補救。

防禦策略

package com.tutorial.openclaw.security;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.List;
import java.util.regex.Pattern;

/**
 * Prompt Injection 偵測器。
 *
 * <p>分析使用者輸入,偵測潛在的 Prompt Injection 攻擊,
 * 包含直接注入和間接注入兩種模式。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class PromptInjectionDetector {

    private static final Logger logger = LogManager.getLogger(
            PromptInjectionDetector.class);

    /** 可疑模式列表 */
    private static final List<Pattern> SUSPICIOUS_PATTERNS = List.of(
            // 角色覆寫
            Pattern.compile("(?i)(ignore|forget|disregard)\\s+(all\\s+)?" +
                    "(previous|above|prior)\\s+(instructions?|rules?)"),
            // 系統提示擷取
            Pattern.compile("(?i)(reveal|show|print|output|display)\\s+" +
                    "(your|the)\\s+(system\\s+)?(prompt|instructions?)"),
            // 角色扮演攻擊
            Pattern.compile("(?i)you\\s+are\\s+now\\s+(a|an|the)"),
            // 越獄嘗試
            Pattern.compile("(?i)(do\\s+anything\\s+now|DAN|jailbreak)"),
            // 分隔符注入
            Pattern.compile("(?i)(\\[SYSTEM\\]|\\[INST\\]|<\\|im_start\\|>)")
    );

    /**
     * 分析輸入文字的注入風險。
     *
     * @param input 使用者輸入
     * @return 風險評估結果
     */
    public RiskAssessment analyze(String input) {
        if (input == null || input.isBlank()) {
            return new RiskAssessment(RiskLevel.NONE, List.of());
        }

        List<String> detectedPatterns = SUSPICIOUS_PATTERNS.stream()
                .filter(p -> p.matcher(input).find())
                .map(Pattern::pattern)
                .toList();

        RiskLevel level;
        if (detectedPatterns.size() >= 3) {
            level = RiskLevel.CRITICAL;
        } else if (detectedPatterns.size() >= 2) {
            level = RiskLevel.HIGH;
        } else if (detectedPatterns.size() == 1) {
            level = RiskLevel.MEDIUM;
        } else {
            level = RiskLevel.LOW;
        }

        if (level.ordinal() >= RiskLevel.MEDIUM.ordinal()) {
            logger.warn("偵測到潛在 Prompt Injection [level={}, patterns={}]",
                    level, detectedPatterns.size());
        }

        return new RiskAssessment(level, detectedPatterns);
    }

    /** 風險等級 */
    public enum RiskLevel {
        NONE, LOW, MEDIUM, HIGH, CRITICAL
    }

    /** 風險評估結果 */
    public record RiskAssessment(
            RiskLevel level,
            List<String> matchedPatterns
    ) {
        public boolean shouldBlock() {
            return level.ordinal() >= RiskLevel.HIGH.ordinal();
        }
    }
}

9.8 稽核日誌

稽核事件格式

{"event":"auth.login","user":"admin@company.com","channel":"slack","ip":"10.0.1.100","ts":"2026-03-05T10:00:00Z","result":"success"}
{"event":"config.change","user":"admin@company.com","field":"models.default.model","old":"gpt-5.5","new":"gpt-5.6","ts":"2026-03-05T10:05:00Z"}
{"event":"skill.install","user":"admin@company.com","skill":"weather-reporter@2.0.0","source":"clawhub","ts":"2026-03-05T10:10:00Z"}
{"event":"access.denied","user":"unknown@external.com","channel":"telegram","reason":"not_in_allowlist","ts":"2026-03-05T10:15:00Z"}
{"event":"tool.execute","agent":"report-agent","tool":"generate_report","params":{"type":"daily"},"duration_ms":1234,"ts":"2026-03-05T10:20:00Z"}

9.9 容器沙箱安全

AppArmor 設定檔

# /etc/apparmor.d/openclaw
profile openclaw flags=(attach_disconnected,mediate_deleted) {
    # 允許讀取設定檔
    /home/openclaw/.openclaw/** r,
    /home/openclaw/.openclaw/skills/** r,
    
    # 允許寫入日誌和資料
    /home/openclaw/.openclaw/logs/** w,
    /home/openclaw/.openclaw/data/** rw,
    
    # 允許網路存取
    network tcp,
    network udp,
    
    # 禁止執行其他程式
    deny /usr/bin/** x,
    deny /bin/** x,
    
    # 允許 Node.js
    /usr/local/bin/node ix,
}

Docker Security Options

services:
  openclaw:
    security_opt:
      - no-new-privileges:true
      - apparmor=openclaw
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=50m

v2026.8.1 沙箱強化與其殘留風險

沙箱身分(sandbox identity)現在包含擁有該執行的工作區,並針對訪客與 worker 建立更細的界線:

情境2.0 行為
新建且需要沙箱的 guest session每位已驗證訪客取得各自的身分;工作區僅能唯讀共享
另一台機器上的 worker session可選擇加入 per-session 容器
預設執行方式仍為直接執行(非沙箱)
貢獻者控制的程式碼在指定的未信任程式碼沙箱中準備

⚠️ per-guest 邊界的缺口:官方明確載明,訪客所建立的子 session 並未建立相同的 per-guest 邊界。若你的模型依賴訪客隔離,需注意這一層不會自動延伸。

檔案存取檢查在 2.0 中能攔截更多逃逸嘗試——透過具名根目錄的逃逸、被拒絕的目錄、超量讀取,以及 POSIX symlink 父層。

⚠️ 仍存在的 TOCTOU 時間窗:官方誠實載明,symlink 的圍堵是在檔案系統操作「之前」檢查,而非在核准的根目錄下以原子方式進行,因此「檢查與使用之間,路徑仍有被變更的時間窗」。在多租戶或有本機惡意行為者的情境中,這個時間窗是真實的攻擊面,需以作業系統層級的隔離(獨立使用者、容器、mount namespace)補強。

Managed worktree 會抑制儲存庫的 Git hooks,除非管理員刻意執行獨立的設定腳本。

⚠️ 這是破壞性變更:原本依賴隱含 Git hooks 的儲存庫,必須將該設定移入明確路徑,否則 hooks 不會執行(見 7.7 第 13 項)。

9.10 零信任架構

零信任原則在 OpenClaw 的應用

graph TB
    subgraph "零信任層"
        VERIFY[持續驗證<br>每個請求驗證身份]
        LEAST[最小權限<br>只授予必要權限]
        ASSUME[假設已被入侵<br>隔離影響範圍]
    end
    
    subgraph "實作方式"
        JWT[JWT Token 驗證]
        RBAC[角色權限控制]
        MTLS[mTLS 雙向認證]
        SEGMENT[網路微分段]
        AUDIT[全面稽核記錄]
    end
    
    VERIFY --> JWT & MTLS
    LEAST --> RBAC
    ASSUME --> SEGMENT & AUDIT

9.11 插件與供應鏈安全(v2026.8.1 新增)

2.0 針對「安裝來源不明的程式碼」建立了一套明確的審查機制。這對企業而言是導入 ClawHub 與第三方插件的前提條件。

能力審查(Capability Review)

受管理的外部插件安裝,現在會顯示一次綁定至該安裝產物的能力審查,且當更新要求更多權限時會再次詢問。

graph LR
    A[安裝外部插件] --> B[能力審查<br/>綁定該 artifact]
    B -->|核准| C[安裝]
    C --> D[更新]
    D -->|要求更多權限| B
    D -->|權限不變| E[直接更新]

⚠️ 能力審查的適用範圍與其限制(官方明確載明):

項目狀態
受管理的外部安裝✅ 適用
內建(bundled)插件❌ 跳過此提示
已啟用的舊有插件❌ 保留其既有存取權
內建執行保有具名的相容性例外

更關鍵的認知:審查顯示的是「插件要求做什麼」,而真實性與程式碼安全性仍取決於 artifact 完整性、登錄身分與程式碼審查。能力審查告訴你插件「聲稱」要什麼權限,不驗證它是否值得信任。

ClawHub 與技能安裝的完整性

機制說明
安全判定綁定版本技能安全判定綁定到確切的發布者與版本
GitHub 安裝需完整 commit SHA不接受可變的 branch 或 tag——這阻斷了「先發布乾淨版本、事後改寫 tag」的攻擊
直接下載驗證驗證宣告的 digest,並在支援的大小限制內檢查完整封存檔
安裝器回應檢查受管理的 Homebrew 或 NodeSource 安裝器,在回應失敗、為空、發生重新導向或缺少 shebang 時停止
本地編輯保護技能更新會保護本地與並行的編輯,除非操作者明確強制覆寫

⚠️ 完整 commit SHA 的保護邊界:SHA 釘住的是下載的封存位元組,但來源 metadata 仍取決於解析器。同樣地,安裝器的回應檢查只確認下載內容看起來像一個腳本,不驗證腳本行為。

實務建議:外部插件與技能應比照第三方相依套件納入軟體供應鏈管理——建立允許清單、釘選版本與 SHA、納入定期的相依套件掃描(見 Dependency Locking)。不要把 OpenClaw 的安裝檢查當作供應鏈安全的全部。

舊有技能安裝的基準線

較舊、未帶指紋的追蹤安裝,需要一次強制更新才能建立該基準。升級後應盤點既有技能,確認其指紋基準已建立。

9.12 2026 年 9 月安全公告潮與強化基準

2026-09-11,官方在 GitHub Security Advisories 一次揭露了 375 筆安全公告(high 150、medium 200、low 25),修補版本分布在 2026.7.1、2026.8.1、2026.8.2、2026.9.2 與 2026.9.3。公告標題反映出幾個反覆出現的弱點類型:

類型代表性公告(摘要)對企業的意義
owner/scope 授權缺漏chat.send could expose owner-only infrastructure tools、MCP configuration changes could omit owner authorization、Browser proxy could miss its admin scope非 owner 透過頻道或 API 取得高權限工具;共用 Gateway 必須升級
exec allowlist 繞過Escaped newlines could confuse exec allowlist parsing、Reusable exec approvals could authorize changed arguments、Exec wrapper allowlists could trust arbitrary inner commandstools.exec.security: "allowlist" 在舊版並不可靠
SSRF/DNS pinningBrowser CDP connections could discard DNS pinning、Video asset downloads could reach private destinationsAgent 可能被誘導存取內網服務
路徑與檔案邊界Unicode fallback could escape workspaceOnly roots、QQBot voice filenames could escape the staging directorytools.fs.workspaceOnly 在舊版有繞過方式
憑證外洩OpenAI-compatible transport could send provider credentials to the wrong endpoint、Config revision hashes could expose password verifiers需輪替可能外洩的憑證

之後的版本又持續強化:10.8(exec allowlist 對 test -v 需審批、沙箱子程序不可執行主機 CLI backend、egress proxy 拒絕不受信任的 eMudhra 憑證鏈)、10.9(修補相依套件漏洞、tools.fs.workspaceOnly 套用到 Gateway 內建工具、MCP CLI 檢視不再顯示即時憑證)、11.1(ClickClack 與 ClawHub 拒絕導向無關私有服務的重新導向、非互動 Doctor 不再未經同意下載插件、日誌遮罩政策錯誤時仍保留內建保護)。

企業強化基準(Hardening Baseline)

#控制項設定/指令驗證方式
1版本下限正式環境至少 2026.9.3;建議 stable 2026.11.1 或 extended-stable 2026.9.36openclaw --version、openclaw_gateway_build_info
2Node 安全版本Node 24.22.1+ 或 26.12.1+node --version
3不對外暴露 Gatewaygateway.bind: "loopback" + Tunnel/反向代理從外網 curl 應無法連線
4強驗證gateway.auth.mode 不可為 none;團隊用 trusted-proxy(11.7)openclaw security audit --deep
5DM 預設不開放各頻道 dmPolicy: "pairing" 或 "allowlist"openclaw doctor
6檔案邊界tools.fs.workspaceOnly: true請 Agent 讀取 ~/.ssh/config 應被拒
7exec 政策tools.exec.security: "allowlist"、ask: "on-miss"、host: "sandbox"未列入的指令觸發審批
8沙箱agents.defaults.sandbox.mode: "non-main"(或 all)群組對話中的 exec 在容器內執行
9SSRFbrowser.ssrfPolicy.blockedHostnames、cron.webhookSsrfPolicy.blockedHostnames;不要開 dangerouslyAllowPrivateNetwork請 Agent 開啟 http://169.254.169.254/ 應被拒
10密鑰SecretRef + Secret Store;高價值憑證走外部保管庫;egress proxy 綁定主機openclaw secrets audit
11插件與技能來源plugins.allow 白名單、security.installPolicyopenclaw plugins list
12稽核logging.audit.enabled: true、executionIdentity: trueopenclaw audit --kind tool_action
// 強化基準的組態部分(openclaw 2026.11.1 config validate 通過)
{
  gateway: { bind: "loopback", auth: { mode: "token", token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  agents: { defaults: { sandbox: { mode: "non-main", workspaceAccess: "ro" } } },
  tools: {
    fs: { workspaceOnly: true },
    exec: { host: "sandbox", security: "allowlist", ask: "on-miss" },
  },
  browser: { ssrfPolicy: { blockedHostnames: ["169.254.169.254", "metadata.google.internal"] } },
  cron: { webhookSsrfPolicy: { blockedHostnames: ["169.254.169.254", "metadata.google.internal"] } },
  logging: { audit: { enabled: true, executionIdentity: true } },
}
openclaw security audit --deep        # 稽核常見的危險設定
openclaw secrets audit
gh api "repos/openclaw/openclaw/security-advisories?per_page=100&sort=published&direction=desc" \
  --jq '.[] | [.published_at[:10], .severity, .summary] | @tsv' | head -20     # 追蹤最新公告

流程建議:把官方 Security Advisories 訂閱到資安團隊的工作流程;high 以上的公告在 7 天內評估並升級,且升級後重跑本表的驗證欄位。

9.13 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1版本不低於修補基準openclaw --version≥ 2026.9.3;建議 2026.11.1 或 2026.9.36
2強化基準 12 項逐項執行 9.12 表格的驗證欄位全部符合;例外有書面風險接受
3沙箱工具過濾位置正確openclaw config get tools.sandbox --jsonallow/deny 位於 tools.sandbox.tools
4TLS 與靜態加密的說法正確審查資安文件TLS 在 gateway.tls;不宣稱 OpenClaw 內建 AES 靜態加密
5插件安裝關卡未被 CI 無條件繞過檢視 CI 腳本--force/--accept-capabilities 只在審查後加入
6自動化稽核openclaw security audit --deep無高風險發現

第十章:實戰案例

10.1 案例一:自動化報表 Agent

需求描述

企業需要一個 Agent,每天自動收集多個系統的數據,產生日報/週報,並透過 Slack 通知相關人員。

架構設計

graph LR
    CRON[Cron 排程<br>每日 9:00] --> AGENT[報表 Agent]
    AGENT --> DB[資料庫<br>擷取數據]
    AGENT --> API[API<br>擷取指標]
    AGENT --> GIT[GitHub<br>擷取提交]
    DB & API & GIT --> ANALYZE[分析引擎]
    ANALYZE --> REPORT[產生報表]
    REPORT --> SLACK[Slack 通知]
    REPORT --> EMAIL[Email 發送]

實作詳述

Skill 定義
---
name: daily-reporter
description: 每日/每週營運報表。當使用者要求日報、週報、daily report,或由每日 09:00 的 Automation 觸發時使用
metadata:
  openclaw:
    requires:
      env: ["METRICS_API_TOKEN"]
---

# 報表生成 Agent

你是一個專業的資料分析師,負責自動收集和分析企業資料。

## 核心職責

1. 收集昨日數據(每日 09:00 的觸發由 Automation 負責,不是寫在 SKILL.md 的 `cron:` 鍵)
2. 計算關鍵指標的趨勢
3. 識別異常和風險
4. 生成結構化報表
5. 透過 Slack 和 Email 分發

## 報表格式規範

### 日報結構
- 標題: `日報 - YYYY-MM-DD`
- 摘要: 3 句話概述當日表現
- KPI 表格: 包含指標名/值/變化/狀態
- 異常事件: 時間線格式列出
- 待辦事項: Checkbox 格式

### 數據精度
- 百分比: 小數點第二位
- 金額: 千分位格式
- 趨勢: 使用 📈📉 表示

排程與存取控制不寫在 SKILL.md(舊版的 cron:、tools:、access:、triggers: 皆非規範鍵),而是分別由 Automations 與 Agent allowlist/頻道政策負責:

# 每日 09:00(台北)觸發,結果送到 Slack #ops-daily
openclaw automations add --name daily-report --cron "0 9 * * *" --tz Asia/Taipei   --agent reporter --message "使用 daily-reporter 技能產生昨日日報" --channel slack --to "#ops-daily"
// 只有 reporter Agent 看得到 daily-reporter;Slack 只接受營運團隊的使用者
{
  agents: { ownership: "explicit", entries: { reporter: { skills: ["daily-reporter"] } } },
  channels: { slack: { botToken: "${SLACK_BOT_TOKEN}", appToken: "${SLACK_APP_TOKEN}", dmPolicy: "allowlist", allowFrom: ["U01OPS", "U02OPS"] } },
  bindings: [{ agentId: "reporter", match: { channel: "slack" } }],
}
Java 報表服務(完整實作)
package com.tutorial.openclaw.cases.reporter;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;

/**
 * 自動化報表生成服務。
 *
 * <p>整合多個資料來源(資料庫、API、GitHub),
 * 產生格式化的日報/週報,並分發到指定頻道。</p>
 *
 * @author Tutorial Team
 * @version 2.0.0
 */
public class ReportService {

    private static final Logger logger = LogManager.getLogger(ReportService.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();
    private static final DateTimeFormatter DATE_FMT =
            DateTimeFormatter.ofPattern("yyyy-MM-dd");
    private static final DateTimeFormatter DATETIME_FMT =
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");

    private final HttpClient httpClient;
    private final String metricsApiUrl;
    private final String githubApiUrl;
    private final String slackWebhookUrl;

    /**
     * 建立報表服務。
     *
     * @param metricsApiUrl   指標 API URL
     * @param githubApiUrl    GitHub API URL
     * @param slackWebhookUrl Slack Webhook URL
     */
    public ReportService(String metricsApiUrl, String githubApiUrl,
                         String slackWebhookUrl) {
        this.httpClient = HttpClient.newHttpClient();
        this.metricsApiUrl = metricsApiUrl;
        this.githubApiUrl = githubApiUrl;
        this.slackWebhookUrl = slackWebhookUrl;
    }

    /**
     * 產生日報。
     *
     * @param date 報表日期
     * @return Markdown 格式的日報內容
     */
    public String generateDailyReport(LocalDate date) {
        logger.info("開始產生日報: {}", date);

        // 收集各項數據
        Map<String, Double> metrics = fetchMetrics(date);
        List<Map<String, String>> events = fetchEvents(date);
        Map<String, Object> githubStats = fetchGitHubStats(date);

        // 組裝報表
        StringBuilder report = new StringBuilder();

        // 標題與摘要
        report.append(String.format("# 📊 日報 - %s\n\n", date.format(DATE_FMT)));
        report.append(String.format("> 產生時間: %s\n\n",
                LocalDateTime.now().format(DATETIME_FMT)));
        report.append(generateSummary(metrics));

        // KPI 表格
        report.append("\n## 關鍵指標\n\n");
        report.append("| 指標 | 數值 | 較前日 | 狀態 |\n");
        report.append("|------|------|--------|------|\n");
        metrics.forEach((name, value) -> {
            double change = (Math.random() - 0.5) * 10; // 模擬變化
            String trend = change > 0 ? "📈" : "📉";
            String status = Math.abs(change) < 5 ? "✅" : "⚠️";
            report.append(String.format("| **%s** | %.2f | %s %.1f%% | %s |\n",
                    name, value, trend, Math.abs(change), status));
        });

        // 異常事件
        report.append("\n## 異常事件\n\n");
        if (events.isEmpty()) {
            report.append("✅ 無異常事件\n");
        } else {
            events.forEach(event -> report.append(String.format(
                    "- ⚠️ **%s** - %s\n", event.get("time"), event.get("description")
            )));
        }

        // GitHub 活動
        report.append("\n## 開發活動\n\n");
        report.append(String.format("| 項目 | 數量 |\n"));
        report.append("|------|------|\n");
        report.append(String.format("| Commits | %s |\n",
                githubStats.getOrDefault("commits", 0)));
        report.append(String.format("| Pull Requests | %s |\n",
                githubStats.getOrDefault("pullRequests", 0)));
        report.append(String.format("| Issues 關閉 | %s |\n",
                githubStats.getOrDefault("issuesClosed", 0)));

        // 待辦事項
        report.append("\n## 待辦事項\n\n");
        report.append("- [ ] 審查前日未關閉的告警\n");
        report.append("- [ ] 確認部署排程\n");
        report.append("- [ ] 整理本週技術文件\n");

        String content = report.toString();
        logger.info("日報已產生,共 {} 行", content.lines().count());
        return content;
    }

    /**
     * 產生週報。
     *
     * @param weekEndDate 週末日期
     * @return Markdown 格式的週報內容
     */
    public String generateWeeklyReport(LocalDate weekEndDate) {
        logger.info("開始產生週報: {} 之週", weekEndDate);

        StringBuilder report = new StringBuilder();
        report.append(String.format("# 📋 週報 - %s 之週\n\n",
                weekEndDate.format(DATE_FMT)));
        report.append(String.format("> 產生時間: %s\n\n",
                LocalDateTime.now().format(DATETIME_FMT)));

        // 週趨勢表格
        report.append("## 週趨勢\n\n");
        report.append("| 日期 | 請求數 | 錯誤率 | P95 延遲 |\n");
        report.append("|------|--------|--------|----------|\n");
        for (int i = 6; i >= 0; i--) {
            LocalDate day = weekEndDate.minusDays(i);
            report.append(String.format("| %s | %,d | %.2f%% | %dms |\n",
                    day.format(DATE_FMT),
                    (int) (Math.random() * 10000 + 5000),
                    Math.random() * 0.5,
                    (int) (Math.random() * 200 + 100)));
        }

        // 週 KPI 達成率
        report.append("\n## KPI 達成率\n\n");
        report.append("| KPI | 目標 | 實際 | 達成率 | 狀態 |\n");
        report.append("|-----|------|------|--------|------|\n");
        report.append("| 可用率 | >99.9% | 99.97% | 100% | ✅ |\n");
        report.append("| P95 延遲 | <500ms | 245ms | 100% | ✅ |\n");
        report.append("| 錯誤率 | <0.1% | 0.03% | 100% | ✅ |\n");
        report.append("| 客戶滿意度 | >4.5 | 4.7 | 104% | ✅ |\n");

        // 下週計畫
        report.append("\n## 下週計畫\n\n");
        report.append("1. 完成 v2.1.0 版本部署\n");
        report.append("2. 更新 SSL 憑證\n");
        report.append("3. 執行季度容量評估\n");

        return report.toString();
    }

    /**
     * 分發報表至 Slack。
     *
     * @param report  報表內容
     * @param channel Slack 頻道
     */
    public void distributeToSlack(String report, String channel) {
        try {
            ObjectNode payload = MAPPER.createObjectNode();
            payload.put("channel", channel);
            payload.put("text", report);
            payload.put("mrkdwn", true);

            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(slackWebhookUrl))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(
                            MAPPER.writeValueAsString(payload)))
                    .build();

            HttpResponse<String> response = httpClient.send(request,
                    HttpResponse.BodyHandlers.ofString());
            logger.info("報表已發送至 Slack #{} (HTTP {})",
                    channel, response.statusCode());
        } catch (Exception e) {
            logger.error("Slack 發送失敗", e);
        }
    }

    /**
     * 將報表儲存至本地檔案。
     *
     * @param report   報表內容
     * @param filename 檔案名稱
     */
    public void saveToFile(String report, String filename) {
        try {
            Path dir = Path.of("reports");
            Files.createDirectories(dir);
            Path file = dir.resolve(filename);
            Files.writeString(file, report);
            logger.info("報表已儲存: {}", file);
        } catch (IOException e) {
            logger.error("檔案儲存失敗", e);
        }
    }

    // -- 私有方法:資料擷取 --

    private Map<String, Double> fetchMetrics(LocalDate date) {
        Map<String, Double> metrics = new LinkedHashMap<>();
        metrics.put("API 請求數", 12345.0);
        metrics.put("平均回應時間 (ms)", 245.0);
        metrics.put("錯誤率 (%)", 0.03);
        metrics.put("活躍使用者", 892.0);
        metrics.put("Agent 處理訊息數", 567.0);
        return metrics;
    }

    private List<Map<String, String>> fetchEvents(LocalDate date) {
        return List.of(
                Map.of("time", "14:23",
                        "description", "API Gateway 短暫延遲 (已自動恢復)")
        );
    }

    private Map<String, Object> fetchGitHubStats(LocalDate date) {
        return Map.of(
                "commits", 23,
                "pullRequests", 5,
                "issuesClosed", 8
        );
    }

    private String generateSummary(Map<String, Double> metrics) {
        return """
                **摘要**: 系統整體運行穩定,API 回應時間符合 SLA 標準,
                活躍使用者數持續成長。有一起短暫的 Gateway 延遲事件已自動恢復。
                
                """;
    }
}
排程觸發器
package com.tutorial.openclaw.cases.reporter;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDate;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

/**
 * 報表排程器。
 *
 * <p>使用 Java ScheduledExecutorService 定期觸發報表生成,
 * 作為 OpenClaw Cron 工具的 Java 端替代方案。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class ReportScheduler {

    private static final Logger logger = LogManager.getLogger(ReportScheduler.class);

    private final ReportService reportService;
    private final ScheduledExecutorService scheduler;

    /**
     * 建立排程器。
     *
     * @param reportService 報表服務
     */
    public ReportScheduler(ReportService reportService) {
        this.reportService = reportService;
        this.scheduler = Executors.newScheduledThreadPool(2);
    }

    /**
     * 啟動排程。
     */
    public void start() {
        // 日報:每天執行
        scheduler.scheduleAtFixedRate(() -> {
            try {
                logger.info("觸發日報排程");
                LocalDate yesterday = LocalDate.now().minusDays(1);
                String report = reportService.generateDailyReport(yesterday);
                reportService.distributeToSlack(report, "#daily-report");
                reportService.saveToFile(report,
                        "daily-" + yesterday + ".md");
            } catch (Exception e) {
                logger.error("日報排程執行失敗", e);
            }
        }, 0, 24, TimeUnit.HOURS);

        // 週報:每 7 天執行
        scheduler.scheduleAtFixedRate(() -> {
            try {
                logger.info("觸發週報排程");
                LocalDate today = LocalDate.now();
                String report = reportService.generateWeeklyReport(today);
                reportService.distributeToSlack(report, "#weekly-report");
                reportService.saveToFile(report,
                        "weekly-" + today + ".md");
            } catch (Exception e) {
                logger.error("週報排程執行失敗", e);
            }
        }, 0, 7, TimeUnit.DAYS);

        logger.info("報表排程器已啟動");
    }

    /**
     * 停止排程。
     */
    public void stop() {
        scheduler.shutdown();
        try {
            if (!scheduler.awaitTermination(10, TimeUnit.SECONDS)) {
                scheduler.shutdownNow();
            }
        } catch (InterruptedException e) {
            scheduler.shutdownNow();
        }
        logger.info("報表排程器已停止");
    }
}

10.2 案例二:智慧客服 Agent

需求描述

建立多層次智慧客服系統,結合 FAQ 快速匹配、AI 理解回覆、工具輔助查詢、真人轉接四個層級。

多層次處理架構

flowchart TD
    MSG[客戶訊息] --> L1{第一層<br>FAQ 匹配}
    L1 -->|命中| FAQ[直接回覆 FAQ]
    L1 -->|未命中| L2{第二層<br>AI 理解}
    L2 -->|簡單問題| AI[AI 生成回覆]
    L2 -->|複雜問題| L3{第三層<br>工具輔助}
    L3 --> TOOL[查詢訂單/帳號]
    TOOL --> AI2[AI 整合回覆]
    L3 -->|無法處理| HUMAN[轉接真人]

Java 智慧客服引擎

package com.tutorial.openclaw.cases.support;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.*;

/**
 * 智慧客服分層處理引擎。
 *
 * <p>實作四層客服處理邏輯:
 * L1 FAQ → L2 AI → L3 工具輔助 → L4 真人轉接</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class CustomerSupportEngine {

    private static final Logger logger = LogManager.getLogger(
            CustomerSupportEngine.class);

    /** FAQ 知識庫 */
    private final Map<String, String> faqDatabase;

    /** 信心閾值 */
    private static final double FAQ_CONFIDENCE_THRESHOLD = 0.85;
    private static final double AI_CONFIDENCE_THRESHOLD = 0.70;

    /**
     * 處理結果。
     */
    public record SupportResult(
            String response,
            String handledBy,
            double confidence,
            boolean escalated
    ) {}

    /**
     * 建立客服引擎。
     */
    public CustomerSupportEngine() {
        this.faqDatabase = new LinkedHashMap<>();
        loadFAQ();
    }

    /**
     * 處理客戶訊息。
     *
     * @param message   客戶訊息
     * @param sessionId 會話 ID
     * @return 處理結果
     */
    public SupportResult handleMessage(String message, String sessionId) {
        logger.info("處理客戶訊息 [session={}]: {}", sessionId,
                message.length() > 50 ? message.substring(0, 50) + "..." : message);

        // L1: FAQ 匹配
        SupportResult faqResult = tryFAQMatch(message);
        if (faqResult != null) {
            logger.info("L1 FAQ 命中 [session={}]", sessionId);
            return faqResult;
        }

        // L2: AI 理解(簡單問題)
        SupportResult aiResult = tryAIResponse(message);
        if (aiResult != null && aiResult.confidence() >= AI_CONFIDENCE_THRESHOLD) {
            logger.info("L2 AI 回覆 [session={}, confidence={}]",
                    sessionId, aiResult.confidence());
            return aiResult;
        }

        // L3: 工具輔助(訂單/帳號查詢)
        if (requiresToolAssist(message)) {
            SupportResult toolResult = handleWithTools(message, sessionId);
            if (toolResult != null) {
                logger.info("L3 工具輔助 [session={}]", sessionId);
                return toolResult;
            }
        }

        // L4: 轉接真人
        logger.info("L4 轉接真人 [session={}]", sessionId);
        return new SupportResult(
                "您的問題需要專人為您服務。正在為您轉接客服人員,請稍候...",
                "human_agent",
                0.0,
                true);
    }

    /**
     * L1: 嘗試 FAQ 匹配。
     */
    private SupportResult tryFAQMatch(String message) {
        String normalizedMsg = message.toLowerCase().trim();
        for (Map.Entry<String, String> entry : faqDatabase.entrySet()) {
            if (normalizedMsg.contains(entry.getKey())) {
                return new SupportResult(
                        entry.getValue(), "faq", 0.95, false);
            }
        }
        return null;
    }

    /**
     * L2: AI 生成回覆。
     */
    private SupportResult tryAIResponse(String message) {
        // 實際會呼叫 OpenClaw Agent
        return new SupportResult(
                "感謝您的詢問。根據我的理解...",
                "ai_agent", 0.75, false);
    }

    /**
     * 判斷是否需要工具輔助。
     */
    private boolean requiresToolAssist(String message) {
        String lower = message.toLowerCase();
        return lower.contains("訂單") || lower.contains("帳號")
                || lower.contains("查詢") || lower.contains("退款");
    }

    /**
     * L3: 使用工具處理。
     */
    private SupportResult handleWithTools(String message, String sessionId) {
        // 實際會呼叫工具 Bridge
        return new SupportResult(
                "我已查詢您的訂單資訊...",
                "tool_assisted", 0.90, false);
    }

    /**
     * 載入 FAQ 知識庫。
     */
    private void loadFAQ() {
        faqDatabase.put("營業時間", "我們的營業時間為週一至週五 09:00-18:00。");
        faqDatabase.put("退款", "退款將在 3-5 個工作天內處理完成。");
        faqDatabase.put("聯絡", "您可以透過 email: support@company.com 聯絡我們。");
        faqDatabase.put("密碼", "請至 https://account.company.com/reset 重設密碼。");
        faqDatabase.put("付款方式", "我們接受信用卡、轉帳和行動支付。");
        logger.info("已載入 {} 條 FAQ", faqDatabase.size());
    }
}

10.3 案例三:任務自動化 Agent

需求描述

建立個人任務管理 Agent,支援自然語言建立任務、設定提醒、追蹤進度,並跨多頻道同步。

自動化流程

flowchart TD
    USER[使用者指令<br>'提醒我明天 3 點開會'] --> NLP[自然語言解析]
    NLP --> EXT{擷取實體}
    EXT --> TIME[時間: 明天 15:00]
    EXT --> ACTION[動作: 提醒]
    EXT --> CONTENT[內容: 開會]
    TIME & ACTION & CONTENT --> TASK[建立任務]
    TASK --> STORE[持久化儲存]
    TASK --> CRON[排程提醒]
    CRON --> |到時| NOTIFY[多頻道通知]

Skill 定義

skills/task-automation/SKILL.md(AgentSkills 格式;觸發條件寫在 description,排程交給內建 Automations):

---
name: task-automation
description: 個人任務管理與自動提醒。當使用者提到待辦、任務、提醒、排程或「幫我記得」時使用
---

# 任務自動化

1. 從訊息中萃取:任務內容、期限(轉為使用者時區的確切時間)、提醒頻道。
2. 時間不明確(例如「下週」)時,先提出一個具體時間請使用者確認。
3. 一次性提醒使用 automations 工具建立 `--at` 排程;週期性提醒使用 `--cron` 並帶時區。
4. 建立後回覆:任務、提醒時間(含時區)、automation ID,方便使用者取消。
5. 每位使用者最多 50 個進行中的提醒;超過時列出最舊的 5 個請使用者整理。

對應的操作者指令(用來驗證 Agent 建立的排程是否正確):

openclaw automations list --json
openclaw automations show <job-id>
openclaw automations rm <job-id>

在對話中也可以直接用 /loop 1h 檢查今天未完成的任務 讓目前對話週期性執行(owner 限定)。

Java 任務管理引擎

package com.tutorial.openclaw.cases.task;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.*;
import java.util.concurrent.*;
import java.util.stream.Collectors;

/**
 * 任務管理引擎。
 *
 * <p>支援任務的 CRUD、排程提醒與多頻道通知。
 * 使用 ScheduledExecutorService 管理定時提醒。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class TaskManager {

    private static final Logger logger = LogManager.getLogger(TaskManager.class);

    /** 任務狀態列舉 */
    public enum TaskStatus {
        PENDING("待處理"),
        IN_PROGRESS("進行中"),
        COMPLETED("已完成"),
        CANCELLED("已取消");

        private final String label;

        TaskStatus(String label) {
            this.label = label;
        }

        public String getLabel() {
            return label;
        }
    }

    /** 任務優先級 */
    public enum Priority {
        LOW("低"), MEDIUM("中"), HIGH("高"), URGENT("緊急");

        private final String label;

        Priority(String label) {
            this.label = label;
        }

        public String getLabel() {
            return label;
        }
    }

    /** 任務記錄 */
    public record Task(
            String id,
            String title,
            String description,
            TaskStatus status,
            Priority priority,
            LocalDateTime createdAt,
            LocalDateTime dueDate,
            LocalDateTime reminderTime,
            String assignee,
            List<String> tags
    ) {}

    private final Map<String, Task> tasks = new ConcurrentHashMap<>();
    private final ScheduledExecutorService scheduler =
            Executors.newScheduledThreadPool(4);
    private final Map<String, ScheduledFuture<?>> reminders =
            new ConcurrentHashMap<>();

    /**
     * 建立新任務。
     *
     * @param title        任務標題
     * @param description  描述
     * @param priority     優先級
     * @param dueDate      到期日
     * @param reminderTime 提醒時間
     * @param assignee     負責人
     * @param tags         標籤
     * @return 建立的任務
     */
    public Task createTask(String title, String description,
                           Priority priority, LocalDateTime dueDate,
                           LocalDateTime reminderTime, String assignee,
                           List<String> tags) {
        String id = "TASK-" + UUID.randomUUID().toString().substring(0, 8);
        Task task = new Task(id, title, description, TaskStatus.PENDING,
                priority, LocalDateTime.now(), dueDate, reminderTime,
                assignee, tags != null ? tags : List.of());
        tasks.put(id, task);
        logger.info("建立任務: {} - {}", id, title);

        // 設定提醒
        if (reminderTime != null && reminderTime.isAfter(LocalDateTime.now())) {
            scheduleReminder(task);
        }

        return task;
    }

    /**
     * 更新任務狀態。
     *
     * @param taskId 任務 ID
     * @param status 新狀態
     * @return 更新後的任務
     */
    public Task updateStatus(String taskId, TaskStatus status) {
        Task old = tasks.get(taskId);
        if (old == null) {
            throw new IllegalArgumentException("找不到任務: " + taskId);
        }
        Task updated = new Task(old.id(), old.title(), old.description(),
                status, old.priority(), old.createdAt(), old.dueDate(),
                old.reminderTime(), old.assignee(), old.tags());
        tasks.put(taskId, updated);
        logger.info("任務 {} 狀態更新: {} → {}", taskId,
                old.status().getLabel(), status.getLabel());

        // 完成或取消時取消提醒
        if (status == TaskStatus.COMPLETED || status == TaskStatus.CANCELLED) {
            cancelReminder(taskId);
        }

        return updated;
    }

    /**
     * 查詢任務列表。
     *
     * @param status   篩選狀態(null 表示全部)
     * @param assignee 篩選負責人(null 表示全部)
     * @return 任務列表
     */
    public List<Task> listTasks(TaskStatus status, String assignee) {
        return tasks.values().stream()
                .filter(t -> status == null || t.status() == status)
                .filter(t -> assignee == null ||
                             assignee.equals(t.assignee()))
                .sorted(Comparator.comparing(Task::priority).reversed()
                        .thenComparing(Task::dueDate,
                                Comparator.nullsLast(
                                        Comparator.naturalOrder())))
                .collect(Collectors.toList());
    }

    /**
     * 產生任務摘要報告。
     *
     * @return Markdown 格式摘要
     */
    public String generateSummary() {
        Map<TaskStatus, Long> statusCount = tasks.values().stream()
                .collect(Collectors.groupingBy(Task::status,
                        Collectors.counting()));
        StringBuilder sb = new StringBuilder();
        sb.append("## 📋 任務摘要\n\n");
        sb.append("| 狀態 | 數量 |\n|------|------|\n");
        for (TaskStatus status : TaskStatus.values()) {
            sb.append(String.format("| %s | %d |\n",
                    status.getLabel(),
                    statusCount.getOrDefault(status, 0L)));
        }

        // 列出高優先級待處理任務
        List<Task> urgent = tasks.values().stream()
                .filter(t -> t.status() == TaskStatus.PENDING)
                .filter(t -> t.priority() == Priority.HIGH
                             || t.priority() == Priority.URGENT)
                .toList();
        if (!urgent.isEmpty()) {
            sb.append("\n### ⚠️ 緊急待處理\n\n");
            urgent.forEach(t -> sb.append(String.format(
                    "- **[%s]** %s (到期: %s)\n",
                    t.id(), t.title(),
                    t.dueDate() != null ? t.dueDate().format(
                            DateTimeFormatter.ofPattern("MM/dd HH:mm"))
                            : "未設定")));
        }

        return sb.toString();
    }

    /**
     * 排程提醒。
     */
    private void scheduleReminder(Task task) {
        long delayMs = java.time.Duration.between(
                LocalDateTime.now(), task.reminderTime()).toMillis();
        if (delayMs <= 0) return;

        ScheduledFuture<?> future = scheduler.schedule(() -> {
            logger.info("觸發提醒: {} - {}", task.id(), task.title());
            // 此處可連接 OpenClaw 通知頻道
        }, delayMs, TimeUnit.MILLISECONDS);

        reminders.put(task.id(), future);
        logger.info("已排程提醒: {} 於 {}", task.id(), task.reminderTime());
    }

    /**
     * 取消提醒。
     */
    private void cancelReminder(String taskId) {
        ScheduledFuture<?> future = reminders.remove(taskId);
        if (future != null) {
            future.cancel(false);
            logger.info("已取消提醒: {}", taskId);
        }
    }

    /**
     * 關閉排程器。
     */
    public void shutdown() {
        scheduler.shutdown();
    }
}

10.4 案例四:DevOps 助手 Agent

需求描述

打造 DevOps 智慧助手,透過自然語言執行常見維運操作:查詢部署狀態、搜尋日誌、處理告警、執行回滾。

核心功能對照

功能觸發方式工具風險等級
部署狀態查詢“部署了什麼版本?”k8s_status低
日誌搜尋“查看錯誤日誌”log_search低
告警處理Webhook 自動alert_handler中
回滾操作“回滾到上一版”k8s_rollback高
效能報告“效能如何?”metrics_query低
擴縮容“增加 Pod 數”k8s_scale高

安全控制流程

flowchart TD
    CMD[使用者指令] --> PARSE[解析意圖]
    PARSE --> RISK{風險評估}
    RISK -->|低風險<br>查詢類| EXEC[直接執行]
    RISK -->|中風險<br>修改類| CONFIRM[要求確認]
    RISK -->|高風險<br>回滾/擴縮| APPROVE{需要審批}
    CONFIRM -->|確認| EXEC
    APPROVE -->|審批通過| EXEC
    APPROVE -->|審批拒絕| DENY[拒絕操作]
    EXEC --> LOG[記錄審計日誌]

Java DevOps 命令執行器

package com.tutorial.openclaw.cases.devops;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDateTime;
import java.util.*;

/**
 * DevOps 指令處理器。
 *
 * <p>解析自然語言 DevOps 指令,根據風險等級執行對應操作。
 * 高風險操作需要審批流程。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class DevOpsCommandExecutor {

    private static final Logger logger = LogManager.getLogger(
            DevOpsCommandExecutor.class);

    /** 風險等級 */
    public enum RiskLevel { LOW, MEDIUM, HIGH, CRITICAL }

    /** 操作類型 */
    public enum OperationType {
        QUERY_STATUS("查詢狀態", RiskLevel.LOW),
        SEARCH_LOGS("搜尋日誌", RiskLevel.LOW),
        QUERY_METRICS("查詢指標", RiskLevel.LOW),
        HANDLE_ALERT("處理告警", RiskLevel.MEDIUM),
        ROLLBACK("回滾部署", RiskLevel.HIGH),
        SCALE("擴縮容量", RiskLevel.HIGH),
        RESTART("重啟服務", RiskLevel.HIGH),
        DELETE("刪除資源", RiskLevel.CRITICAL);

        private final String label;
        private final RiskLevel risk;

        OperationType(String label, RiskLevel risk) {
            this.label = label;
            this.risk = risk;
        }

        public String getLabel() { return label; }
        public RiskLevel getRisk() { return risk; }
    }

    /** 執行結果 */
    public record ExecutionResult(
            boolean success,
            String message,
            OperationType operation,
            RiskLevel risk,
            String executedBy,
            LocalDateTime executedAt
    ) {}

    /** 已核准的操作佇列 */
    private final Set<String> approvedOperations = new HashSet<>();

    /**
     * 解析並執行 DevOps 指令。
     *
     * @param command   自然語言指令
     * @param operator  操作者
     * @return 執行結果
     */
    public ExecutionResult executeCommand(String command, String operator) {
        OperationType opType = parseOperation(command);
        logger.info("解析指令: '{}' → {} (風險: {})",
                command, opType.getLabel(), opType.getRisk());

        // 風險等級檢查
        switch (opType.getRisk()) {
            case LOW:
                return executeDirectly(opType, command, operator);
            case MEDIUM:
                logger.warn("中風險操作需確認: {}", opType.getLabel());
                return executeWithConfirmation(opType, command, operator);
            case HIGH:
            case CRITICAL:
                String opId = UUID.randomUUID().toString();
                if (approvedOperations.contains(opId)) {
                    return executeDirectly(opType, command, operator);
                }
                return new ExecutionResult(false,
                        String.format("❌ %s 為%s操作,需要管理員審批。" +
                                      "操作 ID: %s",
                                opType.getLabel(),
                                opType.getRisk() == RiskLevel.CRITICAL
                                        ? "嚴重" : "高風險",
                                opId),
                        opType, opType.getRisk(), operator,
                        LocalDateTime.now());
        }

        return new ExecutionResult(false, "無法處理指令",
                opType, opType.getRisk(), operator, LocalDateTime.now());
    }

    /**
     * 查詢 Kubernetes 部署狀態。
     *
     * @param namespace 命名空間
     * @return 狀態描述
     */
    public String queryDeploymentStatus(String namespace) {
        // 實際會呼叫 K8s API
        return String.format("""
                ## 📦 部署狀態 (%s)
                
                | 服務 | 版本 | Pods | CPU | Memory | 狀態 |
                |------|------|------|-----|--------|------|
                | gateway | v2026.7.1 | 2/2 | 45%% | 1.2GB | ✅ |
                | tool-bridge | v1.5.0 | 2/2 | 30%% | 800MB | ✅ |
                | worker | v1.3.1 | 3/3 | 60%% | 2.1GB | ✅ |
                
                最後部署: 2024-01-15 14:30 by devops-bot
                """, namespace);
    }

    /**
     * 搜尋錯誤日誌。
     *
     * @param service   服務名
     * @param timeRange 時間範圍(分鐘)
     * @param keyword   關鍵字
     * @return 日誌摘要
     */
    public String searchErrorLogs(String service, int timeRange,
                                  String keyword) {
        return String.format("""
                ## 🔍 日誌搜尋結果
                
                **服務**: %s | **範圍**: 最近 %d 分鐘 | **關鍵字**: %s
                
                找到 **3** 筆錯誤記錄:
                
                ~~~text
                [14:23:01] ERROR Connection timeout to database (retry 1/3)
                [14:23:05] ERROR Connection timeout to database (retry 2/3)
                [14:23:10] WARN  Database connection restored
                ~~~
                
                **分析**: 資料庫連線短暫中斷,已自動恢復。建議檢查資料庫連線池設定。
                """, service, timeRange, keyword);
    }

    // -- 私有方法 --

    private OperationType parseOperation(String command) {
        String lower = command.toLowerCase();
        if (lower.contains("回滾") || lower.contains("rollback"))
            return OperationType.ROLLBACK;
        if (lower.contains("擴") || lower.contains("scale"))
            return OperationType.SCALE;
        if (lower.contains("重啟") || lower.contains("restart"))
            return OperationType.RESTART;
        if (lower.contains("刪除") || lower.contains("delete"))
            return OperationType.DELETE;
        if (lower.contains("告警") || lower.contains("alert"))
            return OperationType.HANDLE_ALERT;
        if (lower.contains("日誌") || lower.contains("log"))
            return OperationType.SEARCH_LOGS;
        if (lower.contains("效能") || lower.contains("metric"))
            return OperationType.QUERY_METRICS;
        return OperationType.QUERY_STATUS;
    }

    private ExecutionResult executeDirectly(OperationType op,
                                            String command, String operator) {
        logger.info("執行操作: {} by {}", op.getLabel(), operator);
        return new ExecutionResult(true,
                "✅ " + op.getLabel() + " 執行成功",
                op, op.getRisk(), operator, LocalDateTime.now());
    }

    private ExecutionResult executeWithConfirmation(OperationType op,
                                                    String command,
                                                    String operator) {
        // 實際會發送確認請求
        logger.info("中風險操作確認後執行: {} by {}",
                op.getLabel(), operator);
        return new ExecutionResult(true,
                "⚠️ " + op.getLabel() + " 已確認並執行",
                op, op.getRisk(), operator, LocalDateTime.now());
    }
}

10.5 案例五:知識庫搜尋 Agent

需求描述

建立 RAG(Retrieval-Augmented Generation)知識庫系統,讓使用者透過自然語言查詢企業文件,並獲得引用來源的精確回答。

搜尋流程

flowchart TD
    Q[使用者問題] --> EMBED[向量嵌入]
    EMBED --> SEARCH[向量搜尋<br>top-k=5]
    SEARCH --> RERANK[重新排序]
    RERANK --> CONTEXT[組合上下文]
    CONTEXT --> LLM[LLM 生成答案]
    LLM --> CITE[附加引用來源]
    CITE --> RESPONSE[回覆使用者]

知識庫索引架構

graph LR
    subgraph "文件來源"
        CONF[Confluence]
        WIKI[Wiki]
        GIT[Git Repos]
        PDF[PDF 文件]
    end
    
    subgraph "索引管線"
        PARSE[文件解析] --> CHUNK[分段切割<br>512 tokens]
        CHUNK --> EMBED[向量嵌入<br>text-embedding-3]
        EMBED --> INDEX[向量索引<br>HNSW]
    end
    
    subgraph "查詢流程"
        QUERY[查詢嵌入] --> ANN[近似搜尋]
        ANN --> RERANK[Cross-Encoder<br>重排序]
    end
    
    CONF & WIKI & GIT & PDF --> PARSE
    INDEX --> ANN

Java RAG 客戶端

package com.tutorial.openclaw.cases.knowledge;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.*;
import java.util.stream.Collectors;

/**
 * RAG 知識庫查詢客戶端。
 *
 * <p>將使用者問題轉為向量嵌入,搜尋知識庫,
 * 並將相關文件片段組合為 LLM 的上下文。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class KnowledgeBaseClient {

    private static final Logger logger = LogManager.getLogger(
            KnowledgeBaseClient.class);
    private static final ObjectMapper MAPPER = new ObjectMapper();

    private final HttpClient httpClient;
    private final String embeddingApiUrl;
    private final String vectorDbUrl;
    private final String openClawUrl;

    /** 搜尋結果 */
    public record SearchResult(
            String documentId,
            String title,
            String content,
            double score,
            String source,
            Map<String, String> metadata
    ) {}

    /** 知識回覆 */
    public record KnowledgeAnswer(
            String answer,
            List<SearchResult> citations,
            double confidence
    ) {}

    /**
     * 建立知識庫客戶端。
     *
     * @param embeddingApiUrl 嵌入 API URL
     * @param vectorDbUrl     向量資料庫 URL
     * @param openClawUrl     OpenClaw API URL
     */
    public KnowledgeBaseClient(String embeddingApiUrl,
                               String vectorDbUrl,
                               String openClawUrl) {
        this.httpClient = HttpClient.newHttpClient();
        this.embeddingApiUrl = embeddingApiUrl;
        this.vectorDbUrl = vectorDbUrl;
        this.openClawUrl = openClawUrl;
    }

    /**
     * 查詢知識庫。
     *
     * @param question 使用者問題
     * @param topK     返回前 K 個結果
     * @return 知識回覆(含引用來源)
     */
    public KnowledgeAnswer query(String question, int topK) {
        logger.info("知識庫查詢: '{}' (top-{})", question, topK);

        // Step 1: 向量嵌入
        double[] embedding = getEmbedding(question);
        logger.debug("嵌入向量維度: {}", embedding.length);

        // Step 2: 向量搜尋
        List<SearchResult> results = vectorSearch(embedding, topK);
        logger.info("搜尋到 {} 筆相關文件", results.size());

        // Step 3: 重新排序(Cross-Encoder)
        results = rerank(question, results);

        // Step 4: 組合上下文並呼叫 LLM
        String context = buildContext(results);
        String answer = generateAnswer(question, context);

        // Step 5: 附加引用來源
        double avgScore = results.stream()
                .mapToDouble(SearchResult::score)
                .average().orElse(0.0);

        return new KnowledgeAnswer(answer, results, avgScore);
    }

    /**
     * 格式化知識回覆為 Markdown。
     *
     * @param ka 知識回覆
     * @return Markdown 格式
     */
    public String formatAnswer(KnowledgeAnswer ka) {
        StringBuilder sb = new StringBuilder();
        sb.append(ka.answer()).append("\n\n");
        sb.append("---\n\n");
        sb.append("📚 **引用來源** (信心度: ")
          .append(String.format("%.0f%%", ka.confidence() * 100))
          .append(")\n\n");

        for (int i = 0; i < ka.citations().size(); i++) {
            SearchResult r = ka.citations().get(i);
            sb.append(String.format(
                    "%d. **[%s](%s)** — 相關度 %.0f%%\n",
                    i + 1, r.title(), r.source(),
                    r.score() * 100));
        }

        return sb.toString();
    }

    // -- 私有方法 --

    private double[] getEmbedding(String text) {
        // 實際呼叫 OpenAI Embedding API
        return new double[1536]; // text-embedding-3-small
    }

    private List<SearchResult> vectorSearch(double[] embedding, int topK) {
        // 實際呼叫向量資料庫(例如 Qdrant / Weaviate)
        return List.of(
                new SearchResult("doc-1", "OpenClaw 安裝指南",
                        "安裝 OpenClaw 需要 Node.js >= 22...",
                        0.92, "docs/install.md", Map.of()),
                new SearchResult("doc-2", "OpenClaw 技能開發",
                        "建立自訂技能需要在 SKILL.md 中...",
                        0.87, "docs/skills.md", Map.of())
        );
    }

    private List<SearchResult> rerank(String query,
                                      List<SearchResult> results) {
        // Cross-Encoder 重排序
        return results;
    }

    private String buildContext(List<SearchResult> results) {
        return results.stream()
                .map(r -> String.format("### %s\n%s\n", r.title(), r.content()))
                .collect(Collectors.joining("\n"));
    }

    private String generateAnswer(String question, String context) {
        // 呼叫 OpenClaw LLM 生成回覆
        return "根據知識庫資料," + question + " 的答案是...";
    }
}

10.6 案例六:多 Agent 協作系統

需求描述

建立多 Agent 協作架構,由協調者 (Orchestrator) Agent 管理多個專職 Agent,協同處理軟體開發生命週期。

專案管理團隊架構

graph TD
    PM[PM Agent<br>協調者] --> PLAN[需求分析]
    PLAN --> ASSIGN[任務分配]
    
    ASSIGN --> CODE[Coding Agent<br>撰寫程式碼]
    ASSIGN --> REVIEW[Review Agent<br>程式碼審查]
    ASSIGN --> TEST[Test Agent<br>撰寫測試]
    ASSIGN --> DEPLOY[Deploy Agent<br>部署管理]
    
    CODE --> |PR| REVIEW
    REVIEW --> |修改建議| CODE
    REVIEW --> |通過| TEST
    TEST --> |通過| DEPLOY
    TEST --> |失敗| CODE
    
    CODE & REVIEW & TEST & DEPLOY --> |進度回報| PM

工作流程

  1. PM Agent 收到需求 → 分析並建立任務
  2. Coding Agent 撰寫程式碼 → PR
  3. Review Agent 審查 → 建議修改
  4. Test Agent 撰寫並執行測試 → 報告結果
  5. Deploy Agent 部署到 Staging → 驗證
  6. PM Agent 彙報進度

Java 多 Agent 協調器

package com.tutorial.openclaw.cases.multiagent;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDateTime;
import java.util.*;
import java.util.concurrent.*;

/**
 * 多 Agent 協作協調器。
 *
 * <p>管理多個 Agent 之間的任務分配、狀態追蹤和進度回報。
 * 支援 DAG(有向無環圖)任務依賴關係。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class AgentOrchestrator {

    private static final Logger logger = LogManager.getLogger(
            AgentOrchestrator.class);

    /** Agent 角色定義 */
    public enum AgentRole {
        PM("專案管理"),
        CODER("程式開發"),
        REVIEWER("程式碼審查"),
        TESTER("品質測試"),
        DEPLOYER("部署管理");

        private final String label;

        AgentRole(String label) {
            this.label = label;
        }

        public String getLabel() {
            return label;
        }
    }

    /** 任務狀態 */
    public enum WorkStatus {
        QUEUED, ASSIGNED, IN_PROGRESS, REVIEW, COMPLETED, FAILED
    }

    /** 工作項目 */
    public record WorkItem(
            String id,
            String description,
            AgentRole assignedTo,
            WorkStatus status,
            List<String> dependencies,
            Map<String, String> output,
            LocalDateTime startedAt,
            LocalDateTime completedAt
    ) {}

    private final Map<String, WorkItem> workItems =
            new ConcurrentHashMap<>();
    private final ExecutorService executor =
            Executors.newFixedThreadPool(4);

    /**
     * 建立開發流程。
     *
     * @param requirement 需求描述
     * @return 工作 ID 列表
     */
    public List<String> createDevelopmentWorkflow(String requirement) {
        logger.info("建立開發流程: {}", requirement);

        List<String> workIds = new ArrayList<>();

        // Step 1: 需求分析
        String planId = createWork("需求分析: " + requirement,
                AgentRole.PM, List.of());
        workIds.add(planId);

        // Step 2: 程式開發(依賴需求分析)
        String codeId = createWork("程式開發",
                AgentRole.CODER, List.of(planId));
        workIds.add(codeId);

        // Step 3: 程式碼審查(依賴程式開發)
        String reviewId = createWork("程式碼審查",
                AgentRole.REVIEWER, List.of(codeId));
        workIds.add(reviewId);

        // Step 4: 單元測試(依賴程式碼審查通過)
        String testId = createWork("撰寫與執行測試",
                AgentRole.TESTER, List.of(reviewId));
        workIds.add(testId);

        // Step 5: 部署(依賴測試通過)
        String deployId = createWork("部署至 Staging",
                AgentRole.DEPLOYER, List.of(testId));
        workIds.add(deployId);

        logger.info("開發流程已建立,共 {} 個工作項目", workIds.size());
        return workIds;
    }

    /**
     * 建立工作項目。
     *
     * @param description  描述
     * @param assignTo     指派給
     * @param dependencies 依賴項
     * @return 工作 ID
     */
    public String createWork(String description, AgentRole assignTo,
                             List<String> dependencies) {
        String id = "WI-" + UUID.randomUUID().toString().substring(0, 6);
        WorkItem item = new WorkItem(id, description, assignTo,
                WorkStatus.QUEUED, dependencies, new HashMap<>(),
                null, null);
        workItems.put(id, item);
        return id;
    }

    /**
     * 執行就緒的工作項目。
     */
    public void executeReadyWork() {
        workItems.values().stream()
                .filter(w -> w.status() == WorkStatus.QUEUED)
                .filter(this::areDependenciesMet)
                .forEach(w -> {
                    logger.info("開始執行: {} ({})",
                            w.id(), w.description());
                    updateStatus(w.id(), WorkStatus.IN_PROGRESS);
                    executor.submit(() -> executeWork(w));
                });
    }

    /**
     * 產生進度報告。
     *
     * @return Markdown 進度報告
     */
    public String generateProgressReport() {
        StringBuilder sb = new StringBuilder();
        sb.append("## 🔄 開發流程進度\n\n");
        sb.append("| ID | 任務 | 負責 | 狀態 |\n");
        sb.append("|-----|------|------|------|\n");

        workItems.values().stream()
                .sorted(Comparator.comparing(w ->
                        w.startedAt() != null ? w.startedAt()
                                : LocalDateTime.MAX))
                .forEach(w -> {
                    String statusIcon = switch (w.status()) {
                        case QUEUED -> "⏳";
                        case ASSIGNED -> "📋";
                        case IN_PROGRESS -> "🔄";
                        case REVIEW -> "👀";
                        case COMPLETED -> "✅";
                        case FAILED -> "❌";
                    };
                    sb.append(String.format("| %s | %s | %s | %s %s |\n",
                            w.id(), w.description(),
                            w.assignedTo().getLabel(),
                            statusIcon, w.status()));
                });

        return sb.toString();
    }

    // -- 私有方法 --

    private boolean areDependenciesMet(WorkItem work) {
        return work.dependencies().stream()
                .allMatch(depId -> {
                    WorkItem dep = workItems.get(depId);
                    return dep != null &&
                           dep.status() == WorkStatus.COMPLETED;
                });
    }

    private void updateStatus(String workId, WorkStatus status) {
        WorkItem old = workItems.get(workId);
        if (old != null) {
            WorkItem updated = new WorkItem(old.id(), old.description(),
                    old.assignedTo(), status, old.dependencies(),
                    old.output(),
                    status == WorkStatus.IN_PROGRESS
                            ? LocalDateTime.now() : old.startedAt(),
                    status == WorkStatus.COMPLETED
                            ? LocalDateTime.now() : old.completedAt());
            workItems.put(workId, updated);
        }
    }

    private void executeWork(WorkItem work) {
        try {
            Thread.sleep(100); // 模擬執行
            updateStatus(work.id(), WorkStatus.COMPLETED);
            logger.info("工作完成: {} ({})", work.id(), work.description());
            // 觸發下游任務
            executeReadyWork();
        } catch (Exception e) {
            updateStatus(work.id(), WorkStatus.FAILED);
            logger.error("工作失敗: {}", work.id(), e);
        }
    }
}

10.7 案例七:企業通知中樞

需求描述

建立統一的企業通知中樞,接收來自 GitHub、Jira、PagerDuty、Jenkins 等系統的事件,透過智慧路由分發到適當的通知頻道。

多頻道通知架構

graph TB
    subgraph "事件來源"
        GH[GitHub]
        JIRA[Jira]
        PAGER[PagerDuty]
        JENKINS[Jenkins]
    end
    
    subgraph "OpenClaw Agent"
        WH[Webhook 接收]
        ROUTE[智慧路由]
        FORMAT[格式化訊息]
    end
    
    subgraph "通知頻道"
        SLK[Slack]
        TG[Telegram]
        TEAMS[Teams]
        EMAIL[Email]
    end
    
    GH & JIRA & PAGER & JENKINS --> WH
    WH --> ROUTE
    ROUTE --> FORMAT
    FORMAT --> SLK & TG & TEAMS & EMAIL

路由規則

事件類型優先級路由目標格式化
PagerDuty CriticalP0Slack + Telegram + SMS🔴 緊急告警
GitHub PR MergedP3Slack #dev📦 合併通知
Jira Issue 到期P2Telegram 負責人⏰ 到期提醒
Jenkins Build 失敗P1Slack #ci-cd❌ 建置失敗
Jenkins Build 成功P4Slack #ci-cd✅ 建置成功

Java 通知路由引擎

package com.tutorial.openclaw.cases.notification;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDateTime;
import java.util.*;
import java.util.concurrent.CopyOnWriteArrayList;

/**
 * 企業通知路由引擎。
 *
 * <p>根據事件類型、優先級和路由規則,將通知分發到適當的頻道。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class NotificationRouter {

    private static final Logger logger = LogManager.getLogger(
            NotificationRouter.class);

    /** 優先級定義 */
    public enum Priority {
        P0("緊急", 0), P1("高", 1), P2("中", 2),
        P3("低", 3), P4("資訊", 4);

        private final String label;
        private final int level;

        Priority(String label, int level) {
            this.label = label;
            this.level = level;
        }

        public String getLabel() { return label; }
        public int getLevel() { return level; }
    }

    /** 通知事件 */
    public record NotificationEvent(
            String source,
            String eventType,
            Priority priority,
            String title,
            String body,
            Map<String, String> metadata,
            LocalDateTime timestamp
    ) {}

    /** 路由規則 */
    public record RoutingRule(
            String source,
            String eventPattern,
            Priority minPriority,
            List<String> channels,
            String template
    ) {}

    /** 通知訊息 */
    public record Notification(
            String channel,
            String formattedMessage,
            Priority priority,
            LocalDateTime sentAt
    ) {}

    private final List<RoutingRule> rules = new CopyOnWriteArrayList<>();
    private final List<Notification> sentLog = new CopyOnWriteArrayList<>();

    /**
     * 建立路由引擎,載入預設規則。
     */
    public NotificationRouter() {
        loadDefaultRules();
    }

    /**
     * 處理 Webhook 事件。
     *
     * @param event 通知事件
     * @return 已發送的通知列表
     */
    public List<Notification> processEvent(NotificationEvent event) {
        logger.info("處理事件: [{}] {} - {} (P{})",
                event.source(), event.eventType(),
                event.title(), event.priority().getLevel());

        List<Notification> notifications = new ArrayList<>();

        // 匹配路由規則
        List<RoutingRule> matchedRules = rules.stream()
                .filter(r -> matchesRule(event, r))
                .toList();

        if (matchedRules.isEmpty()) {
            logger.warn("無匹配規則: [{}] {}",
                    event.source(), event.eventType());
            return notifications;
        }

        // 根據規則分發
        for (RoutingRule rule : matchedRules) {
            String formatted = formatMessage(event, rule.template());
            for (String channel : rule.channels()) {
                Notification notif = new Notification(
                        channel, formatted, event.priority(),
                        LocalDateTime.now());
                notifications.add(notif);
                sentLog.add(notif);
                logger.info("通知已發送: {} → {}", event.title(), channel);
            }
        }

        return notifications;
    }

    /**
     * 取得發送統計。
     *
     * @return Markdown 格式統計
     */
    public String getStatistics() {
        StringBuilder sb = new StringBuilder();
        sb.append("## 📊 通知統計\n\n");
        sb.append(String.format("- 總發送數: **%d**\n", sentLog.size()));

        Map<String, Long> byChannel = new LinkedHashMap<>();
        sentLog.forEach(n ->
                byChannel.merge(n.channel(), 1L, Long::sum));

        sb.append("\n| 頻道 | 數量 |\n|------|------|\n");
        byChannel.forEach((ch, count) ->
                sb.append(String.format("| %s | %d |\n", ch, count)));

        return sb.toString();
    }

    // -- 私有方法 --

    private void loadDefaultRules() {
        rules.add(new RoutingRule("pagerduty", "trigger",
                Priority.P0,
                List.of("slack:#oncall", "telegram:oncall", "sms"),
                "🔴 **P0 告警** - ${title}\n${body}"));
        rules.add(new RoutingRule("github", "pull_request.merged",
                Priority.P3,
                List.of("slack:#dev"),
                "📦 **PR 合併** - ${title}"));
        rules.add(new RoutingRule("jira", "issue.due",
                Priority.P2,
                List.of("telegram:${assignee}"),
                "⏰ **到期提醒** - ${title}"));
        rules.add(new RoutingRule("jenkins", "build.failure",
                Priority.P1,
                List.of("slack:#ci-cd"),
                "❌ **建置失敗** - ${title}\n${body}"));
        rules.add(new RoutingRule("jenkins", "build.success",
                Priority.P4,
                List.of("slack:#ci-cd"),
                "✅ **建置成功** - ${title}"));
        logger.info("已載入 {} 條路由規則", rules.size());
    }

    private boolean matchesRule(NotificationEvent event, RoutingRule rule) {
        return event.source().equalsIgnoreCase(rule.source())
                && event.eventType().contains(rule.eventPattern())
                && event.priority().getLevel() <= rule.minPriority().getLevel();
    }

    private String formatMessage(NotificationEvent event, String template) {
        String msg = template
                .replace("${title}", event.title())
                .replace("${body}", event.body() != null ? event.body() : "");
        if (event.metadata() != null) {
            for (Map.Entry<String, String> entry : event.metadata().entrySet()) {
                msg = msg.replace("${" + entry.getKey() + "}",
                        entry.getValue());
            }
        }
        return msg;
    }
}

10.8 案例八:資料分析管線 Agent

需求描述

建立自動化 ETL (Extract-Transform-Load) 管線 Agent,從多個資料來源擷取數據、進行清洗轉換、載入數據倉庫,並自動生成分析報表。

ETL 管線架構

flowchart LR
    subgraph "Extract"
        DB[(資料庫)]
        API[REST API]
        CSV[CSV 檔案]
    end
    
    subgraph "Transform"
        CLEAN[資料清洗]
        ENRICH[資料擴充]
        AGG[聚合運算]
    end
    
    subgraph "Load"
        DW[(數據倉庫)]
        REPORT[報表生成]
        ALERT[異常告警]
    end
    
    DB & API & CSV --> CLEAN
    CLEAN --> ENRICH --> AGG
    AGG --> DW & REPORT & ALERT

ETL 自動化 Skill 定義

skills/data-pipeline/SKILL.md:工作流程的步驟寫成給模型看的程序,實際的擷取/轉換/載入由下方的 Java 管線或內部 API 執行(Agent 透過 4.4 的工具呼叫它們):

---
name: data-pipeline
description: 企業資料分析管線。當使用者要求分析數據、執行 ETL、產生資料報表或檢查資料品質時使用
metadata:
  openclaw:
    requires:
      bins: ["curl", "jq"]
      env: ["ETL_API_TOKEN"]
---

# 資料分析管線

## 步驟

1. 確認資料來源、期間與輸出格式;任一項不明確就先反問。
2. 呼叫 `etl_run` 工具(ETL 服務),參數:`source`、`from`、`to`、`operations=["clean","aggregate"]`。
3. 檢查回傳的 `rowCount` 與 `rejectedRows`;`rejectedRows` 超過 1% 時,**停止並回報**,不要繼續產出報表。
4. 以 `etl_chart` 產生圖表,並在回覆中附上資料期間、筆數與被剔除的筆數。

## 禁止事項

- 不直接連線資料庫;所有存取都經由 ETL 服務的唯讀帳號。
- 不在回覆中貼出原始個資欄位(姓名、身分證字號、電話)。

❌ 舊版範例以 JSON 定義 triggers、tools、workflow.steps。OpenClaw 的技能沒有這種宣告式工作流程格式;若需要確定性的多步驟流程,請改用 Lobster 管線、Automations,或由外部編排器(4.5)控制。

Java ETL 管線框架

package com.tutorial.openclaw.cases.etl;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.Duration;
import java.time.LocalDateTime;
import java.util.*;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.stream.Collectors;

/**
 * ETL 管線框架。
 *
 * <p>提供流暢式 API 定義 ETL 管線,支援多種擷取來源、
 * 轉換鏈和載入目標。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class EtlPipeline<T> {

    private static final Logger logger = LogManager.getLogger(
            EtlPipeline.class);

    /** 管線步驟 */
    public sealed interface PipelineStep<I, O>
            permits ExtractStep, TransformStep, LoadStep {

        String name();

        O execute(I input);
    }

    /** 擷取步驟 */
    public record ExtractStep<O>(
            String name,
            Function<Void, O> extractor
    ) implements PipelineStep<Void, O> {
        @Override
        public O execute(Void input) {
            return extractor.apply(null);
        }
    }

    /** 轉換步驟 */
    public record TransformStep<I, O>(
            String name,
            Function<I, O> transformer
    ) implements PipelineStep<I, O> {
        @Override
        public O execute(I input) {
            return transformer.apply(input);
        }
    }

    /** 載入步驟 */
    public record LoadStep<I>(
            String name,
            java.util.function.Consumer<I> loader
    ) implements PipelineStep<I, Void> {
        @Override
        public Void execute(I input) {
            loader.accept(input);
            return null;
        }
    }

    /** 管線執行結果 */
    public record PipelineResult(
            boolean success,
            int recordsProcessed,
            Duration duration,
            List<String> errors,
            Map<String, Object> metrics
    ) {}

    private final String pipelineName;
    private final List<Object> steps = new ArrayList<>();

    /**
     * 建立 ETL 管線。
     *
     * @param name 管線名稱
     */
    public EtlPipeline(String name) {
        this.pipelineName = name;
    }

    /**
     * 流暢式 API: 定義擷取步驟。
     */
    @SuppressWarnings("unchecked")
    public <O> EtlPipeline<O> extract(String name,
                                       Function<Void, O> extractor) {
        steps.add(new ExtractStep<>(name, extractor));
        return (EtlPipeline<O>) this;
    }

    /**
     * 流暢式 API: 定義轉換步驟。
     */
    @SuppressWarnings("unchecked")
    public <O> EtlPipeline<O> transform(String name,
                                          Function<T, O> transformer) {
        steps.add(new TransformStep<>(name, transformer));
        return (EtlPipeline<O>) this;
    }

    /**
     * 執行管線。
     *
     * @return 執行結果
     */
    public PipelineResult run() {
        LocalDateTime start = LocalDateTime.now();
        logger.info("開始執行 ETL 管線: {}", pipelineName);

        List<String> errors = new ArrayList<>();
        Object current = null;
        int recordCount = 0;

        for (Object step : steps) {
            String stepName = ((PipelineStep<?, ?>) step).name();
            try {
                logger.info("執行步驟: {}", stepName);
                if (step instanceof ExtractStep<?> es) {
                    current = es.execute(null);
                    if (current instanceof Collection<?> c) {
                        recordCount = c.size();
                    }
                } else if (step instanceof TransformStep<?, ?> ts) {
                    @SuppressWarnings("unchecked")
                    var typedStep = (TransformStep<Object, ?>) ts;
                    current = typedStep.execute(current);
                } else if (step instanceof LoadStep<?> ls) {
                    @SuppressWarnings("unchecked")
                    var typedStep = (LoadStep<Object>) ls;
                    typedStep.execute(current);
                }
                logger.info("步驟完成: {}", stepName);
            } catch (Exception e) {
                String error = String.format(
                        "步驟 '%s' 失敗: %s", stepName, e.getMessage());
                errors.add(error);
                logger.error(error, e);
            }
        }

        Duration duration = Duration.between(start, LocalDateTime.now());
        boolean success = errors.isEmpty();

        PipelineResult result = new PipelineResult(
                success, recordCount, duration, errors,
                Map.of("pipeline", pipelineName,
                        "steps", steps.size()));

        logger.info("ETL 管線 {} 完成 ({}): {} 筆資料, 耗時 {} 秒",
                pipelineName, success ? "成功" : "失敗",
                recordCount, duration.toSeconds());

        return result;
    }
}

使用範例

// 建立並執行 ETL 管線
EtlPipeline<Void> pipeline = new EtlPipeline<>("daily-sales-etl");

EtlPipeline.PipelineResult result = pipeline
        .extract("從資料庫擷取銷售資料", v -> {
            // 模擬擷取資料
            return List.of(
                    Map.of("product", "A", "amount", 100),
                    Map.of("product", "B", "amount", 200),
                    Map.of("product", "A", "amount", 150)
            );
        })
        .transform("清洗與驗證", data -> {
            // 過濾無效記錄
            return ((List<Map<String, Object>>) data).stream()
                    .filter(r -> r.get("amount") != null)
                    .collect(Collectors.toList());
        })
        .transform("聚合統計", data -> {
            // 按產品聚合
            return ((List<Map<String, Object>>) data).stream()
                    .collect(Collectors.groupingBy(
                            r -> (String) r.get("product"),
                            Collectors.summingInt(
                                    r -> (int) r.get("amount"))));
        })
        .run();

System.out.println("成功: " + result.success());
System.out.println("處理記錄: " + result.recordsProcessed());
System.out.println("耗時: " + result.duration().toMillis() + "ms");

10.9 案例九:安全監控 Agent

需求描述

建立自動化安全監控 Agent,即時分析安全日誌、偵測威脅、自動執行初步回應,並在嚴重事件時啟動事件回應流程。

威脅偵測流程

flowchart TD
    LOG[安全日誌<br>Webhook] --> ANALYZE[分析引擎]
    ANALYZE --> THREAT{威脅等級?}
    
    THREAT -->|低| LOG_IT[記錄並監控]
    THREAT -->|中| ALERT[告警通知<br>Slack/Telegram]
    THREAT -->|高| BLOCK[自動封鎖<br>+ 緊急通知]
    THREAT -->|嚴重| INCIDENT[建立事件<br>通知 On-Call<br>自動取證]

威脅等級定義

等級代號範例自動回應SLA
低SEV-4登入失敗 (< 3次)記錄24h
中SEV-3登入失敗 (≥ 5次)告警4h
高SEV-2可疑 API 呼叫模式封鎖+告警1h
嚴重SEV-1資料外洩跡象封鎖+取證+通知15min

Java 安全監控引擎

package com.tutorial.openclaw.cases.security;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.time.LocalDateTime;
import java.time.temporal.ChronoUnit;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;

/**
 * 安全威脅偵測與回應引擎。
 *
 * <p>即時分析安全事件,根據規則判定威脅等級,
 * 執行自動回應動作(記錄、告警、封鎖、取證)。</p>
 *
 * @author Tutorial Team
 * @version 1.0.0
 */
public class SecurityMonitor {

    private static final Logger logger = LogManager.getLogger(
            SecurityMonitor.class);

    /** 威脅等級 */
    public enum Severity {
        LOW("SEV-4", "低"), MEDIUM("SEV-3", "中"),
        HIGH("SEV-2", "高"), CRITICAL("SEV-1", "嚴重");

        private final String code;
        private final String label;

        Severity(String code, String label) {
            this.code = code;
            this.label = label;
        }

        public String getCode() { return code; }
        public String getLabel() { return label; }
    }

    /** 安全事件 */
    public record SecurityEvent(
            String eventId,
            String source,
            String eventType,
            String sourceIp,
            String userId,
            String description,
            Map<String, String> details,
            LocalDateTime timestamp
    ) {}

    /** 威脅評估結果 */
    public record ThreatAssessment(
            SecurityEvent event,
            Severity severity,
            double riskScore,
            List<String> indicators,
            List<String> actions
    ) {}

    /** IP 登入追蹤:IP → 近期失敗次數 */
    private final Map<String, AtomicInteger> loginFailures =
            new ConcurrentHashMap<>();

    /** 被封鎖的 IP */
    private final Set<String> blockedIps =
            ConcurrentHashMap.newKeySet();

    /** 事件歷史 */
    private final List<ThreatAssessment> assessmentHistory =
            new CopyOnWriteArrayList<>();

    /**
     * 分析安全事件。
     *
     * @param event 安全事件
     * @return 威脅評估結果
     */
    public ThreatAssessment analyzeEvent(SecurityEvent event) {
        logger.info("分析安全事件: [{}] {} from {}",
                event.eventType(), event.description(), event.sourceIp());

        List<String> indicators = new ArrayList<>();
        double riskScore = 0.0;

        // 檢查 IP 是否已封鎖
        if (blockedIps.contains(event.sourceIp())) {
            indicators.add("IP 已在封鎖名單中");
            riskScore += 30;
        }

        // 分析事件類型
        switch (event.eventType()) {
            case "login_failure" -> {
                int failures = loginFailures
                        .computeIfAbsent(event.sourceIp(),
                                k -> new AtomicInteger(0))
                        .incrementAndGet();
                riskScore += failures * 10;
                if (failures >= 5) {
                    indicators.add("頻繁登入失敗 (" + failures + " 次)");
                }
                if (failures >= 10) {
                    indicators.add("疑似暴力破解攻擊");
                }
            }
            case "api_anomaly" -> {
                riskScore += 50;
                indicators.add("異常 API 呼叫模式");
            }
            case "data_exfiltration" -> {
                riskScore += 90;
                indicators.add("疑似資料外洩");
            }
            case "privilege_escalation" -> {
                riskScore += 70;
                indicators.add("權限提升嘗試");
            }
            default -> riskScore += 5;
        }

        // 判定威脅等級
        Severity severity;
        if (riskScore >= 80) severity = Severity.CRITICAL;
        else if (riskScore >= 50) severity = Severity.HIGH;
        else if (riskScore >= 25) severity = Severity.MEDIUM;
        else severity = Severity.LOW;

        // 決定回應動作
        List<String> actions = determineActions(severity, event);

        ThreatAssessment assessment = new ThreatAssessment(
                event, severity, riskScore, indicators, actions);
        assessmentHistory.add(assessment);

        // 執行自動回應
        executeActions(assessment);

        logger.info("威脅評估: {} ({}) 風險分數: {}",
                severity.getCode(), severity.getLabel(), riskScore);
        return assessment;
    }

    /**
     * 取得安全摘要報告。
     *
     * @return Markdown 報告
     */
    public String getSecuritySummary() {
        StringBuilder sb = new StringBuilder();
        sb.append("## 🛡️ 安全監控摘要\n\n");
        sb.append(String.format("- 總事件數: **%d**\n",
                assessmentHistory.size()));
        sb.append(String.format("- 封鎖 IP 數: **%d**\n",
                blockedIps.size()));

        // 按等級統計
        Map<Severity, Long> bySeverity = assessmentHistory.stream()
                .collect(java.util.stream.Collectors.groupingBy(
                        ThreatAssessment::severity,
                        java.util.stream.Collectors.counting()));
        sb.append("\n| 等級 | 數量 |\n|------|------|\n");
        for (Severity s : Severity.values()) {
            sb.append(String.format("| %s %s | %d |\n",
                    s.getCode(), s.getLabel(),
                    bySeverity.getOrDefault(s, 0L)));
        }

        // 最近的嚴重事件
        List<ThreatAssessment> recent = assessmentHistory.stream()
                .filter(a -> a.severity() == Severity.HIGH
                             || a.severity() == Severity.CRITICAL)
                .sorted(Comparator.comparing(
                        a -> a.event().timestamp(),
                        Comparator.reverseOrder()))
                .limit(5)
                .toList();

        if (!recent.isEmpty()) {
            sb.append("\n### 近期重要事件\n\n");
            recent.forEach(a -> sb.append(String.format(
                    "- **[%s]** %s — %s (分數: %.0f)\n",
                    a.severity().getCode(), a.event().description(),
                    a.event().sourceIp(), a.riskScore())));
        }

        return sb.toString();
    }

    // -- 私有方法 --

    private List<String> determineActions(Severity severity,
                                          SecurityEvent event) {
        List<String> actions = new ArrayList<>();
        switch (severity) {
            case LOW -> actions.add("記錄事件");
            case MEDIUM -> {
                actions.add("記錄事件");
                actions.add("發送 Slack 告警至 #security");
            }
            case HIGH -> {
                actions.add("記錄事件");
                actions.add("封鎖來源 IP");
                actions.add("發送緊急告警至 #security + On-Call");
            }
            case CRITICAL -> {
                actions.add("記錄事件");
                actions.add("封鎖來源 IP");
                actions.add("啟動事件回應流程");
                actions.add("自動取證(快照日誌)");
                actions.add("通知安全團隊 + 管理層");
            }
        }
        return actions;
    }

    private void executeActions(ThreatAssessment assessment) {
        for (String action : assessment.actions()) {
            logger.info("執行回應: {}", action);
            if (action.contains("封鎖")) {
                blockedIps.add(assessment.event().sourceIp());
                logger.warn("已封鎖 IP: {}",
                        assessment.event().sourceIp());
            }
        }
    }
}

10.10 案例十:完整企業部署案例

部署架構

graph TB
    subgraph "DMZ"
        LB[負載平衡器]
    end
    
    subgraph "應用層"
        GW1[OpenClaw Gateway<br>主要]
        GW2[OpenClaw Gateway<br>備援]
    end
    
    subgraph "服務層"
        TOOL[工具 Bridge<br>Java Spring Boot]
        SEARCH[搜尋服務<br>Elasticsearch]
        CACHE[快取<br>Redis]
    end
    
    subgraph "資料層"
        DB[PostgreSQL]
        S3[物件儲存]
    end
    
    subgraph "監控層"
        PROM[Prometheus]
        GRAF[Grafana]
        ALERT[AlertManager]
        JAEGER[Jaeger]
    end
    
    LB --> GW1
    LB -.->|failover| GW2
    GW1 & GW2 --> TOOL & SEARCH & CACHE
    TOOL --> DB
    GW1 & GW2 --> PROM
    PROM --> GRAF & ALERT
    GW1 & GW2 --> JAEGER

資源規劃

元件CPU記憶體磁碟數量
OpenClaw Gateway2 核4 GB20 GB2
Tool Bridge (Java)2 核2 GB10 GB2
Elasticsearch4 核8 GB100 GB3
Redis1 核2 GB5 GB1
PostgreSQL2 核4 GB50 GB1
Prometheus2 核4 GB50 GB1
Grafana1 核1 GB5 GB1
合計16 核29 GB260 GB12

10.11 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1案例中的技能符合規範檢視每個 SKILL.md無 triggers/tools/cron/access 鍵;觸發條件寫在 description
2排程由 Automations 負責openclaw automations list --json案例需要的排程都存在且時區正確
3存取控制在組態而非技能openclaw config get bindings --json 與各頻道 allowFrom與案例描述一致
4案例的 Java 程式可編譯把程式碼放入 4.2 的 Maven 專案執行 mvn -B compile補齊相依類別後編譯成功
5防捏造以空資料或錯誤資料測試報表類案例Agent 明確回報資料不足,而非自行產生數字

第十一章:多人協作與 Teams 治理

本章前提:v2026.8.1 為 OpenClaw 加入了多使用者協作能力,使其從純粹的 single-operator 系統,延伸為「單一信任域內的多人協作」。但官方對此有一句必須反覆強調的聲明:這些控制項不是租戶隔離,也不是安全邊界。本章在介紹每項能力的同時,會同步說明其治理邊界。

11.1 多使用者 Gateway 模型

在多使用者 Gateway 上,一個對話會保留建立者身分,以及每位可識別使用者的提示內容可見性。

參與者、Session、Agent 與請求者的身分,現在會隨著更多工作一起傳遞,用於歸屬(attribution)而不擴大存取權——這個區分很重要:身分傳遞讓你知道「誰做了什麼」,但不會因此讓誰能做更多事。

身分路徑適用範圍
受管理的 GitHub 身分本地命令列與 API 工作、作者 metadata
Git transport、沙箱、遠端機器、Cloud Workers各自使用獨立的身分路徑(不套用上述身分)

維運意涵:不要假設「在 Control UI 中看到的使用者身分」會一路傳遞到遠端執行環境。跨越到 Cloud Worker 或沙箱時,身分會換軌,稽核串接需自行處理。

11.2 對話分享與角色

擁有者或管理員可決定他人對一個對話的參與程度:

角色能力
read讀取對話
suggest提出建議(建議會保留其作者身分)
draft在草稿中作業(草稿可被建立與發布而不會產生競態)
participate直接參與對話
graph TB
    OWNER[對話擁有者/管理員] -->|授予角色| R[read<br/>唯讀]
    OWNER -->|授予角色| S[suggest<br/>提出建議]
    OWNER -->|授予角色| D[draft<br/>草稿作業]
    OWNER -->|授予角色| P[participate<br/>直接參與]

    R & S & D & P --> CONV[共享對話]
    CONV -.->|保留| META[建立者身分<br/>各人提示可見性<br/>建議作者歸屬]

⚠️ 權限撤銷有可見性延遲:官方明確載明「已撤銷的存取權,可能在 UI 重新整理或 Gateway 拒絕該動作之前,短暫看起來仍然可用」。這代表撤銷不是即時生效於畫面上。若需要立即阻斷,應同時在 Gateway 層面確認該動作已被拒絕,而非僅以 UI 顯示為準。

11.3 Presence 與揭露邊界

輕量的 presence 與輸入中提示,讓人容易看出誰在線上,同時不會讓單人使用情境變得雜亂。

使用者可自行管理顯示名稱與頭像。被允許的 Online 卡片可以顯示某人正在處理什麼,但有明確的揭露限制:

Online 卡片不會揭露:

  • ❌ IP 位址
  • ❌ 檢視者無權開啟的對話

11.4 Incognito 模式

Incognito 預設關閉,且範圍刻意設計得比一般理解更窄。其能力與不保證事項已於 5.9 完整列出,此處摘要其治理重點:

保證不保證
對話留在行程記憶體Model Provider 仍收到訊息
不寫入一般逐字稿與自動記憶工具仍可寫檔或影響外部服務
Gateway 重啟即消失不含內容的稽核 metadata 仍保留
—Gateway 操作者仍可看見進行中的工作

正確定位:Incognito 是一項減少本機持久化的功能,不是隱私或法遵控制。詳見 5.9。

11.5 裝置與配對治理

2.0 將配對權限移至裝置紀錄本身,這是一項重要的治理改善:

機制行為
移除或重新配對裝置退休其舊有的連線與 worker 存取權
非管理員的裝置權杖只能管理自己的配對
macOS 與 Android可檢視配對狀態
管理員可建立短期有效的一次貼上指令供機器加入

受信任 Proxy 與 Tailscale 身分的邊界

⚠️ 這是最容易誤解的一點:經驗證的 proxy 或 Tailscale 身分僅適用於當前連線,不會改寫持久的配對紀錄。換言之,網路層的身分驗證不等於裝置已被授權配對。

受信任 proxy 背後的瀏覽器自動註冊預設關閉,啟用後仍受限於已設定的角色與存取範圍。

SSH 身分檢查(預設開啟)

針對私有網路機器的獨立 SSH 身分檢查預設為開啟,並遵循一般的 OpenSSH HostName 規則。

若你的政策要求「僅限手動配對」:必須主動停用此 SSH 身分檢查,並且不要設定 CIDR 自動核准。這兩項需同時處理,只做其一仍會留下自動配對路徑。

11.6 企業落地建議與風險聲明

這套機制適合的場景

✅ 單一組織、單一信任域內的團隊協作 ✅ 需要工作交接、共同檢視與歸屬追蹤的情境 ✅ 已有外部身分治理框架,OpenClaw 僅作為協作介面

這套機制不適合的場景

⚠️ 請勿將 OpenClaw 的協作角色用於以下場景:

❌ 多租戶 SaaS——官方明確聲明「這些是選用的角色,用來限制單一受信任 OpenClaw 安裝內部的協作,而不是在互相敵對的租戶之間建立隔離」。 ❌ 需要強制隔離的客戶資料分區——角色控制的是協作行為,不是資料邊界。 ❌ 把角色當作唯一的存取控制層——它應與作業系統權限、網路分段、per-session 權限模式(5.2)疊加使用。

建議的治理疊層

graph TB
    L1[第 1 層:網路分段與零信任<br/>9.4 / 9.10]
    L2[第 2 層:Gateway 認證與裝置配對<br/>11.5]
    L3[第 3 層:per-session 權限模式<br/>5.2]
    L4[第 4 層:對話分享角色<br/>11.2]
    L5[第 5 層:審批綁定與稽核<br/>5.4 / 9.8]

    L1 --> L2 --> L3 --> L4 --> L5

    NOTE["協作角色(第 4 層)是最上層的便利機制<br/>不可獨立作為安全邊界"]
    L4 -.-> NOTE

真正的隔離需求該怎麼做:若企業確實需要租戶間隔離,正確做法是為每個信任域部署獨立的 Gateway 實例(見 Multiple Gateways 與 Multi-tenant Hosting),而非依賴單一 Gateway 內的角色設定。

11.7 Team Server 部署實作(Cloudflare Access + trusted-proxy)

官方以 team.openclaw.ai 作為 OpenClaw 自身的共用開發工作區,並把這套做法整理成 Team Server 部署指南。它把前面各章的元件串起來:常駐 Gateway、Cloudflare Tunnel 與 Access、個人登入、GitHub 身分、操作者角色,以及(選用的)另一個 Gateway 的唯讀分享。

⚠️ 信任邊界(再次強調):一個 Gateway 就是一個信任邊界。角色與 Session 擁有權用來支援協作,不能隔離彼此敵對的使用者。不受信任的程式碼放在沙箱或遠端 worker;彼此不信任的團隊用不同的 Gateway、OS 使用者或主機。

架構

graph LR
    U["團隊成員<br/>瀏覽器"] -->|HTTPS| ACC["Cloudflare Access<br/>(企業 IdP 登入)"]
    ACC --> TUN["Cloudflare Tunnel<br/>(出站連線,不需開放入站埠)"]
    TUN -->|"http://localhost:18789<br/>+ cf-access-authenticated-user-email"| GW["Gateway<br/>bind: loopback<br/>auth: trusted-proxy"]
    GW --> ROLES["gateway.roles<br/>observer / member / administrator"]
    GW -.->|唯讀分享| REL["release.example.com<br/>(獨立 Gateway)"]

步驟 1:以單一服務帳號安裝

# 以「將來執行 Gateway 的那個帳號」完成安裝;之後所有組態、備份、更新都用同一帳號
openclaw onboard --install-daemon
openclaw gateway status --deep

只允許管理網段 SSH;Gateway 保持 loopback,不要對外開放 TCP 18789。

步驟 2:Tunnel 只把指定主機名稱導到 loopback Gateway

# /etc/cloudflared/config.yml
tunnel: <tunnel-id>
credentials-file: /etc/cloudflared/<tunnel-id>.json
ingress:
  - hostname: team.example.com
    service: http://localhost:18789
  - service: http_status:404

先建立 Access application,初期只允許完成設定的管理者;不要為 Control UI 或其 WebSocket 建立公開的 bypass。

步驟 3:trusted-proxy 驗證與角色

// 合併到既有組態(保留你的 agents、models、channels)
{
  gateway: {
    mode: "local",
    bind: "loopback",
    publicOrigin: "https://team.example.com",
    trustedProxies: ["127.0.0.1", "::1"],
    auth: {
      mode: "trusted-proxy",
      // 本機維護用的私有密碼(代表共用擁有者;不要發給團隊成員)
      password: { source: "env", provider: "default", id: "OPENCLAW_GATEWAY_PASSWORD" },
      identityScopes: { "admin@example.com": ["operator.admin"] },
      trustedProxy: {
        userHeader: "cf-access-authenticated-user-email",
        requiredHeaders: ["cf-access-jwt-assertion"],
        allowLoopback: true,
        deviceAutoApprove: {
          enabled: true,
          scopes: ["operator.read", "operator.write", "operator.approvals", "operator.questions"],
        },
      },
    },
    roles: {
      default: "observer",
      definitions: {
        observer: { sessions: { others: "view" }, agents: [], scopes: ["operator.read"] },
        member: {
          sessions: { others: "write" },
          agents: ["assistant"],
          scopes: ["operator.read", "operator.write", "operator.approvals", "operator.questions"],
        },
        administrator: { sessions: { others: "write" }, agents: "*", scopes: ["operator.admin"] },
      },
    },
  },
}
openclaw config validate --json
openclaw gateway restart
openclaw gateway status --deep
設定為什麼
移除 gateway.auth.token/OPENCLAW_GATEWAY_TOKEN官方說明共用 token 與 trusted-proxy 模式不相容,且共用 token 無法識別個人。⚠️ 實測 config validate 不會擋下兩者並存(衝突發生在執行期),因此必須人工或以 CI 規則檢查
publicOrigin決定對外宣告的 URL 與預設的瀏覽器 origin 白名單;未設定時 Agent 無法產生 Session 連結
requiredHeaders: ["cf-access-jwt-assertion"]OpenClaw 只檢查標頭存在與代理來源,不驗證 Access JWT 簽章——真正的外部驗證邊界是 Access + 私有 origin
allowLoopback: true會同時信任 cloudflared 與本機所有行程;不要在這台主機上執行不受信任的工作負載
roles.default: "observer"新登入者預設只能檢視,由管理者明確提升

步驟 4:GitHub 身分與 PR 發布

在 Settings → Profile → GitHub connections 連結「My GitHub」(個人)與「System GitHub」(共用)。對話中用 Worktree 開始 repository 任務(4.12),完成後以 Publish PR 發出 Pull Request——發布前務必確認選定的發布帳號。

驗證清單

檢查方法預期
18789 不對外從外網連 <server-ip>:18789連線失敗
未登入無法存取無痕視窗開啟 https://team.example.com被 Access 擋下
角色正確以 observer 帳號登入嘗試傳訊只能檢視他人 Session,無法寫入
組態合法且無殘留 tokenopenclaw config validate --json;openclaw config get gateway.auth.tokenvalid: true;token 未設定(validate 不會檢查此衝突)
稽核可追溯openclaw audit --after <時間> --json事件帶有登入者身分

11.8 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1Gateway 不對外從外網連線 18789失敗;只能經由 Tunnel
2驗證模式openclaw config get gateway.auth --jsontrusted-proxy,且未設定 token(validate 不會檢查此衝突)
3角色最小權限以 observer/member 帳號實際操作observer 只能檢視;operator.admin 只給少數管理者
4信任邊界說明審查導入計畫互不信任的團隊使用不同 Gateway
5個人技能庫不含憑證檢視技能內容無 token、密碼或內部主機憑證

第十二章:分散式執行 —— Cloud Workers 與 Paired Devices

v2026.8.1 讓工作不再必須停留在執行 OpenClaw 的主機上。但這是兩條不同的路徑,需求與失效行為都不同,混用會導致難以診斷的問題。本章釐清兩者的差異與各自的邊界。

12.1 兩條路徑的差異

面向Cloud WorkerPaired Device(配對電腦)
定位租用或雲端佈建的機器你自己的另一台電腦
前提條件已設定的 worker profile 與 OpenClaw runtime相容版本、同意(consent)、可用容量,以及對所請求指令的支援
執行內容在選定的儲存庫中啟動 Session使用 OpenClaw 驗證並提供的 worker bundle 執行完整回合
建立方式Control UI「New Session」的 Where 選項openclaw connect
失聯行為下一則訊息時自動更換新的 worker保留 placement 並等待該裝置回歸
回收可稍後收回主機(reclaim)—
graph TB
    subgraph "Gateway(永遠的擁有者)"
        CONV[對話]
        WS[已調和的工作區]
        CRED[模型憑證]
        PLACE[placement 紀錄]
    end

    subgraph "執行位置(可移動)"
        LOCAL[本機 Gateway]
        PAIRED[配對電腦<br/>openclaw connect]
        CLOUD[Cloud Worker<br/>Crabbox / Daytona]
    end

    CONV --> LOCAL
    CONV --> PAIRED
    CONV --> CLOUD

    NOTE["指令、檔案編輯與工具工作在遠端執行<br/>但對話、工作區、憑證與 placement 始終屬於 Gateway"]
    PLACE -.-> NOTE

12.2 Cloud Worker Profile 設定

Control UI 的 New Session 頁面會探索已設定的 worker profile,將其陳列在 Where 之下,強制套用派工所需的 managed-worktree 契約,並把第一個回合交給啟用中的 worker。

# 檢視已設定的 worker profile(`openclaw worker` 是 worker 端的執行期,沒有 list 子指令)
openclaw config get cloudWorkers.profiles --json
openclaw config validate --json

完整的 profile 設定範例與派工指令見 12.6。

支援的佈建後端

後端說明
Crabbox官方佈建工具,支援 AWS 與 Hetzner 後端
Daytona另一佈建選項

⚠️ 兩項官方已承認的文件不同步(撰寫本文時仍存在,設定時請以實際行為為準):

項目狀況
Cloud Workers 設定指南誇大了 Crabbox 以外的 Provider 所顯示的 profile 資訊
Daytona 指南宣稱 settings.class 可省略,但profile 驗證實際上仍要求該欄位

建議:Daytona profile 應保持 settings.class 明確設定,直到指南與產品契約一致為止。

選擇執行主機

在 Paired Device 情境中,可選擇 Auto,讓 Gateway 自行挑選符合資格、已連線的 Session 主機:

Auto 的挑選規則:對 OpenClaw worker 回合,選擇可用 worker 槽位最多的主機;平手時以裝置 ID 決勝。

12.3 Session Placement 與位址保持

當執行位置在 Gateway、配對裝置與 Cloud Worker 之間移動時,Session 會保留其位址。

Gateway 始終是下列項目的擁有者:

  • 對話本身
  • 已調和的工作區(reconciled workspace)
  • 模型憑證
  • placement 紀錄

而指令、檔案編輯與工具工作則在遠端執行。這個分工是理解整套機制的關鍵:遠端機器提供的是算力,不是權威。

持久性保證:若遠端機器消失,Session 與其持久狀態仍然存續。差別只在於「如何恢復」(見 12.4)。

12.4 失聯與恢復行為

graph TB
    A[遠端機器消失] --> B{目的地類型}
    B -->|Cloud Worker| C[下一則訊息時<br/>自動更換 worker]
    B -->|Paired Device| D[保留 placement<br/>等待裝置回歸]
    C --> E[Session 與持久狀態存續]
    D --> E
目的地恢復方式
Cloud Worker下一則訊息時自動更換,無需人工介入
離線的 Paired Device保留其 placement 並等待該裝置回來——不會自動改派

維運意涵:Paired Device 的「等待」行為代表該裝置長期離線會讓 Session 卡住。若需要高可用性,應使用 Cloud Worker 而非 Paired Device。

12.5 Portable Worker Bundle 的邊界

配對電腦執行的是 OpenClaw 驗證並提供的 worker bundle,而不是該台機器上碰巧安裝的任何程式碼。這是一項重要的安全性質——它避免了「遠端機器上的環境污染影響執行結果」。

⚠️ 但這個設計有一個真實的功能邊界:官方明確載明,可攜式 worker bundle 不包含目的地機器的原生終端機模組。

因此,依賴真正互動式終端機的工作,存在實際的限制。在規劃要派送到配對電腦的工作類型時,需要先確認它不需要互動式 TTY。

12.6 派工與回收範例

派工(dispatch)與回收(reclaim)是 Gateway 的 RPC 方法。操作者可在 Control UI 的 Place 選單完成,也可以用 openclaw gateway call 以腳本執行(適合排程與 CI):

步驟 1:設定 Cloud Worker Profile

// openclaw.json — Crabbox(內建插件)在 AWS 上按需佈建機器
{
  cloudWorkers: {
    preparedPool: { maxTotal: 4 },
    profiles: {
      aws: {
        provider: "crabbox",
        suspendAfter: "45m",      // 閒置 45 分鐘:先調和工作區再釋放機器
        readyWorkers: 1,          // 保留一台預熱機器
        settings: {
          provider: "aws",
          class: "standard",
          ttl: "4h",
          idleTimeout: "45m",
          // 佈建時需要的密鑰從 Secret Store 取得,不寫死
          setupSecrets: { NPM_TOKEN: { source: "store", provider: "default", id: "NPM_TOKEN" } },
        },
      },
    },
  },
}

步驟 2:建立 Repository Session、派工、回收

# 建立以 GitHub repository 為來源的 Session(ref 省略時使用遠端預設分支)
openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","repository":{"url":"https://github.com/example/project.git","ref":"main"}}'

# 派工到 aws profile(需要 operator.admin;首次佈建可能需要數分鐘)
openclaw gateway call sessions.dispatch --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'

# 派工到自己的配對裝置(需要 operator.write)
openclaw gateway call sessions.dispatch --timeout 1500000 \
  --params '{"key":"agent:main:device-work","deviceId":"<paired-device-id>"}'

# 完成後回收:先調和工作區,確認 placement 變為 reclaimed 或 local
openclaw gateway call sessions.reclaim --json --timeout 600000 \
  --params '{"key":"agent:main:big-refactor","agentId":"main"}'

❌ 舊版範例的錯誤:TypeScript 的 createGatewayClient(...)、client.createSession()、client.reclaimSession(),以及 Java 的 client.invoke("sessions_create", ...)。這些 API 都不存在(tsc 實測會回報 has no exported member named 'createGatewayClient')。以程式呼叫時,請用 4.11 的 GatewayClient.request("sessions.dispatch", {...}),或直接包裝上面的 openclaw gateway call。

⚠️ 回收不是強制刪除:離線裝置或尚未完成的 teardown 不算確認釋放。請先讓裝置重新連線並完成清理;不要只為了降版就強制銷毀。

12.7 Cloud Sessions:在本機、配對裝置與雲端之間移動(v2026.10.10)

v2026.10.10 起,Cloud Session 成為一級工作流程:Session 可以從 Session 選單在本機與雲端之間移動;雲端環境依 Repository 組織,並可使用 environment recipes 與經驗證的 Node toolchain;Session 啟動時會顯示快照進度,不必等第一個快照上傳完成。

執行位置機器適合派工需要的 scope
Gateway(預設)執行 openclaw gateway 的主機日常 Session—
Paired device自己的硬體,用 openclaw connect 一次配對閒置的 Mac、建置機、既有伺服器operator.write
Cloud worker透過 Crabbox 租用的拋棄式機器突發運算量、長時間工作、與自有機器隔離operator.admin

無論在哪裡執行,模型推論都經由 Gateway 代理——Provider 憑證永遠不會到達遠端機器;完成的工作以「已接受的 repository checkpoint」形式保留在 Gateway。

# 把一台機器配對為 Session 主機(每個 CPU 核心一個 worker slot,可用 nodeHost.workerRuns.capacity 調整)
openclaw connect <join-url> --service --session-host
設計重點說明
Auto 負載平衡Place 選 Auto(或 dispatch 帶 autoDevice: true)會挑最不忙的配對主機;工作區準備前若主機失去資格,最多改試 3 台已排序的主機
閒置休眠suspendAfter 在閒置後安全停止並釋放機器;readyWorkers 與 warm images 縮短冷啟動
附件派工後的附件經已驗證的傳輸通道複製到 worker 工作區(上限 25,000 個檔案/256 MiB,單檔媒體 6 MiB)
Desktop 與 computer use開啟 Cloud Worker Desktop lab,並在 Crabbox profile 設 settings.desktop: true;同一台機器同時提供 Desktop 面板與 Agent 的 computer 工具
GitHub Enterprisev2026.10.1 起,Cloud Worker 的 repository 探索與預備流程支援設定的 GitHub Enterprise 主機

⚠️ 企業安全要點:

  1. 配對裝置上的 Agent 擁有該作業系統帳號的所有權限;placement 工作區只決定起始目錄與調和範圍,不是 OS 層級隔離。需要隔離時,在配對裝置上使用獨立的最小權限帳號,或啟用 Docker 相容的 Session 容器。
  2. Cloud worker 派工需要 operator.admin;請在 gateway.roles 中只授予少數管理者(見 11.7)。
  3. Worker 逐字稿會保留截圖;含敏感畫面的 Desktop 工作要納入資料保存政策(5.9)。

12.8 本章審查與驗證清單

審查 AI 依本章產出的組態、指令或程式時,逐項執行下表:

#檢查項目驗證方法預期結果
1派工使用真實 RPC檢視腳本使用 openclaw gateway call sessions.create/sessions.dispatch/sessions.reclaim
2Cloud Worker profile 合法openclaw config validate --jsoncloudWorkers.profiles.* 通過驗證
3回收已確認檢視 sessions.reclaim 回應placement 為 reclaimed 或 local
4憑證不到達遠端檢視 worker 環境Provider 憑證不在遠端;setupSecrets 來自 Secret Store
5配對裝置的 OS 權限檢查配對主機使用的帳號使用獨立的最小權限帳號或 Session 容器

附錄 A:企業導入檢查清單

A.1 導入前準備

  • 確認使用場景與 ROI 估算
  • 評估現有基礎設施相容性
  • 選定 LLM Provider 與定價方案
  • 建立資安審查流程
  • 準備測試環境

A.2 環境建置

  • 安裝 Node.js(>=22.22.3 <23、>=24.15.0 <25 或 >=25.9.0,建議 24.15+ LTS)
  • 部署 OpenClaw Gateway
  • 設定 TLS/SSL 加密
  • 設定防火牆規則
  • 設定 Docker 容器安全

A.3 組態與整合

  • 編寫 openclaw.json 主組態
  • 設定 Model References
  • 連接必要的 Channel(Slack/Teams 等)
  • 部署自訂 Skills
  • 設定工具 Bridge

A.4 安全設定

  • 啟用 DM Pairing
  • 設定使用者白名單
  • 設定 API Key 環境變數
  • 啟用稽核日誌
  • 測試 Prompt Injection 防禦

A.5 監控設定

  • 設定 OpenTelemetry 匯出
  • 部署 Prometheus + Grafana
  • 設定告警規則
  • 建立 Grafana 儀表板
  • 設定日誌聚合

A.6 營運就緒

  • 完成壓力測試
  • 建立備份排程
  • 撰寫災難復原計畫
  • 建立 On-Call 輪值
  • 完成團隊教育訓練

附錄 B:疑難排解常見問題

B.1 連線問題

症狀可能原因解決方案
Gateway 無法啟動Port 18789 被佔用lsof -i :18789 檢查並釋放
頻道斷線Token 過期更新 Channel Token
WebSocket 連線失敗防火牆攔截開放 18789 端口
LLM API 錯誤API Key 無效檢查環境變數

B.2 效能問題

症狀可能原因解決方案
回應緩慢上下文過長調整 maxTokens
記憶體暴增Session 未清理設定 Session TTL
CPU 使用率高並行請求過多限制並行數
磁碟空間不足日誌未輪替設定 Log Rotation

B.3 技能問題

症狀可能原因解決方案
Skill 未載入SKILL.md 格式錯誤驗證 YAML 前置資料
觸發失敗觸發詞衝突調整 trigger 關鍵字
工具呼叫失敗Bridge 服務未啟動檢查工具端點可達性

B.4 診斷指令

自 v2026.1 起,OpenClaw 提供 openclaw doctor 一站式診斷工具,可自動檢查環境、組態、連線與依賴項。

# 一站式環境診斷(推薦首選)
openclaw doctor
# 常見輸出項目包括:
#   ✔ Node.js version   → 24.x
#   ✔ Gateway reachable  → localhost:18789
#   ✔ Config valid        → ~/.openclaw/config.json5
#   ✔ Default model       → connected
#   ✗ Channel: Slack      → token expired

# 完整深度診斷(含網路延遲與模型回應測試)
openclaw doctor --deep

# 僅檢查組態(不啟動 Gateway)
openclaw config validate --json

# 唯讀的建議性檢查(CI 可用,不會下載插件或變更狀態)
openclaw doctor --json

# 查看已載入的技能
openclaw skills list

# 查看連線的頻道
openclaw channels status

# 查看日誌(即時)
tail -f ~/.openclaw/logs/openclaw.jsonl | jq .

# 檢查模型認證與 primary/fallbacks 狀態
openclaw models status

# 查看系統狀態摘要(在對話中使用 Chat Command)
# /status

💡 建議:遇到任何問題時,優先執行 openclaw doctor,它會自動列出所有異常項目並給出修復建議。


附錄 C:名詞解釋

術語英文說明
GatewayGatewayOpenClaw 核心守護程序,管理所有連線和訊息路由
Pi AgentPi Agent Runtime嵌入式 Agent 執行環境,源自 pi-mono,以 RPC 模式運行
SkillSkill技能,定義 Agent 在特定領域的行為(SKILL.md)
ToolTool工具,Agent 可呼叫的外部功能(Browser、Cron 等)
ChannelChannel頻道,Agent 連接的通訊平台(Telegram、Slack 等)
Plugin ChannelPlugin Channel插件頻道,透過 extension 套件擴展的額外頻道支援
SessionSession會話,追蹤一次完整的對話上下文(main / group 隔離)
DM PairingDM Pairing私訊配對,使用者身份驗證機制(預設啟用)
ClawHubClawHub官方技能市場 (clawhub.ai),已整合 VirusTotal 安全掃描
Model ReferenceModel Reference模型參照,抽象化 LLM Provider 的設定
Model FailoverModel Failover模型失效轉移,主模型不可用時自動切換備援
Hot ReloadHot Reload熱重載,不重啟即套用新組態
Wire ProtocolWire Protocol有線協定,Gateway 與 Agent 之間的通訊格式
Control UIControl UI內建於 Gateway 的瀏覽器管理介面
WebChatWebChat內建網頁聊天介面,透過 Gateway WebSocket 運作
Canvas / A2UIAgent-to-UIAgent 驅動的互動式視覺工作區
Voice WakeVoice Wake語音喚醒,macOS/iOS 上的喚醒詞偵測
Talk ModeTalk Mode語音對話模式,Android 上的連續語音互動
Companion AppCompanion App伴隨應用,macOS/iOS/Android 客戶端
NodeNode裝置節點,iOS/Android/macOS 裝置透過 WS 連接 Gateway
OperatorOperator操作者,Gateway 的唯一擁有者
SandboxSandbox沙箱模式,非主 Session 在 Docker 容器中隔離執行
Bundled SkillBundled Skill內建技能,隨 OpenClaw 安裝的預設技能
Managed SkillManaged Skill受管理技能,安裝在 ~/.openclaw/skills/ 的技能
Workspace SkillWorkspace Skill工作區技能,專案本地的 ./skills/ 目錄技能
Bootstrap FilesBootstrap FilesAgent 啟動時注入的 Prompt 檔案(AGENTS.md、SOUL.md、TOOLS.md)
OTLPOpenTelemetry ProtocolOpenTelemetry 遙測資料傳輸協定
CalVerCalendar Versioning日曆版本號,格式 vYYYY.M.D,OpenClaw 的版本命名規則
ClawFlowClawFlowRuntime Substrate 層,將 Skill 定義編譯為可執行工作流程(DAG),支援步驟層級重試、條件分支與並行執行
Session ToolsSession Tools跨 Session 操作的工具集(sessions_list / sessions_history / sessions_send)
Chat CommandsChat Commands對話內斜線指令,如 /status、/sessions、/tools,可在任何頻道中使用
Tailscale ServeTailscale Serve透過 Tailscale 提供 tailnet 內 HTTPS 存取
Tailscale FunnelTailscale Funnel透過 Tailscale 提供公開 HTTPS 存取
DoctorDoctor診斷工具,檢查組態、遷移建議、安全警告
DreamingDreaming / Memory Wiki記憶管理系統,支援 ChatGPT 聊天匯入、Wiki 頁面編譯、日記子頁籤瀏覽
video_generateVideo Generate Tool影片生成工具,支援 URL 資產交付、參考音訊輸入、自適應長寬比
Plugin ManifestPlugin Manifest插件清單宣告,描述認證、配對與設定步驟的結構化描述符
Development ChannelsDevelopment Channels開發頻道,stable / extended-stable / beta / dev 四軌發布管道(extended-stable 為 v2026.6 新增的類 LTS 維護線)
Federated CredentialFederated Credential聯合認證,MS Teams 支援的憑證與受管理 OAuth 設定
OpenClaw FoundationOpenClaw Foundation2026 年 2 月成立的非營利治理基金會,創辦人 Peter Steinberger 轉任 OpenAI 後接手專案長期治理
Secret Egress Host BindingSecret Egress Host Bindingv2026.8.1 新增的密鑰目的地主機綁定機制,防止密鑰被導向非預期 HTTPS 目的地
Plugin Provenance WarningPlugin Provenance Warningv2026.8.1 新增,安裝非信任來源的可執行插件時需明確以 --force 確認風險

附錄 D:參考資源

D.1 官方資源

資源網址
官方網站https://openclaw.ai
官方文件https://docs.openclaw.ai
GitHub 倉庫https://github.com/openclaw/openclaw
ClawHub 技能市場https://clawhub.ai
Discord 社群https://discord.gg/clawd
DeepWiki(AI 導讀)https://deepwiki.com/openclaw/openclaw
VirusTotal Trusthttps://trust.openclaw.ai
Showcasehttps://openclaw.ai/showcase
Bloghttps://openclaw.ai/blog
Extended-Stable / LTS 路線圖公告https://openclaw.ai/blog/extended-stable-releases-and-maturity-scorecards
Release Notes(各版本詳細說明)https://docs.openclaw.ai/releases
Release Policy(發布政策)https://docs.openclaw.ai/reference/RELEASING

D.2 技術參考

主題資源
Node.js 官方https://nodejs.org
Docker 文件https://docs.docker.com
Kubernetes 文件https://kubernetes.io/docs
OpenTelemetryhttps://opentelemetry.io
Prometheushttps://prometheus.io
Grafanahttps://grafana.com
Tailscalehttps://tailscale.com

D.3 官方文件深層鏈結

主題連結
架構概覽https://docs.openclaw.ai/concepts/architecture
完整組態參考https://docs.openclaw.ai/gateway/configuration
Gateway 運維手冊https://docs.openclaw.ai/gateway
安全指南https://docs.openclaw.ai/gateway/security
威脅模型https://docs.openclaw.ai/security/THREAT-MODEL-ATLAS
形式驗證https://docs.openclaw.ai/security/formal-verification
頻道設定https://docs.openclaw.ai/channels
頻道存取群組https://docs.openclaw.ai/channels/access-groups
頻道路由https://docs.openclaw.ai/channels/channel-routing
頻道配對https://docs.openclaw.ai/channels/pairing
工具文件https://docs.openclaw.ai/tools
Skills 設定https://docs.openclaw.ai/tools/skills-config
模型設定https://docs.openclaw.ai/concepts/models
模型失效轉移https://docs.openclaw.ai/concepts/model-failover
Session 管理https://docs.openclaw.ai/concepts/session
Session Toolhttps://docs.openclaw.ai/concepts/session-tool
Context Enginehttps://docs.openclaw.ai/concepts/context-engine
Compactionhttps://docs.openclaw.ai/concepts/compaction
Active Memoryhttps://docs.openclaw.ai/concepts/active-memory
Delegate Architecturehttps://docs.openclaw.ai/concepts/delegate-architecture
Multi-Agenthttps://docs.openclaw.ai/concepts/multi-agent
Agent Loophttps://docs.openclaw.ai/concepts/agent-loop
Agent Runtimehttps://docs.openclaw.ai/concepts/agent-runtimes
Standing Intentshttps://docs.openclaw.ai/concepts/standing-intents
Queue 機制https://docs.openclaw.ai/concepts/queue
Queue Steeringhttps://docs.openclaw.ai/concepts/queue-steering
Presencehttps://docs.openclaw.ai/concepts/presence
Streaminghttps://docs.openclaw.ai/concepts/streaming
Usage Trackinghttps://docs.openclaw.ai/concepts/usage-tracking
Plugin SDKhttps://docs.openclaw.ai/plugins/sdk-overview
Plugin Inventoryhttps://docs.openclaw.ai/plugins/plugin-inventory
Building Pluginshttps://docs.openclaw.ai/plugins/building-plugins
Plugin Testinghttps://docs.openclaw.ai/plugins/sdk-testing
Plugin Migrationhttps://docs.openclaw.ai/plugins/sdk-migration
Tailscale 指南https://docs.openclaw.ai/gateway/tailscale
遠端存取https://docs.openclaw.ai/gateway/remote
Web 控制面板https://docs.openclaw.ai/web
Webhookhttps://docs.openclaw.ai/automation/cron-jobs/webhooks
Standing Ordershttps://docs.openclaw.ai/automation/standing-orders
Hookshttps://docs.openclaw.ai/automation/hooks
Lobster 管線(取代已移除的 TaskFlow)https://docs.openclaw.ai/tools/lobster
背景執行與工作流程(Tasks 已於 9.7 移除)https://docs.openclaw.ai/automation
Gmail/IMAP 郵件監看https://docs.openclaw.ai/automation/imap
Gateway 協定https://docs.openclaw.ai/gateway/protocol
Gateway 探索與傳輸https://docs.openclaw.ai/gateway/discovery
Gateway Pairinghttps://docs.openclaw.ai/gateway/pairing
Gateway 健康檢查https://docs.openclaw.ai/gateway/health
Gateway 背景程序https://docs.openclaw.ai/gateway/background-process
Bonjour/mDNShttps://docs.openclaw.ai/gateway/bonjour
沙箱https://docs.openclaw.ai/gateway/sandboxing
Nix 安裝https://docs.openclaw.ai/install/nix
開發頻道切換https://docs.openclaw.ai/install/development-channels
疑難排解https://docs.openclaw.ai/channels/troubleshooting
FAQhttps://docs.openclaw.ai/help/faq

D.4 相關學習資源

主題建議資源
LLM 基礎OpenAI Cookbook, Anthropic Docs
Prompt 工程Prompt Engineering Guide
WebSocketMDN WebSocket API
Docker 安全CIS Docker Benchmark
K8s 安全CIS Kubernetes Benchmark

D.5 平台與部署指南

平台連結
macOShttps://docs.openclaw.ai/platforms/macos
iOShttps://docs.openclaw.ai/platforms/ios
Androidhttps://docs.openclaw.ai/platforms/android
Windows (WSL2)https://docs.openclaw.ai/platforms/windows
Linuxhttps://docs.openclaw.ai/platforms/linux
Dockerhttps://docs.openclaw.ai/install/docker
Kuberneteshttps://docs.openclaw.ai/install/kubernetes
Azurehttps://docs.openclaw.ai/install/azure
GCPhttps://docs.openclaw.ai/install/gcp
DigitalOceanhttps://docs.openclaw.ai/install/digitalocean
Fly.iohttps://docs.openclaw.ai/install/fly
Daytonahttps://docs.openclaw.ai/install/daytona
Hostingerhttps://docs.openclaw.ai/install/hostinger
Hetznerhttps://docs.openclaw.ai/install/hetzner
Oracle Cloudhttps://docs.openclaw.ai/install/oracle
Raspberry Pihttps://docs.openclaw.ai/install/raspberry-pi
Cloudflarehttps://docs.openclaw.ai/install/cloudflare
Ansiblehttps://docs.openclaw.ai/install/ansible
Bunhttps://docs.openclaw.ai/install/bun

D.6 OpenClaw 2.0 新增主題文件

以下為 v2026.8.1 新增或大幅改寫的官方文件,對應本手冊第十一、十二章與各章的 2.0 更新段落:

主題連結本手冊對應
v2026.8.1 發布說明https://docs.openclaw.ai/releases/2026.8.11.11、附錄 E
Cloud Workershttps://docs.openclaw.ai/gateway/cloud-workers12.2
Cloud Sessionshttps://docs.openclaw.ai/gateway/cloud-sessions12.1、12.3
多使用者https://docs.openclaw.ai/concepts/multi-user第十一章
Built-in Memoryhttps://docs.openclaw.ai/concepts/memory-builtin4.6
記憶搜尋https://docs.openclaw.ai/concepts/memory-search4.6
記憶來源標記https://docs.openclaw.ai/concepts/memory-provenance4.6
Session 搜尋https://docs.openclaw.ai/concepts/session-search4.6
Skill Workshophttps://docs.openclaw.ai/tools/skill-workshop4.3
自我學習https://docs.openclaw.ai/tools/self-learning4.3
Code Modehttps://docs.openclaw.ai/tools/code-mode4.4
Secret Storehttps://docs.openclaw.ai/gateway/secrets3.11
1Password 整合https://docs.openclaw.ai/gateway/1password3.11
重啟復原https://docs.openclaw.ai/gateway/restart-recovery6.11
權限模式https://docs.openclaw.ai/gateway/permission-modes5.2
插件權限請求https://docs.openclaw.ai/plugins/plugin-permission-requests9.11
Agent Plugin Bundleshttps://docs.openclaw.ai/plugins/bundles2.8
SDK 子路徑https://docs.openclaw.ai/plugins/sdk-subpaths4.9
相依套件鎖定https://docs.openclaw.ai/gateway/security/dependency-locking9.11
安全檔案操作https://docs.openclaw.ai/gateway/security/secure-file-operations9.9
多 Gateway 部署https://docs.openclaw.ai/gateway/multiple-gateways11.6
信任模型(多租戶需求請改用多個 Gateway)https://docs.openclaw.ai/gateway/security/trust-model11.6
資料庫結構https://docs.openclaw.ai/reference/database-schemas2.11
備份https://docs.openclaw.ai/install/backups6.7
更新https://docs.openclaw.ai/install/updating附錄 E
Teamshttps://docs.openclaw.ai/start/teams第十一章

D.7 OpenClaw 2.x(v2026.8.2 → v2026.11.1)新增與改寫的官方文件

主題連結本手冊對應
v2026.11.1 發布說明https://docs.openclaw.ai/releases1.10、1.12
發布通道https://docs.openclaw.ai/install/development-channels3.12、7.1
Node.js 相容性https://docs.openclaw.ai/install/node-compatibility3.1
Update CLI(修復與恢復)https://docs.openclaw.ai/cli/update7.11
儲存引擎(實驗性 PostgreSQL)https://docs.openclaw.ai/reference/database-engines2.12
Gateway Lockhttps://docs.openclaw.ai/gateway/gateway-lock2.9
儲存位置(異地備份)https://docs.openclaw.ai/concepts/storage-locations6.7
Managed Worktreeshttps://docs.openclaw.ai/concepts/managed-worktrees4.12
Skills(含個人技能庫)https://docs.openclaw.ai/tools/skills1.5、4.13
Tool plugins(defineToolPlugin)https://docs.openclaw.ai/plugins/tool-plugins4.4
工具政策(profiles/groups)https://docs.openclaw.ai/gateway/config-tools/tool-policy1.6
Tool Searchhttps://docs.openclaw.ai/tools/tool-search4.4
OpenAI 相容 HTTP APIhttps://docs.openclaw.ai/gateway/openai-http-api4.2、4.10
建置 Gateway 用戶端https://docs.openclaw.ai/gateway/clients4.11
Webhook ingress(hooks)https://docs.openclaw.ai/automation/cron-jobs/webhooks4.7
Prometheus 指標https://docs.openclaw.ai/gateway/prometheus6.4
OpenTelemetry 組態https://docs.openclaw.ai/gateway/opentelemetry/configuration6.3
Kubernetes(Kustomize)https://docs.openclaw.ai/install/kubernetes8.5
Docker 映像https://docs.openclaw.ai/install/docker3.3
Secret Store 與 egress proxyhttps://docs.openclaw.ai/gateway/secrets/secret-store-and-egress3.11
強化基準https://docs.openclaw.ai/gateway/security/hardened-baseline9.12
信任模型https://docs.openclaw.ai/gateway/security/trust-model第十一章
Team Server 部署https://docs.openclaw.ai/gateway/team-server11.7
Cloud Workers 組態https://docs.openclaw.ai/gateway/config-cloud-workers12.6
推薦模型清單https://docs.openclaw.ai/concepts/recommended-models2.6
CHANGELOG(純文字,供 AI/工具讀取)https://github.com/openclaw/openclaw/tree/main/CHANGELOG7.2
Security Advisorieshttps://github.com/openclaw/openclaw/security/advisories9.12

附錄 E:OpenClaw 2.0 升級遷移指南

適用對象:目前執行 v2026.7.x 或更早版本,準備升級至 v2026.8.1(OpenClaw 2.0) 的維運人員。

為何需要獨立的遷移指南:2.0 包含 13 項破壞性變更、4 項需 doctor --fix 介入的遷移,以及 1 項改變儲存後端的架構變更(SQLite)。逐項照做可避免升級後才發現無法回頭。

E.1 升級決策樹

graph TB
    START[準備升級至 2.0] --> Q1{是否使用<br/>OpenProse 插件?}
    Q1 -->|是| A1[規劃 Agent Skill 遷移]
    Q1 -->|否| Q2
    A1 --> Q2{是否使用 QMD 記憶?}
    Q2 -->|是| A2["確認可失去 reranking/<br/>query expansion/<br/>跨 Agent 逐字稿搜尋"]
    Q2 -->|否| Q3
    A2 --> Q3{是否使用 Code Mode?}
    Q3 -->|是| A3[改寫程式碼:移除 tools/<br/>ALL_TOOLS/exact-ID 呼叫]
    Q3 -->|否| Q4
    A3 --> Q4{是否有自訂插件?}
    Q4 -->|是| A4["遷移 SDK subpath<br/>deactivate → gateway_stop"]
    Q4 -->|否| Q5
    A4 --> Q5{能否接受<br/>降版困難?}
    Q5 -->|否| STOP["暫緩升級<br/>先建立可驗證備份與還原演練"]
    Q5 -->|是| GO[執行 E.2 升級流程]

E.2 升級流程(依序執行)

步驟 1:升級前檢查清單

  • 記錄目前版本:openclaw --version
  • 確認 Node 版本:升到 2.0 當時為 >=22.22.3 <23、>=24.15.0 <25 或 >=25.9.0;若要直接升到 2026.11.1,必須是 >=24.16.0 <25 或 >=26.1.0(見 E.5)
  • 確認沒有已知有漏洞的 Node + SQLite 組合(2.0 會在狀態開啟前擋下)
  • 盤點使用中的插件,標記外部插件與其來源
  • 盤點 Code Mode 程式碼,搜尋 tools.、ALL_TOOLS
  • 確認是否使用 OpenProse、QMD、HEARTBEAT.md、codex/* 模型參照
  • 確認是否使用已外部化的 Provider(Cohere、Meta、BytePlus、ComfyUI、OpenCode、Voyage、Vydra、Volcengine、Mistral、NovitaAI、Teams/Zoom meetings)
  • 確認是否有依賴隱含 Git hooks 的 managed worktree

步驟 2:建立可驗證備份(不可略過)

# 建立完整備份
openclaw backup create

# 驗證備份可用(這一步是「可驗證」的關鍵,不要跳過)
openclaw backup verify <backup-id>

# 另行備份備份工具不涵蓋的項目
#   - 受管理的 dev/ checkout
#   - 本地原始碼修改

⚠️ 為何檔案複製不再足夠:Session 與 Transcript 已改用 SQLite 後端。直接複製目錄可能取得不一致的資料庫狀態(WAL 尚未合併)。務必使用 openclaw backup。

步驟 3:執行升級

# 先預覽升級路徑,不變更任何狀態
openclaw update --dry-run

# 確認無誤後執行
openclaw update

若你在 2026.7.1 + pnpm 11:需手動執行一次 pnpm add -g openclaw@latest。OpenClaw 不會替你升級 Node。

步驟 4:執行四項遷移

openclaw doctor --fix

逐項確認結果:

  • OpenProse 插件已移除,並已依上游指引完成 Agent Skill 遷移
  • codex/*、openai-codex/* 模型參照已轉為 openai/*
  • QMD 已遷移至 Built-in Memory,索引已從正規 Markdown 重建
  • HEARTBEAT.md 的有效工作已遷移至 Automations

⚠️ 期限:2026-09-18。逾期未處理已退休設定鍵可能導致組態無法通過驗證。

注意:已明確退休的調校值會回到內建預設值。若原先依賴這些調校,升級後需重新驗證效能特性。

步驟 5:驗證

# 版本確認
openclaw --version          # 應顯示目標版本(例如 2026.8.1;繼續升級見 E.5)

# 分層診斷(順序有意義)
openclaw doctor             # 組態與本機探索
openclaw health             # 執行中系統的插件與服務狀態
openclaw plugins doctor     # 插件探索與組態

# 技能完整清單(模型可見目錄可能被壓縮,這裡才是權威來源)
openclaw skills check

# 頻道連線
openclaw channels list

步驟 6:升級後的設定檢視

2.0 變更了數項預設值,升級不會自動套用較嚴格的姿態,需主動檢視:

項目預設行為建議動作
Per-session 權限模式非回溯性——既有 Session 沿用舊全域姿態為既有 Session 明確指定模式,或建立新 Session
自我學習模式全新安裝為 auto;升級保留既有選擇有治理要求者明確設為 off(propose 已移除,見 4.3)
Session 重置未設定重置政策者跨日保持開啟檢視長期執行 Agent 的脈絡成本
記憶來源標記僅適用新追蹤素材,舊檔案維持既有分類評估既有記憶是否需重新分類
Activity 位置對可路由位址預設啟用隱私敏感環境應檢視並停用
SSH 身分檢查預設開啟僅限手動配對者須停用,並確認未設 CIDR 自動核准

E.3 降版還原程序

⚠️ 降版的可行性受 SQLite 遷移限制。在執行降版前必須理解:遷移後建立的 Session 不會出現在舊版中。

降版步驟:

  1. 先用當前(2.0)CLI 還原已封存的舊版逐字稿產物——此步驟必須在降版之前完成,降版後就無法執行。
  2. 確認要還原的目標為全新目錄(restore 拒絕覆寫既有目標)。
  3. 安裝指定的舊版本。
  4. 從備份還原。
# 步驟 1(必須在降版前、停止所有寫入者後,以目前版本的 CLI 執行)
# 依 manifest 把保留的舊版逐字稿產物還原到原始路徑;不會逆轉 SQLite schema 遷移
openclaw doctor --session-sqlite restore --session-sqlite-all-agents

# 步驟 3
npm install -g openclaw@2026.7.1-2 --allow-scripts=openclaw

# 步驟 4
openclaw backup restore <backup-id> --target /path/to/fresh-state-dir

其他降版限制:

項目限制
遷移後建立的 Session不會出現在舊版
macOS tunnel 遷移產物無法被僅支援 JSON 的舊版建置讀取
待處理的配對請求與 bootstrap 代碼不會被匯入
部分舊儲存的遷移需先停止擁有該狀態的行程

E.4 三個期限速查表

期限事項逾期後果對應章節狀態(2026-11-08)
2026-09-01Plugin SDK 舊 subpath 匯入關閉插件無法載入4.9已過;10.1 再收斂第三方相容層
2026-09-18執行 openclaw doctor --fix組態可能無法通過驗證7.5已過
2026-10-12beta.5 session-store bridge 失效依賴該 bridge 的用戶端中斷4.9已過

E.5 從 2.0(2026.8.x)升級到 2026.11.1

E.1–E.4 是「2.x 以前 → 2.0」的遷移;本節涵蓋 2.0 之後 到 2026.11.1 的變更。若起點早於 2026 年 6 月,必須先走 E.2 升到 2026.9.5,再回到本節。

破壞性與高影響變更矩陣

#版本變更影響對象處理方式章節
19.3Node 22/25 與早期 24.x/26.x 不再支援(需 >=24.16.0 <25 || >=26.1.0)所有安裝先升 Node 再升 OpenClaw,以免 SQLite 文字截斷;建議 24.22.1+/26.12.1+3.1
29.3Plugin SDK:exec-policy、approval、SDK 別名、Find/Grep 與目錄結果欄位調整插件開發者依官方 runtime utility migration 修改4.9
39.3Skill Workshop 改為每個 Agent 一份,退休 skills.workshop.allowSymlinkTargetWrites使用 Workshop 者openclaw doctor --fix 遷移;檢視歸屬不明的技能4.3
49.52026 年 6 月前的安裝必須經過 9.5舊安裝先升 9.5 → doctor --fix → 再升最新7.11
59.6Compaction checkpoint 還原控制與 sessions.compaction.* RPC 移除依賴 checkpoint 還原者改用一般的 Fork/rewind;無對等替代—
69.7Tasks 與 TaskFlow(面板、指令、API)移除;TaskFlow Webhooks 無 HTTP 替代使用 ❌ openclaw tasks、TaskFlow 者改用 subagents、ACP、背景程序、Automations 歷史或 Lobster;doctor --fix1.6、4.5
79.7Tool Search 改為 search/describe/call 三工具,移除 tool_search_codeTool Search 使用者手動升級後先 doctor --fix 再重啟4.4
810.1第三方插件不得再匯入已退休的相容 facade 與整包 session-store helper插件開發者改用聚焦的 channel/config/session API 與 row-level 操作4.9
910.10macOS App、iOS App、Safari(Control UI)需 26.2+Apple 平台使用者先升級作業系統3.1
1010.10Gemini 4 Argon 成為預設 Gemini 模型;選單不再提供退休模型使用 Gemini 者檢查 agents.defaults.model 與 fallbacks2.6
119.x〜11.1自我學習模式只剩 off/auto(2.0 的 propose 已不存在)有治理要求者明確設定 skills.workshop.autonomous.mode: "off"4.3、5.3

升級步驟(以 npm 安裝為例)

# 0. 前置:Node 版本
node --version                                   # 必須 >=24.16.0 <25 或 >=26.1.0;建議 24.22.1+/26.12.1+

# 1. 備份並預覽
openclaw backup create --verify
openclaw update --tag 2026.11.1 --dry-run --json

# 2. 盤點會受影響的依賴
openclaw config validate --json                  # 退休鍵會出現在 issues/warnings
openclaw plugins list                            # 第三方插件是否宣告支援 2026.11.1
grep -rn "tool_search_code\|TaskFlow\|openclaw tasks" ~/.openclaw/workspace* 2>/dev/null   # ❌ 搜尋已移除的用法

# 3. 升級(失敗會自動回滾)
openclaw gateway suspend --wait --json
openclaw update --tag 2026.11.1 --yes

# 4. 驗證
openclaw --version                               # OpenClaw 2026.11.1 (4ffdd20)
openclaw doctor
openclaw config validate --json
openclaw skills check
curl -sf http://127.0.0.1:18789/readyz | jq -e '.ready == true'

# 5. 確認穩定後才清理遷移原件(清理後無法再以那些原件回滾)
openclaw update cleanup --dry-run

⚠️ 降版注意:若需降版,openclaw doctor --session-sqlite restore --session-sqlite-all-agents 只能還原「保留的舊版逐字稿產物」,不會逆轉 SQLite schema 遷移,也不能取代升級前的備份;而且必須在 openclaw update cleanup 之前執行(E.3)。


附錄 F:v4.0.0 驗證紀錄

本附錄記錄 v4.0.0(2026-11-08)改版時,如何驗證手冊內容與 OpenClaw 2026.11.1 一致,以及發現並修正了哪些錯誤。目的有二:讓讀者信任但可查證本手冊;也讓讀者把同一套方法用在審查 AI 產生的 OpenClaw 內容。

F.1 驗證環境

項目版本/來源
OpenClaw CLIopenclaw@2026.11.1(OpenClaw 2026.11.1 (4ffdd20)),以 npm 安裝於隔離目錄,OPENCLAW_HOME/OPENCLAW_STATE_DIR 指向暫存路徑
官方文件與原始碼github.com/openclaw/openclaw tag v2026.11.1 的 docs/(1,440 個檔案)、CHANGELOG/、package.json、docker-compose.yml、scripts/k8s/manifests
發布資訊GitHub Releases(2026-08-31 起 44 個 release)、npm dist-tags、GitHub Security Advisories
執行環境Windows 11、Node v24.16.0、npm 11.13、OpenJDK 21.0.4、Maven 3.9.9、TypeScript 5.9.3、Hugo 0.151.0
其他工具Prometheus promtool 3.16.0、mermaid 11.12.0(jsdom 解析)、yaml 2.9.1

F.2 驗證方法與工具

驗證對象方法負向測試(證明工具會抓錯)
openclaw.json 範例每個 json5 區塊寫入隔離的 OPENCLAW_CONFIG_PATH,執行 openclaw config validate --json{ gateway: { prot: 18789 } } → Unrecognized key: "prot"
CLI 用法遞迴執行 630 個指令路徑的 --help 建立白名單,以 check_cli.py 比對子指令與旗標❌ openclaw fleet status、doctor --deep-scan、skills frobnicate 皆被抓出
docs 連結check_doclinks.py 比對 v2026.11.1 的 docs/ 樹與 docs.json redirects/gateway/no-such-page → MISSING
YAMLyaml 2.9.1 strict 解析 + compose/k8s 結構檢查;promtool check config舊版 compose 被標出 :latest、全介面開埠、redis 服務
Javamvn -B test(Spring Boot 4.1.2);其餘片段以 JavacTask.parse() 做語法解析突變測試:拿掉「4xx 不重試」與「HTTP/1.1」後對應測試失敗
TypeScripttsc --strict 對 @openclaw/gateway-client@2026.11.1 與 openclaw@2026.11.1 型別檢查舊版 createGatewayClient、openclaw/plugin-sdk/ssrf 皆編譯失敗
插件openclaw plugins init → build → validate → npm test → plugins install未加 --force/--accept-capabilities 時安裝被拒
Mermaidmermaid 11 parse()不完整的 A --> 被抓出
HTTP 端點契約啟動隔離的本機 Gateway(埠 18999),以 curl 與 Java 冒煙測試實打錯誤 token → 401 unauthorized

check_cli.py

"""Check `openclaw ...` invocations in markdown against a dumped CLI help whitelist.

Usage: python -I check_cli.py <cli_help.json> <md files...> [--quiet]
Scans fenced bash/sh/powershell/text blocks and inline `code` spans.
For each invocation it resolves the longest known subcommand path, then checks
every --flag against that command's options plus global options.
Lines containing 'CLI-NOCHECK' are skipped (e.g. deliberate ❌ examples).
Exit code 1 when unknown commands or flags are found.
"""
import json
import re
import sys

args = [a for a in sys.argv[1:] if not a.startswith("--")]
quiet = "--quiet" in sys.argv
helpdb = json.load(open(args[0], encoding="utf-8"))
GLOBAL = set(helpdb[""]["options"]) | {"--help", "-h", "--version", "-V"}
TOPS = set(helpdb[""]["subcommands"])
# commands contributed by bundled/official plugins (documented in docs/, absent from core --help)
PLUGIN_CMDS = {"qa", "matrix", "voicecall", "path", "wiki", "workboard", "policy", "claws", "onnx",
               "vault", "onepassword", "reef", "team-reports", "codex", "ltm", "crabbox", "mcp-relay",
               "slackhuddles", "honcho", "commitments"}

INV = re.compile(r"(?<![\w./@-])(?<!-n )(?<!--namespace )(?<!view )openclaw((?:[ \t]+[^\s|;&`)#]+)*)")


def resolve(tokens):
    path = []
    for t in tokens:
        if t.startswith("-"):
            break
        cand = " ".join(path + [t])
        if cand in helpdb:
            path.append(t)
        else:
            break
    return path


def check_invocation(rest):
    toks = rest.split()
    # skip leading global options (and their values) such as --profile rescue
    i = 0
    while i < len(toks) and toks[i].startswith("-"):
        if toks[i] in ("--profile", "--container", "--log-level") and i + 1 < len(toks):
            i += 2
        else:
            i += 1
    toks = toks[i:]
    if not toks:
        return None
    first = toks[0]
    if first == "openclaw":  # e.g. `docker compose exec openclaw openclaw --version` (container name)
        return check_invocation(" ".join(toks[1:]))
    if first in PLUGIN_CMDS:
        return None
    if not re.match(r"^[a-z][\w:-]*$", first):
        return None  # e.g. openclaw.json, openclaw/plugin-sdk
    if first not in TOPS:
        return f"unknown command: openclaw {first}"
    path = resolve(toks)
    node = helpdb[" ".join(path)]
    nxt = toks[len(path)] if len(toks) > len(path) else None
    if nxt and not nxt.startswith("-") and node["subcommands"] and re.match(r"^[a-z][\w-]*$", nxt):
        # node has subcommands but this word is not one of them; may be a positional arg
        raw = node["raw"]
        if "Arguments:" not in raw and "[command]" in raw and "<" not in raw.split("Usage:")[1].split("\n")[0].replace("[command]", ""):
            return f"unknown subcommand: openclaw {' '.join(path)} {nxt}"
    opts = set(node["options"]) | GLOBAL
    bad = []
    for t in toks[len(path):]:
        if t.startswith("--"):
            flag = t.split("=", 1)[0]
            if flag not in opts and not (flag.startswith("--no-") and "--" + flag[5:] in opts):
                bad.append(flag)
        elif re.match(r"^-[A-Za-z]$", t) and t not in opts:
            bad.append(t)
    if bad:
        return f"unknown flag(s) {bad} for: openclaw {' '.join(path)}"
    return None


def scan(md):
    text = open(md, encoding="utf-8").read().replace("\r\n", "\n")
    lines = text.split("\n")
    findings, negatives, fence = [], 0, None
    for no, line in enumerate(lines, 1):
        m = re.match(r"^\s*```(\w*)", line)
        if m:
            fence = None if fence is not None else (m.group(1) or "plain")
            continue
        if "CLI-NOCHECK" in line:
            continue
        neg = "❌" in line  # lines marked with ❌ are deliberate counter-examples
        segments = []
        if fence in ("bash", "sh", "shell", "powershell", "console", "text", "plain"):
            code = line.split(" #", 1)[0] if not line.lstrip().startswith("#") else ""
            segments.append(code)
        elif fence is None:
            segments += re.findall(r"`([^`]*openclaw[^`]*)`", line)
        for seg in segments:
            for inv in INV.finditer(seg):
                err = check_invocation(inv.group(1))
                if err and neg:
                    negatives += 1
                elif err:
                    findings.append((no, err, seg.strip()[:120]))
    return findings, negatives


total = negs = 0
for md in args[1:]:
    f, n = scan(md)
    total += len(f); negs += n
    if not quiet:
        for no, err, seg in f:
            print(f"{md}:{no}: {err}    | {seg}")
print(f"cli findings: {total} (counter-examples correctly flagged: {negs})")
sys.exit(1 if total else 0)

已知限制:沒有子指令的指令(例如 openclaw worker)後面接的字會被視為位置參數,因此 openclaw worker list 不會被自動抓出(本次以人工審查修正)。由插件提供的指令(matrix、voicecall、wiki 等)列在 PLUGIN_CMDS,不做旗標檢查。

validate_json5.py

"""Validate every JSON5 config block with the real `openclaw config validate --json`.

Usage: python -I validate_json5.py <openclaw.cmd> <blocks dir> <out.json> [file ...]
Each block is written to an isolated OPENCLAW_CONFIG_PATH. Blocks that are
fragments (top-level key not a config root) are reported as such.
Environment placeholders like ${VAR} are given dummy values so SecretRef
resolution does not fail validation.
"""
import json
import os
import pathlib
import re
import subprocess
import sys
import tempfile

EXE, BLOCKS, OUT = sys.argv[1], pathlib.Path(sys.argv[2]), sys.argv[3]
only = sys.argv[4:]


def validate(src: pathlib.Path):
    text = src.read_text(encoding="utf-8")
    env = dict(os.environ)
    for var in set(re.findall(r"\$\{([A-Z0-9_]+)\}", text)):
        env.setdefault(var, "dummy-" + var.lower())
    with tempfile.TemporaryDirectory() as d:
        cfg = pathlib.Path(d) / "openclaw.json5"
        cfg.write_text(text, encoding="utf-8")
        env["OPENCLAW_CONFIG_PATH"] = str(cfg)
        env["OPENCLAW_STATE_DIR"] = str(pathlib.Path(d) / "state")
        p = subprocess.run([EXE, "config", "validate", "--json"], capture_output=True,
                           text=True, encoding="utf-8", errors="replace", env=env, timeout=240)
    out = p.stdout.strip()
    try:
        data = json.loads(out[out.index("{"):])
    except ValueError:
        data = {"unparsed": (out + p.stderr)[-2000:]}
    return {"exit": p.returncode, "result": data}


def main():
    files = [BLOCKS / f for f in only] if only else sorted(BLOCKS.glob("*.json5"))
    res = {}
    for f in files:
        r = validate(f)
        res[f.name] = r
        ok = r["result"].get("valid")
        print(f.name, "VALID" if ok else "INVALID", r["exit"], flush=True)
    json.dump(res, open(OUT, "w", encoding="utf-8"), ensure_ascii=False, indent=1)


if __name__ == "__main__":
    main()

F.3 實跑結果(2026-11-08)

檢查結果
JSON5 組態區塊39/39 通過 config validate(另有 2 個標示 NOVALIDATE 的錯誤示範/$include 片段)
CLI 用法0 筆錯誤;16 筆刻意的 ❌ 反例皆被正確標記
docs.openclaw.ai 連結131 個全部存在(0 個失效、0 個需轉址)
YAML 區塊17/17 解析通過;prometheus.yml 通過 promtool check config
JavaMaven:OpenClawClientTest 10、OpenClawControllerTest 3 通過,LiveGatewaySmokeTest 預設 Skipped;全書 27 個 Java 區塊語法解析 0 錯誤
Java 對真實 GatewaygatewayIsReady 通過;對話回合因測試環境未設定模型金鑰而回 401 No API key found for provider "anthropic"(預期行為,證明請求已抵達 Agent)
TypeScript4.11 Gateway client、2.8 頻道插件 entry、4.9 SDK 子路徑、4.4 tool plugin:tsc --strict 0 錯誤
插件Plugin ticket-lookup is valid.;vitest 3/3 通過;安裝後 enabled、config validate 0 warnings
Mermaid65/65 解析通過
code fence276 組成對,無未閉合區塊
本機 Gateway 端點/healthz → {"ok":true,"status":"live"};/readyz → {"ready":true,...};/startupz → 含 version;未知路徑 → 200 text/html;/v1/models 列出 Agent 目標;未裝插件時 /api/diagnostics/prometheus → 404

F.4 主要修正清單(v3.0.0 → v4.0.0)

#章節舊內容修正後依據
1全書31 個 JSON5 區塊中 29 個無法通過驗證(agent.model、models.default、governance、performance、compliance、security.*、telemetry.exporter、logging.format…)全部改寫為 2026.11.1 schema 的真實鍵config validate 實測
2全書51 處 CLI 錯誤(openclaw start/restart/reload、config show/migrate、tasks、fleet、skills publish/remove、logs -f、message send --to…)全部改為存在的指令--help 白名單
31.5技能載入 3 層;frontmatter 含 triggers/tools/access7 層優先序;AgentSkills 規範鍵;allowlist 規則docs/tools/skills.md
41.6工具 profile/group 不完整;工具呼叫 JSON 被標成組態官方 profile/group 表;正確的 Automations 指令tool-policy.md
51.10/1.12停在 2026.8.1;extended-stable 寫為 6.34補 8.2→11.1;extended-stable 為 9.36(LTS 月線)Releases、dist-tags
62.6modelPolicy 未說明萬用字元規則只接受 provider/*;openai/gpt-6-* 不合法config validate 實測
72.9/2.10多 Gateway + Redis/PostgreSQL 共用 state 的 HA 拓撲單一擁有者模型、救援 Gateway、冷備援、以信任域切分gateway-lock.md、multiple-gateways.md
82.12(新)—實驗性 PostgreSQL 引擎(僅 Workboard)database-engines.md
93.1Node >=22.22.3 等>=24.16.0 <25 || >=26.1.0;建議 24.22.1+/26.12.1+;Apple 26.2node-compatibility.md
103.3/3.5/root/.openclaw、Redis、:latest、全介面開埠官方 compose 精簡版、/home/node/.openclaw、127.0.0.1:官方 docker-compose.yml
113.8/3.9openclaw.<env>.json 自動疊加;hot/restart 重載模式$include;gateway.reload.mode 只有 off/hybridschema、common-tasks.md
123.10指令表含大量不存在的指令依 630 個指令路徑重建--help 白名單
133.11secrets.protected/agentReadable 鍵、vault:// 參照Secret Store kind: secret/env、egress proxy 主機綁定secret-store-and-egress.md
143.12(新)—四條發布通道與企業選型development-channels.md
154.2/4.10Java-WebSocket 送出杜撰的 message.send 協定OpenAI 相容 HTTP API;Spring Boot 4;契約+冒煙測試openai-http-api.md、實測
164.2—實測發現:JDK HttpClient 的 Upgrade: h2c 讓 Gateway 回 400/405,必須固定 HTTP/1.1本機 Gateway 實測
174.4tools: [{ endpoint }] 工具定義MCP Server 與 defineToolPlugin(實際 build/validate/install)tool-plugins.md、實測
184.4Code Mode 範例使用 camelCase 名稱與不存在的 Java 等價類別工具名稱即全域函式、catalog.search、store/loadcode-mode/guest-api.md
194.7只有自建 Java webhook 伺服器原生 hooks.* ingress 與安全規則cron-jobs/webhooks.md
204.11createGatewayClient、validate: 'strict'GatewayClient + chat.send(需 idempotencyKey)+ 配對流程套件型別、clients.md
214.12/4.13(新)—Managed Worktrees、個人技能庫managed-worktrees.md、skills.md
224.3/5.3/E自我學習 off/propose/auto只有 off/auto(propose 已移除)schema enum
235.4agents.defaults.trustedToolstools.* + tools.exec.security/ask/host;Trusted Tool Policy 為插件能力schema、building-plugins.md
245.4transcript.read() 等 SDK 介面plugin-sdk/agent-sessions 等實際介面sdk-runtime/agent.md
256.3/6.4telemetry.exporter;Prometheus /metrics;虛構的指標名稱diagnostics.otel;/api/diagnostics/prometheus(需驗證);真實指標prometheus.md、promtool
266.7只有基本備份指令五條備份路徑、異地備份、Litestream、還原演練install/backups.md
277.3/8.8/8.9滾動升級、流量權重 Canary以 Gateway 為單位、suspend/drain、RecreateGateway lock
287.11(新)—更新預演、admission 錯誤碼、自動回滾、9.5 必經站cli/update.md、CHANGELOG 9.7
298.4/8.5CMD ["openclaw","start"]、curl probe、replicas 未限制官方 manifest:Recreate、JSON probe、唯讀 rootfs官方 deployment.yaml
308.7不存在的 Helm chartFlux Kustomizationinstall/kubernetes.md
318.11(新)—npm integrity、簽章、provenance 實測npm audit signatures
329.x沙箱 allow/deny 位置錯誤、security.tls、security.encryptiontools.sandbox.tools、gateway.tls;澄清 OpenClaw 不做靜態加密schema、Secret Store 文件
339.12(新)—2026-09-11 的 375 筆公告與強化基準Security Advisories
3411.7(新)—Team Server:Cloudflare Access + trusted-proxy + rolesteam-server.md、validate
3512.6/12.7杜撰的 createSession/reclaimSession/sessions_createopenclaw gateway call sessions.create/dispatch/reclaim;Cloud Sessionscloud-workers/*.md
36附錄 D1 個失效連結、3 個轉址連結修正並新增 D.7(27 個 2.x 文件)check_doclinks.py
37附錄 E只涵蓋到 2.0E.5:2.0 → 2026.11.1 破壞性變更矩陣與步驟CHANGELOG
38全書無逐章審查清單每章新增「本章審查與驗證清單」—

F.5 待確認事項(Pending)

#項目原因建議的確認方式
1對話回合的端到端行為(工具呼叫、技能選用)驗證環境未使用真實模型金鑰於預備環境設定金鑰後執行 LiveGatewaySmokeTest 與 8.3 的黃金問題
2Docker 映像與 Kubernetes manifest 的實際部署驗證機的 podman machine 未啟動、無 Kubernetes 叢集docker compose up 與 kubectl apply --dry-run=client -k 後實際部署
3openclaw/releases 的 2026.11.1 evidence 檔GitHub API 查詢該目錄回 404(Release 說明中有連結)直接開啟 Release 說明中的 evidence 連結確認
4第十章各案例 Java 程式的完整編譯案例程式互相引用、相依未定義,僅做語法解析依 10.11 第 4 項放入 Maven 專案補齊相依後編譯
511.1–11.6 的協作功能細節(分享角色、Presence、Incognito)本次以 2026.11.1 文件抽查,未逐項在 Control UI 操作驗證在 Team Server 預備環境以多帳號操作確認
6security.installPolicy.exec 的外部審核指令協定未實作外部審核服務依官方文件撰寫審核指令並以測試插件驗證
7Cloud Worker(Crabbox/AWS)實際佈建需要雲端帳號在沙箱 AWS 帳號建立 profile 並執行 12.6 的派工與回收

文件資訊

  • 文件名稱: OpenClaw 生態系教學手冊
  • 版本: 4.0.0
  • 基於 OpenClaw 版本: 2026.11.1(stable)/2026.9.36(extended-stable)
  • 建立日期: 2026 年 3 月
  • 最後更新: 2026 年 11 月 8 日
  • 維護團隊: Tutorial Team
  • 驗證紀錄: 見附錄 F
  • 授權: 本文件僅供內部教學使用