OpenClaw 架构文档

项目版本：2026.3.24-beta.2

OpenClaw 当前源码体现出的架构可以概括为：

统一入口：CLI 驱动全部核心能力
统一控制面：Gateway 持有配置、连接、事件、客户端与运行态编排
统一执行面：Agent Runtime 负责模型、工具、上下文、失败恢复与交付
统一扩展面：插件系统把工具、渠道、provider、HTTP、CLI、hook、context engine 纳入同一注册框架
统一接入面：渠道与设备节点都被映射到受管运行时单元

1. 项目定位

OpenClaw 是一个多渠道个人 AI 助手运行平台 。它不是一个模型，而是把 AI 模型（Claude、GPT-4、Gemini、Llama 等 25+）作为"引擎"调用的基础设施层。

核心价值主张：

一个以 Gateway 为控制面的本地优先 AI Assistant 平台
一个以 Agent Runtime 为执行面的多模型、多工具、多会话运行时, 提供持久会话、长期记忆、工具执行、插件扩展、多 Agent 编排能力
一个以 Plugin / Channel 为主要扩展机制的宿主系统
一个同时覆盖 CLI、Web Control UI、macOS/iOS/Android 节点、消息渠道接入 的单仓平台

简化理解：

复制代码

外部消息渠道 / Web UI / CLI / 设备节点
                |
                v
         Gateway 控制面
                |
      +---------+---------+
      |                   |
      v                   v
 Agent Runtime        Channel Runtime
      |                   |
      v                   v
模型 / 工具 / 记忆 / 技能    Telegram / Slack / WhatsApp / Matrix ...
      |
      v
会话、转录、配置、插件注册、设备能力

一句话：Claude 是大脑，OpenClaw 是身体 + 神经系统 + 记忆系统。

2. 工程组织

复制代码

openclaw/                         # PNPM monorepo 根
├── src/                          # 主程序（44 个子模块）
│   ├── gateway/                  # 控制平面内核（154 文件）
│   ├── agents/                   # Agent 运行时（470+ 文件，最大模块）
│   ├── plugins/                  # 插件系统（200+ 文件）
│   ├── channels/                 # 渠道抽象层
│   ├── config/                   # 配置 schema、校验、读写、迁移
│   ├── acp/                      # Agent Control Protocol
│   ├── routing/                  # 消息路由与会话映射
│   ├── auto-reply/               # 入站消息调度管道
│   ├── context-engine/           # 可插拔上下文组装引擎
│   ├── memory/                   # 向量数据库、语义搜索
│   ├── media-understanding/      # 音频/图像/视频/PDF 处理
│   ├── browser/                  # Playwright 浏览器自动化
│   ├── tts/                      # 文本转语音
│   ├── plugin-sdk/               # 面向插件作者的 SDK
│   ├── sessions/                 # 会话生命周期
│   ├── security/                 # 安全检查、工具白名单
│   ├── secrets/                  # 密钥管理
│   ├── node-host/                # Node.js 执行沙箱
│   ├── cli/                      # 命令行框架
│   ├── cron/                     # 定时任务
│   ├── hooks/                    # 钩子系统
│   ├── infra/                    # 基础设施（出站投递等）
│   └── [其他 20+ 模块]
│
├── extensions/                   # 85 个插件扩展
│   ├── [AI 提供商 20+]           # openai, anthropic, groq, ollama, deepseek...
│   ├── [消息渠道 20+]            # telegram, whatsapp, slack, discord, line...
│   ├── [工具/服务 20+]           # brave, exa, elevenlabs, firecrawl...
│   └── [其他 20+]                # diagnostics, memory, gateway adapters...
│
├── skills/                       # 50+ 技能脚本（GitHub, Notion, Spotify...）
├── ui/                           # Web Control UI（Lit + Vite）
├── apps/                         # 原生客户端
│   ├── ios/                      # SwiftUI
│   ├── android/                  # Jetpack Compose
│   ├── macos/                    # Swift
│   └── shared/                   # 共享代码
│
├── packages/                     # 额外 npm 包
├── docs/                         # Mintlify 文档（含 zh-CN）
├── scripts/                      # 构建/发布脚本
└── test/                         # 测试工具和 fixtures

3. 系统六层架构

从源码分析，系统可以清晰地划分为六层：

复制代码

┌─────────────────────────────────────────────────────────────┐
│  第 1 层：入口与客户端壳                                      │
│  CLI (src/entry.ts) / Web UI (ui/) / 原生 App (apps/)       │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  第 2 层：Gateway 控制平面                                    │
│  WebSocket + HTTP + 事件总线 + 配置热重载 + 节点管理          │
│  • server.impl.ts — 系统编排器（非单纯 HTTP server）         │
│  • 会话订阅、转录文件、exec approval                         │
│  • 鉴权、速率限制、Tailscale、Control UI 暴露               │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  第 3 层：消息调度与路由                                      │
│  auto-reply 管道 + routing 引擎 + 插件会话绑定               │
│  • 8 级分层路由匹配（peer → guild → team → account → 兜底）  │
│  • 去重、允许列表、命令门控、typing 策略                     │
│  • 插件可在会话级别接管处理                                  │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  第 4 层：Agent 执行运行时(command,run)                                    │
│  ┌──────────────┬───────────────────┬──────────────────────┐│
│  │ 模型管理      │ 上下文引擎         │ 记忆/语义搜索        ││
│  │ • 选择+轮转   │ • 消息编排         │ • 向量化             ││
│  │ • 认证轮转    │ • 历史压缩         │ • 混合搜索           ││
│  │ • 多模型降级  │ • Prompt 动态装配  │ • 时间衰减+MMR       ││
│  ├──────────────┼───────────────────┼──────────────────────┤│
│  │ 工具系统      │ 子代理系统         │ 技能系统             ││
│  │ • 权限+沙箱   │ • 注册表+生命周期  │ • 50+ 可用技能       ││
│  │ • 白名单/黑名单│ • session 派生    │ • ClawhHub 市场      ││
│  └──────────────┴───────────────────┴──────────────────────┘│
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  第 5 层：Plugin / Channel 扩展层                             │
│  • 85 个仓库内插件（渠道、Provider、工具、Hook、HTTP 路由）   │
│  • 插件装载器（发现→manifest→校验→注册→缓存→诊断）           │
│  • 插件是一级架构构件，不是事后扩展                           │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  第 6 层：存储与持久化                                        │
│  • 配置文件（YAML，schema 自动生成，是核心资产）             │
│  • 会话存储（文件系统 — transcript.jsonl / session.json）     │
│  • 向量数据库（sqlite-vec / LanceDB / Pinecone）             │
│  • 认证存储（加密）                                          │
│  • 密钥管理（环境变量 / Secret Manager）                     │
└─────────────────────────────────────────────────────────────┘

OpenClaw 的架构有 5 个最重要的事实：

CLI 是统一入口，不是附属工具。 src/entry.ts 负责进程初始化、环境修正、profile/container 参数处理，最后进入 src/cli/run-main.js。
Gateway 是系统编排器，不只是 HTTP/WS 服务。 src/gateway/server.impl.ts 在启动时完成配置校验、旧配置迁移、插件启动、Secrets 运行时激活、Channel Manager 创建、WS/HTTP 面暴露、Control UI 挂载、定时器与 sidecar 启动。
Agent Runtime 是一个运行框架，不是一层薄封装。 src/agents/agent-command.ts 和 src/agents/pi-embedded-runner/run.ts 共同承担会话恢复、workspace 准备、模型选择、认证轮转、hook、context engine、tool loop、failover、usage 归并。
插件系统是一等公民。 src/plugins/loader.ts 和 src/plugins/registry.ts 不是简单动态导入，而是负责发现、校验、装载、缓存、隔离、注册多类能力。
渠道能力是"长生命周期运行时"，不是简单 webhook 适配器。 src/gateway/server-channels.ts 负责渠道账号级的启动、停止、重启退避、健康监控和运行快照。

4. 核心模块详解

4.1 Gateway 控制平面 (`src/gateway/`)

Gateway 不是单纯的 API 网关，而是系统编排器和控制面内核。

server.impl.ts 中的 startGatewayServer() 是全仓库最关键的编排点，负责把多个子系统装配起来：

读取并校验配置、执行 legacy 配置迁移
自动启用插件、激活 secrets 运行时快照
初始化插件注册表
启动 WebSocket / HTTP 服务
启动 Channel Manager（每个 channel account 是受管运行单元）
挂载 Gateway RPC 方法与事件广播
启动 cron、健康检查、发现服务、Tailscale、Control UI、插件 sidecars
配置热重载与优雅关闭

事件总线特征：Agent 事件广播给 WS 客户端，session transcript 增量广播，UI 通过 Gateway Snapshot + Event 增量同步。

关键文件	职责
`server.impl.ts`	总装配器
`server-methods.ts`	Gateway RPC 方法集合
`server-chat.ts`	Agent 事件到 Gateway 事件的桥接
`server-channels.ts`	Channel 生命周期管理（启动/停止/重连/退避）
`control-ui.ts`	控制台 UI 的 HTTP 暴露
`config-reload.ts`	配置热重载
`auth.ts` / `startup-auth.ts`	启动期与运行期鉴权

4.2 消息调度管道 (`src/auto-reply/`, `src/routing/`)

消息进入系统后的第一道处理链。

auto-reply 调度：

dispatch.ts → reply/dispatch-from-config.ts

复制代码

dispatch-from-config.ts 负责真正的消息分发：
- 入站去重
- session store 查询
- hook 触发
- conversation binding 检查
- route-reply 选择
- typing / TTS / channel delivery 策略
- 最终调用 `getReplyFromConfig` / agent 流程

规范化 inbound context、去重、建立 reply dispatcher
检查插件会话绑定（conversation-binding.ts）
运行前置 Hook、send policy、fast abort
最终决定走插件处理还是默认 Agent 流程

路由引擎 （resolve-route.ts，804 行）采用 8 级分层匹配：负责把渠道上下文映射到内部 session 模型。

复制代码

优先级 1: binding.peer       → 直接匹配对话对象
优先级 2: binding.peer.parent → 父线程继承
优先级 3: binding.guild+roles → 服务器+角色
优先级 4: binding.guild       → 服务器级别
优先级 5: binding.team        → Teams 团队
优先级 6: binding.account     → 账户级别
优先级 7: binding.channel     → 渠道级别
优先级 8: default             → 兜底默认代理

Session Key 格式：

复制代码

agent:{agentId}:main                          # 主会话
agent:{agentId}:{channel}:direct:{peerId}     # 私信会话
agent:{agentId}:{channel}:{peerKind}:{peerId} # 群组/频道会话

路由输出是 ResolvedAgentRoute，路由结果缓存使用 WeakMap（最多 4000 条），配置变更自动失效。

4.3 Agent 运行时 (`src/agents/`)

这是仓库里最大最复杂的模块 （470+ 文件），本质是一个有状态、有退化路径、有工具循环、有认证策略的运行框架。它不是把 prompt 直接丢给 SDK 然后拿结果返回

执行主线

两个核心入口：

agent-command.ts：应用层编排（读配置、解析 session、准备 workspace、选模型）

复制代码

- 加载配置与 session store
- 解析 agent/workspace
- 准备 auth profile store
- 准备 session manager
- 整理模型、thinking、verbose、send policy、skills snapshot
- 调用 `runEmbeddedPiAgent`
- 持久化 session 更新
- 交付结果到 outbound/delivery

pi-embedded-runner/run.ts：模型执行内核

复制代码

- lane/queue 调度
- 运行时插件加载
- workspace 决议
- model/provider resolve
- before_model_resolve / before_agent_start hooks
- auth profile 选择、失败标记、恢复
- context engine 初始化与调用
- run attempt 循环
- failover / backoff / compaction / usage 归并

执行内核的完整流程：

解析 workspace、确保 runtime plugins 已加载
选择 provider/model、解析 auth profile
执行 before-model / before-agent hooks
运行 context engine 组装 Prompt
发起一次或多次 attempt（带超时、限流、鉴权失败处理）
Profile 轮换和 fallback model 机制
Context overflow / compaction 处理
归并 usage、返回 payload

工具系统

工具被当成权限与能力系统管理，分为多个域：

域	工具
文件	read, write, edit, apply_patch
运行	exec, process
Web	web_search, web_fetch
记忆	memory_search, memory_get
会话	session, subagent
浏览器	browser_navigate, browser_click, ...
媒体	audio, image, video
系统	cron, gateway, nodes, messaging

安全边界与工具系统深度耦合：tool-policy*.ts + sandbox/* + tools-effective-inventory.ts。

子代理系统

多 Agent 协作是架构主轴之一，不是边缘功能：

子代理注册表与生命周期管理
Session 派生（main session → sub sessions）
Transcript 与工具结果保护
会话文件修复与一致性维护

4.4 上下文引擎 (`src/context-engine/`)

src/context-engine/index.ts 暴露的不是单一实现，而是注册与解析入口：

registerContextEngine
resolveContextEngine
listContextEngineIds
ensureContextEnginesInitialized

这说明 context engine 在架构上是可替换部件，核心或插件都能提供实现。

可插拔接口，负责消息历史的组装、摄取和压缩：

复制代码

interface ContextEngine {
  assemble(params: AssembleParams): Promise<AssembleResult>;  // 组装上下文
  ingest(params: IngestParams): Promise<IngestResult>;        // 摄取新消息
  compact(params: CompactParams): Promise<CompactResult>;     // 压缩历史
}

Prompt 不是静态模板，而是动态装配产物：

复制代码

base system prompt
+ agent-specific rules
+ skills prompt
+ memory usage instructions
+ hooks injected content
+ conversation history (token 预算控制)
+ current user message
+ prior tool results
= final model input

Session 模型: 从 routing、agent-command、transcript 相关代码看，Session 至少承担这些角色：

并发与 lane 的作用域
transcript 持久化容器
send policy / model override / auth override 的状态载体
与外部渠道对象的映射键
子代理与 reply-back 的组织单位

所以 session 是 OpenClaw 的运行态状态机，不只是聊天历史。

4.5 记忆系统 (`src/memory/`)

内嵌在运行时里的可降级检索子系统，不是独立数据库服务。

它既服务于 tool 调用，也服务于 prompt section 注入,可以通过 registry 与 prompt-section 进入 Agent Runtime.

知识库查询是模型驱动的工具调用（显式 RAG），不是每次强制全库拼接进 Prompt。

两个核心工具：

memory_search：对 MEMORY.md、memory/*.md、session transcript 做语义检索
memory_get：按路径和行范围精确读取

检索管道：

复制代码

文件/会话内容
  → 切块（chunk）
  → 生成 embedding（multilingual-e5-large / llama-text-embed-v2）
  → 写入 sqlite / sqlite-vec / FTS 索引
  → query 时执行 vector + keyword 混合检索
  → MMR 去重 + 时间衰减排序
  → 返回 snippet + citation

降级逻辑：

QMD backend 不可用 → 回退 builtin index
Embedding provider 不可用 → 退化为 FTS-only
Quota/429 出错 → 明确返回"不可用状态"给模型

4.6 插件系统 (`src/plugins/`, `extensions/`)

插件是一级架构构件，不是事后扩展。OpenClaw 通过插件把三类能力统一起来：

外部接入：渠道、HTTP route、CLI 命令
AI 能力：模型 provider、web search、media、memory
运行时行为：hook、context engine、tool、service

插件装载器（loader.ts）职责非常重：

发现插件 → 读取 manifest → 来源/优先级/覆盖关系判定
构建 runtime alias / Jiti loader → 校验配置 schema
按模式注册：full、setup-only、setup-runtime
支持激活型与快照型加载 → 缓存、诊断、错误归档

插件注册表（registry.ts）可注册的能力类型：

能力类型	说明
tool	工具
hook	钩子
channel	消息渠道
provider	AI 模型提供商
speech / media / image / web search provider	各类 AI 子能力
gateway method	Gateway RPC 方法
HTTP route	HTTP 路由
CLI command	命令行命令
service	后台服务
interactive handler	交互处理器
context engine	上下文引擎
memory prompt section	记忆 Prompt 段

4.7 渠道抽象层 (`src/channels/`)

轻量领域抽象层，不是所有渠道实现的存放地。真正的渠道实例通过已激活的插件注册表读取。

职责：

统一 channel id、别名、元信息
Allowlist / mention gating / command gating
线程绑定、目标解析、typing、reaction、status
与会话模型之间的映射

4.8 插件与渠道的关系

一个容易误解的点是：channels 和 plugins 谁是主、谁是辅？

源码显示两者关系是：

channels/ 提供统一的渠道抽象、约束与通用辅助
plugins/ 提供实际扩展装载与注册机制
server-channels.ts 则把已注册的 channel plugin 当作受管 runtime 来调度

也就是说：

复制代码

插件系统决定“可注册什么”
渠道系统决定“消息渠道按什么统一模型运行”
Gateway 决定“这些渠道实例如何被托管”

4.9 ACP 协议 (`src/acp/`)

src/acp/client.ts 表明 ACP 在 OpenClaw 里不是概念装饰，而是实际存在的控制协议客户端层，负责：

与子进程/外部代理进行 NDJSON 流通信
tool permission request
安全工具识别与自动批准边界
Windows 程序解析与环境处理

特性	值
格式	ndjson（每行一个 JSON）
通道	子进程 stdin/stdout
大小限制	2MB（防 DoS）
版本协商	PROTOCOL_VERSION 字段
幂等性	idempotencyKey 防重复处理

4.10配置系统 (`src/config/`)

OpenClaw 的复杂度很大程度来自"可配置平台"。这是一个配置驱动的平台型系统。

关键信号：

schema.base.generated.ts 很大 --- 配置 schema 是核心资产
io.ts 很大 --- 配置读写承担校验、快照、容错、红线控制
agent / session / gateway / channels / tools / sandbox / plugins 等配置切面完整

5. 单次问答完整处理流程

当用户发送一条消息时，系统内部的端到端处理链：

5.1 时序总览

复制代码

用户在渠道发消息
  → Channel Plugin 接收 inbound
  → auto-reply 规范化上下文 / 去重 / 建立 dispatcher
  → 检查 conversation binding / hooks / send policy / fast abort
  → resolve-route 解析 agentId + sessionKey
  → 检查 conversation binding 是否被插件接管
  → 若未接管，进入 agent-command
  → agent-command 读取配置 / session / workspace / model / skills
  → runEmbeddedPiAgent(): pi-embedded-runner 构建运行上下文
  → 构造 Prompt（system + skills + memory + history + 当前问题）
  → 调用大模型
  → 如果模型需要知识：
       → 调 memory_search / memory_get / web_search / web_fetch
       → 工具结果回注入模型继续推理
  → 得到最终 payload
  → 更新 transcript / session store / usage / model state
  → dispatcher / route-reply / outbound
  → 回发原渠道
  → Gateway / UI 同步事件与状态

5.2 详细 12 步流程

复制代码

STEP 1: 渠道适配器（src/channels/）
  • 各渠道 SDK 接收原始消息
  • 格式转换为内部统一格式（channel, peer, sender, text, attachments）

STEP 2: 路由引擎（src/routing/）
  • 8 级分层匹配确定 agentId + sessionKey
  • 路由缓存加速（WeakMap，最多 4000 条）

STEP 3: 插件会话绑定检查
  • 某些插件可声明"这个对话后续由我接管"
  • 绑定存在 → 优先路由给对应插件
  • 插件缺失或不处理 → 回退默认 Agent 流程

STEP 4: 预处理 Hook 与策略
  • before_dispatch hook
  • send policy 检查
  • fast abort（停止命令等）
  • typing policy

STEP 5: Agent 运行上下文准备
  • agent-command.ts 读取配置、session、transcript、workspace
  • 准备技能快照、解析 model override
  • 注册 agent run 上下文

STEP 6: 上下文组装
  • context engine 初始化
  • 组装 system prompt + skills + memory instructions + hooks + history
  • token 预算控制

STEP 7: 模型选择与认证
  • 综合 agent 默认模型、session override、命令 override、auth profile
  • Provider/model normalize、context window 校验
  • Auth profile 轮转准备

STEP 8: 大模型调用
  • 流式调用 LLM API
  • 最多 32-160 次重试迭代
  • 失败处理：context overflow → 压缩重试 / rate limit → 换 profile / auth error → 标记故障

STEP 9: 工具调用循环
  • while (stopReason === "tool_calls") {
  •   权限检查（安全工具自动批准，危险工具请求用户）
  •   执行工具（浏览器/代码/搜索/文件等）
  •   工具结果回注入模型
  •   再次调用模型
  • }

STEP 10: 结果后处理
  • 提取文本块和思考块
  • 工具结果超大截断
  • ingest 新消息到上下文引擎（持久化 + 向量化）
  • 后台异步向量化（batchEmbed，不阻塞回复）
  • afterTurn 判断是否需要压缩

STEP 11: 回复构造
  • 按渠道字符限制分块（Markdown 感知）
  • 规范化为 NormalizedOutboundPayload

STEP 12: 发送回渠道
  • 适配器顺序发送每个分块
  • 追加 assistant 消息到会话 transcript
  • 触发 messageSent plugin hooks
  • 可选 DeliveryMirror 镜像
  • Gateway event bus 广播给 UI 和其他客户端

5.3 时序图（Mermaid）

复制代码

sequenceDiagram
    participant User as 用户
    participant Channel as 渠道插件
    participant Dispatch as auto-reply
    participant Routing as 路由引擎
    participant Binding as 插件绑定
    participant AgentCmd as agent-command
    participant Runner as pi-embedded-runner
    participant LLM as 大模型
    participant Tools as 工具运行时
    participant Memory as 记忆系统
    participant Reply as 回复投递
    participant GW as Gateway/UI

    User->>Channel: 发送问题
    Channel->>Dispatch: 传入 inbound context
    Dispatch->>Dispatch: 去重 / 规范化
    Dispatch->>Binding: 检查会话绑定

    alt 插件已绑定
        Binding-->>Reply: 插件结果
        Reply-->>User: 返回
    else 默认 Agent 流程
        Dispatch->>Routing: 解析 agentId + sessionKey
        Routing-->>AgentCmd: route
        AgentCmd->>AgentCmd: 配置/session/workspace/skills
        AgentCmd->>Runner: 进入模型执行
        Runner->>Runner: 构建 Prompt
        Runner->>LLM: 发送

        loop 工具调用循环
            LLM->>Tools: 调用工具
            Tools->>Memory: memory_search/get
            Tools-->>Runner: tool result
            Runner->>LLM: 继续推理
        end

        LLM-->>Runner: 最终回复
        Runner-->>AgentCmd: payload + meta
        AgentCmd->>Reply: 交付回复
        Reply-->>User: 发回原渠道
        Reply->>GW: 广播事件
    end

5.4 关键路径性能

复制代码

阻塞路径（决定用户感知延迟）：
  消息接收 → 路由 → 上下文组装 → 模型调用 → 回复发送
  ≈ 1ms  + 0.5ms + 50-200ms +  1-30s  + 1-50ms

异步路径（不阻塞回复）：
  • 向量化新消息（batchEmbed）
  • 上下文压缩（compact）
  • 交付队列记录
  • 镜像发送

6. 知识获取三层体系

OpenClaw 的知识获取不是预处理黑盒，而是模型在推理时显式触发的工具调用：

层级	工具	数据源	特点
本地长期记忆	`memory_search` / `memory_get`	MEMORY.md、memory/*.md	向量+BM25 混合检索，可降级
当前会话	context engine `assemble()`	session transcript	token 预算控制，自动压缩
外部 Web	`web_search` / `web_fetch`	互联网	搜索引擎 + 网页抓取

7. 模型选择与认证轮转

7.1 模型选择策略

系统综合以下来源决定最终模型：

Agent 默认模型
Session 存储的 override
本次命令显式 override
Auth profile 约束
Failover 配置

7.2 认证轮转

复制代码

需要调用模型
  → resolveAuthProfile(provider)
  → 获取可用认证配置列表（过滤冷却期）
  → 按优先级排序，选择第一个可用
  → 失败时：标记故障 → 进入冷却期 → 切换下一个
  → 成功时：更新使用统计 → 重置故障计数

支持按任务复杂度路由不同价格模型：

复制代码

简单问候  → Haiku   （低成本）
代码编写  → Sonnet  （中等成本）
复杂推理  → Opus    （高成本）
重复任务  → Ollama  （本地，免费）

8. 安全架构

8.1 工具权限系统

复制代码

危险工具（需明确授权）：exec, shell_execute, file_write, file_delete, network_bind
安全工具（自动批准）：  read, search, web_search

权限请求流：Agent → requestPermission → 用户确认 → 执行/拒绝

8.2 多层安全措施

措施	实现
工具策略	tool-policy.ts --- 白名单/黑名单/审批流
沙箱隔离	代码执行和浏览器操作在独立 Docker 容器
SSRF 防护	URL 规范化，阻止访问本地地址
认证隔离	每个 auth profile 独立轮转，故障冷却期
密钥加密	认证存储加密，不明文存储
Origin 校验	Gateway HTTP 请求来源校验
速率限制	Gateway 级别限流

9. 多媒体子系统

9.1 音频

方向	提供商
ASR（音频→文本）	Deepgram, OpenAI Whisper, Ollama（本地）
TTS（文本→语音）	ElevenLabs, Google TTS, Sherpa ONNX（本地）

9.2 视觉/文档

图像识别：Claude Vision, GPT-4V
视频帧提取
PDF 解析：pdfjs-dist
文档 OCR
链接预览：Firecrawl

9.3 浏览器自动化

基于 Playwright 的真实浏览器操作（非描述性生成）：

页面导航、表单填充、按钮点击、截图
状态机：idle → navigating → acting
超时管理和错误恢复

10. 部署形态

10.1 单机部署

复制代码

用户机器（macOS/Linux/Windows）
└─→ OpenClaw Gateway（Node.js 进程）
    ├─→ 配置文件（~/.config/openclaw/）
    ├─→ 会话存储（~/.local/share/openclaw/）
    └─→ WebSocket 服务器（localhost:18789）

10.2 容器部署

复制代码

Docker / VM / Kubernetes
└─→ OpenClaw Gateway Container
    ├─→ Dockerfile（主应用）
    ├─→ Dockerfile.sandbox（执行沙箱）
    ├─→ Dockerfile.sandbox-browser（浏览器沙箱）
    └─→ 环境变量注入 API Key 和认证信息

10.3 多端拓扑

复制代码

Gateway（控制平面）
├─→ Web Control UI（Lit + Vite 实时控制台）
├─→ iOS App（SwiftUI，承担语音/Canvas/系统能力）
├─→ Android App（Jetpack Compose）
├─→ macOS App（Swift）
└─→ CLI

原生端不只是"壳"，还承担节点、语音、Canvas、系统能力暴露。整个系统存在 Gateway host + device nodes 的拓扑。

11. 核心设计模式

模式	体现
配置驱动	配置 schema 是核心资产；行为通过配置而非硬编码
不可变数据	所有状态更新创建新对象
依赖注入	AgentScope 通过本地存储提供执行上下文
仓库模式	SessionRepository 等标准 CRUD 接口
事件驱动	Gateway 事件总线、agent/session/presence 事件
插件优先	核心能力通过插件注入而非硬编码
显式 RAG	模型主动决定是否调用知识库，而非隐式预处理
可降级设计	向量搜索 → FTS → 不可用状态，多层降级

12. 第三方依赖总览

AI 模型提供商

openai, @anthropic-ai/sdk, google-cloud-vertexai, groq-sdk, mistralai, ollama, node-llama-cpp

消息渠道

whatsapp-web.js, telegraf, slack-bolt, discord.js, matrix-js-sdk, @microsoft/teams-js, mattermost-sdk

向量与搜索

sqlite-vec, lancedb, pinecone-client, voyage-ai

工具与自动化

playwright, deepgram-sdk, sharp, pdfjs-dist

开发工具

vitest, tsx, oxlint, prettier

13. 构建与开发

复制代码

pnpm build         # TypeScript 编译
pnpm test          # 单元测试（vitest）
pnpm test:e2e      # 端到端测试
pnpm dev           # 开发模式
pnpm lint          # 代码检查（Oxlint）
pnpm docker:build  # Docker 镜像构建

TypeScript 配置：target: es2023, module: NodeNext, strict: true, 纯 ESM。

14. 与 Claude 的定位区别

维度	Claude	OpenClaw
本质	高质量 AI 模型 + 产品体验	AI 助手运行平台 / 宿主系统
渠道	官方 Web + API	20+ 通讯渠道统一接入
记忆	上下文窗口内	向量数据库永久保存 + 语义检索
工具	受限沙箱	真实浏览器 + 完整文件系统 + 本地服务
定时任务	不支持	Cron 调度，主动推送
多 API Key	不支持	认证轮转 + 成本路由
会话隔离	平台管理	用户可控的 sessionKey 体系
部署	Anthropic 托管	用户自部署，完全可控
扩展	MCP	完整插件系统（tool/hook/channel/provider/route/...）

两者是互补关系：OpenClaw 把 Claude 从"聊天框"扩展到"真实基础设施代理"。

OpenClaw 更适合：多渠道接入、系统集成、长期运行、自动化、自定义部署 Claude 更适合：单次推理质量、开箱即用、零配置体验

15. 架构特征总结

控制平面中心化：Gateway 是事件、会话、配置、客户端连接的中心
执行平面模块化：Agent Runtime 负责模型、工具、session、sandbox、skills
扩展优先：Plugin 是一级公民，不是附属机制
渠道抽象统一：不同消息平台通过 channel plugin 接入统一运行模型
配置驱动：行为通过配置 schema 而非硬编码决定
状态驱动：session、runtime snapshot、health、presence、approval 都有显式状态结构
安全边界显式：tool policy、sandbox、approval、auth、origin、rate limit 架构内建
可降级设计：记忆、模型、认证均有完整降级链路
多端控制：CLI、Web UI、原生 app 共享 Gateway 控制面

16. 源码阅读推荐顺序

如果要深入理解系统，建议按以下顺序阅读：

src/entry.ts --- CLI 真正入口
src/gateway/server.impl.ts --- 系统编排器（最关键）
src/gateway/server-channels.ts --- Channel 生命周期管理
src/auto-reply/dispatch.ts --- 消息调度入口
src/routing/resolve-route.ts --- 路由引擎
src/plugins/loader.ts --- 插件装载器
src/plugins/registry.ts --- 插件注册表
src/agents/agent-command.ts --- Agent 应用层编排
src/agents/pi-embedded-runner/run.ts --- 模型执行内核
src/agents/tool-catalog.ts --- 工具目录
src/memory/search-manager.ts --- 记忆检索
ui/src/ui/app.ts --- Web 控制台入口

先建立"系统编排视角"，再进入单个子系统细节。

复制代码

启动链路可简化为：
src/entry.ts
  -> src/cli/run-main.js
  -> gateway 命令
  -> src/gateway/server.ts
  -> src/gateway/server.impl.ts:startGatewayServer()

OpenClaw 架构文档

1. 项目定位

2. 工程组织

3. 系统六层架构

4. 核心模块详解

4.1 Gateway 控制平面 (src/gateway/)

4.2 消息调度管道 (src/auto-reply/, src/routing/)

4.3 Agent 运行时 (src/agents/)

执行主线

工具系统

子代理系统

4.4 上下文引擎 (src/context-engine/)

4.5 记忆系统 (src/memory/)

4.6 插件系统 (src/plugins/, extensions/)

4.7 渠道抽象层 (src/channels/)

4.8 插件与渠道的关系

4.9 ACP 协议 (src/acp/)

4.10配置系统 (src/config/)

5. 单次问答完整处理流程

5.1 时序总览

5.2 详细 12 步流程

5.3 时序图（Mermaid）

5.4 关键路径性能

6. 知识获取三层体系

7. 模型选择与认证轮转

7.1 模型选择策略

7.2 认证轮转

8. 安全架构

8.1 工具权限系统

8.2 多层安全措施

9. 多媒体子系统

9.1 音频

9.2 视觉/文档

9.3 浏览器自动化

10. 部署形态

10.1 单机部署

10.2 容器部署

10.3 多端拓扑

11. 核心设计模式

12. 第三方依赖总览

AI 模型提供商

消息渠道

向量与搜索

工具与自动化

开发工具

13. 构建与开发

14. 与 Claude 的定位区别

15. 架构特征总结

16. 源码阅读推荐顺序

4.1 Gateway 控制平面 (`src/gateway/`)

4.2 消息调度管道 (`src/auto-reply/`, `src/routing/`)

4.3 Agent 运行时 (`src/agents/`)

4.4 上下文引擎 (`src/context-engine/`)

4.5 记忆系统 (`src/memory/`)

4.6 插件系统 (`src/plugins/`, `extensions/`)

4.7 渠道抽象层 (`src/channels/`)

4.9 ACP 协议 (`src/acp/`)

4.10配置系统 (`src/config/`)