1. 项目概述为AI智能体注入“结构性纪律”如果你和我一样深度使用过OpenClaw这类AI智能体开发框架一个核心痛点会反复出现智能体太“野”了。它们能力强大但行为模式却像一个才华横溢但缺乏自律的天才程序员——想到哪写到哪不读文档就改代码不做测试就宣布完工甚至可能一个rm -rf就把你的工作目录清空。这种“自由散漫”在快速原型阶段或许能接受但一旦进入严肃的项目开发、系统维护或需要可追溯、可协作的场景就成了灾难。systematic-claw正是为了解决这个问题而生。它不是一个普通的插件而是一个为OpenClaw智能体量身打造的“结构性纪律”强制执行框架。它的核心思想不是去“教育”或“说服”智能体变得守规矩而是通过一套精密的钩子Hook系统在智能体行动的每一个关键节点设置“关卡”和“轨道”让遵守纪律成为阻力最小的路径让破坏性行为在发生前就被拦截。简单来说它把我们从“人肉监督员”的角色中解放出来。你不用再在每次对话中反复叮嘱“先读后改”、“记得测试”、“更新相关文档”。systematic-claw会替你无声地、自动化地执行这些纪律检查。它包含了15道硬性关卡Hard Gates来拦截不良模式4个结构化工作流工具来引导正确流程以及持久化的审计日志来追踪一切。这7200行TypeScript代码构建的是一个让AI智能体工作流从“草稿”升级到“工程化”的关键基础设施。2. 核心设计哲学与架构拆解2.1 为什么是“纪律插件”而非“功能插件”大多数AI工具插件是“赋能型”的比如增加一个搜索API、一个画图工具。systematic-claw的设计哲学截然不同它是“约束与引导型”的。其设计基于几个对AI智能体行为的深刻观察健忘性与上下文丢失智能体在长对话或复杂任务中极易忘记之前读取的文件内容、做出的决策导致行为不一致。跳跃性思维与步骤缺失倾向于直接跳到解决方案跳过规划、验证、关联性更新等关键工程步骤。“完成幻觉”容易在未进行充分验证或未更新所有相关部分时就宣布任务完成。操作的不可逆风险可能执行破坏性Shell命令且缺乏“检查点”机制来回滚。因此systematic-claw的目标不是增加新能力而是为现有能力套上“安全护栏”和“操作手册”强制智能体遵循一套经过验证的、系统化的工程实践。2.2 四层钩子管道拦截、追踪、引导、审计插件的核心是一个四层的处理管道贯穿智能体执行的整个生命周期。理解这个架构就能明白纪律是如何被无缝注入的。用户/主智能体发起请求 ↓ [第一层工作流检测与提示注入] Hook: before_prompt_build 作用分析用户提示识别工作流类型如调试、创建、分析、修复并在给智能体的系统提示中动态注入针对性的引导指令如“检测到调试任务请使用debug_tracker工具”。 ↓ [第二层硬性关卡强制执行] Hook: before_tool_call 作用在智能体每次调用工具读文件、写文件、执行命令等前运行全部15道硬性关卡。例如在写文件前检查是否已读取该文件“读后编辑”关卡。 ↓ [第三层状态追踪与标志管理] Hook: after_tool_call 作用在工具调用成功后追踪关键状态记录文件读写历史、检测是否执行了验证命令如测试、构建、记录记忆搜索操作并在文件写入后清除相关的“单源真理”标志。 ↓ [第四层会话完成质量审计] Hook: agent_end 作用在智能体会话结束时执行最终检查清单是否有未完成的任务是否有未经验证的更改是否遗漏了向记忆库写入关键决策这个管道确保了纪律检查是前置的、实时的、全覆盖的。智能体不是在犯错后被批评而是在试图犯错时就被系统性地阻止。2.3 关键设计决策解析“失效关闭”与“失效开放”策略对Shell工具“失效关闭”如果关卡系统在分析一个Shell命令时出错例如解析复杂管道失败默认策略是阻止该命令执行。这是安全第一的原则宁可错杀不可放过一个潜在的危险命令。对非Shell工具“失效开放”如果关卡在对read_file、write_file这类工具进行检查时出错则允许操作通过。这是可用性优先避免因为插件自身的小bug导致所有文件操作被锁死。内存速度与持久化存储分离内存存储快会话期间的状态如“已读文件列表”、“文件写入计数器”、“关卡触发标志”全部存放在内存的Map对象中。这使得每次工具调用前的关卡检查几乎是零延迟的。持久化存储慢但稳审计日志、会话历史、跨会话的标记如“首次运行”标志则写入SQLite数据库。这保证了数据不会因进程重启而丢失便于事后分析和审计。零配置与智能脚手架插件安装即用所有配置都有符合工程直觉的默认值。首次运行时如果工作空间是空的它会自动创建STATE.md、MEMORY.md、SYSTEM/SSOT_REGISTRY.md这三个核心模板文件并显示一个引导消息。这极大地降低了启动门槛直接给出了一个结构化工作的范本。3. 15道硬性关卡深度解析与实战意义这15道关卡是纪律体系的基石。它们不仅仅是规则更是对软件工程最佳实践的编码。3.1 核心工作流关卡杜绝“想当然”开发关卡1读后编辑规则禁止编辑一个尚未被读取的文件。实战意义直接对抗智能体“盲改”的倾向。在修改config.json前必须先用read_file工具查看其当前内容。这避免了基于过时或错误的假设进行修改是代码审查和协同工作的基础。关卡2先计划后创建规则在“创建”类工作流中创建新文件需要有一个活跃的、已批准的plan_mode计划。实战意义防止项目结构变得混乱。要求智能体在创建一堆新文件前先通过plan_mode工具思考架构、命名规范和位置确保创建行为是整体设计的一部分而非随意散落。关卡3系列验证驱动完成规则3a在标记任务或计划完成前必须运行测试、构建或lint等验证命令。3b当计划完成且涉及文件变更时必须附带quality_checklist。3c计划完成时会检查“相关文件规则”如果有关联文件未更新则阻止完成。实战意义彻底消灭“完成幻觉”。它强制要求“完成”不是一个主观声明而是一个有客观证据验证通过、自查完成、关联更新的状态。这直接提升了交付物的可靠性和完整性。3.2 安全与防呆关卡守护你的工作空间关卡4死循环检测规则如果最近8次工具调用中对同一文件进行了3次以上完全相同的操作则触发此关卡将智能体重定向到debug_tracker工具。实战意义智能体有时会陷入逻辑循环反复执行一个无效操作。此关卡能及时中断这种“鬼打墙”行为强制其转入结构化的调试流程分析根本原因而不是无意义地重复。关卡5危险命令拦截规则拦截rm -rf、git push --force、删除工作空间等不可逆的破坏性命令。支持通过配置添加自定义正则表达式。实战意义这是最重要的安全网。它能防止因提示词歧义或智能体逻辑错误导致的灾难性数据丢失。实操心得建议在生产环境中将此关卡始终置于block模式并考虑将git reset --hard等命令也加入自定义黑名单。关卡6 7资源与节奏管控规则6引导/配置文件大小超过28KB警告超过35KB则阻止写入。防止巨型配置文件浪费宝贵的上下文窗口。7每进行3-4次文件写入操作后必须执行一次验证命令才能继续写入。实战意义关卡6优化了上下文使用效率。关卡7则强制了“小步快跑持续验证”的敏捷开发节奏避免在大量未经验证的代码上越走越远一旦出错回溯成本极高。3.3 质量与一致性关卡提升工程输出关卡8复杂性审查规则当一次性修改超过2个文件且没有附带quality_checklist时操作会被阻止。实战意义多文件变更通常意味着更复杂的逻辑改动风险更高。此关卡强制智能体在此时进行自我审查思考变更的影响面和回归风险将质量保障内化到流程中。关卡9系列单源真理意识规则9a创建包含4步以上或已有修改的计划时必须首先读取SSOT_REGISTRY.md。9c每次向工作空间文件写入前都必须已读取过SSOT_REGISTRY.md该标志在每次写入后重置。实战意义这是维护项目知识一致性的关键。SSOT_REGISTRY.md定义了每个信息的权威来源。此关卡确保智能体在修改任何东西前都清楚信息的归属和依赖避免在多个文件中维护重复或冲突的信息这是中大型项目可维护性的生命线。关卡10 12上下文与意图管理规则10向其他智能体会话发送消息前必须先进行记忆搜索。12创建子智能体时必须提供thinking参数。实战意义关卡10确保信息分发是基于上下文的而不是随意的“广播”提高了智能体间协作的针对性。关卡12则杜绝了“无脑创建”子智能体的行为要求创建者必须明确交代意图和背景使得多智能体协作更加有序。关卡11 13技能与工作空间规范规则11写入skills/目录下的文件前必须阅读对应的技能说明文档。13工作空间根目录只允许存放.md文件其他类型文件会被阻止。实战意义关卡11保证了技能开发的规范性遵循其设计契约。关卡13则是一种强制的项目结构治理保持根目录的整洁和文档化将代码、配置等资源约束在合适的子目录中这是一种良好的工程习惯。3.4 Shell写入检测无死角的防护一个精妙的设计是关卡11b和13b能够解析Shell命令文本检测通过重定向操作符,,tee,cat 进行的文件写入。这意味着即使智能体试图用echo code src/file.js或cat config.yaml来绕过常规的write_file工具这些关卡依然会生效确保了防护体系没有漏洞。4. 四大工作流工具从混乱到有序的导航仪如果说关卡是“禁止做什么”那么这四个工具就是“应该怎么做”的指南针。它们将最佳实践封装成智能体可以交互的标准化流程。4.1task_tracker层次化任务管理这不是一个简单的待办清单。它支持父子任务关系非常适合管理具有依赖关系的复杂项目。核心操作create,update,add_subtask,complete,delete,list,checkpoint,rollback。核心价值检查点/回滚在执行风险操作如重构、批量替换前可以创建一个检查点。如果出现问题可以快速回滚到之前的状态。这为智能体的操作提供了“撤销”保险。文件关联任务可以记录files_affected建立了任务与产出物之间的可追溯链路。验证证据完成任务时需要记录是如何验证的例如“运行了单元测试X通过了所有用例”。这使得“完成”状态是可审计的。4.2plan_mode结构化执行计划这是应对复杂任务的终极武器。它将执行过程标准化为创建 → 批准 → 执行 → 验证 → 完成。核心操作create,approve,advance,complete_step,verify,complete,status,cancel。核心价值四透镜头脑风暴当计划步骤≥4时强制要求从约束条件、影响半径、可逆性、成功标准四个维度进行思考。这迫使智能体在动手前进行全面的风险评估和方案设计。备选方案分析同样对于≥4步的计划要求提供至少两种实现方案并进行权衡分析。这避免了“第一条路走到黑”的思维定式。与任务跟踪器联动计划中的每一步都可以自动链接到task_tracker中的一个子任务实现了宏观计划与微观任务的无缝对接。4.3debug_tracker基于证据的调试协议禁止“瞎试”强制“科学调试”。它要求遵循“开始 → 复现 → 提出假设 → 测试 → 解决/上报”的严格流程。核心价值假设驱动每个假设必须附带证据和测试计划。不能只说“可能是A问题”而要说“因为出现了Y日志所以假设是A问题我将通过执行X操作来验证”。失败熔断最多允许3个假设失败。如果3个假设都被证伪则必须将问题上交给用户。这防止了智能体在错误的方向上无限期地浪费时间。结构化记录整个调试过程被完整记录形成了宝贵的故障排查知识库。4.4quality_checklist强制自我审查在会话结束或完成关键变更前强制智能体进行一轮标准的自我审查。审查项每项要求至少15个字符不能用“N/A”敷衍验证你运行了哪些命令来验证边界情况你考虑了哪些边界情况回归风险什么可能被破坏差距分析还有什么是不完整的压力测试你是否进行了压力测试实战意义这五个问题是从代码审查清单中提炼的精华。强制回答这些问题能显著提升智能体输出的思考深度和完备性将潜在问题暴露在实施之前。5. 完整配置、部署与定制指南5.1 安装与零配置启动部署极其简单体现了“约定优于配置”的思想。# 1. 进入OpenClaw扩展目录 cd ~/.openclaw/extensions # 2. 克隆插件仓库 git clone https://github.com/ilkerbbb/systematic-claw.git # 3. 安装依赖 cd systematic-claw npm install # 4. 编辑OpenClaw主配置文件 # 将以下配置添加到你的 openclaw.json 中 { plugins: { allow: [systematic-claw], // 允许加载此插件 entries: { systematic-claw: { enabled: true // 启用插件 } } }, tools: { alsoAllow: [group:plugins] // 允许插件注册的工具被调用 } } # 5. 重启OpenClaw网关 # 具体重启命令取决于你的部署方式通常是 openclaw gateway restart # 或者重启你运行gateway的进程完成以上步骤后插件即生效。首次运行时如果你的工作空间目录默认为~/.openclaw/workspace是空的你会看到引导信息并发现系统自动创建了STATE.md等核心模板文件。5.2 核心配置项详解虽然插件开箱即用但为了适应不同团队和项目的需求它提供了细致的配置选项。你可以在openclaw.json的插件配置部分进行覆盖。{ plugins: { entries: { systematic-claw: { enabled: true, config: { gateMode: block, // 关键决定关卡是“阻止”还是“警告” gateVerbosity: summary, // 控制关卡活动在提示中的可见度 taskTrackerEnabled: true, planModeEnabled: true, completionCheckEnabled: true, // 会话结束时的审计 memoryEnforcementEnabled: true, // 记忆相关关卡 debugTrackerEnabled: true, workflowDetectionEnabled: true, // 自动工作流检测 propagationEnabled: true, // 相关文件更新传播 scaffoldOnFirstRun: true, // 首次运行创建模板 workspaceRoot: ~/.openclaw/workspace, // 工作空间路径 dangerousCommands: [], // 可扩展的危险命令列表 bootstrapSizeWarnKB: 28, bootstrapSizeBlockKB: 35, dependencyMapPath: null // 自定义依赖映射文件 } } } } }关键配置决策建议gateMode: warn用于过渡期如果你刚开始引入这个插件或者你的智能体已经习惯了无约束环境可以先将模式设为warn。这样智能体仍能执行操作但会在日志中收到警告帮助你了解哪些行为需要被规范是一个平滑的适应过程。自定义危险命令dangerousCommands数组允许你添加项目特定的危险命令正则表达式。例如如果你的项目有自定义的清理脚本./scripts/nuke-everything.sh可以将其加入列表。调整文件大小限制bootstrapSizeWarnKB和bootstrapSizeBlockKB主要针对的是引导配置文件。如果你的项目确实需要大型配置文件可以根据实际情况调高这些阈值。5.3 高级定制相关文件规则与依赖映射这是插件最强大的可扩展性特性之一允许你定义项目特有的文件关联逻辑。内置相关文件规则已经覆盖了常见场景例如修改STATE.md就应该更新MEMORY.md修改技能文件就应该更新TOOLS.md。自定义依赖映射对于更复杂的项目结构你可以创建一个JSON文件来定义精确的依赖关系。创建依赖映射文件例如./my-project-deps.json{ src/core/api.ts: [ src/core/api.test.ts, docs/api-reference.md, src/clients/sdk.ts ], database/schema.prisma: [ src/generated/client.ts, scripts/migrate-db.sh, docs/data-models.md ], package.json: [ README.md, // 确保README中的安装说明同步 Dockerfile // 确保Dockerfile中的依赖版本同步 ] }在插件配置中指定路径dependencyMapPath: ./my-project-deps.json配置后当智能体修改了src/core/api.ts并试图完成一个计划时如果api.test.ts或docs/api-reference.md未被更新关卡3c就会触发阻止计划完成。这强制实现了跨文件的逻辑一致性更新是保持项目文档、代码、测试同步的自动化利器。实操心得建议在项目初期就定义这个依赖映射。它不仅仅是一个约束工具更是一个活的项目架构文档清晰地定义了模块间的依赖和影响关系。新加入项目的智能体或开发者通过这个映射就能快速理解项目的结构脉络。6. 实战场景与避坑指南6.1 场景一从零开始构建一个微服务API假设你要求智能体“为我们新的用户服务创建一个RESTful API包含用户CRUD操作。”没有systematic-claw智能体可能直接开始创建app.js、routes/user.js、models/User.js等文件过程中可能会忘记创建测试文件、更新package.json、编写API文档。最后它说“完成了”但你无法确信是否所有部分都就绪。有systematic-claw工作流检测识别为“创建”工作流在提示中建议使用plan_mode。计划阶段智能体被迫使用plan_mode create。由于步骤肯定超过4步它必须进行“四透镜头脑风暴”和“备选方案分析”比如考虑使用Express还是Fastify数据库用SQL还是NoSQL。执行阶段每次创建文件前会检查SSOT_REGISTRY.md关卡9c。尝试直接写models/User.js时会被关卡1读后编辑阻止因为它还没读这个不存在的文件。它会先创建文件然后写入。在连续创建了几个文件后关卡7验证优先会要求它运行npm test即使测试是空的或npm run lint确保环境没问题。关联更新当它修改package.json添加依赖时内置规则会检查README.md是否更新了安装说明。你的自定义依赖映射可能还会检查Dockerfile。完成阶段在标记计划完成前必须运行测试关卡3a填写quality_checklist关卡3b并确保所有相关文件已更新关卡3c。最终审计会话结束时agent_end钩子会检查是否有未完成的任务或未验证的更改。整个过程是结构化、可审计、高质量的。6.2 场景二调试一个棘手的生产环境Bug用户报告“用户上传大文件时服务偶尔会返回500错误。”没有systematic-claw智能体可能会随机地查看日志文件、修改配置、重启服务进行各种尝试过程混乱且没有记录。有systematic-claw工作流检测识别为“调试”工作流强烈建议使用debug_tracker。结构化调试智能体启动debug_tracker。复现它首先尝试复现问题记录步骤和环境。假设1“可能是Nginx客户端最大 body size 限制”。它必须提供证据查看Nginx错误日志并制定测试计划调整client_max_body_size并测试。测试后假设被证伪。假设2“可能是Node.js流处理内存溢出”。同样需要证据和测试。如果连续三个假设都失败debug_tracker会强制智能体将问题上交给你并附上完整的调试记录节省了大量无方向的摸索时间。6.3 常见问题与排查技巧问题智能体所有操作都被阻塞日志显示大量Gate错误。排查首先检查gateMode是否误设为block而智能体还未适应新规则。可以临时改为warn模式观察具体哪些关卡被触发。最常见的原因是未阅读SSOT_REGISTRY.md关卡9c。确保在会话开始或进行任何写操作前智能体已执行read_file读取了该文件。技巧在给智能体的初始提示中可以加入一条指令“在开始任何工作前请首先阅读SYSTEM/SSOT_REGISTRY.md文件以了解本项目的信息架构。”问题task_tracker或plan_mode工具无法正常使用智能体说找不到工具。排查检查openclaw.json配置中是否包含了alsoAllow: [group:plugins]。没有这一行插件注册的工具不会被暴露给智能体。排查确认插件已正确启用且网关已重启。可以查看OpenClaw的网关日志搜索systematic-claw看是否有加载成功的消息或错误信息。问题自定义的dependencyMapPath规则似乎没有生效。排查确认配置文件路径是否正确是相对于网关进程的工作目录还是绝对路径。检查JSON格式是否正确确保是有效的JSON。规则只在plan_mode complete或特定关卡3c触发时检查普通文件写入不会触发。确保你是在一个计划完成的上下文中测试。查看插件的审计日志通常存储在SQLite数据库中可以看到关卡触发的详细记录。问题插件导致性能下降工具调用变慢。分析15道关卡的检查是在内存中进行的开销极低。性能瓶颈可能出现在SQLite审计日志写入大量工具调用时每次after_tool_call都写库可能成为瓶颈。可以考虑在开发环境降低日志级别或确保数据库文件在SSD上。复杂Shell命令解析如果智能体频繁执行极其复杂的管道命令解析开销会增大。但这通常不是问题。建议对于超高性能要求的场景可以暂时关闭completionCheckEnabled和auditLogEnabled如果未来版本提供来测试。问题如何查看插件到底做了什么方法将gateVerbosity设置为verbose。这样在每次给智能体的提示中都会附带一份详细的关卡活动报告包括每个关卡检查了多少次、阻止/警告了多少次。这是了解和调试插件行为的宝贵窗口。方法直接查询插件的SQLite数据库文件通常位于插件目录的store/下里面完整记录了所有会话、工具调用和关卡事件。7. 开发与扩展指南systematic-claw本身是开源的TypeScript项目这意味着你可以根据自己的需求进行修改或扩展。7.1 项目结构与扩展点systematic-claw/ ├── src/hooks/ # 核心钩子实现 │ ├── hard-gates.ts # 【扩展点1】在此添加新的硬性关卡 │ └── prompt-inject.ts # 【扩展点2】在此修改工作流检测逻辑或提示词 ├── src/tools/ # 工作流工具实现 │ └── ... # 【扩展点3】在此创建新的结构化工具 ├── src/store/ # 状态与持久化 │ └── schema.ts # 【扩展点4】在此修改数据库结构 └── src/scaffold.ts # 首次运行脚手架添加一个新关卡在src/hooks/hard-gates.ts的HARD_GATES数组中添加一个新的Gate对象。实现其check函数接收ToolCall和SessionState返回GateResult。在src/hooks/hard-gates.ts的runHardGates函数中确保它被调用。添加一个新的工作流检测规则在src/hooks/prompt-inject.ts的WORKFLOW_PATTERNS数组中添加新的正则表达式模式。在detectWorkflow函数中关联该模式与一个工作流类型。在getWorkflowGuidance函数中为该类型返回特定的引导文本。7.2 开发工作流# 1. 克隆并进入项目 git clone https://github.com/ilkerbbb/systematic-claw.git cd systematic-claw # 2. 安装依赖 npm install # 3. 进行代码修改 # 4. 类型检查项目直接加载TS无需构建 npx tsc --noEmit # 5. 一个重要的检查确保没有硬编码的用户路径 grep -r /Users/ src/ # 或适用于你系统的路径模式 # 插件应使用 os.homedir() 或环境变量来保证可移植性。 # 6. 测试重启OpenClaw网关观察你的修改是否生效。 # 你可以通过在一个测试工作空间中触发相关行为来验证。开发心得由于插件通过钩子深度集成到OpenClaw运行时一个错误的关卡可能导致所有工具调用被阻塞。建议在开发新功能时始终在配置中设置gateMode: warn并开启gateVerbosity: verbose以便在不中断工作流的情况下观察插件行为看到详细的日志输出。7.3 设计你自己的结构化工具如果你有一个重复的、需要规范化的复杂操作流程可以考虑将其设计成一个类似plan_mode的工具。一个好的结构化工具应该有明确的阶段或状态像调试的“复现-假设-测试”阶段。强制输入关键信息像质量检查清单的五个必填项。与关卡系统联动工具可以设置或检查会话状态中的标志被关卡系统所感知。提供撤销或回滚能力像task_tracker的检查点机制。systematic-claw不仅仅是一个插件它更提供了一种方法论如何将人类的最佳实践编码成机器可理解和执行的规则。通过使用它、理解它甚至扩展它你最终训练出的不仅是一个更守纪律的AI智能体更是一个与你有着相同工程哲学和质量标准的数字化协作者。