OpenClaw 深度解析

Gateway 架構、Workspace 檔案系統、記憶機制、生態風險與實務應用

Overview##

OpenClaw 是 2026 年最大的開源 AI Agent 框架——353K+ GitHub stars、3.2M 月活躍用戶、13,700+ 社群技能。它由 PSPDFKit 創辦人 Peter Steinberger 建立，定位是一個 24/7 常駐的個人 AI 助理。

與聊天機器人不同，OpenClaw 不只是回答問題——它能主動執行任務、連接 25+ 即時通訊平台、管理檔案系統、排程工作，並且記住跨 session 的上下文。

graph LR
  A[User] -->|WhatsApp / Telegram / Slack| B[OpenClaw Gateway]
  B --> C[Agent Runtime]
  C --> D[LLM - Claude / GPT / Local]
  C --> E[AgentSkills]
  C --> F[Memory]
  C --> G[Scheduled Tasks]

Architecture##

Gateway — 核心控制層###

OpenClaw 採用 hub-and-spoke 架構，所有請求經過單一 Gateway 控制平面：

graph TB
  subgraph Channels
    A1[WhatsApp]
    A2[Telegram]
    A3[Slack]
    A4[Discord]
    A5[WebChat]
  end
  subgraph Gateway - 127.0.0.1:18789
    B[Channel Bridge] --> C[Session Resolution]
    C --> D[Command Queue]
    D --> E[Agent Runtime]
    E --> F[Tool Dispatch]
  end
  A1 --> B
  A2 --> B
  A3 --> B
  A4 --> B
  A5 --> B
  F --> G[LLM Provider]
  F --> H[AgentSkills]
  F --> I[Memory Store]

一則訊息的完整生命週期：

Inbound Message → Channel Bridge → Session Resolution → Command Queue → Agent Runtime
   (WhatsApp)       (協定轉換)       (找到/建立 session)     (排隊)       (LLM 執行)

Provider Plugin System###

2026 年的重大重構將 LLM 層從寫死改為 plugin 架構：

// 動態載入模型 provider
// 支援 Anthropic、OpenAI、本地模型
// 核心重構後只有 ~8MB

// 設定範例（非實際程式碼）
// providers:
//   - anthropic:
//       model: claude-sonnet-4-6
//       apiKey: ${ANTHROPIC_API_KEY}
//   - openai:
//       model: gpt-4.1
//       apiKey: ${OPENAI_API_KEY}
//   - local:
//       model: nemotron
//       endpoint: http://localhost:11434

模型可以在運行時切換——例如簡單任務用便宜的 Haiku，複雜推理用 Opus。

Workspace##

檔案系統設計###

OpenClaw 最獨特的設計是用 Markdown 檔案定義 agent 的一切行為。整個 workspace 結構：

~/.openclaw/
├── SOUL.md           ← 人格、價值觀、邊界
├── AGENTS.md         ← 操作規則、安全策略
├── USER.md           ← 使用者個人 context
├── IDENTITY.md       ← 名稱、頭像、emoji
├── TOOLS.md          ← 環境資訊
├── MEMORY.md         ← 長期記憶（永久）
├── HEARTBEAT.md      ← 排程任務（cron）
├── memory/           ← 記憶檔案目錄
│   └── compacted/    ← 壓縮的歷史記憶
└── skills/           ← 技能目錄
    └── my-skill/
        └── SKILL.md

SOUL.md — 人格定義###

SOUL.md 是 agent 的「靈魂」——每個 session 開始時第一個載入的檔案。它定義 agent 是誰：

# SOUL.md

You are Atlas, a professional AI assistant.

## Personality

- Direct and concise communication style
- Proactive: suggest improvements without being asked
- Honest: admit uncertainty rather than guessing

## Values

- Privacy first: never share user data externally
- Accuracy over speed: verify before responding
- Minimal disruption: batch notifications, don't spam

## Boundaries

- Never execute destructive commands without confirmation
- Never send messages on behalf of user without approval
- Never access files outside the workspace directory

AGENTS.md — 操作規則###

SOUL.md 定義 agent 是誰，AGENTS.md 定義 agent 怎麼做事：

# AGENTS.md

## Security Rules

- Always confirm before: sending emails, deleting files, making purchases
- Never store API keys in memory files
- Log all tool executions to daily notes

## Workflow Rules

- Write daily logs to memory/YYYY-MM-DD.md
- Summarize completed tasks at end of each session
- When unsure, ask rather than assume

## Communication Rules

- Respond in the same language as the user
- Keep messages under 500 words unless asked for detail
- Use bullet points for lists of 3+ items

HEARTBEAT.md — 排程任務###

HEARTBEAT.md 是 agent 的 cron——用自然語言定義排程：

# HEARTBEAT.md

## Every morning at 8:00 AM

- Check email inbox for urgent messages
- Summarize overnight notifications
- Send daily briefing via WhatsApp

## Every Friday at 5:00 PM

- Generate weekly activity report
- Archive completed tasks
- Update project status in memory

## Every 2 hours during work hours (9-18)

- Check GitHub for new issues assigned to me
- Monitor Slack channels for mentions

OpenClaw 每 30 分鐘讀取這個檔案。當排程時間到了，自動執行——不需要你主動觸發。

SKILL.md — 技能定義###

每個技能是一個目錄，包含一個 SKILL.md：

---
name: github-issue-tracker
description: Monitor and manage GitHub issues
tools: [shell, web]
---

# GitHub Issue Tracker

## When asked to check issues

1. Run `gh issue list --repo {repo} --state open`
2. Filter by assignee if specified
3. Summarize each issue: number, title, labels, age
4. Highlight issues older than 7 days

## When asked to create an issue

1. Confirm title and description with user
2. Run `gh issue create --title "{title}" --body "{body}"`
3. Report the issue URL

技能的設計原則：

Memory##

記憶層級###

OpenClaw 的記憶系統分為四層：

graph TB
  A["MEMORY.md（永久記憶）"] --> B["每個 session 都載入"]
  C["Daily Notes（每日筆記）"] --> D["按需載入"]
  E["Compacted History（壓縮摘要）"] --> F["自動摘要舊對話"]
  G["Active Context Window"] --> H["~70% 觸發 compaction"]
  A --- C --- E --- G

Context Compaction###

當 context window 使用率超過 ~70% 時，OpenClaw 觸發 compaction：

1. 觸發 silent turn → 提醒 agent 保存重要資訊到 MEMORY.md
2. 摘要歷史對話 → 壓縮成精簡版本
3. 釋放 context window → 繼續新的對話

已知限制###

記憶系統是 OpenClaw 最受爭議的部分。社群指出的核心問題：

1. 依賴 LLM 判斷：什麼「值得記住」由 LLM 決定，不可靠
2. Compaction 遺失：壓縮過程會丟失細節，長 session 後記憶品質下降
3. 無語義檢索：原生記憶是文字匹配，不支援語義搜尋

社群的解決方案是整合 Mem0（向量資料庫記憶層），用 embedding 做語義檢索而非依賴 LLM 主動寫入。

Ecosystem##

ClawHub — 技能市場###

ClawHub 是 OpenClaw 的官方技能 registry，類似 npm 之於 Node.js：

# 安裝技能
npx clawhub@latest install github-tracker

# 搜尋技能
npx clawhub@latest search "email automation"

# 發布自己的技能
npx clawhub@latest publish ./my-skill

截至 2026 年 4 月，ClawHub 擁有 13,700+ 社群技能，涵蓋：

ClawHavoc 供應鏈攻擊###

2026 年初，ClawHub 遭遇重大安全事件——ClawHavoc：

• 824 個惡意技能被發現，佔 registry 的 20-26%
• 9,000+ 安裝受影響
• 攻擊方式：偽裝成熱門技能的變體，名稱相似（typosquatting）
• 根本原因：任何人只需一週以上的 GitHub 帳號就能發布

這跟 npm 的 event-stream 事件和 PyPI 的 typosquatting 攻擊如出一轍。

成熟開放生態的安全演進：

Phase 1: 完全開放 → 快速成長
Phase 2: 重大安全事件 → ClawHavoc / event-stream
Phase 3: 引入審核機制 → verified publishers, signing
Phase 4: 分層信任 → official / community / unverified

目前 ClawHub 缺乏的安全機制：

Use Cases##

開發者工作流###

OpenClaw 在開發者場景有最高的滿意度。典型的設定：

GitHub Skill    → 自動追蹤 issue、建立 PR
Terminal Skill  → 執行 build、deploy 指令
Linear Skill    → 同步任務狀態
Code Review     → 自動檢查 PR 並留言

根據社群回報，開發團隊使用 OpenClaw 後效率提升 2-3x。

內容自動化###

最廣泛採用的場景。典型流程：

Blog RSS Feed → OpenClaw 偵測新文章
             → 產生 LinkedIn 摘要版本
             → 產生 Twitter thread 版本
             → 產生 Threads 短摘要版本
             → 等待用戶確認後發布

有使用者回報每週節省 10+ 小時的社群媒體管理時間。

企業報告###

一個牙醫集團（30 個據點）使用 OpenClaw 查詢財務數據：

用戶：「上個月各據點的營收排名？」
Agent：查詢多個管理系統 → 彙整資料 → 產生排名報表

取代了過去手動從多個系統拉報表的流程。

Quiz##

Summary##

• OpenClaw 是最大的開源 AI Agent 框架（353K+ stars），採用 Gateway hub-and-spoke 架構
• Gateway 綁定 127.0.0.1:18789，負責頻道路由、session 管理、工具分派
• Workspace 用 Markdown 檔案定義行為：SOUL.md（人格）、AGENTS.md（規則）、HEARTBEAT.md（排程）、SKILL.md（技能）
• 記憶系統分四層：MEMORY.md（永久）→ Daily Notes → Compacted History → Context Window
• 記憶的核心限制：依賴 LLM 判斷，compaction 會遺失細節——關鍵資訊應寫在設定檔而非依賴記憶
• ClawHub 有 13,700+ 技能，但 ClawHavoc 事件暴露缺乏安全審核機制
• 最佳實踐：搭配 NemoClaw 使用，加入 OpenShell sandbox 和 policy guardrails