用过 Claude Code、OpenClaw 这类 AI 编程 Agent 的人，几乎都撞上过同一堵墙：会话跑久了，上下文越塞越满，要么被硬截断丢掉早前的工作记忆，要么每轮请求都背着几十万 token 的历史在跑，又慢又贵。OpenClaw 的一个共享会话连跑 40 个任务，输入 token 会从 4.9 万一路爬到 37.4 万——这就是上下文不做治理的代价。而 flowctx 给出的解法有些反直觉：记忆应该随距离变淡，而不是到点掐断——离当前任务越远压得越狠，越近保得越全，当前正在做的事则分毫不动。它在 SWE-bench Verified 上把长会话的 token 消耗砍掉 56%，解题成功率却保持在 68% 不降。
flowctx 是什么：OpenClaw 的「上下文引擎」
flowctx（GitHub: Ayou-Claw/flowctx，MIT 协议）是一个 OpenClaw ContextEngine 插件，本质是会话上下文的「分层记忆管理器」。它不改变模型、不改变工具，而是接管「每轮请求往上下文里放什么」这件事。
OpenClaw 本身在溢出时并非没有处理——它有 pre-emptive 检查、ToolResult Guard、compaction safeguard 三道防线，但思路是「先尽量塞，快满再截断/摘要」。这种兜底式治理有四个代价：
- 工作记忆丢失：早期轮次里的失败路线、关键约束被 prune 后，模型容易重复踩坑
- 精确信息不可恢复：
[... N more truncated]是单向裁剪，被删的字节没有回溯指针
- KV Cache 被打爆：summarize / prune / 重排都会改写前缀，下一轮走 cold path，延迟飙升
- 卡在交互关键路径上：压缩发生在回合中途，用户能感知到明显停顿
flowctx 的取舍是把上下文当作「有纵深的记忆」，只压缩远端、绝不碰当前任务，而且所有压缩都有退路。它内部实现了 OpenClaw ContextEngine 契约的 assemble() / ingest() / compact() / maintain() 四件套：assemble() 做轻量投影，重活全部丢给 maintain() 后台执行。
三层压缩，怎么做到「越远越省、随时可还原」
flowctx 把会话历史按离当前任务的距离分成三档，每档用不同的压缩强度：
| 档位 | 处理方式 | 细节 |
|---|---|---|
| 当前轮任务 | 零语义丢失 | 原文原样入模，不压缩不摘要 |
| 临近过往轮 | 结构化压缩（零 LLM、确定性） | 按内容类型识别，压缩结果可按 hash 字节级还原 |
| 更早历史 | 摘要压缩（LLM、后台、阈值门控） | 折叠成分层交接笔记，逐字保留失败做法与关键标识符 |
三层机制各有关键设计：
1. 读时投影（projection）。压缩只发生在 assemble() 输出给模型的那个视图上，磁盘上的宿主会话永远是未压缩的原文真相源。任何被压过的内容都能用 flowctx_retrieve 工具按 SHA-256 哈希逐字节取回——「压」和「删」是两回事。
2. 确定性结构化压缩（0 LLM）。projection.ts 按内容类型路由超大工具结果：JSON 走词法 minify + 哈希中段裁剪，diff 走 hunk 压缩，CLI 输出走规则引擎（作者声称日志类可压 5–20 倍+），代码走结构提取，日志做相邻重复折叠。两道防线（行一致性校验 + 严格字节收缩）拒绝无效压缩，兜底是 head60%+tail30%。这一层每轮都跑、不花一分钱 LLM 调用，把窗口占用压低了，LLM 摘要自然就没那么频繁需要触发。
3. 后台 LLM 摘要（只在需要时）。只有当「组装后视图 token ÷ 上下文窗口 ≥ 阈值」（默认 0.2）时才触发，且跑在 maintain() 的后台车道，不阻塞交互回合。摘要走分层 Summary DAG：早期历史冻结成永不重写的 leaf 节点（默认 4 万 token 一片），攒够 6 片就凝聚成一层概述。摘要采用「工程师交接笔记」提示词，专门逐字保留标识符、文件路径、失败 vs 可行的路线——专治压缩后失忆。代际守卫会取消新回合时还在跑的过期摘要任务，避免陈旧结果被提交。
4. KV Cache 友好。assemble() 保持稳定前缀逐字节不变，被压缩的内容因「内容 hash → 相同字节」天然幂等，跨轮前缀稳定，provider 前缀缓存持续命中。作者实测：折叠摘要节点只会让 KV 命中率掉约 2 个百分点（96.1% → 93.9%）。
实测佐证：仓库自带 254 个 vitest 测试（31 个测试文件）全部通过，覆盖约束 C1–C6（非阻塞 / append-only / 可逆可审计 / LLM 摘要后台门控 / KV 前缀稳定 / 结构化压缩）以及多 leaf 折叠循环、实时配置生效等场景。唯一跳过的 live-LLM 测试需 Anthropic 凭证，会自动跳过。
关键配置：改这几个键就能调行为
所有配置都放在 ~/.openclaw/openclaw.json 的 plugins.entries.flowctx.config 下，全部可选、越界值自动 clamp。最值得调的是这几个：
| 配置键 | 默认值 | 作用 |
|---|---|---|
shortTermMemory |
true |
总开关，关掉即整体停用 |
projectionThreshold |
1000 |
超过此 token 数的工具结果才做结构化压缩，越小越激进 |
projectionKeepRecentTurns |
1 |
最近 N 个用户回合（当前任务）豁免压缩 |
freshTailWindow |
64 |
最近 N 条消息原文保留（是前者的上限，防长任务拖垮窗口） |
summaryTriggerRatio |
0.2 |
组装后占用达窗口比例即触发后台摘要，越小越早压 |
summaryKeepRecentTurns |
2 |
摘要折叠前保留的用户回合数 |
layeredSummary |
true |
分层 leaf + condense，false 则退化为单条滚动笔记 |
leafChunkTokens |
40000 |
一片 leaf 覆盖的原文 token 数 |
condenseFanout |
6 |
攒够几片同层节点凝聚成上一层 |
maxSummaryDepth |
1 |
摘要树最大深度（0=只有 leaf） |
作者在文档里给了一个「激进调试配置」示例（窗口 3 万、触发比 0.3、dumpSummaryRequests: true 等），用来在小窗口上快速观察引擎工作过程；生产环境建议关掉 debug 输出、把窗口设成模型真实值。
还有一个容易踩的坑：config 受 manifest 的 configSchema 校验（additionalProperties: false），写入非法键会被 openclaw doctor --fix 把整段 config 重置，引擎悄悄回退默认阈值、看起来像「没生效」。
实测数据：token 砍 56%，解题率不降
作者用 SWE-bench Verified 做了确定性评测：抽取 40 个真实 issue→PR 任务（12 个 repo、3 个难度档），被测模型是 mimo-v2.5-pro，裁判用 claude-opus-4-8 对比候选 patch 与 golden patch。关键对照组是共享会话（40 个任务共用同一个 session，上下文跨任务累积——这正是 flowctx 工作的场景）：
| 配置 | 解决率 (/40) | 均分 | KV 命中率 | tokens/任务 |
|---|---|---|---|---|
| flowctx 关 · isolated | 68%（27/40） | 70.2 | 98.7% | 88k |
| flowctx 关 · shared | 68%（27/40） | 71.1 | 96.1% | 288k |
| flowctx 开 · shared（两次均值） | 68%（27/40） | 71.8 | 93.9% | 127k |
三个关键结论：
- 压缩不伤解题力：解决率 68% ↔ 68%、均分 71.1 ↔ 71.8，基本持平（开 flowctx 的两次运行分别是 70% 和 65%，作者取了均值）
- token 大幅下降：同样累积上下文的场景下，288k → 127k / 任务，省 56%（约 16.2 万 token/任务）
- KV 命中率只是小幅波动：96.1% → 93.9%，折叠摘要节点的重算成本约 2 个百分点
值得注意的是对照组揭示的「失控曲线」：不压缩的共享会话 prompt token 随任务单调爬升（4.9 万→37.4 万），而 flowctx 开时每次折叠都把组装规模拉回 10 万 token 门槛内。
仓库里还附了 TTFT 实测：500k prompt 冷缓存首 token 延迟高达 30–51 秒，热缓存能压到 3.7–6.3 秒（加速 13.9 倍）——KV 缓存保不住时，长上下文的延迟代价是实打实的。
局限（作者自述 + 代码审读）：
- 目前仅面向 OpenClaw 生态；普通文本内容仍主要靠 head/tail 粗裁剪，还没做提纲式提取
flowctx_retrieve只能整块取回，模型想只看一小段也得拉整段原文，作者规划做 range 子块取回
- token 预算是本地估算（Unicode 码点感知：CJK≈1.5、emoji≈2、ASCII≈0.25 token/字符），不依赖 SDK usage 字段——方向对了，但估算非精确
- 摘要质量缺乏自动评估，交接笔记能否稳定保住失败路线和关键标识符还靠人工观察
安装、适用场景与同类对比
安装需要 Node ≥ 20，在 OpenClaw 环境内一条命令链：
npm install # 一次性：拉开发依赖（esbuild/typescript/vitest）
./install.sh # 构建、链接、启用，并把 flowctx 设为活动的 context engine
openclaw gateway restart # 改完必重启install.sh 默认会设置 plugins.slots.contextEngine = "flowctx"——注册 context engine 不等于启用，slot 必须指向它。想不接管引擎槽位可用 --no-engine，改选别的用 --engine 。运行时日志前缀方便 grep：[flowctx:trigger]（真正触发的事件，info 级可见）、[flowctx:engine]（细粒度调试，默认关）。
适合谁：
- OpenClaw / 长会话 Agent 用户，跑多任务共享会话、上下文经常逼近窗口上限的人
- token 账单敏感、但不想牺牲解题质量的团队——省的是真金白银的输入 token
- 对 KV 缓存命中率有执念的性能调优者
不适合谁：
- 单轮短会话为主、会话很少超过几万 token 的人——加了引擎徒增复杂度
- 不是 OpenClaw 生态的用户（Claude Code 场景可看同类思路的 headroom / 协议层代理）
与同类方案的定位差异（详见仓库 docs/context-management.md）：
- headroom：协议层压缩代理，位于 agent 与 provider 之间，host 无关、运行时基本不做 LLM 摘要，覆盖压缩器广；但看不到 host 的 session/轮次语义，需要 sidecar，且挡不住 host 内部的同步 summarize
- lossless-claw / LCM：同为 OpenClaw 引擎层插件，以 LLM 摘要 + 语义召回为主路径，摘要 DAG 可跨会话查；但对普通工具结果的结构化压缩覆盖弱，且作者记录过它曾把非法 assistant 结尾的消息序列写回 host 造成无限死循环
- flowctx：在引擎层优先确定性结构化压缩（零 LLM），只有远期历史才交给后台 LLM 摘要——三层里两层的日常工作是免费的
flowctx 目前还是个小众项目（13 star、2026 年 7 月创建、作者持续更新到 8 月中旬），本质上是作者在真实 OpenClaw 运营中打磨出的自用插件开源。它的价值不在社区热度，而在于把「上下文治理」这个被多数人当成「溢出时再处理」的问题，重新定义成了「记忆的分层保真」——并且用 254 个测试和 SWE-bench 实测证明了这条路走得通。如果你正在被长会话的 token 账单和失忆问题困扰，又恰好用 OpenClaw，这个插件值得一试；如果还没到窗口吃紧的阶段，把它放进观察清单即可——当你的 Agent 会话开始「越跑越贵、越跑越笨」时，你会想起它的。
关注 AI商业快讯，每天一篇 AI 热点深度解读。
相关阅读：