🧠 核心概念

OpenClaw 会话管理

理解 Agent 的"记忆"是如何工作的

            一句话定义： OpenClaw 会话管理是 Agent 系统的核心机制，负责维护对话上下文、管理记忆、协调多个并发任务，确保 Agent 能够连贯地理解用户意图。
        

🎯 什么是会话 (Session)？

会话就像 Agent 的"工作记忆"。当你和 Agent 对话时，它需要记住你之前说了什么、做了什么。OpenClaw 的会话系统支持多种模式：

┌──────────────────────────────────────────────────────────┐ │ OpenClaw Gateway │ ├──────────────────────────────────────────────────────────┤ │ Session Manager │ ├────────────┬────────────┬────────────┬───────────────────┤ │ Main │ Isolated │ Sub │ Named │ │ Session │ Session │ Agent │ Session │ │ (主会话) │ (隔离会话) │ (子代理) │ (命名会话) │ ├────────────┴────────────┴────────────┴───────────────────┤ │ Context & Memory │ ├──────────────────────────────────────────────────────────┤ │ - 对话历史 - 工具结果 - 文件上下文 - 长期记忆 │ └──────────────────────────────────────────────────────────┘

📋 会话类型详解

🟢 主会话 (Main)

用户直接交互的主对话，保持完整的上下文历史。

场景： 日常聊天、问答

🔵 隔离会话 (Isolated)

独立的临时会话，不影响主对话。

场景： 定时任务、后台工作

🟣 SubAgent 会话

由主 Agent 派生的子代理，可并行执行。

场景： 复杂任务分解、并行处理

🟡 命名会话 (Named)

持久化的会话，可跨多次交互保持状态。

场景： 长期项目、持续跟踪

🔧 核心 API

会话列表

# 获取所有可见会话
sessions = sessions_list(
    kinds=["main", "isolated", "subagent"],
    limit=10,
    activeMinutes=60,  # 最近60分钟活跃的
    includeLastMessage=True
)

# 按标签过滤
sessions = sessions_list(label="seo-task")

会话历史

# 获取会话历史记录
history = sessions_history(
    sessionKey="main",
    limit=20,
    includeTools=True  # 包含工具调用记录
)

会话间通信

# 向其他会话发送消息
sessions_send(
    sessionKey="seo-work",
    message="请生成今日SEO报告",
    timeoutSeconds=30
)

# 通过 agentId 发送
sessions_send(
    agentId="miaoquai",
    message="查看今日任务进度"
)

创建 SubAgent

# 创建子代理执行任务
sub = sessions_spawn(
    task="搜索今日AI新闻并生成日报",
    taskName="daily-news",
    runtime="subagent",
    mode="run",  # 一次性执行
    timeoutSeconds=300
)

# 等待子代理完成
sessions_yield(message="等待子代理完成...")

📊 会话上下文构成

上下文类型	说明	容量
对话历史	用户与Agent的消息记录	受 context window 限制
工具结果	工具调用的返回值	自动截断过长内容
文件内容	通过 read/load 加载的文件	按需加载
系统提示	SOUL.md、USER.md 等配置	固定注入
长期记忆	MEMORY.md 中的持久信息	按需检索

⚡ 会话生命周期

# 会话状态流转

创建 → 活跃 → 空闲 → 过期 → 清理
  │       │       │       │
  ▼       ▼       ▼       ▼
init   active  idle    expired
        │
        ├── 接收消息 → 处理中 → 响应完成
        ├── 调用工具 → 等待结果 → 继续对话
        └── 派生子代理 → 等待完成 → 合并结果

🚀 最佳实践

            ✅ 推荐做法：
            定时任务用隔离会话 - 避免干扰主对话
复杂任务用 SubAgent - 并行处理提高效率
长期项目用命名会话 - 保持上下文连续性
及时清理过期会话 - 释放系统资源
合理设置 timeout - 避免任务挂起

        

⚠️ 常见问题

问题	原因	解决方案
上下文丢失	会话过期或被清理	使用命名会话保持状态
响应缓慢	上下文过长	定期清理历史、使用压缩
子代理超时	任务过复杂	增加 timeoutSeconds 或拆分任务
会话冲突	多会话同时写入	使用隔离会话避免干扰