# OpenClaw 專案架構分析（2026-02-01）

> 本報告提供給首次接觸 OpenClaw 的工程師作為入門導覽。內容以「主題章節」方式整理，協助從不同切入點理解整體架構與實作方式。

::: warning
以下內容中包含 Copilot 與個人解讀，有任何錯誤都請提出！
:::

## 1. 專案總覽（What & Why）

OpenClaw 是一個「本機優先（local‑first）」的個人 AI 助理平台，重點在於**把所有聊天通道、裝置與工具都透過同一個控制平面協調**。它不是單一聊天機器人，而是能在多通道、多裝置之間協作的工作流系統。

**核心概念**：
- Gateway 是整個系統的中樞（控制平面）。
- 所有對外通道、CLI、UI、App 都以 Gateway 作為統一入口。
- Agent runtime 負責推理（模型）與工具調度。

這樣的設計使得：
- 通道擴充變得可插拔。
- UI / App / CLI 都只是不同形態的 Client。
- 安全策略可以集中在 Gateway 層處理。

<br>

## 2. 架構分層（High‑Level Architecture）

OpenClaw 可以抽象成以下幾層：

1. **控制平面（Gateway）**
- 主要負責 WebSocket 通訊、狀態同步、會話管理、事件分發、工具與節點管理。
- 任何 client 都透過 Gateway 溝通，避免重複的互通邏輯。

2. **通道適配層（Channels / Adapters）**
- 每個聊天平台都有獨立的 Adapter。
- 功能是把「平台原生格式」轉為「OpenClaw 通用事件」，再由 Gateway 分派給對應 session。

3. **Agent Runtime（推理 + 工具協調）**
- Agent 是「模型 + 工具」的實作核心。
- 推理後可呼叫工具（browser/canvas/nodes/cron 等）。

4. **UI / 客戶端**
- WebChat / Control UI / CLI / macOS/iOS/Android App。
- 這些都是「Gateway client」，本質只是一個入口形式的差異。

5. **Extensions / Plugins**
- 擴展通道或功能用的外掛，依賴獨立管理。
- 能減少核心依賴膨脹，也利於團隊/社群擴充。

<br>

## 3. 技術選擇（Tech Stack）

以下是從 codebase 中可觀察的主要技術選擇：

### 語言與平台

- TypeScript (ESM)
- Node.js 22+
- pnpm 為主的套件管理流程

### 主要核心技術

- WebSocket (`ws`)：Gateway 的核心通訊層。
- Express：提供 Web 與控制面入口。
- CLI (`commander`)：命令列入口與操作工具。
- Schema 驗證 (`ajv`, `@sinclair/typebox`, `zod`)：強化配置與資料安全。
- UI (`lit`)：WebChat/Control UI。
- 測試 (`vitest`)：單元與整合測試。

### 平台整合

- 多通道 SDK（Slack/Discord/Telegram/WhatsApp 等）。
- macOS/iOS/Android 透過 Node/Swift/Kotlin 交互。

<br>

## 4. 專案搭建方式（Project Composition）

從 repo 結構可見 OpenClaw 是「多工作區 + 核心」的設計：

- `src/`：核心平台（Gateway、CLI、commands、infra、media 等）。
- `extensions/`：外掛通道與擴展功能。
- `apps/`：macOS/iOS/Android 原生應用。
- `ui/`：Web UI。
- `docs/`：文檔。

這種結構特別適合：

- 核心邏輯穩定、擴展容易。
- 不同平台能夠獨立演進。
- 支援開源生態的插件開發。

<br>

## 5. 基本執行邏輯（End‑to‑End Flow）

以下是訊息從進入到回覆的簡化流程：

1. **訊息進入**：
某通道（如 Telegram/WhatsApp）收到訊息。

2. **通道 Adapter 轉換**：
平台專用格式轉換成統一的 OpenClaw 事件。

3. **Gateway Routing**：
根據 session/router 規則，將訊息送往正確 agent。

4. **Agent Runtime 推理**：
模型產出回應，必要時呼叫工具。

5. **回傳**：
回覆交由 Gateway -> 通道 Adapter -> 原平台。

這個設計讓所有通道與工具共用同一套 ***routing / 安全 / 狀態*** 管理。

<br>

## 6. Junior 工程師的學習路線（建議切入點）

### Step 1：先理解「Gateway 是中樞」

**邏輯**：所有元件都 ***不直接互通***，而是經由 Gateway 交換事件、狀態與指令。

- Gateway = 系統的**大腦**與**路由**中心
- UI / CLI / Apps / Channels 都是 Gateway client
- 集中處理：Session 狀態、事件派發、工具調度、權限與安全政策

**為什麼重要**：

- 讓「多通道」與「多裝置」的協作成本降低
- 安全與審計集中化（控制點只有 Gateway）
- 擴展時不需要更動其他元件，只要連上 Gateway

### Step 2：理解「通道只是 Adapter」

**邏輯**：每個通道只做「翻譯」與「傳遞」，不做推理與決策。

- 入口：平台原生事件 → OpenClaw 通用事件
- 出口：OpenClaw 回覆 → 平台原生訊息
- 統一行為：只關注格式、速率限制、送達狀態

**為什麼重要**：

- 讓通道擴充「可插拔」，避免每個平台綁死核心邏輯
- 減少耦合，Gateway 依然能提供一致的 routing 與安全策略

### Step 3：理解「Agent 是推理 + 工具的核心」

**邏輯**：Agent 代表一個工作單元（session），負責推理與呼叫工具。

- 每個 session 都有自己的上下文、工具權限、設定
- 推理結果可觸發工具（browser / canvas / nodes / cron 等）
- 工具的回應再回流到 session，形成完整工作流

**為什麼重要**：

- 多 session 模式可支援「多角色 / 多任務」並行
- 工具調用與 Sandbox 策略都可由 session 控制

### Step 4：理解「UI/CLI 是 Client」

**邏輯**：UI/CLI/App 只是 Gateway 的不同使用介面。

- UI 提供視覺化管理與監控
- CLI 提供腳本化與自動化操作
- App 提供本機能力（語音、通知、Canvas、Camera）

**為什麼重要**：

- 功能不分散：所有操作流程與狀態都來自 Gateway
- UI/CLI/App 可以同時存在且不互相干擾

### Step 5：理解「Extensions 是外掛化」

**邏輯**：將可選功能與特定通道獨立成插件，以減少核心膨脹。

- 核心保持最小必要功能
- 插件各自管理依賴與版本
- 插件可獨立發佈、升級或下架

**為什麼重要**：

- 維護成本降低
- 社群可平行開發新通道
- 更容易做版本與安全隔離

<br>

## 7. 總結

OpenClaw 的核心價值在於「統一控制平面 + 多通道/多裝置協作」。

對初學者來說，理解順序建議是：

1. Gateway → 2) Channels → 3) Agent → 4) Tools → 5) UI/Apps → 6) Extensions。

一旦掌握這個脈絡，就能快速理解其模組化設計與可擴展性。

<br>

## 8. System Design Frame（圖解）

以下是以系統設計視角的整體框架圖，幫助工程師快速理解「訊息流」、「控制流」與「工具流」的關係：

┌──────────────────────────────────────────────────────────────────────┐
│                              Channels                                │
│ WhatsApp / Telegram / Slack / Discord / Google Chat / iMessage       │
│               (Extensions: Teams / Matrix / Zalo / ... )             │
└──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│                             Gateway (WS)                             │ 
│    - Session routing   - Events & presence   - Auth & policy         │
│    - Tool dispatch     - Control UI/WebChat  - Node registry         │
└──────────────┬───────────────────────┬───────────────────────────────┘
               │                       │
               │                       │
               ▼                       ▼
   ┌────────────────────┐     ┌────────────────────┐
   │   Agent Runtime    │     │    UI / Clients    │
   │  - Model reasoning │     │  - WebChat / UI    │
   │  - Tool invocation │     │  - CLI / Apps      │
   └──────────┬─────────┘     └────────────────────┘
              │
              ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │                             Tools                                │
   │ Browser / Canvas / Nodes / Cron / Webhooks / Media Pipeline      │
   └──────────────────────────────────────────────────────────────────┘
              │
              ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │                         Devices / Nodes                          │
   │ macOS / iOS / Android (camera, screen, voice, notify, system.run)│
   └──────────────────────────────────────────────────────────────────┘

**如何閱讀這張圖**：

- 上層（Channels）：所有外部訊息來源都是「輸入入口」。
- 中間（Gateway）：控制平面集中處理「路由 / 安全 / 狀態同步」。
- 右側（UI/Clients）：只是不同介面，功能來源都來自 Gateway。
- 下層（Agent + Tools + Nodes）：推理與執行的工作流，所有工具呼叫皆由 Gateway 調度。

<br>

## 9. System Prompt（設計理念與成效來源）

本專案的 System Prompt 並不是「單一長字串」，而是 ***以多層提示檔案* 與 *執行規範* 組合而成的提示框架**。在本專案中，提示與執行行為是高度整合的：一方面約束模型輸出風格與安全邊界，另一方面也提供可操作的工具與工作流程，讓模型能在可控的環境中完成任務。

### 9.1 System Prompt 的構成方式（從 codebase 觀察）

OpenClaw 的 agent 會載入「注入式提示檔案」，並以一致的規範驅動工具與工作流：

- **注入式提示檔案**：例如 `AGENTS.md` / `SOUL.md` / `TOOLS.md`（在專案的工作區與 agent workspace 會被注入使用）。
- **工具規範與限制**：提示內容會明確定義工具可用範圍、何時可操作、何時禁止。
- **一致的輸出與風格**：提示系統要求輸出簡潔、可追溯、並避免無根據的臆測。

### 9.2 為什麼能更有效率地驅動模型

這個專案的 Prompt 不只是「說明該怎麼回答」，還把**執行規則、工具流程與安全策略**一起納入：

- **任務導向**：Prompt 明確要求「完成任務」與「可執行行動」，避免空泛回覆。
- **工具導向**：模型被要求在需要時使用工具，並遵守工具使用規範。
- **安全導向**：對敏感內容、破壞性操作、與不安全輸出有明確限制。
- **上下文管理**：透過工作區與注入檔案，將專案規則與風格持續保持一致。

### 9.3 與其他專案的差異（概念層比較）

以下是以「架構策略」層級的比較（不涉及其他專案細節）：

| 比較面向 | 常見專案做法 | OpenClaw 作法 | 優勢 |
| ------------ | --------------- | ---------------------------------- | ---------------------- |
| Prompt 結構 | 單一長 prompt | 多檔案注入式提示框架 | 可維護、可分工、可擴展 |
| 工具使用 | 依模型自行決定 | 明確規範何時可/不可使用工具 | 可控性高、可審計 |
| 安全限制 | 僅靠模型自律 | Prompt + Gateway + Policy 多層限制 | 減少誤用、提升可靠性 |
| 上下文一致性 | 依 session 記憶 | 透過固定提示 + 配置檔保持一致 | 跨任務一致性高 |

### 9.4 專案強大之處（Prompt 角度）

OpenClaw 的 Prompt 能「有效、高性能」並非因為文字本身更長，而是因為：

1. **Prompt 是流程的一部分**：不是只控制輸出，而是控制行為。
2. **工具與策略綁定**：把工具規範與安全策略寫進模型的「行為邊界」。
3. **可維護的知識注入**：以多檔案與工作區配置管理提示，避免單一巨大 prompt 失控。
4. **全系統一致性**：所有 client（CLI/UI/Apps/Channels）都共享同一套規則與流程，模型行為一致。

這些特性使得 OpenClaw 的 Prompt 不只是「指令」，而是**一整套可控、可審計、可擴展的行為框架**，也是其可靠性與可擴展性的關鍵來源之一。

<br>

## 10. Pipeline（處理流程、優勢與優化方向）

### 10.1 Pipeline 概念總覽

OpenClaw 的 pipeline 可以理解為「事件流 + 控制流 + 工具流」的組合，從訊息進入到回覆輸出都由 Gateway 統一協調。典型流程如下：

1. **Ingress（通道收訊）**：Channel Adapter 接收外部平台事件。
2. **Normalization（統一格式）**：轉成 OpenClaw 通用事件。
3. **Routing & Policy（路由與策略）**：依 session/router 規則決定 agent；同時套用安全/權限政策。
4. **Agent Reasoning（推理）**：模型推理與任務拆解。
5. **Tool Orchestration（工具調度）**：調用 browser/canvas/nodes/cron 等工具。
6. **Post‑Process（回應整形）**：格式化輸出、分段、附加 metadata。
7. **Delivery（通道回送）**：回覆送回原平台。
8. **Telemetry（狀態與紀錄）**：事件、狀態、使用量、錯誤回報。

### 10.2 這樣的流程有什麼優勢？為什麼強大？

- **統一入口與出口**：所有通道走相同管道，降低異質平台整合成本。
- **一致的安全控制**：在 Routing 階段就能應用安全政策，避免工具濫用。
- **可插拔的擴展能力**：通道與工具都是插件化設計，新增功能不需更動核心。
- **可觀測性強**：集中式事件與狀態記錄，便於追蹤與除錯。
- **多 Client 並存**：UI/CLI/App 同時使用，不互相干擾。

### 10.3 未來可考慮的優化方向

以下是一般 AI Agent 平台可考慮的改進方向（概念層）：

- **更細緻的事件追蹤與分散式 tracing**：提升問題定位效率。
- **模型選擇與成本路由**：動態選擇模型以平衡成本與品質。
- **回應快取與重試策略**：減少重複推理成本，提高穩定性。
- **工具沙箱隔離加強**：降低執行風險與安全攻擊面。
- **插件依賴與版本隔離**：避免擴展造成核心不穩。
- **長期記憶與工作流編排**：讓 agent 能更好地處理長期任務。

### 10.4 在 agent 專案中，重要優化會落在 prompt 還是 codebase？為什麼？

**答案是兩者都重要，但優先順序依目標不同而變化：**

- **Prompt 優化**：影響模型的理解力、意圖拆解與回應品質。
- 主要用於提升任務完成率、回覆一致性、與人機互動體驗。
- **Codebase 優化**：影響穩定性、延遲、成本、安全與可觀測性。
- 在長期運行的生產環境中，codebase 的改進通常更關鍵。

**結論**：

- 如果目標是「提升任務表現」，Prompt 優化的效果最快顯著。
- 如果目標是「提升可靠性與可維運性」，Codebase 優化才是核心。
- 在 OpenClaw 這類平台中,最強的做法是 **Prompt + Pipeline 的協同演進**，以行為規則驅動模型，再以系統架構保證穩定性。

<br>

## 11. 參考資料與程式碼驗證（Codebase References）

本章節列出報告中提及的關鍵概念對應的實際檔案與程式碼位置，供讀者進一步驗證與深入研究。

### 11.1 Gateway（控制平面）

**核心實作**：

- `src/gateway/server.impl.ts` - Gateway 主伺服器實作，包含 WebSocket 與 HTTP 服務啟動邏輯
- `src/gateway/server/ws-connection.ts` - WebSocket 連線處理與 client 管理
- `src/gateway/server-runtime-state.ts` - Gateway 執行階段狀態管理（clients、broadcast、sessions）
- `src/gateway/server-methods.ts` - Gateway RPC 方法處理（agent、sessions、config 等）

**協議定義**：

- `src/gateway/protocol/schema.ts` - Gateway WebSocket 協議的 TypeBox schema
- `docs/gateway/protocol.md` - Gateway 協議完整文檔（framing、roles、scopes）

**關鍵概念驗證**：

// src/gateway/server-runtime-state.ts
export function createGatewayRuntimeState(params) {
  const clients = new Set<GatewayWsClient>();
  const { broadcast } = createGatewayBroadcaster({ clients });
  // Session routing, tool dispatch, presence management
  return { clients, broadcast, agentRunSeq, chatRunState, ... };
}

### 11.2 Channels（通道適配層）

**通道架構**：

- `src/channels/plugins/types.ts` - 通道插件介面定義
- `src/channels/plugins/index.ts` - 通道插件註冊與查找
- `src/channels/registry.ts` - 通道 ID 標準化與元資訊管理

**具體通道實作**（範例）：

- `extensions/telegram/` - Telegram 通道插件
- `extensions/discord/` - Discord 通道插件
- `extensions/slack/` - Slack 通道插件
- `extensions/whatsapp/` - WhatsApp 通道插件（Baileys）

**Adapter 模式驗證**：

// src/channels/plugins/types.adapters.ts
export type ChannelOutboundAdapter = {
  deliveryMode: "direct" | "gateway";
  sendText: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
  sendMedia: (
    ctx: ChannelOutboundMediaContext,
  ) => Promise<OutboundDeliveryResult>;
};

### 11.3 Routing & Session Management

**路由邏輯**：

- `src/routing/resolve-route.ts` - Agent 路由解析（根據 channel/peer/binding 決定 session）
- `src/routing/bindings.ts` - Agent bindings 管理（多 agent 路由規則）
- `src/routing/session-key.ts` - Session key 格式化與解析

**Session 管理**：

- `src/gateway/session-utils.ts` - Session store 讀寫與列表操作
- `src/config/sessions.ts` - Session 配置與持久化

**路由範例**：

// src/routing/resolve-route.ts
export function resolveAgentRoute(
  input: ResolveAgentRouteInput,
): ResolvedAgentRoute {
  // 依 binding 規則決定 agentId + sessionKey
  const bindings = listBindings(input.cfg);
  // Match by peer/guild/team/account/channel
  return { agentId, sessionKey, matchedBy };
}

### 11.4 Agent Runtime & Tools

**Agent 執行**：

- `src/agents/pi-embedded-runner/run/attempt.ts` - Agent 推理執行入口
- `src/agents/pi-tools.ts` - Pi agent 工具集註冊
- `src/agents/openclaw-tools.ts` - OpenClaw 專屬工具（sessions\_\*, agents_list 等）

**Tools 實作範例**：

- `src/agents/tools/sessions-spawn-tool.ts` - Sub-agent 產生工具
- `src/agents/tools/sessions-send-tool.ts` - 跨 session 訊息傳送
- `src/agents/tools/session-status-tool.ts` - Session 狀態查詢
- `src/agents/bash-tools.process.ts` - Process 管理工具

**工具調度驗證**：

// src/agents/pi-tools.ts
export function createPiAgentTools(options?) {
  const tools = [
    createBashTool(...),
    createProcessTool(...),
    createWebSearchTool(...),
    createBrowserTool(...),
    // ... 其他工具
  ];
  return tools;
}

### 11.5 System Prompt（注入式提示框架）

**提示檔案模板**：

- `docs/reference/templates/AGENTS.md` - Agent 工作區指南（記憶、工作流程）
- `docs/reference/templates/SOUL.md` - Agent 性格與行為準則
- `docs/reference/templates/TOOLS.md` - 工具與環境特定配置

**實際應用位置**：

- `~/.openclaw/workspace/AGENTS.md` - 使用者工作區（執行時注入）
- `~/.openclaw/workspace/SOUL.md` - Agent 性格檔案
- `~/.openclaw/workspace/TOOLS.md` - 環境特定配置

**提示框架特點**（從模板可見）：

# AGENTS.md 核心指令

## Every Session

Before doing anything else:

1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` for recent context
4. **If in MAIN SESSION**: Also read `MEMORY.md`

# SOUL.md 行為準則

**Be genuinely helpful, not performatively helpful.**
**Have opinions.** You're allowed to disagree.
**Be resourceful before asking.** Try to figure it out.

### 11.6 Pipeline 流程驗證

**事件流處理**：

- `src/gateway/server-chat.ts` - 訊息進入後的 agent 調度
- `src/infra/outbound/deliver.ts` - 訊息回送與通道適配
- `src/gateway/server-methods/agent.ts` - Agent RPC 方法（推理入口）

**Pipeline 階段對照**：

// 簡化流程示意（實際分散在多個檔案）
1. Ingress: Channel Adapter 收訊
2. Normalization: 統一為 OpenClaw 事件格式
3. Routing: resolveAgentRoute() 決定 sessionKey
4. Agent Reasoning: callAgent() 呼叫模型
5. Tool Orchestration: 工具執行與回應
6. Post-Process: 格式化輸出
7. Delivery: deliverResponse() 回送通道
8. Telemetry: 狀態記錄與事件廣播

### 11.7 配置與文檔

**配置結構**：

- `src/config/config.ts` - 配置檔讀寫與驗證
- `src/config/types.gateway.ts` - Gateway 配置 TypeScript 型別
- `src/config/zod-schema.agent-runtime.ts` - Agent runtime 配置 Zod schema

**官方文檔**（完整架構說明）：

- `docs/gateway/index.md` - Gateway 運行指南
- `docs/concepts/architecture.md` - 架構總覽
- `docs/cli/index.md` - CLI 完整參考

### 11.8 測試與驗證

**測試範例**（驗證上述邏輯確實運作）：

- `src/gateway/server.config-patch.e2e.test.ts` - Gateway 配置更新測試
- `src/agents/openclaw-tools.agents.test.ts` - Agent 工具測試
- `src/agents/openclaw-tools.subagents.sessions-spawn-applies-model-child-session.test.ts` - Sub-agent 模型繼承測試

<br>

## 12. 結語

本報告所述內容均可在 OpenClaw codebase 中找到對應實作。以上參考資料提供了驗證路徑，讀者可依此深入研究各模組的細節實作。

OpenClaw 的強大之處在於「設計即程式碼」：架構概念與實際執行高度一致，Prompt 與 Pipeline 協同演進，使其成為一個既可靠又可擴展的 AI Agent 平台。