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 → 串行执行所有runs
Session B → Lane B → 串行执行所有runs
Session 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 normal

Status: 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 check
2026-04-24 00:00:05 [INFO] Session main:user:ou_xxx received message
2026-04-24 00:00:10 [INFO] Agent started reasoning
2026-04-24 00:00:15 [INFO] Tool call: feishu_fetch_doc
2026-04-24 00:00:20 [INFO] Tool result: doc content retrieved
2026-04-24 00:00:25 [INFO] Agent generated response
2026-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: github
description: 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

## 工作流程

### 创建Issue
1. 确认Issue标题和描述
2. 构建gh命令：gh issue create --title "..." --body "..."
3. 执行命令
4. 解析结果，返回Issue URL

### 提交PR
1. 确认分支名称和目标
2. gh pr create --base main --head feature-xxx
3. 添加reviewers
4. 返回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 | bash
   
2. 运行onboarding
   openclaw onboard --install-daemon
   
3. 配置飞书机器人
   在飞书开放平台创建应用，获取AppId/AppSecret
   
4. 发送第一条消息
   在飞书中@机器人，开始对话

---

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