OpenClaw Session 管理架构

0｜Session 是什么

Session是 Agent 运行时状态的容器，封装了：

与 LLM 的对话历史

当前上下文（Context）中加载的文件和变量

工具调用的状态和结果缓存

该 Session 专属的资源配额和权限边界

Session 是 OpenClaw 实现"多任务并发"和"状态隔离"的基础单元。

1｜Session 的生命周期

INIT → ACTIVE → IDLE → SUSPENDED → TERMINATED

状态	说明
INIT	Session 被创建，Agent 初始化完成，极短
ACTIVE	Agent 正在处理任务，消息在 LLM 和工具之间流动
IDLE	没有活跃请求，但状态保留——正常等待状态
SUSPENDED	被显式暂停（用户手动或系统资源策略）
TERMINATED	销毁——正常结束、超时、或被强制终止

2｜sessions_spawn：Session 的分裂机制

sessions_spawn 是构建多代理系统的入口，从父 Session 分裂出子 Session，各子 Session 独立运行但共享父 Session 的上下文。

run vs session 模式：

run 模式

（一次性）：子 Session 接收任务，执行完毕后返回结果，然后自动终止。适合独立的、边界清晰的任务。

session 模式

（持久化）：子 Session 保持活跃，可接收后续消息，适合需要多轮交互的任务。

继承规则：

✅ 继承：workspace 目录访问权限、已加载的 Context 文件、模型配置

❌ 不继承：父 Session 的对话历史——这确保每个子任务的上下文干净、可控

3｜亲和性：任务应该分配给哪个 Session

OpenClaw 使用**亲和性（Affinity）**机制确保相关任务落在同一个 Session 里，减少上下文加载的开销。

场景	亲和性策略
同一 Agent 的连续消息	优先分配到同一个 Session
同一任务的子任务	分配到同一个 Session（缓存上下文）
全新任务	分配到新的空闲 Session 或创建新 Session

风险：如果一个 Session 处理了太多不相关的任务，上下文会变得臃肿，LLM 推理质量下降（context overflow）。系统会在超限时触发"session refresh"，压缩或归档旧上下文。

4｜三种隔离级别

隔离级别	文件系统	环境变量	工具结果	适用场景
共享（Shared）	共享	共享	共享	任务之间有协作，需要读取彼此产出
软隔离（Soft）	共享	独立	不共享	有数据共享需求，但不希望工具结果相互污染
完全隔离（Fully）	独立	独立	完全独立	高风险操作、不受信任的任务

5｜资源控制

控制维度	说明
并发数限制	`maxConcurrentSessions` ，达上限时新请求进入队列
运行时长	`runTimeoutSeconds` ，超时强制 SUSPENDED 或 TERMINATED
Token 用量	接近配额时发出警告，硬限制后终止 LLM 调用
内存与存储	IDLE 时序列化到磁盘，释放内存；恢复时重新加载

6｜sessions_list 与 sessions_history

sessions_list：监控当前状态——检查僵尸 Session、监控系统负载、发现异常。

sessions_history：调试的核心工具——翻看完整历史，找到 LLM 推理偏差、工具调用参数错误、或 Approval 卡住的具体位置。

7｜实际多代理场景示例

Copy

用户提交代码 → Session A（主控）分析任务

↓ 分裂

Session B（执行审查）+ Session C（生成修复建议）

↓ ↓

发现问题多独立运行

↓

合并结果 → 返回给用户

Session A 负责理解任务、分解任务、合并结果；Session B 和 C 平行分裂，分别处理不同子任务。如果 B 发现问题比预期多，可再分裂出 B1、B2 并行处理。

8｜总结

OpenClaw Session 管理架构核心：

分裂（sessions_spawn）

：从父 Session 按需分裂子 Session，独立运行但可访问父级上下文

亲和性

：相关任务自然落在同一个 Session，减少上下文加载开销

三级隔离

：从共享到完全隔离，根据信任关系选择合适级别

资源控制

：并发数、运行时长、Token 配额、内存管理，防止资源耗尽

运维工具

：sessions_list 和 sessions_history 是生产环境调试的眼睛