Session 管理深入解析
单个 Gateway 进程 端到端地拥有会话状态。UI（macOS 应用、web Control UI、TUI）向 Gateway 查询会话列表和 token 计数。在远程模式下，每个 agent 的 SQLite 数据库位于远程主机上，因此检查本地 Mac 的状态不会反映 Gateway 正在使用的内容。
先看概览文档：会话管理、压缩、记忆概览、记忆搜索、会话修剪、转录卫生，完整配置参考见 Agent 配置。
本页是一个索引。深入内容分布在五个页面中，每个页面对应一项读者任务。打开与你任务匹配的页面并停留在那里。
| 页面 | 阅读时机 |
|---|---|
| 磁盘上的会话状态 | 两个持久化层以及 Gateway 主机上每个 agent 的路径。 |
| 存储维护与保留 | session.maintenance 键、磁盘预算清理、cron 保留策略，以及 SQLite 降级路径。 |
| 会话键、ID 和转录事件 | sessionKey 模式、sessionId 生命周期、SessionEntry 字段，以及转录条目类型。 |
| 压缩行为与设置 | 压缩做什么、何时运行、它的设置和提供者，以及它在哪些地方呈现。 |
| 静默轮次与记忆刷新 | NO_REPLY 契约和 agents.defaults.compaction.memoryFlush。 |
各章节迁移位置¶
之前单页版本的每个章节标题在此处保留其锚点，因此诸如 /reference/session-management-compaction#when-auto-compaction-happens 的现有链接仍然有效。每个条目都指向现在承载相应内容的页面。
- 两个持久化层
- 磁盘上的位置
- 存储维护与磁盘控制
- SQLite 切换后的降级
- Cron 会话与运行日志
- 会话键（
sessionKey） - 会话 ID（
sessionId） - 会话存储模式
- 转录事件结构
- 上下文窗口与跟踪的 token
- 压缩：它是什么
- 块边界与工具配对
- 自动压缩何时发生
- 压缩设置
- 可插拔压缩提供者
- 用户可见的表层
- 静默维护（
NO_REPLY） - 压缩前记忆刷新
故障排查清单¶
- 会话键错误？ 从 /concepts/session 开始，并确认
/status中的sessionKey。 - 存储与转录不匹配？ 通过
openclaw status确认 Gateway 主机和存储路径。 - 压缩过于频繁？ 检查模型的上下文窗口（太小会导致频繁压缩）以及工具结果膨胀（调整会话修剪）。
- 在小型本地模型上每个 prompt 似乎都溢出？ 确认提供者报告了正确的模型上下文窗口。只有当该窗口已知时，OpenClaw 才能限制有效保留空间。
- 静默轮次泄漏？ 确认回复以确切的静默 token
NO_REPLY（不区分大小写）开头，并且你所在的构建包含流式抑制修复（2026.1.10及更高版本）。
相关文档¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw