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 方向：

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

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

2.2 JSON 工作方案：计划直接进入状态管理

每个任务开始前，先落一个结构化的 JSON 工作方案，让计划直接进入状态管理。

怎么做：

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

这里的重点，是让计划成为系统可读、可校验、可恢复的状态锚点。

好处：

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

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

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

怎么做：

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

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

好处：

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

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

搜索会被拆成一条可治理的链路。

怎么做：

• 先把搜索能力拆成不同角色：本地线索、引擎搜索、通用来源、垂直来源、证据浏览器
• 再把搜索计划拆成不同通道：本地通道、通用通道、垂直通道
• 本地通道负责本地线索确认，比如 qmd、本地知识库、现有审计记录
• 通用通道负责泛搜索和候选扩展
• 垂直通道负责垂直平台补充
• 搜索工具主要负责找候选链接和线索，真正要下结论时再交给证据浏览器打开页面做取证
• 某些不希望走的内置工具会直接屏蔽，强制只走允许链路
• 候选链接进入结果区之前，会先做可访问性校验，HTTP 200 才进入有效结果
• 如果需求指定了链接数量，链路会继续补充候选并完成校验，直到有效结果数量满足要求
• 资料核实时会同步整理 evidence_records（证据记录表）和 source_matrix（来源矩阵），再检查独立来源数量
• 当搜索覆盖还不够，或者仍有可用引擎时，链路会继续补充，直到结果收口
• 搜索结果输出前还会检查独立来源覆盖，默认至少要补到 2 个独立站点

这里把本地优先直接收进搜索治理里：本地能确认的先确认，再把外部搜索当成扩展链路往外推。

好处：

• 搜索链路可以被治理，并保持稳定
• 本地线索、泛搜索、垂直搜索的分工更清楚
• 找到候选和验证候选被拆开，误判率会明显下降
• 链接清单、下载链接、资料来源这类结果更容易直接交付成可用集合

2.5 结果优先：执行拦截直接围绕结果展开

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

怎么做：

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

所以这里的结果优先，会落实成三件事：

1. 持续推进
2. 结果带证据
3. 收口前补齐验证

好处：

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

2.6 遇到问题先自愈

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

怎么做：

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

好处：

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

2.7 长任务保活和自动恢复

长任务会利用定时器巡查，持续检查推进状态。

怎么做：

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

这个机制会把停滞和恢复一起纳入运行态管理，形成完整的长任务保活链路。

好处：

• 长任务挂住时也会留下明确的状态回响和恢复信号
• 恢复动作有据可依
• 失败、停滞、阻塞都会留下状态痕迹

2.8 执行交付：改动、核验、回执一起回报

执行类任务完成后，交付会把改动和证据一起挂出来。

怎么做：

• 修改类任务完成后，会直接回报文件路径和改动落点
• 如果一次改了多个文件，会按文件逐项列出路径和作用
• 执行验证会补命令结果、日志片段或页面证据
• 搜索结果会补有效链接、过滤统计、来源标注和来源矩阵
• 资料核实会补独立来源数和可回溯的证据编号
• 交付阶段会把这些信息整理成可直接回看的结果块，方便后续复盘

好处：

• 改了哪些文件一眼能看出来
• 哪些结果已经核实、哪些还在待验能直接分开
• 交付内容可以直接进入复盘和审查

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 里投影出任务、技能、事件这类节点和边，用来辅助召回
• 图谱召回作为辅助层，负责提升相关上下文定位能力，事实判断仍由事实层和证据链承接

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

好处：

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