夜雨聆风点击上方“太虚算经”，选择“置顶公众号”
关键时刻，第一时间送达！
这项目去年刚出还没这么火的时候就分析过，再做一个标记
1. 项目概览
OpenClaw 是一个个人 AI 助手，运行在用户自己的设备上，通过各种消息渠道与用户交互。它提供了一个统一的控制平面（Gateway），管理会话、渠道、工具和事件，使用户能够在各种平台上与 AI 助手进行交互。
主要功能/亮点：
多渠道集成（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal 等） 语音唤醒和通话模式 实时 Canvas 可视化工作区 浏览器控制能力 设备节点（相机、屏幕录制、位置等） 定时任务和 webhooks 技能平台（ClawHub） 安全沙箱机制
典型应用场景：
个人助手：通过各种消息渠道进行日常对话和任务处理 语音交互：通过语音唤醒和通话模式进行免手操作 视觉交互：通过 Canvas 进行可视化操作和展示 自动化：通过定时任务和 webhooks 实现自动化工作流
2. 目录结构
OpenClaw 项目采用模块化架构，清晰地分离了核心功能、扩展、文档和脚本。核心代码位于 src/ 目录，包含网关、配置、CLI 等核心组件；extensions/ 目录包含各种集成和插件；docs/ 目录包含项目文档；scripts/ 目录包含构建和工具脚本；ui/ 目录包含用户界面代码；apps/ 目录包含移动应用代码。
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line├── src/ # 核心源代码│ ├── cli/ # 命令行接口│ ├── config/ # 配置管理│ ├── gateway/ # 网关实现│ ├── context-engine/ # 上下文引擎│ ├── pairing/ # 设备配对│ └── process/ # 进程管理├── extensions/ # 各种插件和集成├── docs/ # 文档├── scripts/ # 构建和工具脚本├── ui/ # 用户界面├── apps/ # 移动应用（iOS、Android、macOS）├── assets/ # 资源文件├── test/ # 测试文件└── test-fixtures/ # 测试固定数据
src/cli/: 命令行工具实现，包含各种命令和选项处理 src/config/: 配置管理，包含配置模式、验证和默认值 src/gateway/: 网关实现，包含 WebSocket 服务器、认证、会话管理等 src/context-engine/: 上下文引擎，处理对话上下文 src/pairing/: 设备配对系统，用于安全连接设备 src/process/: 进程管理，处理子进程和命令执行 extensions/: 各种集成和插件，如消息渠道、模型提供商等 docs/: 项目文档，包含使用指南、架构说明等 scripts/: 构建脚本、工具脚本和CI/CD脚本 ui/: Web用户界面代码 apps/: 移动应用代码，包括iOS、Android和macOS应用
3. 系统架构与主流程
OpenClaw 采用分层架构，以 Gateway 为核心控制平面，连接各种客户端和服务。系统通过 WebSocket 进行实时通信，支持多客户端同时连接。
架构图
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineflowchart TDsubgraph 用户交互层A1[WhatsApp] --> GA2[Telegram] --> GA3[Slack] --> GA4[Discord] --> GA5[WebChat] --> GA6[macOS应用] --> GA7[iOS节点] --> GA8[Android节点] --> Gendsubgraph 核心控制层G[GatewayWebSocket控制平面] --> S[会话管理]G --> C[配置管理]G --> T[工具管理]G --> E[事件系统]G --> A[认证系统]endsubgraph 服务层S --> M[模型提供商]T --> B[浏览器控制]T --> Can[Canvas]T --> N[节点管理]T --> Cr[定时任务]T --> W[Webhooks]endsubgraph 扩展层M --> P1[OpenAI]M --> P2[Anthropic]M --> P3[Mistral]M --> P4[其他模型]N --> D1[设备控制]N --> D2[相机]N --> D3[屏幕录制]N --> D4[位置服务]end
主要流程
启动流程：
启动 Gateway 服务，绑定到指定端口（默认 18789） 加载配置文件和插件 初始化 WebSocket 服务器 连接配置的消息渠道 消息处理流程：
接收来自消息渠道的消息 验证发送者身份（基于 DM 策略） 路由消息到相应的会话 调用 AI 模型处理消息 执行工具调用（如果需要） 将响应发送回原始渠道 工具调用流程：
AI 模型生成工具调用请求 Gateway 验证工具调用权限 执行工具操作（浏览器、Canvas、节点等） 将工具执行结果返回给 AI 模型 AI 模型生成基于工具结果的响应 设备配对流程：
设备生成配对代码 用户在 CLI 中批准配对 设备获得访问权限 设备可以执行本地操作（相机、屏幕录制等）
4. 核心功能模块
4.1 Gateway
Gateway 是 OpenClaw 的核心控制平面，负责管理会话、渠道、工具和事件。它通过 WebSocket 为客户端提供实时通信能力，支持多客户端同时连接。
主要功能：
WebSocket 服务器管理 会话管理和状态维护 消息路由和处理 工具调用和执行 认证和授权 配置管理和热重载 事件广播和通知
关键组件：
server.ts: 主服务器实现client.ts: 客户端连接管理commands.ts: 命令处理auth.ts: 认证和授权session-utils.ts: 会话管理工具
4.2 记忆系统
OpenClaw 实现了独特的记忆系统，包括个性定义和长期记忆管理。
核心组件：
SOUL.md: 定义助手的个性、语气和风格 MEMORY.md: 长期记忆，存储持久事实、偏好和决策 memory/YYYY-MM-DD.md: 每日笔记，存储运行上下文和观察结果 记忆运行时: 管理长期记忆和检索 记忆插件: 提供不同的记忆存储后端
SOUL.md 功能：
定义助手的语气和个性 设置回答风格和边界 控制幽默程度和简洁性 提供个性化的交互体验
记忆系统架构：
记忆运行时 ( memory-runtime.ts): 管理记忆插件的生命周期记忆状态 ( memory-state.ts): 维护记忆系统的状态记忆核心 ( memory-core.ts): 提供记忆存储和检索的核心功能记忆插件: 如 LanceDB 等存储后端
记忆系统工作流程：
会话消息被处理和存储 记忆系统定期同步和索引消息 当需要时，记忆系统检索相关历史信息 检索结果被注入到提示中，增强助手的上下文理解 自动记忆刷新：在对话压缩前，系统会提醒助手将重要上下文保存到记忆文件
记忆搜索机制：
混合搜索: 结合向量相似性（语义含义）和关键词匹配（精确术语如 ID 和代码符号） 自动检测: 自动检测可用的嵌入提供商（如 OpenAI、Gemini、Voyage、Mistral） 语义搜索: 即使措辞与原始不同，也能找到相关笔记
记忆后端：
内置存储 (默认): 基于 SQLite，支持关键词搜索、向量相似性和混合搜索，无额外依赖 QMD: 本地优先的侧边栏，支持重排序、查询扩展和索引工作区外的目录 Honcho: AI 原生跨会话记忆，具有用户建模、语义搜索和多代理感知
Dreaming (实验性)：
背景巩固过程，重新访问每日文件中的短期回忆 对回忆进行评分，只将合格项目提升到长期记忆 保持长期记忆高信号：默认禁用，按计划运行，通过分数、回忆频率和查询多样性门控
配置和使用：
SOUL.md 位于工作区根目录 ( ~/.openclaw/workspace/SOUL.md)MEMORY.md 位于工作区根目录 ( ~/.openclaw/workspace/MEMORY.md)每日笔记位于 ~/.openclaw/workspace/memory/目录记忆插件通过配置文件启用和配置 支持不同的记忆后端，如内置存储或 QMD
SOUL.md 最佳实践：
保持简洁明了，专注于行为和风格 避免冗长的背景故事 使用具体的规则和示例 定期更新以保持助手的新鲜度 避免使用 corporate 风格的语言 不要使用 "Great question" 等陈词滥调 当用户有好主意时，给予真诚的赞美 当用户可能做出错误决定时，温和地指出
4.3 渠道集成
OpenClaw 支持多种消息渠道，允许用户通过各种平台与 AI 助手交互。
支持的渠道：
WhatsApp Telegram Slack Discord Google Chat Signal BlueBubbles (iMessage) iMessage (legacy) IRC Microsoft Teams Matrix Feishu LINE Mattermost Nextcloud Talk Nostr Synology Chat Tlon Twitch Zalo Zalo Personal WeChat WebChat
渠道管理：
每个渠道都有独立的配置和认证机制 支持群聊和私聊 实现了统一的消息处理接口 支持消息格式转换和适配
4.4 工具系统
OpenClaw 提供了丰富的工具集，使 AI 助手能够执行各种操作。
主要工具：
浏览器控制：控制 Chrome/Chromium 浏览器，执行网页操作 Canvas：实时可视化工作区，支持 A2UI 节点管理：设备控制，如相机、屏幕录制、位置获取 定时任务：设置和管理定时任务 Webhooks：接收和处理 webhook 事件 会话工具：在会话之间传递消息和协调工作
工具执行流程：
AI 模型生成工具调用请求 Gateway 验证工具调用权限 执行工具操作 将结果返回给 AI 模型 AI 模型基于结果生成响应
4.5 安全系统
OpenClaw 实现了多层次的安全机制，确保系统安全运行。
安全特性：
DM 策略：控制谁可以发送消息给助手 沙箱模式：在 Docker 容器中运行非主会话 权限管理：细粒度的工具权限控制 认证系统：设备配对和身份验证 安全默认值：默认配置优先考虑安全性
安全默认值：
DM 策略默认为 "pairing"，需要配对码才能开始对话 非主会话默认在沙箱中运行 工具访问需要明确授权
4.6 技能平台
OpenClaw 提供了技能平台，允许扩展助手的能力。
技能系统：
ClawHub：技能注册表，提供技能发现和安装 捆绑技能：核心提供的基础技能 工作区技能：用户自定义技能
技能管理：
技能安装和更新 技能权限控制 技能发现和搜索
4.7 心跳机制
OpenClaw 实现了心跳机制，用于定期检查系统状态、处理系统事件和保持助手活跃。
核心功能：
定期执行心跳检查 处理系统事件（如执行完成、定时任务） 向用户发送状态更新 维护系统健康状态
心跳机制架构：
心跳运行器 ( heartbeat-runner.ts): 管理心跳的调度和执行心跳唤醒 ( heartbeat-wake.ts): 处理心跳的触发和唤醒心跳事件 ( heartbeat-events.ts): 处理心跳相关的事件心跳可见性 ( heartbeat-visibility.ts): 控制心跳消息的可见性心跳摘要 ( heartbeat-summary.ts): 生成心跳摘要信息
心跳工作流程：
心跳运行器根据配置的时间间隔调度心跳 当心跳触发时，系统检查是否在活跃时间内 检查是否有正在进行的请求 解析心跳配置和会话信息 构建心跳提示，包括系统事件和当前时间 调用 AI 模型生成心跳响应 处理响应，过滤掉空响应和重复内容 向用户发送心跳消息（如果配置为可见） 更新心跳状态和时间戳
4.8 插件系统
OpenClaw 实现了强大的插件系统，允许扩展和定制助手的功能。
核心功能：
动态加载和管理插件 支持多种插件类型（渠道、提供商、工具等） 插件生命周期管理 插件间通信和依赖管理
插件系统架构：
插件注册表 ( registry.ts): 管理插件的注册和发现插件加载器 ( loader.ts): 负责加载和初始化插件插件 API ( api-builder.ts): 提供插件开发接口插件槽位 ( slots.ts): 管理插件的槽位分配
插件类型：
渠道插件：添加新的消息渠道 提供商插件：添加新的 AI 模型提供商 工具插件：添加新的工具和功能 记忆插件：提供记忆存储和检索功能 语音插件：提供语音识别和合成功能 媒体理解插件：提供媒体内容理解功能 图像生成插件：提供图像生成功能 Web 搜索插件：提供网页搜索功能
插件生命周期：
加载：从文件系统或 npm 包加载插件 验证：验证插件的有效性和安全性 注册：将插件功能注册到系统中 激活：启用插件功能 停用：禁用插件功能 卸载：移除插件
插件开发：
插件使用标准的 npm 包格式 插件通过 openclaw.plugin.json声明其功能和依赖插件可以使用 OpenClaw 提供的 API 来扩展系统功能
4.9 CLI 系统
OpenClaw 提供了强大的命令行界面，用于管理和控制助手。
核心功能：
命令解析和执行 配置管理 插件管理 系统状态监控 会话管理
CLI 系统架构：
命令构建 ( build-program.ts): 构建命令行程序命令注册 ( command-registry.ts): 注册和管理命令命令执行 ( preaction.ts): 处理命令执行前的操作命令上下文 ( context.ts): 管理命令执行上下文
主要命令：
gateway：启动和管理网关 agent：与助手交互 message：发送消息 channels：管理消息渠道 config：管理配置 plugins：管理插件 memory：管理记忆系统 heartbeat：管理心跳机制 onboard：引导设置助手 doctor：诊断系统问题
CLI 扩展：
插件可以注册自定义 CLI 命令 命令支持子命令和选项 命令支持帮助文档生成
CLI 工作流程：
解析命令行参数 加载命令上下文 执行命令前的钩子 执行命令逻辑 处理命令结果 显示命令输出
5. 核心 API/类/函数
5.1 Gateway API
server.start()
功能：启动 Gateway 服务器 参数：配置对象，包含端口、绑定地址等 返回值：Promise，解析为服务器实例 使用场景：启动 OpenClaw 服务
client.connect()
功能：建立与 Gateway 的 WebSocket 连接 参数：WebSocket URL 和认证信息 返回值：Promise，解析为客户端实例 使用场景：客户端连接到 Gateway
session.create()
功能：创建新的会话 参数：会话配置，包含模型、工具等 返回值：Promise，解析为会话 ID 使用场景：初始化新的对话会话
message.send()
功能：发送消息到指定渠道 参数：渠道信息、接收者、消息内容 返回值：Promise，解析为发送结果 使用场景：发送消息到各种渠道
5.2 配置 API
config.load()
功能：加载配置文件 参数：配置文件路径 返回值：Promise，解析为配置对象 使用场景：初始化系统配置
config.validate()
功能：验证配置有效性 参数：配置对象 返回值：验证结果，包含错误信息 使用场景：确保配置正确无误
config.merge()
功能：合并多个配置源 参数：多个配置对象 返回值：合并后的配置对象 使用场景：组合默认配置和用户配置
5.3 工具 API
tool.invoke()
功能：执行工具调用 参数：工具名称和参数 返回值：Promise，解析为工具执行结果 使用场景：执行各种工具操作
browser.snapshot()
功能：获取浏览器页面快照 参数：浏览器实例 ID 和选项 返回值：Promise，解析为快照数据 使用场景：捕获网页内容
canvas.push()
功能：向 Canvas 推送内容 参数：Canvas 实例 ID 和内容 返回值：Promise，解析为推送结果 使用场景：更新 Canvas 显示
node.invoke()
功能：执行设备节点操作 参数：节点 ID、命令和参数 返回值：Promise，解析为操作结果 使用场景：控制设备功能
5.4 渠道 API
channel.login()
功能：登录到消息渠道 参数：渠道名称和认证信息 返回值：Promise，解析为登录结果 使用场景：连接到各种消息服务
channel.send()
功能：通过渠道发送消息 参数：渠道消息对象 返回值：Promise，解析为发送结果 使用场景：向渠道发送响应
channel.receive()
功能：处理来自渠道的消息 参数：渠道消息对象 返回值：Promise，解析为处理结果 使用场景：处理 incoming 消息
5.5 会话 API
session.addMessage()
功能：向会话添加消息 参数：会话 ID 和消息对象 返回值：Promise，解析为添加结果 使用场景：记录会话消息
session.getHistory()
功能：获取会话历史 参数：会话 ID 和选项 返回值：Promise，解析为历史消息 使用场景：查看会话历史
session.reset()
功能：重置会话 参数：会话 ID 返回值：Promise，解析为重置结果 使用场景：开始新的对话
5.6 记忆系统 API
getActiveMemorySearchManager()
功能：获取活跃的记忆搜索管理器 参数：配置对象、代理 ID 和目的 返回值：Promise，解析为记忆搜索管理器 使用场景：检索记忆系统中的信息
resolveActiveMemoryBackendConfig()
功能：解析活跃的记忆后端配置 参数：配置对象和代理 ID 返回值：记忆后端配置对象 使用场景：获取记忆系统的配置信息
closeActiveMemorySearchManagers()
功能：关闭所有活跃的记忆搜索管理器 参数：配置对象（可选） 返回值：Promise 使用场景：清理记忆系统资源
buildMemoryPromptSection()
功能：构建记忆提示部分 参数：可用工具和引用模式 返回值：字符串数组，包含记忆提示 使用场景：将记忆信息注入到提示中
5.7 心跳机制 API
runHeartbeatOnce()
功能：执行一次心跳检查 参数：配置对象、代理 ID、会话密钥、心跳配置、原因和依赖项 返回值：Promise，解析为心跳运行结果 使用场景：手动触发心跳检查
startHeartbeatRunner()
功能：启动心跳运行器 参数：配置对象、运行时环境、中止信号和运行一次函数 返回值：心跳运行器对象，包含停止和更新配置方法 使用场景：启动心跳调度系统
areHeartbeatsEnabled()
功能：检查心跳是否启用 参数：无 返回值：布尔值，表示心跳是否启用 使用场景：检查心跳系统状态
setHeartbeatsEnabled()
功能：设置心跳是否启用 参数：布尔值，表示是否启用心跳 返回值：无 使用场景：启用或禁用心跳系统
requestHeartbeatNow()
功能：立即请求心跳 参数：原因和合并毫秒数 返回值：无 使用场景：立即触发心跳检查
5.8 插件系统 API
createPluginRegistry()
功能：创建插件注册表 参数：日志器、核心网关处理器、运行时环境和激活全局副作用标志 返回值：插件注册表对象，包含各种注册方法 使用场景：初始化插件系统
resolveRuntimePluginRegistry()
功能：解析运行时插件注册表 参数：配置对象、激活源配置和自动启用原因 返回值：插件注册表 使用场景：加载和激活插件
registerPluginCommand()
功能：注册插件命令 参数：插件 ID、命令定义和选项 返回值：注册结果 使用场景：为插件添加命令
validatePluginCommandDefinition()
功能：验证插件命令定义 参数：命令定义 返回值：验证错误（如果有） 使用场景：确保插件命令定义有效
5.9 CLI 系统 API
buildProgram()
功能：构建命令行程序 参数：无 返回值：命令行程序对象 使用场景：初始化 CLI 系统
registerProgramCommands()
功能：注册程序命令 参数：命令行程序、上下文和命令行参数 返回值：无 使用场景：添加命令到 CLI
createProgramContext()
功能：创建程序上下文 参数：无 返回值：程序上下文对象 使用场景：为命令执行提供上下文
configureProgramHelp()
功能：配置程序帮助信息 参数：命令行程序和上下文 返回值：无 使用场景：设置 CLI 帮助文档
6. 技术栈与依赖
核心依赖：
ws：WebSocket 服务器 zod：配置验证 vitest：测试框架 oxlint：代码 linting tsx：TypeScript 执行
记忆系统依赖：
LanceDB：可选的记忆存储后端 QMD：可选的记忆存储后端
心跳机制依赖：
Node.js 定时器：用于调度心跳 系统事件系统：用于处理系统事件触发的心跳
模型提供商：
OpenAI Anthropic Mistral Google 以及多种其他提供商
7. 关键模块与典型用例
7.1 基本设置与运行
功能说明：设置和运行 OpenClaw Gateway
配置与依赖：
Node.js 24 或 22.16+ 模型 API 密钥 消息渠道配置
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 全局安装npm install -g openclaw@latest# 运行 onboard 向导openclaw onboard --install-daemon# 启动 Gatewayopenclaw gateway --port 18789 --verbose# 发送消息openclaw message send --to +1234567890 --message "Hello from OpenClaw"# 与助手对话openclaw agent --message "Ship checklist" --thinking high
7.2 渠道配置
功能说明：配置各种消息渠道
配置与依赖：
各渠道的 API 密钥或认证信息 渠道特定的配置参数
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{"channels": {"telegram": {"botToken": "123456:ABCDEF"},"discord": {"token": "1234abcd"},"whatsapp": {"allowFrom": ["+1234567890"]}}}
7.3 工具使用
功能说明：使用各种工具增强助手能力
配置与依赖：
浏览器配置（可选） 设备节点配对（可选）
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 配置浏览器openclaw config set browser.enabled trueopenclaw config set browser.color "#FF4500"# 配对设备openclaw pairing approve ios 123456# 使用 Canvasopenclaw canvas push --content "Hello Canvas!"
7.4 技能管理
功能说明：安装和管理技能
配置与依赖：
ClawHub 访问 技能配置
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 安装技能openclaw skills install "clawhub:weather"# 列出已安装技能openclaw skills list# 更新技能openclaw skills update "clawhub:weather"
7.5 记忆系统配置
功能说明：配置和使用记忆系统，包括 SOUL.md 个性化和记忆存储设置
配置与依赖：
工作区目录设置 记忆插件安装
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 查看当前工作区目录openclaw config get agents.defaults.workspace# 编辑 SOUL.md 文件nano ~/.openclaw/workspace/SOUL.md# 配置记忆后端openclaw config set memory.backend "lancedb"# 查看记忆系统状态openclaw memory status# 手动同步记忆openclaw memory sync# 搜索记忆openclaw memory search "TypeScript preferences"# 重建记忆索引openclaw memory index --force
SOUL.md 示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# SOUL.md## 语气- 简洁直接，避免冗长的开场白- 保持专业但友好的语气- 适当使用幽默，但不要过度- 对用户的问题给出明确的回答## 风格- 避免使用 corporate 风格的语言- 不要使用 "Great question" 等陈词滥调- 当用户有好主意时，给予真诚的赞美- 当用户可能做出错误决定时，温和地指出## 边界- 保持专注于用户的问题- 不要偏离主题- 尊重用户的隐私- 避免讨论敏感话题Be the assistant you'd actually want to talk to at 2am. Not a corporate drone. Not a sycophant. Just... good.
7.6 心跳机制配置
功能说明：配置和使用心跳机制，用于定期检查系统状态和处理系统事件
配置与依赖：
心跳间隔设置 活跃时间配置 目标渠道设置
使用场景：
定期检查系统状态 处理执行完成事件 处理定时任务事件 保持助手活跃
使用示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 启用心跳openclaw config set agents.defaults.heartbeat.enabled true# 设置心跳间隔（毫秒）openclaw config set agents.defaults.heartbeat.intervalMs 3600000# 设置心跳活跃时间openclaw config set agents.defaults.heartbeat.activeHours.start "08:00"openclaw config set agents.defaults.heartbeat.activeHours.end "22:00"# 设置心跳目标openclaw config set agents.defaults.heartbeat.target "whatsapp:+1234567890"# 立即触发心跳openclaw heartbeat now# 查看心跳状态openclaw heartbeat status
心跳配置示例：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line{"agents": {"defaults": {"heartbeat": {"enabled": true,"intervalMs": 3600000,"activeHours": {"start": "08:00","end": "22:00"},"target": "whatsapp:+1234567890","showOk": false,"showAlerts": true,"isolatedSession": true}}}}
8. 配置、部署与开发
8.1 配置
OpenClaw 使用 JSON 配置文件，默认位于 ~/.openclaw/openclaw.json。配置文件包含以下主要部分：
agent：代理设置，包括模型选择 channels：消息渠道配置 browser：浏览器控制设置 gateway：网关设置 skills：技能配置 sandbox：沙箱设置
最小配置示例：
ounter(lineounter(lineounter(lineounter(lineounter(line{"agent": {"model": "anthropic/claude-opus-4-6",}}
8.2 部署
本地部署：
使用 openclaw onboard进行引导设置安装为系统服务（launchd/systemd）
Docker 部署：
使用项目提供的 Dockerfile 挂载配置和数据卷
远程部署：
使用 Tailscale Serve/Funnel 进行安全访问 使用 SSH 隧道进行远程访问
8.3 开发
从源码构建：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(linegit clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm ui:buildpnpm build# 开发循环（自动重载）pnpm gateway:watch
测试：
ounter(lineounter(lineounter(lineounter(lineounter(line# 运行测试pnpm test# 运行特定测试pnpm test --config vitest.unit.config.ts
代码质量：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 代码格式化pnpm format# 代码 lintingpnpm lint# 检查类型pnpm tsgo
9. 监控与维护
9.1 日志
OpenClaw 提供详细的日志系统，记录系统运行状态和错误信息。
日志位置：
默认： ~/.openclaw/logs/可通过配置修改
日志级别：
error warn info debug trace
9.2 健康检查
内置健康检查：
Gateway 状态端点 渠道连接状态 模型可用性检查
使用 doctor 命令：
ounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# 运行系统检查openclaw doctor# 检查特定组件openclaw doctor --component gatewayopenclaw doctor --component channels
9.3 常见问题排查
渠道连接问题：
检查认证信息 验证网络连接 查看渠道特定日志
模型调用失败：
检查 API 密钥 验证模型权限 查看模型提供商状态
工具执行失败：
检查工具权限 验证设备连接 查看工具特定日志
10. 其他重要模块
10.1 多智能体体系（Multi-Agent System）
核心功能：
支持创建和管理子智能体，实现任务分解和并行处理 提供智能体间通信和协作机制 支持不同类型的智能体会话模式（一次性运行和持久会话） 实现智能体生命周期管理和资源控制 支持主智能体之间的平级隔离和协调
智能体类型与关系：
主智能体（Agent）：完全独立的智能体实例，有自己的工作区、状态目录和会话存储 子智能体（Subagent）：由主智能体或其他子智能体创建的临时智能体，用于执行特定任务 智能体层级： 主智能体之间是平级关系，相互隔离 子智能体是主智能体的下属，有深度层级限制（默认最大深度为5） 子智能体可以从父智能体继承某些属性，但也可以指定不同的模型和配置
主要组件：
subagent-registry.ts：子智能体注册表，管理子智能体的运行记录subagent-spawn.ts：子智能体的创建和启动机制subagent-registry.types.ts：子智能体运行记录的类型定义subagent-registry-read.ts：子智能体注册表的读取操作session-subagent-reactivation.ts：子智能体会话的重新激活multi-agent.md：多智能体概念文档，定义主智能体之间的关系和配置
关键概念：
子智能体运行记录 ( SubagentRunRecord)：记录子智能体的运行状态、任务、生命周期等信息智能体深度 ( spawnDepth)：限制子智能体的嵌套层级，防止无限递归智能体模式 ( SpawnSubagentMode)：支持"run"（一次性运行）和"session"（持久会话）两种模式沙箱隔离：子智能体可以在沙箱中运行，提高安全性 线程绑定：子智能体可以绑定到特定线程，支持持续对话 智能体绑定：通过绑定规则将消息路由到特定智能体
智能体创建流程：
参数验证：验证任务描述、智能体ID、模型选择等参数 权限检查：检查智能体深度限制、活跃子智能体数量限制 会话创建：创建子智能体会话，生成唯一会话密钥 配置设置：设置子智能体的模型、思考级别、运行超时等参数 线程绑定：如果需要，为子智能体绑定到特定线程 附件处理：处理子智能体的附件文件 系统提示构建：构建子智能体的系统提示，包含任务描述和上下文信息 运行启动：启动子智能体运行，执行指定任务 运行注册：在子智能体注册表中注册运行记录 生命周期事件：发送子智能体创建的生命周期事件
智能体协调机制：
主智能体协调：
通过消息路由和绑定规则进行协调 可以配置一个协调者智能体，创建和管理多个工作智能体 工作智能体完成任务后向协调者报告结果 协调者可以汇总结果并做出决策 子智能体协调：
父智能体创建多个子智能体并行执行任务 子智能体完成任务后自动向父智能体报告结果 父智能体可以根据子智能体的结果进行决策和汇总
智能体隔离措施：
主智能体隔离：
每个主智能体有自己的工作区（包含SOUL.md、AGENTS.md等） 每个主智能体有独立的状态目录和会话存储 主智能体之间的认证信息不自动共享 可以为每个主智能体配置不同的沙箱和工具权限 子智能体隔离：
子智能体可以在沙箱中运行，与父智能体隔离 子智能体有自己的运行环境和资源限制 子智能体的权限不能超过父智能体
智能体通信方式：
主智能体之间通信：
通过 agentToAgent工具进行通信（需要显式启用）通过消息路由和绑定规则传递消息 可以通过QMD内存搜索共享信息 子智能体与父智能体通信：
自动公告机制：子智能体完成任务后自动向父智能体发送结果 线程绑定：通过线程绑定实现持续对话 生命周期事件：通过事件系统通知状态变化
智能体管理：
运行状态管理：跟踪子智能体的运行状态（运行中、已完成、已失败等） 深度控制：限制子智能体的嵌套层级（默认最大深度为5） 数量控制：限制每个智能体的活跃子智能体数量（默认5个） 清理机制：支持子智能体的自动清理和手动终止 重新激活：支持已完成子智能体会话的重新激活
安全与限制：
智能体ID验证：确保智能体ID格式正确 权限控制：限制子智能体的创建权限和目标智能体 沙箱隔离：子智能体可以在沙箱中运行，提高安全性 资源限制：限制子智能体的运行时间和资源使用 工具权限：为不同智能体配置不同的工具权限
关键文件：
[src/agents/subagent-spawn.ts](file:///workspace/openclaw/src/agents/subagent-spawn.ts)：子智能体的创建和启动 [src/agents/subagent-registry.ts](file:///workspace/openclaw/src/agents/subagent-registry.ts)：子智能体注册表 [src/agents/subagent-registry.types.ts](file:///workspace/openclaw/src/agents/subagent-registry.types.ts)：子智能体运行记录的类型定义 [src/agents/subagent-registry-read.ts](file:///workspace/openclaw/src/agents/subagent-registry-read.ts)：子智能体注册表的读取操作 [src/gateway/session-subagent-reactivation.ts](file:///workspace/openclaw/src/gateway/session-subagent-reactivation.ts)：子智能体会话的重新激活 [docs/concepts/multi-agent.md](file:///workspace/openclaw/docs/concepts/multi-agent.md)：多智能体概念文档
10.2 上下文引擎（Context Engine）
核心功能：
管理对话上下文的生命周期，包括消息的摄入、组装和压缩 提供插件化的上下文管理接口，支持不同的上下文管理策略 实现会话维护和转录重写功能
主要组件：
ContextEngine接口：定义了上下文引擎的核心方法，如ingest、assemble、compact等LegacyContextEngine：传统上下文引擎实现registry.ts：上下文引擎注册表，用于注册和管理不同的上下文引擎实现
关键文件：
[src/context-engine/types.ts](file:///workspace/openclaw/src/context-engine/types.ts)：定义上下文引擎的核心类型和接口 [src/context-engine/registry.ts](file:///workspace/openclaw/src/context-engine/registry.ts)：上下文引擎注册和管理 [src/context-engine/legacy.ts](file:///workspace/openclaw/src/context-engine/legacy.ts)：传统上下文引擎实现
工作流程：
消息摄入：将新消息添加到上下文存储中 上下文组装：根据令牌预算组装适合模型的上下文 上下文压缩：当上下文超出令牌限制时进行压缩 会话维护：定期进行会话维护，优化上下文存储
10.2 渠道系统（Channels）
核心功能：
实现多渠道集成，支持WhatsApp、Telegram、Slack等多种消息平台 提供统一的渠道接口，简化渠道的添加和管理 处理消息的 inbound 和 outbound，确保消息的正确传递
主要组件：
ChannelPlugin：渠道插件接口，定义了渠道的核心功能ChannelManager：渠道管理器，负责渠道的生命周期管理Registry：渠道注册表，管理所有可用的渠道插件
支持的渠道：
WhatsApp Telegram Slack Discord iMessage Signal Google Chat Microsoft Teams IRC Matrix Feishu LINE Mattermost Nextcloud Talk Nostr Synology Chat Tlon Twitch Zalo Zalo Personal WeChat WebChat
关键文件：
[src/channels/plugins/registry.ts](file:///workspace/openclaw/src/channels/plugins/registry.ts)：渠道插件注册表 [src/channels/registry.ts](file:///workspace/openclaw/src/channels/registry.ts)：渠道系统注册表 [src/channels/session-conversation.ts](file:///workspace/openclaw/src/channels/session-conversation.ts)：会话和对话管理
渠道管理流程：
渠道配置：用户配置渠道的认证信息和设置 渠道启动：系统启动并连接到配置的渠道 消息接收：渠道插件接收来自外部平台的消息 消息处理：系统处理接收到的消息，包括路由和格式转换 消息发送：系统通过渠道插件发送响应消息
10.3 技能平台（Skills）
核心功能：
管理和加载技能，扩展OpenClaw的功能 提供技能的发现、注册和执行机制 支持本地和远程技能的加载和使用
主要组件：
Skill：技能接口，定义了技能的核心功能SkillRegistry：技能注册表，管理所有可用的技能SkillLoader：技能加载器，负责从不同来源加载技能
技能类型：
捆绑技能：核心提供的基础技能 工作区技能：用户自定义技能 插件技能：通过插件提供的技能
关键文件：
[src/agents/skills/types.ts](file:///workspace/openclaw/src/agents/skills/types.ts)：技能系统的核心类型定义 [src/agents/skills/refresh.ts](file:///workspace/openclaw/src/agents/skills/refresh.ts)：技能刷新机制 [src/agents/skills/local-loader.ts](file:///workspace/openclaw/src/agents/skills/local-loader.ts)：本地技能加载器
技能管理流程：
技能发现：系统发现可用的技能 技能加载：系统加载技能定义和实现 技能注册：技能被注册到系统中 技能执行：AI 模型调用技能执行特定任务 技能更新：系统定期更新技能
10.4 配置系统
核心功能：
管理OpenClaw的各种配置选项 提供配置验证和默认值管理 支持环境变量替换和配置覆盖
主要组件：
Config：配置管理核心Schema：配置模式定义Validation：配置验证
配置文件：
默认位置： ~/.openclaw/openclaw.json支持 JSON 和 YAML 格式 支持环境变量替换
关键文件：
[src/config/config.ts](file:///workspace/openclaw/src/config/config.ts)：配置管理核心 [src/config/schema.ts](file:///workspace/openclaw/src/config/schema.ts)：配置模式定义 [src/config/validation.ts](file:///workspace/openclaw/src/config/validation.ts)：配置验证
10.5 安全系统
核心功能：
处理认证和授权 提供沙箱隔离机制 管理权限和访问控制
主要组件：
Auth：认证系统Sandbox：沙箱隔离Permissions：权限管理
安全特性：
DM 策略：控制谁可以发送消息给助手 沙箱模式：在 Docker 容器中运行非主会话 权限管理：细粒度的工具权限控制 认证系统：设备配对和身份验证 安全默认值：默认配置优先考虑安全性
关键文件：
[src/gateway/auth.ts](file:///workspace/openclaw/src/gateway/auth.ts)：认证系统 [src/config/sandbox.ts](file:///workspace/openclaw/src/config/sandbox.ts)：沙箱配置 [src/gateway/role-policy.ts](file:///workspace/openclaw/src/gateway/role-policy.ts)：角色和权限管理
11. 总结与亮点回顾
OpenClaw 是一个功能强大、高度可扩展的个人 AI 助手平台，具有以下核心优势：
技术亮点：
统一控制平面：Gateway 作为中央控制中心，管理所有组件 多渠道集成：支持几乎所有主流消息平台 丰富的工具生态：浏览器控制、Canvas、设备节点等 安全设计：默认安全配置，沙箱隔离 扩展性：插件系统和技能平台 跨平台：支持 macOS、iOS、Android、Linux、Windows (WSL2) 上下文管理：智能的上下文引擎，优化模型输入 记忆系统：独特的 SOUL.md 和记忆管理 心跳机制：定期系统检查和状态更新 多智能体体系：支持子智能体创建、管理和协作，实现任务分解和并行处理
应用价值：
个性化助手：在用户自己的设备上运行，保护隐私 多渠道访问：通过用户熟悉的平台进行交互 强大的工具集成：不仅仅是对话，还能执行实际操作 可定制性：通过技能和配置适应个人需求 开源透明：社区驱动的开发和改进
OpenClaw 代表了 AI 助手的未来发展方向：个人化、本地化、多模态、可扩展。它不仅是一个实用工具，也是一个展示如何构建现代 AI 应用的优秀范例。
优化空间：
支持更多模型提供商和渠道 增强工具生态系统 改进语音和视觉交互 提供更丰富的技能和自动化能力 进一步优化性能和安全性 扩展上下文引擎的能力 增强记忆系统的智能性
原创文章,欢迎转发 | 勿抄袭,转载请注明出处
