OpenClaw 核心概念学习笔记

本文档整理自 2026年3月7日 学习内容，适合有编程基础的读者。文章中有较多 asci 图适合电脑端打开阅读

一、OpenClaw 是什么？

OpenClaw（原名 Clawdbot / Moltbot）是一款开源的本地优先 AI 代理与自动化平台。

核心定位：不是聊天机器人，而是「AI 执行者」—— 能帮你干活的数字员工。

二、核心概念层级关系

2.1 完整层级结构

OpenClaw Gateway    │    ├── Agent (一个"人")    │       │    │       ├── Channel 1 (Telegram)    │       │       │    │       │       ├── Session A (私聊)    │       │       │       └── sandbox: off (主会话)    │       │       │    │       │       └── Session B (群组)    │       │               └── sandbox: non-main    │       │    │       ├── Channel 2 (飞书)    │       │       │    │       │       └── Session C (私聊)    │       │               └── sandbox: off    │       │    │       └── Channel 3 (Discord)    │               │    │               └── Session D (频道)    │                       │    │                       └── Subagents (子代理)    │                               ├── Subagent 1 (搜索任务)    │                               │       └── sandbox: on (隔离)    │                               │    │                               └── Subagent 2 (代码分析)    │                                       └── sandbox: on    │    └── Workspace (工作区)

2.2 关系总结

三、Session（会话）管理

3.1 Session 是什么？

Session 是 Agent 运行时的对话上下文，不是另一个 Agent。

Agent: main (一个"人")    │    ├── 会话 A: Dashboard 私聊 (main:main)    ├── 会话 B: Telegram 群组 (main:telegram:group-123)    └── 会话 C: 飞书频道 (main:feishu:channel-456)

3.2 Session Key 格式

3.3 dmScope（私信分组策略）

dmScope 控制的是：当多个人给你发私信时，OpenClaw 如何管理对话历史。

{"session":{"dmScope":"main"// main/per-peer/per-channel-peer/per-account-channel-peer}}

3.4 dmScope 具体例子

场景：你有 3 个人在 Telegram 给你发私信

dmScope: "main" （默认）┌─────────────────────────────────────────┐│ 会话: agent:main:main                   ││                                         ││ 张三: "帮我查天气"                      ││ 李四: "今天有什么新闻"                  ││ 王五: "帮我订外卖"                      ││                                         ││ ❌ 张三的对话全混在一起了               ││    AI 会混淆谁是谁                      │└────────────────────────────────────────┘dmScope: "per-peer"┌─────────────────────────────────────────┐│ 会话1: agent:main:telegram:user-zhang   ││   张三: "帮我查天气"                    ││   (独立上下文)                          │├─────────────────────────────────────────┤│ 会话2: agent:main:telegram:user-li      ││   李四: "今天有什么新闻"                ││   (独立上下文)                          │├─────────────────────────────────────────┤│ 会话3: agent:main:telegram:user-wang    ││   王五: "帮我订外卖"                    ││   (独立上下文)                          │└────────────────────────────────────────┘dmScope: "per-channel-peer"┌─────────────────────────────────────────┐│ 会话1: agent:main:telegram:user-zhang   ││   张三 (Telegram): "帮我查天气"         │├─────────────────────────────────────────┤│ 会话2: agent:main:feishu:user-zhang    ││   张三 (飞书): "再帮我查下上海天气"      ││   (Telegram 和飞书的张三分开)            │└────────────────────────────────────────┘dmScope: "per-account-channel-peer"┌─────────────────────────────────────────┐│ 场景：你有 2 个 Telegram 号 + 1 个飞书号 ││       张三在 3 个平台上都给你发了消息    │└─────────────────────────────────────────┘┌─────────────────────────────────────────┐│ 会话1: agent:main:telegram:acc-001:user-zhang ││   Telegram 号1 + 张三: "帮我查天气"     │├─────────────────────────────────────────┤│ 会话2: agent:main:telegram:acc-002:user-zhang ││   Telegram 号2 + 张三: "上次说的那个事"  ││   (与 acc-001 的张三分开)              │├─────────────────────────────────────────┤│ 会话3: agent:main:feishu:acc-003:user-zhang   ││   飞书号 + 张三: "帮我订外卖"           ││   (完全独立，与 Telegram 分开)          │└─────────────────────────────────────────┘

四、Sandbox（沙箱）配置

4.1 为什么需要 Sandbox？

这就是"主会话 vs 群组会话"的区别：

• 主会话 = 管理员后台，完全信任
• 群组会话 = 前台公众页面，需要防护

4.2 完整属性

{"sandbox":{"enabled":false,// 是否启用沙箱"workspaceAccess":"rw",// 工作区访问权限: rw/r/none"mode":"non-main"// 模式: on/off/non-main}}

4.3 mode 三种值

4.4 组合配置示例

// 场景1: 个人助手（完全访问主机）{"agents":{"defaults":{"sandbox":{"mode":"off"}}}}// 场景2: 主 Agent 显式配置{"routing":{"agents":{"main":{"workspace":"~/.openclaw/workspace","sandbox":{"mode":"off"}}}}}// 场景3: 安全隔离{"agents":{"defaults":{"sandbox":{"enabled":true,"workspaceAccess":"r","mode":"on"}}}}

五、Gateway 路由（类比 Rails）

5.1 路由对比一一对应

5.2 代码示例对比