OpenClaw 深度解析
Part 1: 开篇 —— 为什么 OpenClaw 突然火了


1.1 AI应用演进时间线:从被动响应到主动执行
2022-2026:AI应用架构五次范式转变

范式转变的本质:从”被动响应”到”主动执行”
| 维度 | 传统ChatBot(2022-2024) | OpenClaw(2026) |
| 触发方式 |
|
|
| 运行时间 |
|
|
| 记忆持久 |
|
|
| 执行能力 |
|
|
| 接入渠道 |
|
|
| 部署位置 |
|
|
用户视角的转变

传统ChatBot体验:
用户:早上9点打开ChatGPT网页用户:输入 "帮我查一下今天的日程"ChatGPT:返回日程列表用户:关闭网页ChatGPT:停止运行,等待下次触发
OpenClaw体验:
Gateway:早上9点主动巡查Gateway:发现今天有重要会议Agent:主动发送飞书消息:"早安!今天10:00有产品评审会议,请提前准备材料"用户:收到提醒,无需主动询问Gateway:继续巡查下一个任务...
1.2 三大爆火原因深度剖析
原因一:24小时不间断工作
技术实现:Gateway守护进程 + 心跳巡查机制

心跳巡查的具体内容:
| 检查项 | 检查频率 | 发现后动作 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
原因二:信任权限高(本地部署,数据不出厂)
为什么信任重要?

OpenClaw的数据隐私保护机制:
| 数据类型 | 存储位置 | 是否上传云端 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
企业级场景的信任需求:

原因三:社区生态好(开源+技能市场+活跃社区)
MIT开源的优势:
| 维度 | 闭源商业产品 | OpenClaw开源 |
| 代码透明 |
|
|
| 定制能力 |
|
|
| 厂商锁定 |
|
|
| 成本 |
|
|
| 更新速度 |
|
|
ClawHub技能市场:
1.3 OpenClaw 核心定位:
定义解析
OpenClaw 是一个自托管的多渠道AI智能体网关,将你常用的聊天应用连接到AI编码代理,实现24小时不间断的智能助手服务。
拆解理解:
| 关键词 | 含义 | 技术对应 |
| 自托管 |
|
|
| 多渠道 |
|
|
| AI智能体 |
|
|
| 网关 |
|
|
| 24小时不间断 |
|
|
类比理解:智能电网模型

1.4 全维度对比分析:OpenClaw vs 其他方案
对比维度矩阵
| 对比维度 | OpenClaw | Claude Code | Cursor | ChatGPT | CrewAI |
| 开源 |
|
|
|
|
|
| 部署方式 |
|
|
|
|
|
| 数据隐私 |
|
|
|
|
|
| 主动执行 |
|
|
|
|
|
| 24小时运行 |
|
|
|
|
|
| 工具扩展 |
|
|
|
|
|
| 多渠道 |
|
|
|
|
|
| 记忆持久 |
|
|
|
|
|
| 成本 |
|
|
|
|
|
| 开箱即用 |
|
|
|
|
|
1.5 核心价值主张总结
OpenClaw 解决的核心痛点
| 痛点 | 传统方案 | OpenClaw解决方案 | 用户价值 |
| 需要人工触发 |
|
|
|
| 数据隐私担忧 |
|
|
|
| 能力受限 |
|
|
|
| 单渠道接入 |
|
|
|
| 无长期记忆 |
|
|
|
| 定制能力弱 |
|
|
|
Part 2: 总体架构 —— 五层模型解析

2.1 五层架构全景图
五层金字塔模型详解
OpenClaw采用分层架构设计:

各层职责详解
| 层级 | 名称 | 核心职责 | 关键组件 | 技术栈 |
| L5 |
|
|
|
|
| L4 |
|
|
|
|
| L3 |
|
|
|
|
| L2 |
|
|
|
|
| L1 |
|
|
|
|
2.2 Gateway-centric 设计哲学
核心设计原则:单控制平面
设计格言:
为什么必须是单Gateway?
| 原因 | 说明 | 后果(如果多Gateway) |
| Single Baileys session |
|
|
| Session consistency |
|
|
| Event serialization |
|
|
| Memory ownership |
|
|
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 |
|
|
| node |
|
|
Scope权限控制:
| Scope | 权限范围 |
operator.read |
|
operator.write |
|
operator.admin |
|
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 } }}
功能二:连接平台(多渠道接入)
渠道架构:

渠道特性对比表:
| 渠道 | 协议 | 连接方式 | 消息类型 | 特殊能力 |
| 飞书 |
|
|
|
|
| Telegram |
|
|
|
|
| Discord |
|
|
|
|
|
|
|
|
|
|
| Signal |
|
|
|
|
| iMessage |
|
|
|
|
| Slack |
|
|
|
|
| 微信 |
|
|
|
|
功能三:会话隔离
隔离机制:

配置示例:
{ session: { dmScope: "per-channel-peer", // DM隔离策略 groupScope: "per-channel-group", // 群聊隔离策略 // Session过期策略 reset: { daily: { hour: 4 }, // 每天4:00重置 idleMinutes: 120 // 120分钟无活动重置 } }}
功能四:排队控制
Task Queue架构:

功能五:心跳巡查
心跳检查内容详解:
| 检查项 | 检查频率 | 具体内容 | 发现后动作 |
| 未读消息 |
|
|
|
| 日程提醒 |
|
|
|
| Cron任务 |
|
|
|
| 邮件检查 |
|
|
|
| 系统状态 |
|
|
|
| 数据监控 |
|
|
|
心跳配置示例:
{ 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 |
|
|
|
memory/YYYY-MM-DD.md |
|
|
|
MEMORY.md |
|
|
|
auth-profiles.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 |
|
|
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 |
|
|
|
| iOS Node |
|
|
|
| Android Node |
|
|
|
| Headless Node |
|
|
|
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 |
|
{ desiredAccuracy: "precise" } |
{ lat: 31.x, lon: 121.x } |
| notifications.list |
|
{ limit: 20 } |
{ notifications: [...] } |
| notifications.action |
|
{ key: "xxx", action: "open" } |
{ success: true } |
| canvas.present |
|
{ url: "https://..." } |
{ success: true } |
| canvas.snapshot |
|
{ } |
{ imageKey: "img_xxx" } |
Part 4: 核心16模块详解
4.1 Tools工具三层架构

三层架构详解
Layer 1: Built-in Tools(内置工具)
| 工具 | 功能 | 参数示例 | 使用场景 |
| exec |
|
{ command: "git status", timeout: 30000 } |
|
| read |
|
{ path: "/path/to/file" } |
|
| write |
|
{ path: "/path/to/file", content: "..." } |
|
| edit |
|
{ path: "...", oldText: "...", newText: "..." } |
|
| browser |
|
{ action: "navigate", url: "..." } |
|
| web_search |
|
{ query: "OpenClaw architecture" } |
|
| web_fetch |
|
{ url: "...", maxChars: 5000 } |
|
| message |
|
{ action: "send", to: "...", message: "..." } |
|
| canvas |
|
{ action: "present", url: "..." } |
|
| nodes |
|
{ action: "status" } |
|
| cron |
|
{ action: "add", job: {...} } |
|
| gateway |
|
{ action: "restart" } |
|
Layer 2: Skills(技能系统)
Skills = 基础工具 + 专业知识 + 工作流程
| Skills | 基础工具组合 | 专业知识 | 工作流程 |
| github |
|
|
|
| feishu-doc |
|
|
|
| autoglm-browser |
|
|
|
| weather |
|
|
|
| summarize |
|
|
|
Layer 3: External Tools(外部工具)
| 类型 | 说明 | 接入方式 |
| MCP Server |
|
|
| Third-party API |
|
|
| Custom 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精确匹配 |
|
|
| parentPeer |
|
|
| guildId+roles |
|
|
| 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 |
|
{ kind: "systemEvent", text: "早安提醒" } |
| agentTurn |
|
{ kind: "agentTurn", message: "生成日报" } |
调度模式详解
| 模式 | 说明 | 配置示例 |
| at |
|
{ kind: "at", at: "2026-04-24T09:00:00+08:00" } |
| every |
|
{ kind: "every", everyMs: 86400000 }
|
| cron |
|
{ kind: "cron", expr: "0 9 * * 1-5", tz: "Asia/Shanghai" }
|
投递方式详解
| 方式 | 说明 | 使用场景 |
| none |
|
|
| announce |
|
|
| webhook |
|
|
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 |
|
|
| 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 |
|
|
|
| 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
工具批准机制
需要批准的操作类型:
| 操作类型 | 命令示例 | 批准方式 |
| 破坏性文件操作 |
|
/approve
|
| 提升权限命令 |
|
/approve elevated |
| 外部网络调用 |
|
/approve network |
| 敏感工具调用 |
|
/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 |
|
|
| acp |
|
|
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 |
|
| 渠道连接失败 |
|
openclaw channels status --probe |
|
| 消息无响应 |
|
bindings配置 |
|
| 工具调用失败 |
|
tools.allow/deny |
|
| 内存泄漏 |
|
session.maxHistoryLength |
|
| 配对失败 |
|
|
|
| LLM调用超时 |
|
openclaw logs --filter timeout |
|
| Rate Limit |
|
gateway.queue.rateLimit |
|
7.4 资源汇总
关键资源汇总
| 资源类型 | 名称 | 链接 | 说明 |
| 官方文档 |
|
|
|
| 源码仓库 |
|
|
|
| 技能市场 |
|
|
|
| 社区支持 |
|
|
|
附录:Q&A预设问题
Q1: OpenClaw和Claude Code有什么本质区别?
核心区别:主动执行能力
| 维度 | Claude Code | OpenClaw |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Q2: Gateway为什么被称为”心脏”?
Gateway是统一控制平面,负责所有关键功能:
| 功能 | 说明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Q3: Skills如何理解?
公式:Skills = 基础工具 + 专业知识 + 工作流程
示例:
-
• read是基础工具 -
• github是Skills -
• github=exec工具 + GitHub专业知识 + Issue/PR工作流程
Q4: Multi-Agent有什么实际应用场景?
三大场景:
| 场景 | 说明 |
| 多用户共享 |
|
| 性格切换 |
|
| 渠道隔离 |
|
Q5: 如何保证安全?
五层安全机制:
| 层级 | 机制 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Q6: 数据隐私如何保证?
本地部署,数据不出厂:
| 数据类型 | 存储位置 | 是否上传云端 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Q7: Gateway心跳巡查具体做什么?
六大检查项:
| 检查项 | 频率 | 动作 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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: 如何诊断问题?
诊断命令矩阵:
| 问题类型 | 诊断命令 |
|
|
openclaw gateway status --deep |
|
|
openclaw channels status --probe |
|
|
openclaw logs --filter error |
|
|
openclaw gateway health |
|
|
openclaw doctor --fix |
夜雨聆风