OpenClaw 源代码学习笔记

cosmoslife

467人浏览 · 2026-04-10 15:56:52

cosmoslife · 2026-04-10 15:56:52 发布

OpenClaw 源代码学习笔记

学习日期：2026年4月2日项目版本：2026.4.2 学习者：OpenClaw AI Assistant

1. 项目概述

1.1 项目定位

OpenClaw 是一个个人 AI 助手平台，具有以下特点：

多通道支持：支持 WhatsApp、Telegram、Slack、Discord、Signal、飞书等 20+ 消息平台
本地优先：Gateway 作为控制平面运行在用户自己的设备上
可扩展：插件系统支持自定义通道、工具和功能
跨平台：支持 macOS、Linux、Windows (WSL2)、iOS、Android

1.2 技术栈

{ "runtime": "Node.js 24+ (推荐) 或 22.16+", "language": "TypeScript 6.0+", "build": "tsdown (基于 esbuild)", "packageManager": "pnpm 10+", "webFramework": "Hono (轻量级 HTTP 框架)", "websocket": "ws (WebSocket 实现)", "ai": "@mariozechner/pi-ai (Pi Agent Runtime)" }

1.3 项目结构

C:\work\openclaw\ ├── src/ # 源代码主目录 │ ├── gateway/ # Gateway 核心服务器 │ ├── agents/ # AI Agent 运行时 │ ├── channels/ # 通道插件 (消息平台集成) │ ├── plugins/ # 插件系统 │ ├── config/ # 配置管理 │ ├── auto-reply/ # 消息回复处理 │ ├── sessions/ # 会话管理 │ ├── plugin-sdk/ # 插件 SDK │ ├── infra/ # 基础设施 (事件、心跳等) │ ├── hooks/ # 钩子系统 │ ├── tts/ # 语音合成 │ ├── secrets/ # 密钥管理 │ └── ... ├── extensions/ # 扩展插件目录 ├── apps/ # 移动应用 (iOS/Android/macOS) ├── docs/ # 文档 ├── skills/ # 技能包 ├── ui/ # Web UI (Lit + TypeScript) └── test/ # 测试代码

2. 架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────┐ │ 消息通道层 (Channels) │ │ WhatsApp | Telegram | Slack | Discord | Signal | 飞书 ... │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Gateway (控制平面) │ │ ┌─────────────┬──────────────┬──────────────────────────┐ │ │ │ WebSocket │ HTTP Server │ Canvas Host Server │ │ │ │ (主通信) │ (API/UI) │ (可视化工作区) │ │ │ └─────────────┴──────────────┴──────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 会话管理 (Sessions) │ │ │ └──────────────────────────────────────────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Pi Agent Runtime (AI 引擎) │ │ ┌──────────────┬──────────────┬────────────────────────┐ │ │ │ Model Layer │ Tool System │ Context Management │ │ │ │ (模型调用) │ (工具调用) │ (上下文管理) │ │ │ └──────────────┴──────────────┴────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘

2.2 核心设计理念

Gateway 作为控制平面：所有通信都通过 Gateway 进行，实现统一管理
插件化架构：通道、工具、钩子都是插件，可动态加载
会话隔离：每个会话独立管理上下文和历史
本地优先：数据存储在本地，保护隐私

2.3 Gateway 启动流程

// src/gateway/server.impl.ts export async function startGatewayServer( port = 18789, opts: GatewayServerOptions = {}, ): Promise<GatewayServer> { // 1. 加载配置 let configSnapshot = await readConfigFileSnapshot(); // 2. 迁移旧配置 if (configSnapshot.legacyIssues.length > 0) { const { config: migrated } = migrateLegacyConfig(configSnapshot.parsed); await writeConfigFile(migrated); } // 3. 激活密钥快照 const prepared = await prepareSecretsRuntimeSnapshot({ config }); activateSecretsRuntimeSnapshot(prepared); // 4. 加载启动插件 const { pluginRegistry } = loadGatewayStartupPlugins({ cfg, workspaceDir, log, coreGatewayHandlers, baseMethods, pluginIds: startupPluginIds, }); // 5. 创建运行时状态 const { httpServer, wss, clients, broadcast, canvasHost, } = await createGatewayRuntimeState({...}); // 6. 启动服务发现 (Bonjour/mDNS) const discovery = await startGatewayDiscovery({...}); // 7. 启动 Tailscale 暴露 (可选) const tailscaleCleanup = await startGatewayTailscaleExposure({...}); // 8. 注册 WebSocket 处理器 attachGatewayWsHandlers({ wss, clients, gatewayMethods, events: GATEWAY_EVENTS, broadcast, context: gatewayRequestContext, }); // 9. 启动通道 await startGatewaySidecars({...}); // 10. 启动配置热重载 configReloader = startGatewayConfigReloader({...}); return { close }; }

3. 核心模块详解

3.1 Gateway 模块

职责：作为整个系统的控制平面，管理所有通信和状态

核心组件：

3.1.1 WebSocket Server

// src/gateway/server-runtime-state.ts const wss = new WebSocket.Server({ server: httpServer, path: "/ws", maxPayload: 100 * 1024 * 1024, // 100MB });

3.1.2 Gateway Methods (API 方法)

// src/gateway/server-methods.ts export const coreGatewayHandlers: GatewayRequestHandlers = { ...connectHandlers, // 连接管理 ...healthHandlers, // 健康检查 ...channelsHandlers, // 通道管理 ...chatHandlers, // 聊天处理 ...cronHandlers, // 定时任务 ...deviceHandlers, // 设备管理 ...modelsHandlers, // 模型管理 ...configHandlers, // 配置管理 ...sessionsHandlers, // 会话管理 ...toolsCatalogHandlers, // 工具目录 ...skillsHandlers, // 技能管理 ...agentHandlers, // Agent 管理 ...agentsHandlers, // 多 Agent 管理 };

3.1.3 请求处理流程

export async function handleGatewayRequest(opts: GatewayRequestOptions) { const { req, respond, client, context } = opts; // 1. 授权检查 const authError = authorizeGatewayMethod(req.method, client); if (authError) { respond(false, undefined, authError); return; } // 2. 速率限制 if (CONTROL_PLANE_WRITE_METHODS.has(req.method)) { const budget = consumeControlPlaneWriteBudget({ client }); if (!budget.allowed) { respond(false, undefined, rateLimitError); return; } } // 3. 路由到处理器 const handler = coreGatewayHandlers[req.method]; await handler({ req, params, client, respond, context }); }

3.2 Agents 模块

职责：管理 AI Agent 的运行时，包括模型选择、工具调用、上下文管理

核心概念：

3.2.1 Agent 运行时

// 使用 Pi Agent Runtime import { runEmbeddedPiAgent } from "./agents/pi-embedded.js"; // Agent 运行参数 interface AgentRunParams { sessionKey: string; // 会话标识 model: string; // 模型 ID messages: Message[]; // 消息历史 tools: AgentTool[]; // 可用工具 systemPrompt: string; // 系统提示词 thinkLevel?: ThinkLevel; // 思考级别 }

3.2.2 模型选择

// src/agents/model-selection.ts // 默认模型配置 export const DEFAULT_MODEL = "claude-sonnet-4-6"; export const DEFAULT_PROVIDER = "anthropic"; // 模型选择逻辑 function resolveModelSelection(config: OpenClawConfig) { // 1. 优先使用配置中的模型 // 2. 考虑降级和故障转移 // 3. 应用模型别名 }

3.2.3 工具系统

// src/agents/tools/common.ts export type AnyAgentTool = { name: string; // 工具名称 description: string; // 工具描述 input_schema: object; // JSON Schema execute: (params: any) => Promise<any>; // 执行函数 }; // 工具分类 const toolCategories = [ "file", // 文件操作 (read, write, edit) "exec", // 命令执行 (bash, process) "web", // 网络操作 (web_search, web_fetch) "browser", // 浏览器控制 "canvas", // Canvas 操作 "sessions", // 会话管理 "message", // 消息发送 "nodes", // 节点控制 ];

3.3 Channels 模块

职责：集成各种消息平台，处理消息的接收和发送

通道插件结构：

// src/channels/plugins/types.ts export type ChannelPlugin = { id: ChannelId; // 通道标识 (如 "telegram", "whatsapp") gatewayMethods?: string[]; // 提供的 Gateway 方法 setup?: ChannelSetupAdapter; // 设置向导 login?: ChannelAuthAdapter; // 登录流程 outbound?: ChannelOutboundAdapter; // 发送消息 inbound?: ChannelInboundAdapter; // 接收消息 capabilities: ChannelCapabilities; // 能力描述 // 适配器集合 adapters: { messaging?: ChannelMessagingAdapter; threading?: ChannelThreadingAdapter; group?: ChannelGroupAdapter; directory?: ChannelDirectoryAdapter; // ... }; };

已支持的通道：

// src/channels/plugins/registry.ts export function listChannelPlugins(): ChannelPlugin[] { return [ "telegram", // Telegram Bot API "whatsapp", // WhatsApp (Baileys) "slack", // Slack Bolt "discord", // Discord.js "signal", // Signal CLI "feishu", // 飞书 "googlechat", // Google Chat "msteams", // Microsoft Teams "matrix", // Matrix "irc", // IRC "line", // LINE "mattermost", // Mattermost "bluebubbles", // iMessage (BlueBubbles) "nostr", // Nostr "twitch", // Twitch "zalo", // Zalo "wechat", // 微信 (插件) // ... ]; }

3.4 Plugins 模块

职责：提供插件运行时，支持扩展功能

插件类型：

// src/plugins/types.ts export type PluginKind = | "memory" // 记忆引擎 | "context-engine" // 上下文引擎 | "channel" // 通道插件 | "provider" // 模型提供商 | "speech" // 语音合成 | "cli-backend"; // CLI 后端 export type OpenClawPluginApi = { // 配置模式 configSchema?: OpenClawPluginConfigSchema; // 工具工厂 tools?: OpenClawPluginToolFactory; // 钩子 hooks?: InternalHookHandler; // 生命周期 register?: (runtime: PluginRuntime) => Promise<void>; start?: () => Promise<void>; stop?: () => Promise<void>; };

插件运行时：

// src/plugins/runtime/types.ts export type PluginRuntime = { // 日志 logger: RuntimeLogger; // 子 Agent 运行 runSubagent: (params: SubagentRunParams) => Promise<SubagentRunResult>; // 配置访问 getConfig: () => OpenClawConfig; // 工具注册 registerTool: (tool: AnyAgentTool) => void; // 钩子注册 registerHook: (hook: HookEntry) => void; // 事件发送 sendEvent: (event: string, payload: any) => void; };

4. 关键数据结构

4.1 OpenClawConfig (配置对象)

// src/config/types.ts export type OpenClawConfig = { // Agent 配置 agent?: { model?: string; // 默认模型 systemPrompt?: string; // 系统提示词 thinking?: ThinkingLevel; // 思考级别 timeout?: number; // 超时时间 }; // Agents 配置 (多 Agent) agents?: { defaults?: AgentDefaults; profiles?: Record<string, AgentProfile>; }; // Gateway 配置 gateway?: { port?: number; // 端口 (默认 18789) bind?: "loopback" | "lan" | "tailnet" | "auto"; auth?: GatewayAuthConfig; // 认证配置 tls?: GatewayTlsConfig; // TLS 配置 controlUi?: { enabled?: boolean; allowedOrigins?: string[]; }; }; // 通道配置 channels?: { telegram?: TelegramConfig; whatsapp?: WhatsAppConfig; slack?: SlackConfig; discord?: DiscordConfig; feishu?: FeishuConfig; // ... }; // 模型配置 models?: { providers?: Record<string, ModelProviderConfig>; aliases?: Record<string, string>; defaults?: ModelDefaults; }; // 插件配置 plugins?: { installs?: Record<string, PluginInstall>; }; // 技能配置 skills?: { bundled?: string[]; managed?: string[]; }; // 钩子配置 hooks?: HookEntry[]; // 密钥配置 secrets?: { defaults?: SecretDefaults; }; };

4.2 Session (会话对象)

// 会话数据 export interface SessionData { sessionKey: string; // 会话标识 sessionId: string; // 会话 UUID kind: "main" | "group" | "channel" | "subagent"; // 模型信息 modelProvider?: string; model?: string; // Token 统计 inputTokens: number; outputTokens: number; totalTokens: number; estimatedCostUsd?: number; // 状态 status: "active" | "idle" | "ended"; startedAt: number; updatedAt: number; // 通道信息 channel?: string; chatType?: "direct" | "group"; subject?: string; // 群组主题 // 配置 thinkingLevel?: string; verboseLevel?: number; elevatedLevel?: string; sendPolicy?: string; // 层级关系 parentSessionKey?: string; childSessions?: string[]; spawnDepth?: number; // 生成深度 // 交付上下文 deliveryContext?: DeliveryContext;

// 交付上下文 deliveryContext?: DeliveryContext;

// 标签 label?: string; displayName?: string;

// 上下文管理 contextTokens?: number; compactedAt?: number; }

// 交付上下文 - 消息应该发送到哪里 export interface DeliveryContext { channel: string; // 目标通道 accountId?: string; // 账户 ID to?: string; // 接收者标识

// 回复引用 replyToTag?: boolean; threadId?: string; // 线程 ID

// 消息类型 chatType?: "direct" | "group"; }

### 4.3 Message (消息对象) ```typescript // AI 消息格式 export interface AgentMessage { role: "user" | "assistant" | "system" | "tool"; content: string | Array<ContentBlock>; // 工具调用 (assistant -> tool) tool_calls?: ToolCall[]; // 工具响应 (tool -> assistant) tool_call_id?: string; // 元数据 metadata?: MessageMetadata; } export interface ContentBlock { type: "text" | "image" | "tool_use"; text?: string; image_url?: string; tool_use?: { id: string; name: string; input: object; }; } export interface MessageMetadata { timestamp?: number; source?: "channel" | "inline" | "system_event"; channel?: string; messageId?: string; replyToMessageId?: string; }

4.4 ReplyPayload (回复载荷)

// src/auto-reply/types.ts export type ReplyPayload = { // 文本内容 text?: string; // 媒体 mediaUrl?: string; mediaUrls?: string[]; // 交互式组件 interactive?: InteractiveReply; // 引用回复 replyToId?: string; replyToTag?: boolean; replyToCurrent?: boolean; // 特殊标记 audioAsVoice?: boolean; isError?: boolean; isReasoning?: boolean; isCompactionNotice?: boolean; // 通道特定数据 channelData?: Record<string, unknown>; };

10. 工具系统

10.1 工具架构

工具系统是 OpenClaw AI Agent 的核心能力扩展机制。通过工具，AI 可以执行文件操作、网络请求、系统命令等操作。

// 工具接口定义 export interface AnyAgentTool { name: string; // 工具名称 (唯一) description: string; // 工具描述 (AI 用来理解何时使用) input_schema: object; // JSON Schema (参数验证) execute: (params: any) => Promise<any>; // 执行函数 category?: string; // 工具分类 permissionRequired?: boolean; // 是否需要权限 }

10.2 内置工具列表

文件操作工具

read: 读取文件内容，支持文本和图片
write: 创建或覆盖文件，自动创建父目录
edit: 精确编辑文件，使用文本替换

执行工具

exec: 执行 shell 命令，支持后台运行
process: 管理后台进程

Web 工具

web_search: 使用 DuckDuckGo 搜索
web_fetch: 获取网页内容并提取

浏览器工具

browser: 控制浏览器，支持快照、截图、操作

会话工具

sessions_list: 列出其他会话
sessions_send: 发送消息到其他会话

消息工具

message: 发送消息和通道操作

11. 安全机制

11.1 安全模型

OpenClaw 采用分层安全模型：

网络层安全
1. Gateway 认证 (Token/TLS/OpenID Connect)
2. WebSocket 速率限制
3. IP 白名单/黑名单
通道层安全
1. DM 配对码机制
2. 白名单管理
3. @提及门控 (群组)
会话层安全
1. 会话隔离
2. 工具权限控制
3. 代码执行审批
4. 沙箱模式 (Docker)
数据层安全
1. 密钥加密存储
2. 敏感信息过滤
3. 本地优先数据存储

11.2 DM 配对机制

未配对的发送者会收到配对码，需要管理员运行审批命令：

openclaw pairing approve telegram <code>

11.3 执行审批

执行敏感命令需要审批：

// 检查权限 if (requiresApproval(sessionKey)) { // 广播审批请求 broadcast("exec.approval.request", { sessionKey, command, sessionId }); // 等待审批结果 const result = await waitForApproval(sessionId); if (!result.approved) { return { error: "Command not approved" }; } }

12. 总结与最佳实践

12.1 架构最佳实践

Gateway 作为单一控制平面
1. 所有通信都通过 Gateway
2. 统一的认证和授权
3. 集中的配置管理
插件化扩展
1. 通道、工具、钩子都是插件
2. 按需加载，减少内存占用
3. 易于扩展和定制
会话隔离
1. 每个会话独立管理上下文
2. 防止数据泄露
3. 支持多租户场景

12.2 性能优化

流式处理
1. 使用 WebSocket 流式传输
2. 减少首字节时间
3. 改善用户体验
上下文压缩
1. 自动压缩历史消息
2. 减少 token 消耗
3. 降低成本
缓存策略
1. 配置缓存
2. 模型目录缓存
3. 工具结果缓存

12.3 安全建议

最小权限原则
1. 默认拒绝所有操作
2. 按需授予权限
3. 定期审计权限
本地优先
1. 敏感数据存储在本地
2. 避免云端存储密钥
3. 定期备份
审计日志
1. 记录所有操作
2. 监控异常行为
3. 定期检查日志

12.4 开发建议

代码组织
1. 遵循模块化设计
2. 单一职责原则
3. 清晰的接口定义
错误处理
1. 使用 Result 模式
2. 提供有用的错误信息
3. 实现优雅降级
测试策略
1. 单元测试覆盖核心逻辑
2. 集成测试验证端到端流程
3. 契约测试保证兼容性

附录

A. 常用命令

启动 Gateway

openclaw gateway --port 18789

安装插件

openclaw plugins install @openclaw/matrix

配置模型

openclaw config set agent.model "anthropic/claude-sonnet-4-6"

审批配对

openclaw pairing approve telegram

查看状态

openclaw status

运行诊断

openclaw doctor

### B. 配置示例 ```json5 { agent: { model: "anthropic/claude-sonnet-4-6", thinking: "medium", timeout: 120 }, gateway: { port: 18789, bind: "loopback", auth: { mode: "token", token: "your-secret-token" } }, channels: { telegram: { enabled: true, botToken: "123456:ABC...", dmPolicy: "pairing" } }, models: { providers: { anthropic: { apiKey: "sk-ant-..." } } } }