OpenClaw 完全指南（06）：Agent、Session、SubAgent 三角关系——一个小白也能看懂的详细讲解

这一篇专门为新手设计。不管你对 OpenClaw 了解多少，这里我会用最直白的类比、最清晰的图表、最实用的例子，把 Agent、Session、SubAgent 这三个概念讲透。

前言：为什么这三个概念这么容易搞混？

你第一次看到 OpenClaw 的文档时，可能会被这三个词搞懵：

• Agent — 是一个"身份"？还是一个"进程"？
• Session — 是一次"对话"？还是一个"容器"？
• SubAgent — 是"分身"？还是"工作流"？

说实话，我一开始也这样想。但当我读完官方文档、跑过完整的代码后，我才明白：这三个东西根本不在一个维度上。

这篇文章的目标很简单：用你能听懂的话，把这三层关系讲清楚。

---

第一层：Agent（身份层）

Agent 是什么？

Agent 是一个身份标签 + 权限容器。 它答回的问题是：“这个 AI 助手是谁？它能干什么？”

想象一下现实中的例子：

• 你有一个"工作邮箱"身份（工作相关）
• 你有一个"个人邮箱"身份（生活相关）
• 两个邮箱在同一台电脑上运行，但它们的通讯录、文件夹、权限完全不同

在 OpenClaw 里，Agent 就像这两个邮箱。

Agent 的三个核心属性

Agent = { 
  id: "唯一身份名",           // 比如 "main" 或 "work" 或 "data-analyzer"
  permissions: [...],          // 能用什么工具？能访问哪些文件？
  workspace: "/path/to/agent"  // 独立的工作目录
}

一个实例

假设 Arvin 为自己配置了两个 Agent：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "description": "日常助手",
        "workspace": "/Users/arvin/.openclaw/agents/main",
        "permissions": ["read", "write", "exec", "message"]
      },
      {
        "id": "data",
        "description": "数据分析师",
        "workspace": "/Users/arvin/.openclaw/agents/data",
        "permissions": ["read", "write", "exec"]  // 注意：不能 message
      }
    ]
  }
}

重要：Agent 不在"运行"。它只是一个配置。就像你的两个邮箱账号一样，即使你没打开邮箱程序，账号配置也存在。

---

第二层：Session（对话层）

Session 是什么？

Session 是一次具体的对话实例。 它记录了：

• "谁"在说话（Agent ID）
• "什么时候"开始的（时间戳）
• “说了什么”（消息历史 + 上下文）
• “现在的状态”（运行中、已完成、出错、等待）

Session 的生命周期

1. 创建（用户启动一个新对话）
   ↓
2. 运行（AI 读取文件、调用工具、思考、回复）
   ↓
3. 保存（对话记录存储到磁盘）
   ↓
4. 查询（后续会话可以检索历史）
   ↓
5. 清理（超过 TTL 或手动删除后归档）

Session 的身份格式

OpenClaw 给每个 Session 一个唯一的"身份证"（Session Key）：

agent:main:main
↑      ↑     ↑
|      |     └── "main" 分支（主要对话）
|      └───────── Agent ID
└──────────────── 这是一个 Agent 类型的 Session

其他例子：

agent:main:feishu:dm:ou_xxx              // 飞书私聊
agent:main:feishu:group:oc_xxx           // 飞书群聊
agent:main:telegram:dm:123456789         // Telegram 私聊
agent:work:heartbeat                     // 定时检查任务

一个实际场景

假设你在 Feishu 里给机器人发了个消息：

用户：「帮我分析一下这个数据」

OpenClaw 的内部会：

1. 创建一个 Session：agent:main:feishu:dm:ou_xxx
2. 触发 Agent “main” 的执行
3. Agent 接收消息，执行工具，思考
4. 生成回复
5. 把 Session 状态、对话历史、工具输出都记录到磁盘

如果你之后再问同一个机器人：「那个数据怎样了？」

• OpenClaw 会用同一个 Session Key，读取历史上下文
• Agent “main” 知道你在讲什么
• 对话连贯

---

第三层：SubAgent（并行层）

SubAgent 是什么？

SubAgent 是一个由主 Agent 在后台启动的、隔离运行的 Agent 实例。

最简单的类比：你让一个同事帮你处理一个复杂的任务，让他一个人在另一间办公室工作，工作完了回来汇报。

SubAgent 和 Session 的关系

每个 SubAgent 本质上还是一个 Session，但它有特殊的身份和行为：

主 Session:  agent:main:main
    └── SubAgent Session 1:  agent:main:subagent:<uuid>
    └── SubAgent Session 2:  agent:main:subagent:<uuid>
    └── SubAgent Session 3:  agent:main:subagent:<uuid>

SubAgent 的三个关键特点

特点 1：后台运行，不阻塞主进程

你的主 Agent 可以：

1. 读取用户消息
2. 说："我要研究这个问题，请稍候..."
3. 立即启动 SubAgent 去搜索、分析、编码
4. 同时继续做其他事，不用等待 SubAgent
5. SubAgent 完成后自动向用户汇报结果

特点 2：隔离执行环境

每个 SubAgent 有自己的：

• 独立 Session Key
• 独立上下文和消息历史（只继承 AGENTS.md + TOOLS.md，不继承 USER.md、SOUL.md 等私密信息）
• 独立工作目录选项
• 可选的不同模型（比如主 Agent 用 Claude Opus，SubAgent 用 Claude Haiku 省钱）

特点 3：嵌套结构（可选）

SubAgent 本身也可以创建 SubAgent（如果配置允许）：

主 Agent "main"
    └── SubAgent 1（协调者）
            └── SubAgent 1.1（数据收集）
            └── SubAgent 1.2（数据分析）
            └── SubAgent 1.3（报告生成）

这叫"Orchestrator Pattern"（编排者模式）。

SubAgent 何时有用？

场景 1：并行任务
─────────────
主 Agent：「我要同时搜索 5 个网站，比较价格」
→ 创建 5 个 SubAgent 并行搜索
→ 都完成后汇总结果
→ 回复用户

场景 2：复杂计算
─────────────
主 Agent：「分析这 100 个文件，找出问题」
→ 创建一个 SubAgent 专门做代码审查
→ 主 Agent 继续处理其他事
→ SubAgent 完成后汇报

场景 3：不同工具集
─────────────
主 Agent：「我需要一个特殊的数据分析能力」
→ 创建一个 SubAgent（"data" Agent），只给它数据工具
→ 让它处理数据
→ 回报给主 Agent

场景 4：控制成本
─────────────
主 Agent 用 GPT-4（贵）
SubAgent 用 GPT-3.5（便宜）
─ 只在关键决策用主 Agent
─ 重复性工作用 SubAgent

---

现在让我们把三层连起来

图解：Agent、Session、SubAgent 的关系

┌─ OpenClaw 系统 ─────────────────────────────────────────┐
│                                                           │
│  ┌─ Agent "main" 配置 ──────────────────────────────┐   │
│  │ - 权限：read, write, message                      │   │
│  │ - 工作目录：~/.openclaw/agents/main              │   │
│  │ - 能用的工具：所有工具                            │   │
│  └────────────────────────────────────────────────────┘   │
│       ↓                                                     │
│  ┌─ 当前运行的 Session ─────────────────────────────┐   │
│  │ Key: agent:main:feishu:dm:ou_xxx               │   │
│  │ Status: 运行中                                   │   │
│  │ Context: [系统 prompt、工具列表、上文...]      │   │
│  │ Messages: [用户消息、AI 回复、工具调用...]     │   │
│  └────────────────────────────────────────────────────┘   │
│       ↓                                                     │
│  ┌─ SubAgent 1（搜索） ──────────────────────────┐       │
│  │ Key: agent:main:subagent:uuid-1              │       │
│  │ Task: 搜索 "OpenClaw 最佳实践"                │       │
│  │ Status: 运行中                                 │       │
│  │ Model: claude-haiku-4.5（更便宜）             │       │
│  └────────────────────────────────────────────────┘       │
│       ↓                                                     │
│  ┌─ SubAgent 2（分析） ──────────────────────────┐       │
│  │ Key: agent:main:subagent:uuid-2              │       │
│  │ Task: 分析搜索结果，提取关键信息              │       │
│  │ Status: 等待 SubAgent 1 完成                   │       │
│  │ Model: claude-haiku-4.5（更便宜）             │       │
│  └────────────────────────────────────────────────┘       │
│                                                           │
│  执行流：                                                  │
│  1. 用户消息进来 → 创建 Session                           │
│  2. 主 Agent 决定需要并行工作 → 启动 SubAgent 1、2       │
│  3. 主 Agent 继续其他工作（不阻塞）                       │
│  4. SubAgent 1、2 完成 → 向用户汇报                       │
│  5. 主 Agent 整合信息 → 最终回复                          │
│  6. Session 保存 → 关闭                                   │
│                                                           │
└───────────────────────────────────────────────────────────┘

核心的"三层"模式

【Agent 层】——— 身份、权限、工作空间
        ↑
        │ (配置关系)
        │
【Session 层】—— 一次对话的实例
        ↑
        │ (运行中的对话)
        │
【SubAgent 层】— 后台隔离的并行任务

---

常见问题解答（Q&A）

Q1：Agent 和 Session 是一对一关系吗？

答：不是。一个 Agent 可以有多个并发 Session。

Agent "main" 同时处理：
  └── Session: agent:main:feishu:dm:user1    (和 User 1 聊天)
  └── Session: agent:main:feishu:group:xxx   (在群聊里)
  └── Session: agent:main:telegram:dm:user2  (和 User 2 聊天)
  └── Session: agent:main:heartbeat          (定时任务)

所以，一个 Agent 可以同时"活跃"在很多地方。

Q2：SubAgent 能访问主 Agent 的文件吗？

答：不能（默认）。SubAgent 只继承：

• AGENTS.md（可用的 Agent 列表）
• TOOLS.md（本地工具备忘）

不继承：

• USER.md（用户信息）
• SOUL.md（个性）
• MEMORY.md（长期记忆）

这是为了隔离。如果 SubAgent 需要额外上下文，主 Agent 可以明确传递。

Q3：我可以有多少个 Agent？

答：没有硬限制。但建议：

• 1-3 个用于个人用户（“main”、“work”、“data”）
• 5-10 个用于团队（按职能分）
• 50+ 需要考虑权限管理复杂度

Q4：Session 会一直保存吗？

答：不会。规则是：

保存时间 = max(
  最后活跃时间 + TTL,
  创建时间 + 绝对上限
)

比如：

• 一个 Session 最后活跃 7 天前 → 默认归档
• 一个 Session 即使频繁活跃，60 天后也归档
• 可配置这些阈值

归档的 Session 不删除，只是从"活跃"转移到"历史"。

Q5：SubAgent 失败了怎么办？

答：

失败场景 1：工具调用错误
→ SubAgent 捕捉错误，记录到自己的 Session
→ 向主 Agent 汇报："我尝试了 X，但失败了，原因是 Y"
→ 主 Agent 收到汇报，决定下一步

失败场景 2：超时
→ SubAgent 运行超过配置的时限（比如 5 分钟）
→ 被自动杀死
→ 向主 Agent 汇报："我被超时杀死了"

失败场景 3：权限不足
→ SubAgent 尝试用没有权限的工具
→ 被拒绝
→ 向主 Agent 汇报

都是可以处理的，不会让主 Agent 崩溃。

---

实战：一个完整的例子

场景：「分析我最近的 CSDN 文章表现」

用户说：“Javis，帮我分析一下我最近 5 篇 CSDN 文章的阅读量、点赞数、评论数趋势。”

内部发生了什么：

第 1 步：创建 Session
  Key: agent:main:feishu:dm:ou_xxx
  Context: 导入 SOUL.md、USER.md、MEMORY.md
  
第 2 步：主 Agent 读取用户需求
  "好的，我需要获取最近 5 篇文章的数据"
  
第 3 步：主 Agent 做决定
  "这需要：
   - 从 CSDN 爬取数据（网络 I/O，有点慢）
   - 做统计分析（CPU 密集）
   - 生成报告（快速）
   
   我应该启动 SubAgent 去爬数据，同时继续做其他事"
  
第 4 步：启动 SubAgent 1（数据采集工）
  - 创建 Session: agent:main:subagent:uuid-data-fetch
  - 分配任务：「爬取 CSDN 最近 5 篇文章的统计数据」
  - 模型：claude-haiku（便宜版）
  - 工具：web-fetch、exec（可以运行 Python 爬虫）
  
第 5 步：启动 SubAgent 2（分析工）
  - 创建 Session: agent:main:subagent:uuid-analysis
  - 分配任务：「等待数据到达后，做趋势分析」
  - 模型：claude-haiku
  - 工具：exec（可以跑 Python 数据分析）
  
第 6 步：主 Agent 对用户说
  "正在获取数据中，请稍候..."（立即回复，不阻塞）
  
第 7 步：SubAgent 1 执行
  - 读取 MEMORY.md（获取 CSDN 用户 ID）
  - 调用 web-fetch 工具
  - 爬取数据
  - 完成后汇报："数据已获取，存在 /tmp/csdn_stats.json"
  
第 8 步：SubAgent 2 读取 SubAgent 1 的汇报
  - 等不需要了，我们可以让 SubAgent 1 的输出直接流到 SubAgent 2
  - SubAgent 2 接收数据，开始分析
  - 计算趋势、增长率、最佳表现文章等
  - 完成后汇报："分析完成，见下表..."
  
第 9 步：主 Agent 整合
  - 收到 SubAgent 1、2 的汇报
  - 整理成漂亮的格式
  - 向用户汇报完整结果
  
第 10 步：Session 关闭
  - 所有消息、工具输出、SubAgent 结果都记录
  - Session 保存到磁盘
  - 如果用户之后再问相关问题，可以快速查历史

总耗时：假设 10 秒

序列执行的耗时：
  爬数据 5 秒 + 分析 3 秒 + 整合 1 秒 = 9 秒

并行执行的耗时（使用 SubAgent）：
  max(爬数据 5 秒, 分析 3 秒) + 整合 1 秒 = 6 秒

但 OpenClaw 在启动 SubAgent 上花了 0.5 秒开销
实际：5-6 秒（对用户来说就快多了）

---

深入理解：Session 的内部结构

当你 read 一个 Session 的文件时，你会看到：

{
  "sessionKey": "agent:main:feishu:dm:ou_xxx",
  "sessionId": "s_abc123xyz",
  "agentId": "main",
  "channel": "feishu",
  "startTime": "2026-03-11T18:00:00Z",
  "lastActivityTime": "2026-03-11T18:05:00Z",
  "status": "completed",
  "context": {
    "systemPrompt": "...",
    "workspace": "/Users/arvin/.openclaw/agents/main",
    "tools": ["read", "write", "exec", "web_fetch", ...]
  },
  "messages": [
    {
      "role": "user",
      "content": "分析我的 CSDN 文章",
      "timestamp": "2026-03-11T18:00:05Z"
    },
    {
      "role": "assistant",
      "content": "正在获取数据中...",
      "timestamp": "2026-03-11T18:00:06Z"
    },
    {
      "role": "tool",
      "toolName": "web_fetch",
      "toolResult": "...",
      "timestamp": "2026-03-11T18:00:12Z"
    },
    ...
  ],
  "subagentResults": [
    {
      "sessionKey": "agent:main:subagent:uuid-data-fetch",
      "task": "爬取 CSDN 最近 5 篇文章的统计数据",
      "status": "completed",
      "result": "数据已获取，存在 /tmp/csdn_stats.json",
      "runtime": "5.2s",
      "tokens": { "input": 500, "output": 200 }
    },
    {
      "sessionKey": "agent:main:subagent:uuid-analysis",
      "task": "做趋势分析",
      "status": "completed",
      "result": "分析完成...",
      "runtime": "3.1s",
      "tokens": { "input": 800, "output": 500 }
    }
  ],
  "tokenUsage": {
    "input": 4500,
    "output": 2100,
    "total": 6600,
    "estimatedCost": "$0.42"
  }
}

看到了吗？一个 Session 完整记录了：

1. 身份信息 — 谁在说话（agentId）、在哪里说话（channel）
2. 时间轴 — 什么时候开始、最后活跃时间
3. 上下文 — 这个 Session 能用什么工具、工作在哪
4. 对话历史 — 用户说什么、AI 如何回复、工具怎么调用
5. SubAgent 记录 — 哪些 SubAgent 被启动了、它们做了什么、花了多少钱
6. 成本统计 — 消耗了多少 token、花了多少钱

这就是为什么"查询历史"这么强大——所有信息都在这里。

---

最后：三层的设计意义

为什么这样分层？

层级	存在的理由	解决的问题
Agent	身份与权限隔离	一个人可以有多个"角色"，每个角色权限不同
Session	对话的上下文管理	同一个对话中需要记住历史、工具输出、决策
SubAgent	并行与独立执行	不是所有任务都线性执行，需要后台并行工作

现实类比

想象一个公司：

【Agent = 部门】
  - 销售部门（权限：可以联系客户、查看销售数据）
  - 技术部门（权限：可以访问代码库、部署系统）
  - 财务部门（权限：可以查看报表、处理发票）

【Session = 一个项目任务】
  - "销售部门处理 X 客户的订单"
    - 消息历史：客户说了什么、销售部怎么回复
    - 工具：CRM 系统、邮件、合同模板
    - 成本：这个项目花了多少人力
  
【SubAgent = 项目中的子任务】
  - "财务部门"（SubAgent）受销售部门委托
  - 任务："审核这份合同的价格"
  - 隔离：财务部用自己的工具、权限、上下文
  - 完成后汇报："合同已审核，价格合理"

---

总结一句话

• Agent = 身份 + 权限（“你是谁，你能干什么”）
• Session = 一次对话（“这次聊天的完整记录”）
• SubAgent = 后台工作（“我派你去做这件事，完了告诉我结果”）

三个东西看起来像"嵌套"，其实是"分层设计"：

• Agent 在配置层
• Session 在运行层
• SubAgent 在并行层

理解这一点，就理解了 OpenClaw 为什么这么强大。

---

推荐阅读

• 官方文档：SubAgents（https://docs.openclaw.ai/tools/subagents）
• 官方文档：Sessions（https://docs.openclaw.ai/cli/sessions）
• 官方文档：Agent Client Protocol（https://agentclientprotocol.com/）