OpenClaw使用和约束机制

本文记录在 OpenClaw 之上额外补的一层约束机制，包括这些机制怎么约束 agent，怎么落地，分别解决什么问题。

1. 常用 Skills

本地还做了几类组合 skill：

• lightpanda-browser：Lightpanda 优先，失败时自动回退到 agent-browser
• pmem-distill：定时蒸馏持久化记忆
• backup：任务级备份
• temp-janitor：清理运行态目录

2. 行为机制

额外补上的约束层整体分两条线：

1. 用 prompt、规则文档把行为写死
2. 用 hook、plugin、运行时把这些要求变成硬性拦截

2.1 可复用知识的封装：Skill 和 CLI

一类知识只要反复出现，而且执行路径已经稳定，就不继续堆在 prompt 里，而是封装出去。封装有两个方向，各自解决不同的问题：

Skill 方向：

• 把一类能力整理成 skill，让它从上下文里的说明变成可以直接调用的能力
• 适合需要 agent 理解上下文、做判断、灵活组合的场景
• 维护时改 skill 定义即可，不用反复调 prompt

CLI 方向：

• 把确定性高的操作做成命令行工具，执行入口固定，参数明确
• 适合流程已经完全确定、不需要 agent 做额外判断的场景
• 执行路径锁死，结果可预期

两者的共同点是把重复解释变成重复调用，降低 prompt 负担，让同一类任务的执行路径更稳定。

2.2 JSON 工作方案：不是计划文本，而是任务状态对象

每个任务开始前，先落一个结构化的 JSON 工作方案，而不是只写一段自然语言计划。

怎么做：

• 任务一启动就生成方案对象，里面至少有目标、约束条件、前置检查、执行步骤、工具计划、搜索策略、验证标准、委派规则、看门狗配置
• 这个方案不是一次性文档，而是一个持续更新的状态对象
• 如果方案缺字段，就自动补全结构
• 如果用户中途改了目标、范围或输出要求，就自动刷新
• 如果执行过程中发现方案还没准备好，就自动修复或重新生成一个可执行版本
• 方案本身也有状态，比如草稿和就绪，很多执行动作本质上是在等这个状态切换
• 工具拦截层直接读取这个对象：计划没就绪就不进执行；工具不在允许列表内就不放行；搜索任务的通道、页面访问、验证要求，也都从这个对象里读

这里真正有用的点，不是”先做计划”，而是让计划变成系统可读、可校验、可恢复的状态锚点。

好处：

• 任务状态始终有落点
• 工具调用能真正依赖计划，而不是靠模型自觉
• 中断恢复时不用重新猜当前做到哪一步
• 长任务的子任务拆分、验证方式、保活策略都能挂在同一个对象上

2.3 多轮需求澄清：把目标、范围、完成标准补齐

需求不清楚时，不让 agent 直接开干，而是先把影响执行路径的几个关键点问清楚。

怎么做：

• 不是一次丢十个问题，而是优先只问当前最影响执行的那一个
• 澄清的重点不是泛泛地问”你想要什么”，而是目标、边界、禁止项、交付物、是否允许修改、是否允许联网这些会直接改变执行链路的条件
• 每轮澄清完，不只更新模型理解，还会把结果写回工作方案里的目标、约束条件、决策变更记录
• 如果这些关键条件还不够完整，方案就保持草稿状态，执行拦截不会放行
• 如果用户中途改口，不是靠模型临时记忆去猜，而是把旧决定和新决定都落到约束和决策变更里，再重排后续步骤

这个机制的重点是把澄清从聊天动作变成任务编排的一部分。

好处：

• 模糊需求能被逐轮收口成可执行需求
• 目标变更有记录，不容易前后矛盾
• 可以显著减少方向错了但已经做了一半的返工

2.4 搜索治理：角色化、分通道、先候选再取证

搜索不再是一个笼统动作，而是拆成一条可治理的链路。

怎么做：

• 先把搜索能力拆成不同角色：本地线索、引擎搜索、通用来源、垂直来源、证据浏览器
• 再把搜索计划拆成不同通道：本地通道、通用通道、垂直通道
• 本地通道负责本地线索确认，比如 qmd、本地知识库、现有审计记录
• 通用通道负责泛搜索和候选扩展
• 垂直通道负责垂直平台补充
• 搜索工具主要负责找候选链接和线索，真正要下结论时再交给证据浏览器打开页面做取证
• 某些不希望走的内置工具会直接屏蔽，强制只走允许链路
• 如果当前搜索覆盖还不够，或者还有可用引擎没试完，就继续补充，不允许过早收口
• 搜索结果输出前还会检查独立来源覆盖，默认至少要补到 2 个独立站点，不够就继续搜，不直接总结

这里的本地优先没有单独拉成口号，因为它本来就应该包含在搜索治理里：本地能确认的先确认，本地没有再往外扩。

好处：

• 搜索链路可以被治理，不再随机漂移
• 本地线索、泛搜索、垂直搜索的分工更清楚
• 找到候选和验证候选被拆开，误判率会明显下降

2.5 结果优先：不是一句口号，而是一组反空转拦截

所谓结果优先，不是让 agent 嘴上说”以结果为准”，而是把几类常见的空转行为直接拦掉。

怎么做：

• 进入执行态或验证态后，如果回复里出现”是否继续""要不要继续”这类中途回问，会触发自动续跑拦截，要求按既定方案继续，不准把责任甩回用户
• 如果已经用了”已完成""结果如下”这种收口表达，但没有命令、文件、日志、页面证据，就触发结果证据拦截，不让假完成过关
• 如果回复只是弱进度、空进度、提前收口，也会触发继续推进拦截，要求补完剩余动作后再汇报
• 搜索场景下，如果已经开始给结论，但独立来源数量不够，也会被挡回去继续补证据
• 运行时还会统计连续无动作轮次，如果连续 3 轮只有说法没有实际工具动作，就直接阻断
• 执行态的汇报格式也有要求，必须包含当前动作、实时记录、证据落点和下一步计划，缺了哪项系统会自动补齐，不允许只写一段模糊进度

所以这里的结果优先本质上是三件事：

1. 不允许空转
2. 不允许假完成
3. 不允许没证据就收口

好处：

• 可以直接压制看起来很忙但实际上没做的输出
• 真正完成和假完成会被明确区分
• 结果汇报会被强制带上可复核的落点

2.6 遇到问题先自愈，不允许原地停下

执行过程中出现报错、失败或阻塞时，不允许 agent 直接停下来说”做不到”，而是强制切到问题求解模式。

怎么做：

• 运行时会识别执行过程中的问题信号，比如报错、失败、阻塞、超时
• 一旦命中，不接受”做不到""先停下”这类输出，而是要求按固定的恢复流程走
• 恢复流程至少包括：给出失败证据、检查本地现有能力有没有直接解法、补充线上方案、收敛出候选修复路径、选一个立即重试、重试后再回到主任务链
• 也就是说，出错后的默认动作是先解决问题再继续推进，而不是把失败当成任务结束

好处：

• agent 遇错时有固定的恢复路径可走
• 故障处理过程会留下明确的证据和重试记录
• 减少因单次失败就放弃整个任务的情况

2.7 长任务保活和自动恢复

长任务不是放出去就不管，而是挂上看门狗，持续看它有没有真的在推进。

怎么做：

• 搜索任务和长步骤任务默认会打开看门狗
• 运行态不是只看有没有回复，而是看更新时间、当前阶段、最近一次有效进展这些指纹有没有变化
• 默认按 60 秒节拍巡检，连续 2 个停滞周期没变化就写入唤醒信号和唤醒日志，推动它按当前阶段继续执行
• 如果连续唤醒超过 3 次，就把任务显式标成阻塞或进入恢复态，而不是静默挂死
• 任务状态卡也会同步改成执行中、自动恢复、阻塞原因这类可追踪状态

这个机制的重点不是提醒，而是把停滞和恢复也纳入运行态管理。

好处：

• 长任务挂住时不会无声失联
• 恢复动作有据可依，不是靠临时拍脑袋
• 失败、停滞、阻塞都会留下状态痕迹

3. 记忆机制：文件系统方案

用文件系统做记忆，把原始现场、主题知识、时间归档、任务路由和自动融合放进同一条链路。

3.1 现场、知识、归档分轨存储

怎么做：

• raw 只存原始现场，包括对话、执行轨迹、审计片段
• mind 只存按主题融合后的知识，不直接堆日志
• archives 单独存日报、周报、月报、年报这类时间快照，不混到主题知识里
• 同一主题的新记忆不是不断开新文件，而是持续融合进原有主题文件，避免主题碎裂
• 通过 raw-route 把会话和任务稳定映射到同一条审计路径，避免同一个任务的后续记录四处分叉

核心思路是：先把原始事实保住，再做知识提炼，而且两层都要能回溯。

3.2 记忆融合与读取

怎么做：

• 记忆读取时先读热层，冷归档按需展开，不做全量注入
• 定时跑 memory-fusion 这类工作流，扫描 raw，把纠错、决策、偏好、知识提炼进 mind
• 融合过程会带锁和心跳，避免重复跑、并发跑、跑挂了没人知道

好处：

• 结构直观，调试成本低
• 原始现场和提炼结果不会混在一起
• 适合早期快速迭代

4. 记忆机制：数据库方案

数据库方案是另一种设计方向，把事实层、工作层、注入层彻底拆开，用显式的写入规则和指针模型来管理记忆。

4.1 分层存储与事实守卫

把”发生了什么""什么能算长期事实""什么只是当前工作态""什么只是注入产物”彻底拆开。

怎么做：

• episodes 记录原始现场，保存的是对话和执行过程本身
• memories 存长期事实，也就是可以进入事实层的内容
• context_artifacts 存的是给 prompt 用的派生上下文，不直接把事实层原文拿去注入
• recent/* 存会话期、工作期、短期状态
• 事实层存稳定长期记忆，recent/* 不能直接冒充事实层
• 写入长期记忆时会经过事实守卫：作用域不对不行，工作态稳定度不够不行，派生类别不行，没有来源不行，没有证据引用也不行

核心思路是先把不同性质的内容拆成不同层，再给每层单独的写入规则。

好处：

• 原始现场、当前状态、长期事实不会再混成一锅
• 短期工作态污染长期记忆的问题会小很多
• 长期记忆默认具备证据链和可追溯性

4.2 指针式上下文

当前生效上下文用指针模型来决定。

怎么做：

• 会话上下文被拆成不同层，常用的是 L0、L1、L2、L3
• 每一层都先写成上下文快照
• active_views 只负责指向每一层当前生效的那一份快照
• 注入时直接读当前指针，不用扫描文件目录去猜最新版本
• 会话目标、限制条件、工作状态也不再混成一段总摘要，而是拆成结构化快照分别更新，比如会话核心、会话约束、会话工作态
• 预算不够时，优先保留高价值层，其他层先压缩，而不是一刀切截断

好处：

• 当前上下文永远有唯一现行版本
• 哪一层失真、缺失、过期更容易定位
• 上下文预算紧张时也能按层降级，而不是整体崩掉

4.3 长期记忆治理：待审、替换、回执

长期记忆写进去之后还需要持续治理。

怎么做：

• 长期记忆有审核状态，至少区分已通过、待审、审核中
• 低置信或证据弱的内容，先停在待审态，不直接当稳定事实使用
• 新记忆可以替代旧记忆，旧记录会被显式标成废弃，而不是一直无上限追加
• 单独做了审核工作台，把低置信、待审、仍在活跃路径上的记忆拉出来治理
• 治理动作支持通过、拒绝、替代
• 每次注入、提交、清理、审查都会留回执，比如注入回执、提交回执、清理回执、审查回执，后面能追到”这次为什么会注入这段上下文""为什么这条记忆被替换”

好处：

• 低质量事实不会立刻污染稳定层
• 长期记忆能显式演化，而不是只会堆叠
• 整个记忆链路不再是黑箱

4.4 可视观测和操作台

数据库记忆单独配了一层可视化的观测界面，用来查看和管理记忆状态。

怎么做：

• 做了一个本地 Web 界面作为持久化记忆的伴随工具
• 默认首页是审核工作台，优先处理待审事实、证据链、活跃引用和回执，而不是先展示原始数据表
• 观测维度拆成几层：长期事实、当前生效内容、工作记忆、注入投影、演化审计
• 当前会话实际注入了什么内容，可以直接在投影视图里看到
• 每个作用域和层级当前指向哪份快照，也可以直接在活跃视图里确认
• 审查操作只开放通过、拒绝、替代这几个动作，不允许直接修改底层字段
• 认证方式跟随 OpenClaw 当前的网关配置，不单独维护一套账号体系
• 网关启动时如果观测界面不在线，会自动探测并在后台拉起，保持默认可用

好处：

• 当前生效内容、实际注入内容、长期事实可以被直观区分
• 审查操作有固定入口，不需要每次手动拼命令
• 记忆相关的问题可以直接在观测层定位，减少反复翻库的成本

4.5 派生层：蒸馏、压缩、图谱辅助

在事实层之上还有一层派生记忆，用来提升召回和注入效率，但派生层不反过来冒充事实层。

怎么做：

• 对 episodes 先切片段，再做摘要、蒸馏、压缩
• prompt 预算过大时，系统主动做压缩合并，而不是等模型被动截断
• 会定期做 pmem-distill，把近期会话里的稳定内容往长期范围收敛
• 蒸馏不只靠定时任务触发，运行时还会在消息入口识别维护信号（比如会话重置、任务完成、任务阻塞、准备收尾），然后把这些信号写进蒸馏队列，推动后续维护链及时介入
• 图谱辅助层会从 episodes 里投影出任务、技能、事件这类节点和边，用来辅助召回
• 图谱召回只是一层辅助，它提高的是找到相关上下文的能力，不直接定义事实

事实层负责准，派生层负责快；事实层负责稳定，派生层负责召回和压缩。

好处：

• 大上下文下的注入效率更高
• 召回不只靠全文检索，还能引入任务、技能、事件之间的关联
• 派生层出错时，不会直接污染长期事实层