第一章 · 概述与架构

1.1 OpenClaw 是什么？

OpenClaw 是一个开源 (MIT) 的多通道 AI 网关平台，它充当个人 AI 代理的"控制平面"——在多个消息通道（Telegram、WhatsApp、Discord、Slack、Matrix、iMessage 等）和多个 AI 模型提供商（Anthropic Claude、OpenAI GPT、Google Gemini、AWS Bedrock、OpenRouter、本地模型等）之间架起桥梁。

用一句话概括：OpenClaw 让你可以在任何聊天应用中、使用任何 AI 模型、带着自定义工具和记忆来执行任务。

1.1.1 核心价值

┌──────────────────────────────────────────────────────────┐
│                    你（操作用户）                            │
│   Telegram / WhatsApp / Discord / Slack / iMessage ...    │
└─────────────┬──────────────────────────┬─────────────────┘
              │                          │
              ▼                          ▼
    ┌─────────────────┐        ┌─────────────────┐
    │   Agent A        │        │   Agent B        │
    │   身份：编程助手   │        │   身份：日常助理   │
    │   模型：Claude     │        │   模型：GPT       │
    │   工具：exec, fs   │        │   工具：web, note │
    └────────┬─────────┘        └────────┬─────────┘
             │                           │
             ▼                           ▼
    ┌──────────────────────────────────────────────┐
    │             OpenClaw Gateway                  │
    │    Express + WebSocket + Agent Runtime        │
    └──────────────────────────────────────────────┘

关键特性：

• 多模型支持：Anthropic Claude（原生 + Vertex）、OpenAI GPT（原生 + Codex）、Google Gemini、AWS Bedrock、OpenRouter、DeepSeek、LM Studio、Ollama 等
• 多通道支持：Telegram、WhatsApp、Discord、Slack、Matrix、iMessage、LINE、Feishu、Microsoft Teams、Nostr、Twitch 等 20+ 平台
• 插件化架构：50+ 扩展插件，通过严格的 SDK 边界整合
• Agent 系统：可配置的多 Agent，各自拥有独立身份、工具策略、记忆和工作区
• 安全沙箱：Docker 隔离执行，命令审批机制
• 原生客户端：macOS (SwiftUI)、iOS (SwiftUI)、Android (Kotlin)

1.1.2 技术栈

层级	技术选型
运行环境	Node.js 22.14+
语言	TypeScript (ESM, strict mode)
包管理	pnpm 10.x (workspace monorepo)
构建工具	tsdown (TypeScript bundler)
测试框架	Vitest (multi-project, 最多 16 workers)
HTTP 服务	Express 5.x
实时通信	WebSocket (ws 8.x)
CLI 框架	Commander.js 14.x
模式校验	Zod 4.x / TypeBox 1.x
前端 UI	Lit (Web Components)
原生应用	SwiftUI (macOS/iOS) / Kotlin (Android)
容器化	Docker (multi-stage, SHA256 pinned)

1.2 仓库全景

openclaw/
├── src/                          # 核心 TypeScript 源码
│   ├── entry.ts                  # 主入口（CLI 启动、命令分发）
│   ├── index.ts                  # 公共 API 导出
│   ├── library.ts                # 延迟加载外观
│   ├── cli/                      # CLI 命令框架 (50+ 文件)
│   ├── gateway/                  # 网关服务 (100+ 文件)
│   │   └── protocol/             # 协议定义 (Zod/TypeBox schemas)
│   ├── agents/                   # Agent 运行时 (100+ 文件)
│   ├── plugin-sdk/               # 公共插件 SDK (100+ 文件)
│   ├── plugins/                  # 插件加载器/注册表 (50+ 文件)
│   ├── channels/                 # 通道抽象层 (50+ 文件)
│   ├── config/                   # 配置管理
│   ├── tools/                    # 工具系统
│   ├── process/                  # 进程执行
│   ├── infra/                    # 基础设施工具
│   ├── terminal/                 # 终端 UI
│   ├── logging/                  # 结构化日志
│   ├── auto-reply/               # 自动回复引擎
│   └── canvas-host/              # Canvas/A2UI 宿主
├── extensions/                   # 50+ 扩展插件
│   ├── telegram/                 # Telegram Bot 插件
│   ├── whatsapp/                 # WhatsApp 插件
│   ├── discord/                  # Discord 插件
│   ├── slack/                    # Slack 插件
│   ├── anthropic/                # Anthropic 模型提供商
│   ├── openai/                   # OpenAI 模型提供商
│   └── ...                       # 更多插件
├── ui/                           # Control UI (Lit Web Components)
├── apps/                         # 原生应用
│   ├── macos/                    # macOS 应用 (SwiftUI, 180+ 文件)
│   ├── ios/                      # iOS 应用 (SwiftUI)
│   └── android/                  # Android 应用 (Kotlin)
├── packages/                     # 额外工作区包
├── skills/                       # Agent 技能定义 (50+ 技能)
├── docs/                         # 文档站点 (Mintlify/MDX)
├── scripts/                      # 构建/CI/维护脚本
├── test/                         # 集成/E2E 测试
├── security/                     # OpenGrep 安全规则
├── patches/                      # pnpm 依赖补丁
├── vendor/                       # 第三方依赖 (A2UI)
├── docker-compose.yml            # Docker Compose 配置
├── Dockerfile                    # 多阶段 Docker 构建
├── fly.toml                      # Fly.io 部署配置
├── render.yaml                   # Render.com 部署配置
├── package.json                  # 根工作区配置
├── pnpm-workspace.yaml           # pnpm 工作区定义
├── tsconfig.json                 # TypeScript 根配置
├── tsdown.config.ts              # tsdown 打包配置
├── vitest.config.ts              # Vitest 测试配置
├── openclaw.mjs                  # Node.js 启动器
└── Makefile                      # 构建别名

1.3 分层架构

OpenClaw 采用严格的分层架构，每一层都有明确的职责边界：

┌─────────────────────────────────────────────────────────┐
│ Layer 6: 消息通道                                        │
│ Telegram, WhatsApp, Discord, Slack, Matrix, iMessage...  │
├─────────────────────────────────────────────────────────┤
│ Layer 5: 插件系统 (extensions/)                          │
│ 通道插件 + 模型提供商插件                                  │
│ 通过 plugin-sdk 契约接入核心                               │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Plugin SDK 边界 (src/plugin-sdk/)              │
│ 插件可导入的公开 API 集合 (80+ 子路径)                      │
│ 运行时助手、审批流、通道抽象、媒体处理                        │
├─────────────────────────────────────────────────────────┤
│ Layer 3: 核心网关 (src/gateway/)                          │
│ Express HTTP 服务器                                       │
│ WebSocket 实时双向通信                                     │
│ Control UI, 认证, 健康检查                                  │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Agent 运行时 (src/agents/)                       │
│ AI 模型传输层 (Anthropic / OpenAI)                         │
│ 工具执行, 子代理 (ACP), 会话管理, 工作区                      │
├─────────────────────────────────────────────────────────┤
│ Layer 1: CLI (src/cli/)                                  │
│ Commander.js 命令框架                                      │
│ 启动引导, 配置解析, Profile 管理                             │
├─────────────────────────────────────────────────────────┤
│ Layer 0: 基础设施                                          │
│ Node.js 22+, Express, WebSocket, Docker, Fly.io           │
└─────────────────────────────────────────────────────────┘

1.3.1 信任模型

OpenClaw 的信任模型是 “一个操作用户，多个 Agent”：

• 网关不是多租户平台
• 所有经过认证的调用者都是受信任的操作用户
• 安全边界来自于：主机/配置信任、身份认证、工具策略、沙箱隔离 (Docker)、命令审批

1.4 核心设计模式

1.4.1 延迟加载 (.runtime 后缀约定)

重型运行时模块使用 *.runtime.ts 命名约定。静态导入仅限于轻量级契约文件，动态导入通过专用的运行时子路径进行。

模块加载策略：
  - 热路径：仅导入轻量契约文件（类型定义、常量和 schema）
  - 冷启动：按需动态导入重型运行时逻辑
  - 结果：降低启动成本，提高响应速度

1.4.2 描述符优先的工具系统

工具使用平台级的描述符规划器进行可见性和可用性检查。插件工具描述符在规划时缓存，在执行时实时加载。

流程：规划时 → 缓存工具描述符 → 执行时 → 加载并调用

1.4.3 Manifest 优先的控制平面

插件注册、通道目录、提供商目录和能力元数据全部使用 manifest 驱动声明。这允许系统在不加载插件代码的情况下进行元数据级控制。

1.4.4 网关/节点模式

网关（控制平面）将路由与执行分离：

• Gateway: 路由消息、管理会话、协调工具
• Node: 执行扩展，与网关配对

1.4.5 ACP 协议 (Agent Client Protocol)

子代理生成使用 @agentclientprotocol/sdk，支持：

• 子代理委托
• 沙箱执行
• 工具路由

1.5 核心依赖速览

包名	版本	用途
@anthropic-ai/sdk	0.92.0	Anthropic Claude API
openai	6.35.0	OpenAI API
@google/genai	1.51.0	Google Gemini API
express	5.2.1	HTTP 服务器
ws	8.20.0	WebSocket 通信
commander	14.0.3	CLI 参数解析
zod	4.4.1	Schema 验证
typebox	1.1.37	JSON Schema 生成
@agentclientprotocol/sdk	0.21.0	子代理协议
@modelcontextprotocol/sdk	1.29.0	MCP 工具集成
grammy	1.42.0	Telegram Bot 框架
playwright-core	1.59.1	浏览器自动化

---

下章预告：启动流程 —— 深入 openclaw.mjs 和 entry.ts，看 OpenClaw 如何从敲下命令到运行起来。