跳转至

会话管理深入解析

单个 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。
会话记录工作集 提议中的 worker 自有获取机制、常驻预算以及历史读取器迁移。

各节内容迁移位置

先前单页版本中的每个节标题都在此处保留了锚点,因此诸如 /reference/session-management-compaction#when-auto-compaction-happens 的既有链接仍然可以解析。每个条目都指向当前承载对应内容的页面。

故障排查清单

  • 会话键不对? 从 /concepts/session 开始,并确认 /status 中的 sessionKey。
  • 存储与记录不一致? 通过 openclaw status 确认 Gateway 主机和存储路径。
  • 压缩过于频繁? 检查模型的上下文窗口(过小会导致频繁压缩)以及工具结果的膨胀(调整会话修剪)。
  • 在小型本地模型上,每个 Prompt 似乎都会溢出? 确认提供方报告了正确的模型上下文窗口。只有在已知该窗口时,OpenClaw 才能对有效保留空间设置上限。
  • 静默轮次泄漏? 确认回复以精确的静默 token NO_REPLY 开头(不区分大小写),并且你使用的是包含流式抑制修复的构建版本(2026.1.10 及以上)。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw