OpenClaw 源代码学习笔记

张

张建站

2026/4/20 21:05:29

10分钟阅读

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、Android1.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 {}, ): PromiseGatewayServer { // 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) Promiseany; // 执行函数 }; // 工具分类 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) Promisevoid; start?: () Promisevoid; stop?: () Promisevoid; };插件运行时// src/plugins/runtime/types.ts export type PluginRuntime { // 日志 logger: RuntimeLogger; // 子 Agent 运行 runSubagent: (params: SubagentRunParams) PromiseSubagentRunResult; // 配置访问 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?: Recordstring, 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?: Recordstring, ModelProviderConfig; aliases?: Recordstring, string; defaults?: ModelDefaults; }; // 插件配置 plugins?: { installs?: Recordstring, 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 | ArrayContentBlock; // 工具调用 (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?: Recordstring, unknown; };10. 工具系统10.1 工具架构工具系统是 OpenClaw AI Agent 的核心能力扩展机制。通过工具AI 可以执行文件操作、网络请求、系统命令等操作。// 工具接口定义 export interface AnyAgentTool { name: string; // 工具名称 (唯一) description: string; // 工具描述 (AI 用来理解何时使用) input_schema: object; // JSON Schema (参数验证) execute: (params: any) Promiseany; // 执行函数 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 采用分层安全模型网络层安全Gateway 认证 (Token/TLS/OpenID Connect)WebSocket 速率限制IP 白名单/黑名单通道层安全DM 配对码机制白名单管理提及门控 (群组)会话层安全会话隔离工具权限控制代码执行审批沙箱模式 (Docker)数据层安全密钥加密存储敏感信息过滤本地优先数据存储11.2 DM 配对机制未配对的发送者会收到配对码需要管理员运行审批命令openclaw pairing approve telegram code11.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作为单一控制平面所有通信都通过 Gateway统一的认证和授权集中的配置管理插件化扩展通道、工具、钩子都是插件按需加载减少内存占用易于扩展和定制会话隔离每个会话独立管理上下文防止数据泄露支持多租户场景12.2 性能优化流式处理使用 WebSocket 流式传输减少首字节时间改善用户体验上下文压缩自动压缩历史消息减少 token 消耗降低成本缓存策略配置缓存模型目录缓存工具结果缓存12.3 安全建议最小权限原则默认拒绝所有操作按需授予权限定期审计权限本地优先敏感数据存储在本地避免云端存储密钥定期备份审计日志记录所有操作监控异常行为定期检查日志12.4 开发建议代码组织遵循模块化设计单一职责原则清晰的接口定义错误处理使用 Result 模式提供有用的错误信息实现优雅降级测试策略单元测试覆盖核心逻辑集成测试验证端到端流程契约测试保证兼容性附录A. 常用命令启动 Gatewayopenclaw 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-... } } } }C. 参考资源官方文档: https://docs.openclaw.aiGitHub: https://github.com/openclaw/openclawDiscord: https://discord.gg/clawdClawHub (技能市场): https://clawhub.ai学习完成日期2026年4月2日本笔记基于 OpenClaw v2026.4.2 版本源代码学习整理