乐于分享
好东西不私藏

OpenClaw 深度解析

OpenClaw 深度解析

Part 1: 开篇 —— 为什么 OpenClaw 突然火了

1.1 AI应用演进时间线:从被动响应到主动执行

2022-2026:AI应用架构五次范式转变

范式转变的本质:从”被动响应”到”主动执行”

维度 传统ChatBot(2022-2024) OpenClaw(2026)
触发方式
用户主动发起对话
Agent主动巡查执行
运行时间
会话结束后停止
Gateway守护进程永不关机
记忆持久
单次会话内有效
文件存储记忆,跨会话持久
执行能力
仅文本对话
文件操作、Shell命令、浏览器控制等
接入渠道
Web/App单一渠道
飞书/Telegram/Discord等25+渠道
部署位置
云端服务器
本地机器(数据不出厂)

用户视角的转变

传统ChatBot体验:

用户:早上9点打开ChatGPT网页用户:输入 "帮我查一下今天的日程"ChatGPT:返回日程列表用户:关闭网页ChatGPT:停止运行,等待下次触发

OpenClaw体验:

Gateway:早上9点主动巡查Gateway:发现今天有重要会议Agent:主动发送飞书消息:"早安!今天10:00有产品评审会议,请提前准备材料"用户:收到提醒,无需主动询问Gateway:继续巡查下一个任务...

1.2 三大爆火原因深度剖析

原因一:24小时不间断工作

技术实现:Gateway守护进程 + 心跳巡查机制

心跳巡查的具体内容:

检查项 检查频率 发现后动作
未读消息
每5分钟
读取并处理,生成回复
日程提醒
每10分钟
提前2小时提醒,发送通知
Cron任务
按计划执行
定时生成日报、周报等
系统状态
每30分钟
检查Gateway健康、Agent状态
邮件/通知
每15分钟
检查重要邮件并摘要

原因二:信任权限高(本地部署,数据不出厂)

为什么信任重要?

OpenClaw的数据隐私保护机制:

数据类型 存储位置 是否上传云端
文件内容
本地Workspace
❌ 不上传
会话历史
本地sessions.json
❌ 不上传
API密钥
本地auth-profiles.json
❌ 不上传
记忆数据
本地MEMORY.md
❌ 不上传
用户配置
本地openclaw.json
❌ 不上传
LLM调用
本地发起,仅对话内容发送
⚠️ 仅对话文本

企业级场景的信任需求:

原因三:社区生态好(开源+技能市场+活跃社区)

MIT开源的优势:

维度 闭源商业产品 OpenClaw开源
代码透明
❌ 无法审计
✅ GitHub公开,可审计每一行代码
定制能力
❌ 受限
✅ 可自由修改、扩展
厂商锁定
⚠️ 有锁定风险
✅ 无锁定,数据完全自有
成本
💰 月费$20-200
✅ 免费,仅LLM API费用
更新速度
⚠️ 厂商决定
✅ 社区驱动,快速迭代

ClawHub技能市场:

1.3 OpenClaw 核心定位:

定义解析

OpenClaw 是一个自托管的多渠道AI智能体网关,将你常用的聊天应用连接到AI编码代理,实现24小时不间断的智能助手服务。

拆解理解:

关键词 含义 技术对应
自托管
自己部署在本地机器
Local-First架构
多渠道
支持25+聊天应用
Channels系统
AI智能体
能思考、能执行、能记忆的AI
Agent + Tools + Memory
网关
统一控制平面,永不关机
Gateway守护进程
24小时不间断
主动巡查,无需人工触发
心跳机制 + Cron任务

类比理解:智能电网模型


1.4 全维度对比分析:OpenClaw vs 其他方案

对比维度矩阵

对比维度 OpenClaw Claude Code Cursor ChatGPT CrewAI
开源
✅ MIT开源
❌ 闭源
❌ 闭源
❌ 闭源
✅ 开源
部署方式
本地部署
云端服务
云端服务
云端服务
自行部署
数据隐私
数据不出厂
代码上传云端
代码上传云端
对话上传云端
自行控制
主动执行
✅ 心跳巡查
❌ 人工触发
❌ 人工触发
❌ 人工触发
❌ 需开发
24小时运行
✅ Gateway守护
❌ 需IDE在线
❌ 需编辑器
❌ 需网页
❌ 需守护
工具扩展
Skills市场
受限工具集
受限
无工具
无市场
多渠道
25+渠道
仅IDE
仅IDE
仅Web/App
无
记忆持久
✅ 文件存储
⚠️ 项目内
⚠️ 项目内
❌ 会话内
⚠️ 需配置
成本
LLM API费
$20/月
$20/月
$20/月
自行成本
开箱即用
✅ 一键部署
✅
✅
✅
❌ 需开发

1.5 核心价值主张总结

OpenClaw 解决的核心痛点

痛点 传统方案 OpenClaw解决方案 用户价值
需要人工触发
每次都要打开应用、输入指令
Gateway心跳巡查,主动执行
省时间、不遗漏
数据隐私担忧
数据上传云端,不可控
本地部署,数据不出厂
安全、合规
能力受限
只能对话,不能执行
Tools + Skills,真实执行
真干活、有产出
单渠道接入
只能在一个地方用
25+渠道,随时随地接入
方便、无缝
无长期记忆
每次对话都重新开始
文件存储记忆,跨会话持久
智能、连贯
定制能力弱
闭源产品,无法修改
开源+Skills市场,自由扩展
灵活、可控


Part 2: 总体架构 —— 五层模型解析

2.1 五层架构全景图

五层金字塔模型详解

OpenClaw采用分层架构设计:

各层职责详解

层级 名称 核心职责 关键组件 技术栈
L5
Communication Channels
多渠道接入与消息路由
Provider插件、WebSocket连接
各渠道自有协议
L4
Gateway
守护进程、会话管理、心跳巡查
WebSocket Server、HTTP API、Control UI
TypeScript、Node.js
L3
Agent
思考推理、任务执行、结果检查
Pi Loop、Memory Manager、Tool Registry
pi-agent-core
L2
Tools & Skills
执行具体操作、提供专业知识
Built-in Tools、Skills文件、MCP Server
各工具自有实现
L1
LLM
提供思考推理能力
Model Registry、Auth Profiles
Anthropic/OpenAI/GLM API

2.2 Gateway-centric 设计哲学

核心设计原则:单控制平面

设计格言:

为什么必须是单Gateway?

原因 说明 后果(如果多Gateway)
Single Baileys session
WhatsApp连接不能split
Duplicate messages、连接冲突
Session consistency
所有state由Gateway管理
Session撕裂、状态不一致
Event serialization
Agent runs通过per-session queue
Tool races、并发冲突
Memory ownership
记忆文件由Gateway刷盘
数据覆盖、记忆丢失

Gateway架构模型

Wire Protocol:简单但类型化

协议设计原则:

  • • 不用binary protocol(orchestration系统不需要那点latency gain)
  • • Text frames with JSON payloads(易debug)
  • • TypeBox → JSON Schema → Swift codegen(end-to-end typed)

协议格式:

// Request(客户端发起){  "type": "req",  "id": "abc123",  "method": "agent",  "params": {    "message": "帮我查一下飞书文档",    "sessionId": "session-xxx"  }}// Response(服务端返回){  "type": "res",  "id": "abc123",  "ok": true,  "payload": {    "assistantTexts": ["已找到文档..."],    "toolMetas": [...]  }}// Event(服务端推送){  "type": "event",  "event": "agent",  "payload": {    "sessionId": "session-xxx",    "status": "running"  },  "seq": 42}

2.3 数据流向完整解析

完整数据流路径

完整数据流(用户消息到结果反馈):1. 用户发送消息   ↓2. Channel Provider接收   → 飞书WebSocket接收消息   → Telegram Bot API接收消息   ↓3. Gateway消息路由   → 解析消息来源(用户ID、群组ID)   → 根据bindings匹配Agent   → 创建/复用Session   ↓4. Agent会话处理   → 加载历史记忆   → 构建System Prompt   → 加载Skills   ↓5. LLM推理   → 发送到Claude/GPT/GLM API   → 接收流式响应   → 解析tool_use   ↓6. 工具调用循环   → 执行工具函数(如read、browser)   → 获取工具结果   → 继续LLM推理   ↓7. 结果生成   → 整合assistantTexts   → 收集toolMetas   → 计算usage统计   ↓8. Gateway记忆刷盘   → 写入session transcript   → 提取关键信息到MEMORY.md   → 写入memory/YYYY-MM-DD.md   ↓9. 消息回复   → 通过Channel Provider发送   → 支持富文本、图片、文件   ↓10. 用户收到回复

并发与队列控制

Session Lane机制:

Session Lane(会话车道):每个Session有一个独立的车道(Lane)Session A → Lane A → 串行执行所有runsSession B → Lane B → 串行执行所有runsSession C → Lane C → 串行执行所有runs防止同一Session内的并发冲突

Global Lane(可选):

Global Lane(全局车道):跨Session的并发控制防止过多Agent同时运行LLM调用配置示例:{  agents: {    globalLane: {      maxConcurrent: 5,  // 最多5个Agent同时运行      queueSize: 100      // 队列容量100    }  }}

2.4 Gateway连接握手流程

完整握手协议

角色 说明 典型使用
operator
控制面角色,管理Gateway
CLI、macOS App、Control UI
node
能力节点,暴露命令表面
iOS、Android、Headless设备

Scope权限控制:

Scope 权限范围
operator.read
读取状态、查看日志
operator.write
发送消息、创建Session
operator.admin
管理配置、重启Gateway

2.5 Gateway常用命令详解

状态查看命令

# 查看Gateway基本状态openclaw gateway status输出示例:┌─────────────────────────────────┐│ Gateway Status                   ││                                  ││ Status:     Running              ││ Port:       18789                ││ Uptime:     3d 12h 30m           ││ Agents:     2 running            ││ Sessions:   15 active            ││ Channels:   3 connected          ││                                  │└─────────────────────────────────┘# 深度检查(包含详细诊断)openclaw gateway status --deep输出示例:┌─────────────────────────────────┐│ Deep Gateway Status              ││                                  ││ WebSocket Connections:           ││   - macOS App: Connected         ││   - iOS Node: Connected          ││                                  ││ Channel Providers:               ││   - Feishu: Connected ✓          ││   - Telegram: Connected ✓        ││   - Discord: Disconnected ✗     ││                                  ││ Agent Instances:                 ││   - main: Running, 8 sessions    ││   - work: Running, 3 sessions    ││                                  ││ Memory:                          ││   - Total: 1.2GB                 ││   - Sessions: 800MB              ││                                  ││ Errors (last 24h):               ││   - 2 rate limit errors          ││   - 1 timeout                    ││                                  │└─────────────────────────────────┘

健康检查命令

# Gateway健康检查openclaw gateway health输出示例:Gateway health check:  ✓ Gateway process running  ✓ WebSocket server responsive  ✓ HTTP API responsive  ✓ Channels connected (2/3)  ✓ Agents healthy  ✓ Memory usage normalStatus: HEALTHY# 渠道状态检查openclaw channels status --probe输出示例:Channel Status:  Feishu:    ✓ WebSocket connected    ✓ Message receive OK    ✓ Message send OK    Last message: 2 minutes ago  Telegram:    ✓ Bot API connected    ✓ Polling active    Last message: 5 minutes ago  Discord:    ✗ Gateway disconnected    Error: Token expired    Action needed: Refresh token

日志查看命令

# 实时日志跟踪openclaw logs --follow输出示例:2026-04-24 00:00:00 [INFO] Gateway heartbeat check2026-04-24 00:00:05 [INFO] Session main:user:ou_xxx received message2026-04-24 00:00:10 [INFO] Agent started reasoning2026-04-24 00:00:15 [INFO] Tool call: feishu_fetch_doc2026-04-24 00:00:20 [INFO] Tool result: doc content retrieved2026-04-24 00:00:25 [INFO] Agent generated response2026-04-24 00:00:30 [INFO] Message sent to Feishu# 错误日志过滤openclaw logs --filter error# 最近100条日志openclaw logs --limit 100

Part 3: 核心16模块

3.1 Gateway网关核心模块

Gateway六大核心功能详解

功能一:不关机(守护进程)

技术实现:

Gateway Daemon 代码逻辑(简化版):async function main() {  // 初始化  const gateway = await initializeGateway();  // 无限循环  while (true) {    try {      // 心跳检查      await heartbeatCheck();      // 处理消息队列      await processMessageQueue();      // 执行Cron任务      await executeCronJobs();      // 刷盘记忆      await flushMemory();      // 等待下一个周期      await sleep(config.heartbeatInterval);    } catch (error) {      // 错误处理      await handleError(error);      // 自动恢复      if (shouldRestart(error)) {        await restartGateway();      }    }  }}

配置参数:

{  gateway: {    daemon: {      enabled: true,      heartbeatInterval: 300000,  // 5分钟      autoRestart: true,      maxRestartAttempts: 3    }  }}

功能二:连接平台(多渠道接入)

渠道架构:

渠道特性对比表:

渠道 协议 连接方式 消息类型 特殊能力
飞书
WebSocket
长连接
文本、富文本卡片、文件
企业级、卡片交互
Telegram
Bot API
HTTP Polling
文本、Markdown、图片
国际化、群组管理
Discord
Gateway WS
长连接
文本、Embed、图片
社区、频道管理
WhatsApp
Baileys
长连接(QR配对)
文本、图片、语音
个人通信、端到端加密
Signal
signal-cli
CLI封装
文本、图片
安全通信
iMessage
BlueBubbles
macOS服务
文本、图片、文件
Apple集成
Slack
RTM API
WebSocket
文本、Block Kit
企业协作
微信
WeChaty
长连接
文本、图片
国内生态

功能三:会话隔离

隔离机制:

配置示例:

{  session: {    dmScope: "per-channel-peer",  // DM隔离策略    groupScope: "per-channel-group",  // 群聊隔离策略    // Session过期策略    reset: {      daily: { hour: 4 },  // 每天4:00重置      idleMinutes: 120     // 120分钟无活动重置    }  }}

功能四:排队控制

Task Queue架构:


功能五:心跳巡查

心跳检查内容详解:

检查项 检查频率 具体内容 发现后动作
未读消息
5分钟
飞书/Telegram/Discord未读消息
读取→处理→回复
日程提醒
10分钟
日历中即将开始的事件
提前2小时提醒用户
Cron任务
按计划
定时任务队列
执行日报生成、数据备份等
邮件检查
15分钟
重要邮件(可配置)
摘要→发送通知
系统状态
30分钟
Gateway健康、Agent状态
异常→自动恢复→通知用户
数据监控
60分钟
自定义数据源
异常→告警→发送通知

心跳配置示例:

{  gateway: {    heartbeat: {      enabled: true,      interval: 300000,  // 5分钟      checks: [        { type: "messages", interval: 300000 },        { type: "calendar", interval: 600000 },        { type: "cron", interval: 60000 },        { type: "system", interval: 1800000 }      ]    }  }}

功能六:记忆刷盘

记忆存储流程:

记忆刷盘流程:实时交互  ↓短期记忆(Session Transcript)  → 存储在内存中  → 实时记录所有消息、工具调用、结果  ↓定期刷盘(每1分钟)  ↓长期记忆文件  → memory/YYYY-MM-DD.md(每日记忆)  → MEMORY.md(关键信息提取)  ↓会话重启恢复  → 加载MEMORY.md  → 加载最近的daily memory  → 恢复上下文

存储内容详解:

存储位置 内容 格式 用途
sessions/<id>.jsonl
Session transcript
JSONL append-only
完整对话历史
memory/YYYY-MM-DD.md
每日交互日志
Markdown
日常回顾
MEMORY.md
关键信息提取
Markdown
跨会话记忆
auth-profiles.json
API认证配置
JSON
模型认证

3.2 Agentic Loop 推理循环

推理循环核心架构

四层架构:

详细流程解析

单次推理尝试完整流程:

工具调用循环详解

工具循环工作原理:

关键调用链

完整调用链(从用户消息到结果):用户消息  ↓runAgentTurnWithFallback()  (agent-runner-execution.ts)  ↓runEmbeddedPiAgent()  (pi-embedded-runner/run.ts)  ↓ [while循环 - 重试]runEmbeddedAttempt()  (pi-embedded-runner/run/attempt.ts)  ↓createAgentSession()  + activeSession.prompt()  ↓ [LLM调用 + 工具循环]subscribeEmbeddedPiSession()  (pi-embedded-subscribe.ts)  ↓事件分发  → message_start/update/end  → tool_execution_*  ↓返回payloads

工具调用循环(Tool Loop):

工具调用循环(Tool Loop):LLM Response (包含 tool_use)  ↓SDK识别 tool_use  ↓handleToolExecutionStart  → 解析工具名称、参数  → 检查工具是否在allowlist  → 检查是否需要approval  ↓Execute Tool Function  → 执行具体工具函数  → 可能是read、exec、browser等  ↓handleToolExecutionUpdate  → 流式报告执行进度  ↓handleToolExecutionEnd  → 收集工具结果  → 格式化为tool_result  ↓添加 tool_result 到历史  ↓继续调用 LLM  → LLM看到工具结果  → 可能继续调用工具  → 或生成最终回复  ↓循环继续...

3.3 Channels多渠道系统

渠道全景分类

三大类渠道:

渠道配置详解

飞书渠道配置:

{  channels: {    feishu: {      enabled: true,      // 应用配置      appId: "cli_xxx",      appSecret: "xxx",      // DM访问策略      dmPolicy: "allowlist",  // 或 pairing/open/disabled      allowFrom: ["ou_xxx", "ou_yyy"],      // 群聊配置      groups: {        "*": { requireMention: true },  // 所有群需@提及        "oc_xxx": { requireMention: false }  // 特定群无需@      },      // 消息配置      messages: {        mentionPatterns: ["@OpenClaw", "openclaw"],        replyQuoted: true  // 支持引用回复      }    }  }}

DM配对策略详解

Policy 行为 适用场景 配置示例
pairing
未知发送者收到配对码,需输入验证
个人使用、安全优先
dmPolicy: "pairing"
allowlist
仅白名单用户可直接对话
团队内部使用
allowFrom: ["ou_xxx"]
open
公开接入,任何人可对话(需显式opt-in)
公共服务、演示
dmPolicy: "open"
disabled
拒绝所有私聊,仅群聊
仅群聊机器人
dmPolicy: "disabled"

配对流程:

DM配对流程(pairing策略):未知发送者发送消息  ↓Gateway检测到未知ID  ↓发送配对请求  → "你是谁?请输入配对码以验证身份"  → 显示6位配对码(如123456)  ↓用户输入配对码  ↓Gateway验证  → 配对码正确 → 批准配对  → 配对码错误 → 拒绝或重试  ↓批准后  → 添加到trusted list  → 允许后续对话管理员手动批准:openclaw pairing approve feishu 123456

3.4 Nodes设备节点系统

Nodes架构详解

Node概念:Node = 设备(IOS、Android,PC),连接Gateway WebSocket,暴露命令表面。

Node类型与能力

Node类型 平台 暴露命令 典型用途
macOS Node
macOS菜单栏应用
canvas., camera., system.run
桌面控制、截图、远程执行
iOS Node
iPhone/iPad App
canvas., camera., device.*, location.get
移动拍照、定位、通知
Android Node
手机/平板App
canvas., camera., notifications.*
移动拍照、通知管理
Headless Node
远程执行机
system.run
远程命令执行、CI/CD

Node命令表面详解

命令表面 功能 参数示例 返回结果
camera.snap
拍照
{ facing: "front" } { imageKey: "img_xxx" }
camera.clip
录制视频
{ duration: "30s", facing: "back" } { videoKey: "vid_xxx" }
screen.record
彏幕录制
{ durationMs: 60000 } { videoKey: "vid_xxx" }
location.get
获取GPS位置
{ desiredAccuracy: "precise" } { lat: 31.x, lon: 121.x }
notifications.list
查看通知
{ limit: 20 } { notifications: [...] }
notifications.action
操作通知
{ key: "xxx", action: "open" } { success: true }
canvas.present
显示Canvas
{ url: "https://..." } { success: true }
canvas.snapshot
Canvas截图
{ } { imageKey: "img_xxx" }

Part 4: 核心16模块详解

4.1 Tools工具三层架构

三层架构详解

Layer 1: Built-in Tools(内置工具)

工具 功能 参数示例 使用场景
exec
执行Shell命令
{ command: "git status", timeout: 30000 }
系统操作、脚本执行
read
读取文件
{ path: "/path/to/file" }
文档读取、配置解析
write
写入文件
{ path: "/path/to/file", content: "..." }
创建文件、保存数据
edit
编辑文件
{ path: "...", oldText: "...", newText: "..." }
精确修改、代码编辑
browser
控制Chromium
{ action: "navigate", url: "..." }
网页操作、截图
web_search
网络搜索
{ query: "OpenClaw architecture" }
信息检索
web_fetch
抓取网页
{ url: "...", maxChars: 5000 }
内容提取
message
发送消息
{ action: "send", to: "...", message: "..." }
主动通知
canvas
驱动Canvas
{ action: "present", url: "..." }
可视化展示
nodes
节点管理
{ action: "status" }
设备发现、调用
cron
定时任务
{ action: "add", job: {...} }
任务调度
gateway
网关管理
{ action: "restart" }
配置、重启

Layer 2: Skills(技能系统)

Skills = 基础工具 + 专业知识 + 工作流程

Skills 基础工具组合 专业知识 工作流程
github
exec (gh CLI)
GitHub API知识、Issue/PR规范
创建Issue → 审核 → 合并
feishu-doc
web_fetch + read
飞书协议、Wiki结构
解析URL → 获取内容 → Markdown转换
autoglm-browser
browser + web_search
浏览器自动化最佳实践
打开网页 → 搜索 → 截图 → 提取
weather
web_fetch
天气API、数据解析
获取API → 解析JSON → 格式化输出
summarize
read + web_fetch
内容总结技巧、关键点提取
读取内容 → 提取要点 → 生成摘要

Layer 3: External Tools(外部工具)

类型 说明 接入方式
MCP Server
模型上下文协议
mcporter桥接
Third-party API
第三方服务
直接HTTP调用
Custom Tools
用户自定义工具
编写Tools文件

4.2 Skills技能系统详解

Skills核心公式

Skills加载优先级

Skills加载顺序(从高到低优先级):1. <workspace>/skills   → 工作区技能(项目特定)   → 最高优先级2. <workspace>/.agents/skills   → 项目Agent技能   → 项目团队共享3. ~/.agents/skills   → 个人Agent技能   → 个人私有4. ~/.openclaw/skills   → 托管技能   → 从ClawHub安装5. bundled skills   → 内置技能   → OpenClaw自带6. skills.load.extraDirs   → 额外目录   → 自定义位置同一技能名,优先级高的覆盖低的

Skills文件格式详解

---name: githubdescription: GitHub操作技能 - issue/PR/CI管理metadata: {  "openclaw": {    "requires": {      "bins": ["gh"],      // 需要gh CLI      "env": ["GITHUB_TOKEN"]  // 需要环境变量    },    "homepage": "https://clawhub.ai/skills/github"  }}---# GitHub操作技能使用 gh CLI 进行 GitHub 操作。## 使用场景- 创建/管理 GitHub Issue- 提交/审核 Pull Request- 查看 CI/CD 运行状态- 搜索代码仓库## 工具列表- gh issue create/list/view- gh pr create/list/merge- gh run list/view## 工作流程### 创建Issue1. 确认Issue标题和描述2. 构建gh命令:gh issue create --title "..." --body "..."3. 执行命令4. 解析结果,返回Issue URL### 提交PR1. 确认分支名称和目标2. gh pr create --base main --head feature-xxx3. 添加reviewers4. 返回PR URL## 注意事项- 需要先配置GITHUB_TOKEN- 确保gh CLI已安装- 注意权限控制

4.3 Session会话管理详解

Session Key格式解析

Session Key格式:agent:<agentId>:<mainKey>mainKey类型:- user:<openId>         // DM私聊- chat:<chatId>         // 群聊- thread:<threadId>     // 话题- guild:<guildId>       // Discord服务器- account:<accountId>   // 账户级别示例:agent:main:user:ou_xxx           → 主Agent与用户ou_xxx的私聊agent:work:chat:oc_xxx           → Work Agent与群oc_xxx的群聊agent:family:thread:omt_xxx      → Family Agent在话题omt_xxx中agent:main:guild:discord_xxx     → 主Agent在Discord服务器中

Session路由规则

匹配规则 优先级 说明
peer精确匹配
最高
DM/群组精确路由
parentPeer
高
话题继承父会话
guildId+roles
中
Discord角色匹配
accountId
低
账户级别匹配
默认Agent
最低
无匹配时使用默认

Session生命周期

Session生命周期:创建  → 用户首次发送消息  → Gateway创建Session  → 分配Session Key复用  → 同一用户/群组再次发消息  → 复用已有Session  → 加载历史记忆运行  → Agent处理消息  → 调用工具  → 生成回复  → 刷盘记忆过期  → 触发重置条件  → Daily reset(每天4:00)  → Idle reset(120分钟无活动)销毁  → Session过期后  → 清理session transcript  → 保留MEMORY.md(长期记忆)

4.4 Memory记忆管理详解

Memory存储结构

Memory刷盘机制

刷盘流程:实时记录  → 每条消息、工具调用、结果  → 写入Session Transcript  → 内存中定期刷盘(每1分钟)  → Session Transcript写入sessions/<id>.jsonl  → 提取关键信息写入memory/YYYY-MM-DD.md  → 重要决策、用户偏好写入MEMORY.md会话重启  → 加载MEMORY.md(长期记忆)  → 加载最近3天的memory/YYYY-MM-DD.md  → 恢复上下文

4.5 Cron定时任务系统详解

Cron任务类型

类型 说明 配置示例
systemEvent
注入系统事件到Session
{ kind: "systemEvent", text: "早安提醒" }
agentTurn
Agent主动执行任务
{ kind: "agentTurn", message: "生成日报" }

调度模式详解

模式 说明 配置示例
at
一次性定时(ISO 8601时间戳)
{ kind: "at", at: "2026-04-24T09:00:00+08:00" }
every
周期性间隔(毫秒)
{ kind: "every", everyMs: 86400000 }

(每天)
cron
Cron表达式(标准格式)
{ kind: "cron", expr: "0 9 * * 1-5", tz: "Asia/Shanghai" }

(工作日9点)

投递方式详解

方式 说明 使用场景
none
静默执行,无通知
后台任务、数据备份
announce
公告通知,发送到指定渠道
定时报送、提醒通知
webhook
HTTP POST回调
与外部系统集成

Cron配置完整示例

{  cron: {    jobs: [      // 早间提醒(工作日9点)      {        name: "早间提醒",        schedule: { kind: "cron", expr: "0 9 * * 1-5", tz: "Asia/Shanghai" },        payload: {           kind: "systemEvent",           text: "早安!今日日程提醒:检查邮件和日程安排"         },        delivery: { mode: "announce" },        sessionTarget: "main"      },      // 每日日报(每天18点)      {        name: "每日日报",        schedule: { kind: "cron", expr: "0 18 * * *", tz: "Asia/Shanghai" },        payload: {           kind: "agentTurn",           message: "生成今日工作日报并发送到飞书群",          timeoutSeconds: 300        },        delivery: { mode: "announce", channel: "feishu", to: "oc_xxx" },        sessionTarget: "isolated"      },      // 每小时数据监控      {        name: "数据监控",        schedule: { kind: "every", everyMs: 3600000 },        payload: {           kind: "agentTurn",           message: "检查关键数据指标,如有异常发送告警"        },        delivery: { mode: "webhook", to: "https://api.example.com/callback" },        sessionTarget: "isolated"      }    ]  }}

Part 5: 安全机制 —— 沙箱隔离与权限设计

5.1 安全设计哲学

核心原则:Strong defaults + Explicit knobs

设计权衡:

策略 说明 配置
Default powerful
main session有完整权限
不配置sandbox
Group safety
非主会话沙箱隔离
sandbox.mode: "non-main"
DM pairing
未知发送者需配对
dmPolicy: "pairing"
Tool approval
破坏性操作需批准
exec.ask: "elevated"

5.2 Sandbox沙箱机制详解

Docker隔离架构

Sandbox配置详解

{  sandbox: {    enabled: true,    // Docker配置    dockerImage: "openclaw-sandbox:latest",    dockerOptions: {      memory: "512m",      cpuShares: 512    },    // 工具策略    toolPolicy: {      browser: "deny",        // 禁止浏览器      exec: "allowlist",      // 仅允许白名单命令      system: "deny",         // 禁止系统命令      canvas: "deny"          // 禁止Canvas    },    // 命令白名单    execAllowlist: [      "/usr/bin/git",      "/usr/bin/node",      "/usr/bin/npm",      "/usr/bin/python3"    ],    // 文件访问限制    fsPolicy: {      allowPaths: [        "/tmp/sandbox",        "/workspace/sandbox"      ],      denyPaths: [        "~/.openclaw",        "~/.ssh"      ]    }  }}

5.3 DM Policy详解

四种Policy对比

Policy 行为 安全级别 适用场景
pairing
未知发送者需配对码验证
最高
个人使用、高安全需求
allowlist
仅白名单用户可对话
高
团队内部、企业使用
open
公开接入,任何人可对话
低
公共服务、演示Demo
disabled
拒绝所有私聊
最高
仅群聊机器人

配置示例

{  channels: {    // 飞书:白名单策略    feishu: {      dmPolicy: "allowlist",      allowFrom: [        "ou_ee09fa76de1e9e130bf6c3857034674a",  // 军哥        "ou_xxx",  // 其他团队成员        "ou_yyy"      ]    },    // Telegram:配对策略    telegram: {      dmPolicy: "pairing",      pairingTimeout: 60000  // 配对码有效期60秒    },    // Discord:仅群聊    discord: {      dmPolicy: "disabled",      groups: {        "*": { requireMention: true }      }    }  }}

5.4 Tool Approval Gates

工具批准机制

需要批准的操作类型:

操作类型 命令示例 批准方式
破坏性文件操作
rm、delete、drop
/approve

 或 Control UI
提升权限命令
sudo、chmod、chown
/approve elevated
外部网络调用
curl、wget(非白名单域名)
/approve network
敏感工具调用
gateway.restart、cron.add
/approve admin

配置示例

{  tools: {    exec: {      security: "ask",        // 执行前询问      ask: "elevated",        // 提升权限命令需批准      // 白名单命令(无需批准)      allowlist: [        "git status",        "git log",        "ls",        "cat"      ],      // 黑名单命令(禁止)      denylist: [        "rm -rf",        "sudo rm",        "format"      ]    }  }}

Part 6: 企业级智能体演进

6.1 Multi-Agent架构详解

Multi-Agent核心概念

一个Gateway运行多个隔离Agent:

Multi-Agent架构:Gateway进程  ├── Agent: main  │   ├── Workspace: ~/.openclaw/workspace  │   ├── agentDir: agents/main/  │   ├── Sessions: 独立存储  │   ├── Auth Profiles: 独立配置  │   ├── Skills: github, weather, feishu-doc  │   └── Persona: 龙虾仔仔 🦞  │  ├── Agent: work  │   ├── Workspace: ~/workspace-work  │   ├── agentDir: agents/work/  │   ├── Sessions: 独立存储  │   ├── Skills: github, slack, calendar  │   └ Persona: 工作助手 💼  │  └── Agent: family      ├── Workspace: ~/workspace-family      ├── agentDir: agents/family/      ├── Sessions: 独立存储      ├── Skills: weather, calendar, todo      └ Persona: 家庭助手 🏠

完整配置示例

{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"]      }    },    list: [      {        id: "main",        workspace: "~/.openclaw/workspace",        skills: ["github", "weather", "feishu-doc"]      },      {        id: "work",        workspace: "~/.openclaw/workspace-work",        skills: ["github", "slack", "calendar"],        model: {          primary: "anthropic/claude-opus-4"  // 更强模型        }      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        skills: ["weather", "calendar", "todo"],        model: {          primary: "openai/gpt-4o-mini"  // 更便宜模型        }      }    ]  },  bindings: [    // 军哥的飞书私聊 → main Agent    {      agentId: "main",      match: {        channel: "feishu",        peer: { kind: "direct", id: "ou_ee09fa76de1e9e130bf6c3857034674a" }      }    },    // Discord技术群 → work Agent    {      agentId: "work",      match: {        channel: "discord",        guildId: "xxx"      }    },    // WhatsApp家庭群 → family Agent    {      agentId: "family",      match: {        channel: "whatsapp",        peer: { kind: "group", id: "+1555xxx" }      }    }  ]}

6.2 Sub-Agent子智能体

sessions_spawn详解

创建隔离子智能体:

// Spawn参数{  runtime: "subagent",  // 或 "acp"  mode: "run",          // 或 "session"  task: "分析这份飞书文档并生成摘要",  model: "anthropic/claude-opus-4",  // 可指定更强模型  timeoutSeconds: 300,  thinking: "enabled",  // 或 "disabled"  cwd: "/workspace/subagent-tasks",  sandbox: "require",   // 要求沙箱隔离  attachments: [    { name: "doc.pdf", content: "...", mimeType: "application/pdf" }  ]}

runtime模式对比

runtime 说明 特点
subagent
OpenClaw子智能体
轻量、快速、继承Skills
acp
ACP编码会话(Codex/Claude Code)
专业编程、长时间任务

6.3 自进化机制详解

三层自进化机制

自进化三层机制:1. Skill Workshop   → 从观察到的工作流程创建Skills   → 分析Agent执行的任务模式   → 自动生成SKILL.md文件   → 添加到Skills目录2. Hermes Evolution   → 根据经验优化行为规则   → 分析Agent的成功/失败案例   → 更新AGENTS.md中的规则   → 自动改进Agent行为3. Memory Reflection   → 定期反思更新长期记忆   → 回顾memory/YYYY-MM-DD.md   → 提取关键经验写入MEMORY.md   → 保持记忆的连贯性

Part 7: 最佳实践与部署

7.1 快速部署完整指南

安装步骤详解

完整安装流程:步骤1: 安装Node.js  → 推荐v24 LTS  → macOS: brew install node@24  → Windows: 官网下载安装包步骤2: 安装OpenClaw  → macOS/Linux: curl -fsSL https://openclaw.ai/install.sh | bash  → Windows: iwr -useb https://openclaw.ai/install.ps1 | iex  → npm: npm install -g openclaw@latest步骤3: 运行onboarding  → openclaw onboard --install-daemon  → 配置渠道(飞书/Telegram等)  → 选择模型(Claude/GPT/GLM)  → 设置Workspace步骤4: 验证Gateway  → openclaw gateway status  → 确认Running状态  → 检查Channels连接步骤5: 打开Dashboard  → openclaw dashboard  → 浏览器打开 http://localhost:18789  → 管理Agent、查看日志

7.2 配置文件结构详解

完整配置文件结构:~/.openclaw/├── openclaw.json           # 主配置文件(JSON5格式)│   ├── agents              # Agent配置│   ├── bindings            # 路由规则│   ├── channels            # 渠道配置│   ├── gateway             # Gateway配置│   ├── sandbox             # 沙箱配置│   ├── tools               # 工具配置│   ├── cron                # 定时任务│   └── memory              # 记忆配置│├── agents/│   ├── main/│   │   ├── agent/│   │   │   ├── auth-profiles.json    # API认证│   │   │   ├── model-registry.json   # 模型注册│   │   │   └── skills-snapshot.json  # Skills快照│   │   └── sessions/│   │   │   ├── sessions.json         # Session索引│   │   │   └── <session-id>.jsonl    # Session transcript│   ││   └── work/│   │   ├── agent/│   │   └── sessions/│├── workspace/              # 默认工作区│   ├── AGENTS.md           # Agent行为规则│   ├── SOUL.md             # Agent性格定义│   ├── USER.md             # 用户信息│   ├── MEMORY.md           # 长期记忆│   ├── TOOLS.md            # 工具本地配置│   ├── HEARTBEAT.md        # 心跳任务│   ├── skills/             # 工作区技能│   └── memory/             # 每日记忆│       └── YYYY-MM-DD.md│└── skills/                 # 托管技能目录    ├── github/    │   └── SKILL.md    ├── feishu-doc/    │   └ SKILL.md    └── ...

7.3 常见问题排查手册

问题诊断表

问题 可能原因 诊断命令 解决方案
Gateway启动失败
配置验证错误
openclaw doctor --fix
修复配置、检查JSON语法
渠道连接失败
Token错误/网络问题
openclaw channels status --probe
更新Token、检查网络
消息无响应
Session路由错误
检查bindings配置
修正路由规则
工具调用失败
权限限制
检查tools.allow/deny
调整工具策略
内存泄漏
Session历史过长
session.maxHistoryLength
配置历史长度限制
配对失败
配对码过期
重新发送配对请求
延长配对超时时间
LLM调用超时
网络问题/模型过载
openclaw logs --filter timeout
配置fallback模型
Rate Limit
API调用过快
gateway.queue.rateLimit
降低QPM/TPM

7.4 资源汇总

关键资源汇总

资源类型 名称 链接 说明
官方文档
OpenClaw Docs
https://docs.openclaw.ai
完整配置与使用指南
源码仓库
GitHub
https://github.com/openclaw/openclaw
MIT开源源码
技能市场
ClawHub
https://clawhub.com
Skills技能分享平台
社区支持
Discord
https://discord.com/invite/clawd
活跃技术讨论

附录:Q&A预设问题

Q1: OpenClaw和Claude Code有什么本质区别?

核心区别:主动执行能力

维度 Claude Code OpenClaw
触发方式
人工触发(在IDE中)
Gateway心跳巡查,主动执行
运行时间
IDE打开时运行
24×7永不关机
接入渠道
仅IDE
飞书/Telegram/Discord等25+渠道
记忆持久
项目内有效
文件存储,跨会话持久

Q2: Gateway为什么被称为”心脏”?

Gateway是统一控制平面,负责所有关键功能:

功能 说明
消息路由
所有消息流量经过Gateway
会话管理
Session生命周期管理
心跳巡查
主动发现任务、执行
记忆刷盘
确保数据持久化
工具协调
防止并发冲突
节点通信
iOS/Android设备桥接

Q3: Skills如何理解?

公式:Skills = 基础工具 + 专业知识 + 工作流程

示例:

  • • read是基础工具
  • • github是Skills
  • • github = exec工具 + GitHub专业知识 + Issue/PR工作流程

Q4: Multi-Agent有什么实际应用场景?

三大场景:

场景 说明
多用户共享
家人共享一个Gateway,各自有独立Agent
性格切换
工作Agent(严肃)vs 家庭Agent(温馨)
渠道隔离
飞书Agent(企业)vs WhatsApp Agent(个人)

Q5: 如何保证安全?

五层安全机制:

层级 机制
DM配对
未知发送者需配对码验证
Docker沙箱
非主会话隔离运行
工具黑白名单
敏感工具受限
批准机制
破坏性操作需确认
Local-First
数据不上传云端

Q6: 数据隐私如何保证?

本地部署,数据不出厂:

数据类型 存储位置 是否上传云端
文件内容
本地Workspace
❌ 不上传
会话历史
本地sessions.json
❌ 不上传
API密钥
本地auth-profiles.json
❌ 不上传
记忆数据
本地MEMORY.md
❌ 不上传
LLM调用
仅对话文本
⚠️ 仅对话文本发送

Q7: Gateway心跳巡查具体做什么?

六大检查项:

检查项 频率 动作
未读消息
5分钟
读取→处理→回复
日程提醒
10分钟
提前2小时提醒
Cron任务
按计划
执行定时任务
邮件检查
15分钟
摘要→发送通知
系统状态
30分钟
异常→自动恢复
数据监控
60分钟
异常→告警

Q8: 如何快速上手?

4步快速上手:

1. 安装OpenClaw   curl -fsSL https://openclaw.ai/install.sh | bash2. 运行onboarding   openclaw onboard --install-daemon3. 配置飞书机器人   在飞书开放平台创建应用,获取AppId/AppSecret4. 发送第一条消息   在飞书中@机器人,开始对话

Q9: Cron定时任务怎么配置?

完整示例:

{  cron: {    jobs: [      {        name: "每日日报",        schedule: { kind: "cron", expr: "0 18 * * *", tz: "Asia/Shanghai" },        payload: { kind: "agentTurn", message: "生成今日工作日报" },        delivery: { mode: "announce", channel: "feishu", to: "oc_xxx" },        sessionTarget: "isolated"      }    ]  }}

Q10: 如何诊断问题?

诊断命令矩阵:

问题类型 诊断命令
Gateway状态
openclaw gateway status --deep
渠道连接
openclaw channels status --probe
错误日志
openclaw logs --filter error
健康检查
openclaw gateway health
自动修复
openclaw doctor --fix