research-blog/content/posts/openclaw-development-mechanism.md at 9671be81295c799ae73084a33cf5c83bf7b7fa75

wuyang/research-blog

Fork 0

Files

T

wuyang6 b861578bb8 publish OpenClaw development mechanism research

2026-08-10 11:41:00 +08:00

34 KiB

Raw Blame History

title, summary, date, updated, topic, tags, kind, status, visibility, canonicalUrl, sourceRepo, preview

title

summary

date

updated

topic

先区分五种东西

理解 OpenClaw 的第一步，不是背 Skill 名称，而是分清它们在系统中的位置。

对象	它是什么	什么时候起作用	能否自行产生外部变化
`AGENTS.md`	给 Agent 的仓库规则和路由说明	Agent 进入仓库或相应目录时读取	不能；它只是规则文本
Skill	某类任务的具体工作方法，通常是一份 `SKILL.md`	Agent 接到匹配任务、规则要求使用，或操作者显式调用时	取决于 Skill 调用的工具和权限；Skill 本身不是进程
GitHub Workflow	由事件、定时任务或人工按钮启动的自动化流程	YAML 中的 `on` 条件成立时	可以，但权限由 Workflow 和 Token 决定
维护服务	有队列、状态、调度和恢复能力的长期系统，如 ClawSweeper	收到事件、命令或定时扫描时	可以，但实际写操作应经过策略和状态复核
CI / 门禁	编译、测试、扫描、证据校验和聚合状态	PR、Push、Release 等事件发生时	通常只给出状态；分支保护据此允许或拒绝合并

OpenClaw 根目录的 AGENTS.md 用一句话划清了边界：根规则负责硬约束和任务路由，Skill 负责具体工作流程。进入子目录后，Agent 还要读取离代码更近的 scoped AGENTS.md。因此规则不是一个无限增长的总提示词，而是按代码责任范围逐层加载。

一项改动怎样完成

OpenClaw 的开发闭环可以压缩为七步。这里同时标出 Agent、确定性系统和人的责任。

阶段	Agent 做什么	系统怎样验证	谁拥有最终决定
1. 接收问题	读取 Issue、PR、规则、产品方向和相关历史	检查目标对象、分支和当前状态	维护者决定产品方向和优先级
2. 调查原因	沿入口、Owner、调用者、被调用者、相邻实现、测试和依赖建立证据图	通过源码、历史、复现和依赖契约交叉验证	Agent 可以形成判断；高风险结论交给 Owner
3. 复现问题	在修改前保存失败命令、场景或真实行为证据	要求同一复现在旧代码失败	无法复现时不能把猜测当成根因
4. 实现修复	在责任边界处修复根因，并检查相邻功能	相关测试、静态检查、Diff 和生产代码增量	行为、协议、安全或迁移变化需要相应 Owner
5. 本地复审	使用 `autoreview` 让第二个模型审查未提交改动；修改后重新审查	`test-audit` 检查测试是否真实、有效且不重复	新发现必须处理或明确说明不采纳原因
6. 提交证据	PR 说明问题、原因、影响和验证证据	CI、真实行为证明、ClawSweeper 评论和 Required Gate	平台策略决定是否满足合并条件
7. 合并或发布	Agent 可协助修复 CI、更新文档、生成发布材料	精确 Head SHA、必需检查、可合并状态、发布校验	维护者或预先授权的确定性策略执行最终动作

这套流程的核心不是步骤多，而是模型不能同时拥有判断、写入和最终授权。例如 ClawSweeper 的审查阶段不给 Codex GitHub 写 Token；模型先产出结构化判断，随后由可信代码重新读取 GitHub 当前状态、校验快照和策略，才可能评论、关闭或合并。相关约束可在 ClawSweeper README 和 VISION 中核对。

三个 Skill 怎样执行

`autoreview`：提交前的第二个模型审查

位置：/.agents/skills/autoreview/SKILL.md

它在非简单代码改动准备提交或交付前生效。根规则把它设为默认必经步骤，除非用户明确跳过，或改动确实只是简单文档。

执行过程是：

确认审查范围，是未提交 Diff 还是一段 Commit；
先做密钥扫描，避免把敏感信息送入审查模型；
打包 Diff、必要上下文和仓库规则；
默认调用 Codex，也可使用 Claude 或 Pi 作为独立审查者；
输出按严重程度组织的结构化 Findings；
修复可采纳问题，重新执行相应测试；
对新 Diff 再审一遍，直到没有可执行问题。

它解决的是“实现者容易忽略自己引入的问题”，不是证明程序真实可用。源码审查对运行行为不可见，因此仍需测试、真实行为证据和 CI。

`test-audit`：防止测试只是看起来通过

位置：/.agents/skills/test-audit/SKILL.md

它在新增、修改或审查测试时生效。关注点不是“有没有测试文件”，而是测试是否真的保护了行为：

确认测试对应的生产行为和失败风险；
检查修改前的代码是否会让该测试失败；
检查测试是否调用真实入口，而不是绕过生产接线；
检查 Mock 是否掩盖了集成问题；
检查断言是否只验证“函数被调用”，而没有验证用户可见结果；
搜索相邻测试，避免复制同一断言形成虚假的覆盖量；
删除低价值测试或补足缺少的边界、故障和回归场景。

这也是 OpenClaw 所谓“验证证据”的一部分：一个测试通过，并不自动等于它有证明力。

`crabbox`：把高成本或高风险验证送到隔离环境

位置：/.agents/skills/crabbox/SKILL.md

Crabbox 不是代码审查模型，而是远程验证的控制面。它在全量测试、跨操作系统、真实服务、桌面交互、安装升级、性能剖析，或不应在本机执行不可信代码时生效。

典型过程是：选择可信级别和目标环境，申请带租约的远程机器，同步指定 Commit，执行真实场景，收集日志、截图、录像和时间数据，确认目标 SHA，最后释放环境。仓库规则还区分可信维护者代码与外部 PR：不可信代码不能回退到本机执行，也不能获得带凭据的测试环境。

因此它解决的是“在哪里、以什么权限、拿什么证据运行”，不是替代测试设计。

45 个项目内 Skill

下表以当前 Commit 为准。每个 Skill 的真实位置都是 .agents/skills/<name>/SKILL.md；表中的“生效时机”表示任务匹配后由 Agent 加载执行，不表示后台常驻。

开发、审查与文档

Skill	主要任务	项目位置	生效时机
`agent-transcript`	为 Agent 创建的 Issue/PR 附加脱敏会话记录	路径	Agent 准备创建 GitHub Issue 或 PR 时
`autoreview`	用独立模型审查本地 Diff，并循环修复 Findings	路径	非简单代码改动提交、交付或开 PR 前
`channel-message-flows`	为频道消息链路生成 QA Lab 过程证据	路径	验证频道收发、状态和失败路径时
`control-ui-e2e`	用 Vitest、Playwright 和 Mock Gateway 验证 Control UI	路径	UI 行为变化需要浏览器证据时
`openclaw-debugging`	选择日志、探针、实时环境和复现路径定位问题	路径	模型、Provider、Tool、Streaming 或线上行为异常时
`openclaw-docker-e2e-authoring`	编写 Docker E2E 和真实 Provider 验证 Lane	路径	新增或修改容器化端到端测试时
`openclaw-live-updater`	维护实时 Main Checkout、Gateway、Mac App 和全发布验证	路径	更新持续运行的 OpenClaw 验证环境时
`openclaw-refactor-docs`	在源码核对后重构现有文档页	路径	修改既有文档结构或表述时
`openclaw-testing`	按改动风险选择测试、CI、Docker 和发布验证	路径	需要决定跑哪些检查或解释失败时
`prototype-openclaw-tui`	用固定 Fixture 制作一次性 TUI 原型	路径	探索终端界面方案且不接真实状态时
`technical-documentation`	编写和审查技术文档与 Agent 指令	路径	需要形成可维护的技术说明时
`test-audit`	审计测试是否真实、有效、非重复	路径	新增、修改或审查测试时强制使用

QA、远程环境与真实行为证明

Skill	主要任务	项目位置	生效时机
`auto-qa`	组织多 Lane 自主 QA、修复与证据汇总	路径	人工发起大范围 QA 活动时；不是定时服务
`crabbox`	调度远程、跨 OS、E2E、桌面和隔离验证	路径	本地验证不合适、不可信或成本过高时
`openclaw-parallels-smoke`	在 macOS、Windows、Linux Guest 验证安装、升级和 Gateway	路径	需要虚拟机跨平台 Smoke 时
`openclaw-qa-testing`	执行、观察、调试和扩展 QA Lab 场景	路径	QA Lab Case 或产物需要验证时
`parallels-discord-roundtrip`	在虚拟机中完成 Discord 发送、回复和回读闭环	路径	Discord 跨主机真实闭环验证时
`telegram-crabbox-e2e-proof`	在 Crabbox 中用真实 Telegram 用户行为生成录像与证据	路径	Telegram 可见行为需要真实端到端证明时

GitHub 维护、检索与积压治理

Skill	主要任务	项目位置	生效时机
`claw-score`	审计并更新功能成熟度 Scorecard	路径	需要结合 QA 证据重算成熟度时
`clawdtributor`	用 Discrawl 和实时 GitHub 证据整理贡献者 PR/Issue	路径	贡献者分诊、归组和摘要时
`clawsweeper`	操作 ClawSweeper 审查、修复、Autofix、Automerge 和监控	路径	人在 Agent 会话中管理 ClawSweeper 系统时
`discord-clawd`	与 Discord 中的 OpenClaw Agent/Session 对话	路径	需要调用 Discord 侧 Agent，而非搜索历史时
`discrawl`	搜索、同步和汇总 Discord Archive	路径	需要从 Discord 历史中取证时
`gitcrawl`	本地化 GitHub Issue/PR，做检索、聚类和重复项分析	路径	批量分诊或查找相关 Issue/PR 时
`graincrawl`	搜索和同步 Granola 会议记录与转录	路径	需要从会议资料中找决策依据时
`notcrawl`	搜索、同步和导出 Notion 页面与数据库	路径	需要从 Notion 工作区取证时
`openclaw-pr-maintainer`	处理 OpenClaw Issue/PR 的调查、审查、标签、关闭和合并	路径	维护者任务出现 Issue/PR URL 或编号时立即使用
`openclaw-repair-sweep`	用 Worker Fleet 调查和修复一批 Issue/PR	路径	人工发起有边界的批量修复活动时
`slacrawl`	搜索、同步和查询 Slack Archive	路径	需要从 Slack 历史中取证时
`tag-duplicate-prs-issues`	用 GitCrawl 分组并标注重复 Issue/PR	路径	批量治理重复项并同步 GitHub 时

性能、CI 与安全

Skill	主要任务	项目位置	生效时机
`openclaw-ci-limits`	分析 Runner 容量、并发、分片和排队健康	路径	CI 变慢、排队或需要调整 Fan-out 时
`openclaw-ghsa-maintainer`	调查、修补、验证和发布 GitHub Security Advisory	路径	维护 GHSA 和私有安全修复分支时
`openclaw-secret-scanning-maintainer`	分诊、脱敏并解决 Secret Scanning Alert	路径	GitHub 报告密钥泄漏风险时
`openclaw-test-heap-leaks`	用 RSS、Heap Snapshot 和 Retainer 定位测试内存增长	路径	Vitest OOM、RSS 持续增长或怀疑泄漏时
`openclaw-test-performance`	建立基线并诊断测试、Import、CPU、内存和覆盖开销	路径	测试或插件套件变慢，需要优化时
`security-triage`	结合发布版本、信任边界和证据分诊安全问题	路径	安全报告或可疑行为需要定级时

发布与对外沟通

Skill	主要任务	项目位置	生效时机
`discord-user-post`	以已登录用户身份发布经过批准的 Discord 消息	路径	维护者批准需以用户身份发布的消息时
`openclaw-changelog-update`	根据 Git 历史重新生成发布 Changelog	路径	准备 Release 内容时
`release-openclaw-announcement`	起草并发布 Discord Release Announcement	路径	Release 已确认，需要对外公告时
`release-openclaw-ci`	启动、观察、调试并总结完整 Release CI	路径	发布候选进入完整门禁时
`release-openclaw-mac`	处理 macOS 签名、公证、Appcast 和资产	路径	发布 macOS 应用时
`release-openclaw-maintainer`	组织 Stable、Beta、Extended Release 和 Backport	路径	维护者准备正式或测试发布时
`release-openclaw-nightly`	维护 Alpha/Nightly 分支、保留策略和前向合并	路径	夜间发布自动化或故障恢复时
`release-openclaw-plugin-testing`	验证插件预发布包、生命周期、Doctor、SDK 和 Docker	路径	插件进入预发布验证时
`verify-release`	从精确版本、产物来源、安装和 Live Gateway 核验发布	路径	发布前后需要独立确认时

AI 自动维护系统

Skill 只有被 Agent 调用才执行。下面这些才是会被定时、事件或人工 Dispatch 启动的自动系统。表中只列当前源码能够确认使用模型进行判断或生成的维护任务，不把普通 CI 混入其中。

系统	触发方式	AI 负责什么	非 AI 系统负责什么	是否直接改仓库
ClawSweeper	定时扫描、Issue/PR 事件、维护者命令	审查、根因判断、修复方案、受限代码修复	Token、幂等、Ledger、Snapshot、配额、评论/关闭/合并门禁	审查默认只提议；Autofix/Automerge 需显式授权和精确状态门禁
Clownfish	维护者提供或系统生成的候选 Cluster	对一组高度相关 Issue/PR 做第二遍保守归并判断	重新读取实时状态，限制只处理一个 Cluster，记录动作	默认 Proposal-first，满足策略后才执行窄范围整理
`dated-todo-sweep.yml`	每周一及人工启动	阅读带日期 TODO 的上下文，判断逾期、到期或未来事项	脚本收集候选、验证报告、用新 Token 更新跟踪 Issue	模型无 GitHub 写 Token；Publisher 更新 Issue
`docs-agent.yml`	Trusted Main CI 成功后及人工启动；有小时限流	修正现有文档与当前源码不一致之处	只允许文档、README、CHANGELOG；禁止增删文件；验证当前 Main SHA 和文档检查	模型不 Push；可信 Job 在无过期竞争时提交
`test-performance-agent.yml`	Trusted Main CI 成功后及人工启动；有每日限流	寻找小型、保持覆盖率的测试性能优化	固定前后基线、限制路径、禁止增删改名、保证测试数不减少、跑完整检查	验证通过后由 Bot 提交，而不是模型直接 Push
`maturity-scorecard.yml`	人工启动或被其他 Workflow 调用	依据 QA 证据更新成熟度判断	只允许修改一个 YAML，验证并渲染文档，另一个 Job 创建 PR	可生成 PR，不直接修改 Main
`control-ui-locale-refresh.yml`	相关文件 Push、Release、每日定时、人工启动	Anthropic 优先、OpenAI 回退，刷新 20 个 UI Locale	并行矩阵、补丁合并、确定性校验、生成 PR	创建可自动合并的生成型 PR
`native-app-locale-refresh.yml`	相关文件 Push 或人工启动	刷新 21 个 Native App Locale	合并补丁、验证格式和范围、生成 PR	创建可自动合并的生成型 PR
`mantis-telegram-desktop-proof.yml`	人工启动	Codex 判断改动需要怎样的 Telegram Desktop 前后证据并执行验证	Workflow 约束目标 PR、环境、产物和发布方式	不维护业务代码；只发布验证证据

auto-qa 和 openclaw-repair-sweep 虽然可以让 Agent 大规模工作，但它们仍是人工发起的 Agent 工作方法，不是常驻后台服务。相反，ClawSweeper 有自己的队列、状态、Ledger、定时扫描和恢复机制，才是真正的自治维护系统。

还要避免另一个误解：ClawSweeper 当前主要审查 Issue 和 PR，不是持续扫描每个 Commit。它的 Push/Manual Commit Review Lane 已在 2026 年 7 月停止，离线分支审查仍保留为 local-review；只有选定主分支 Commit 的人工审查能力保留。提交前审查主要由本地 autoreview 和 PR 阶段的 CI/ClawSweeper 分担。

这些维护 Agent 还依赖四个容易被误认为“另一个 AI”的支撑系统：

系统	实际职责	为什么不是另一个审查模型
Barnacle Auto Response	根据可信 Workflow 代码执行标签、模板提示、自动响应和 Stale 规则	规则由 JavaScript 明确实现；它提供可预测的仓库卫生处理
GitCrawl	把 Issue/PR 同步到本地数据库，支持检索、重复聚类和批量分诊	它准备数据和候选集合，最终语义判断交给 Agent 或维护者
Crabbox	租用、同步和管理隔离测试机器，收集日志、遥测和真实行为证据	它是执行与证据控制面，不决定代码是否正确
CrabFleet	记录、观察和干预长时间运行的 Agent Job	它提供会话注册、时间线和 Steering，不替代具体任务 Agent

这四个系统分别解决规则执行、数据输入、验证环境和运行控制。模型判断、基础设施和权限控制因此可以独立替换和审计。

性能不是一条 Workflow

OpenClaw 的性能机制分成测量、诊断和修复三层。

层次	主要实现	产出
测量	`openclaw-performance.yml` 与 `package.json` 中的 Perf Scripts	Kova 场景、Gateway 启动/WebSocket/Health、SQLite、CLI 启动、扩展内存、CPU/Heap/Trace 产物
诊断	`openclaw-test-performance`、`openclaw-test-heap-leaks`	前后基线、慢 Group、Import Hotspot、CPU、RSS、Heap Retainer 和根因说明
自动修复	`test-performance-agent.yml`	在完整基线和路径限制下尝试小型优化，验证不减少测试和覆盖后提交

openclaw-performance.yml 不是笼统地记录一次总耗时。它把目标解析、Kova 场景、源码性能探针、产物发布和缺少产物保护拆开；需要时还生成 CPU、Heap 和 Trace。仓库脚本另有 test:perf:groups、test:perf:groups:compare、test:perf:hotspots、test:perf:imports、test:startup:bench、test:extensions:memory 和 test:sqlite:perf 等入口。

Test Performance Agent 最值得借鉴的不是“AI 会优化测试”，而是它的防作弊结构：

修改前先跑完整测试分组基线；
模型只能修改允许的现有文件，不能新增、删除或改名；
修改后使用同一命令重跑完整基线；
测试数量不得减少；
再执行变化范围检查；
只有确定性 Job 确认改善且没有破坏约束，才允许 Bot 提交。

AI 负责寻找优化机会，测试数量、路径范围、前后比较和提交权限仍由代码控制。

验证证据怎样进入 PR

OpenClaw 的 PR 模板要求说明问题、选择该方案的原因、用户影响和 Evidence。贡献指南接受的证据包括聚焦测试、CI、截图、录像、终端输出、真实观察、脱敏日志和可下载产物；UI 或行为变化强调前后对比。参见 CONTRIBUTING.md 和 PR 模板。

这里存在两类判断：

确定性校验：证据字段是否存在、产物能否读取、Head SHA 是否匹配、必需检查是否成功、测试数是否下降；
语义判断：证据是否覆盖了真实故障、是否走了生产入口、是否证明了用户可见行为、是否足以支持合并。

前一类适合脚本和 CI，后一类由 Agent Review 与人共同完成。OpenClaw 的 Real Behavior Proof 还明确区分主要证据和补充证据：单元测试、Mock、Snapshot、Lint 和普通 CI 可以支持结论，但不能单独替代真实 OpenClaw 环境中的 After-fix 观察。维护者仍可以通过明确的 Override 接受例外，并留下责任记录。

AI 参与度能否量化

OpenClaw 要求贡献者披露 AI 辅助，但当前 PR 模板没有强制的结构化 AI 字段。因此公开数据只能测“文字中主动披露”，不能测实际代码由 AI 生成的比例。

在 2026 年 7 月 10 日至 8 月 9 日这个固定窗口内，GitHub Search 返回 13,845 个新 PR，其中 4,463 个标题或正文含 AI-assisted，约 32.2%；同期 9,356 个合并 PR 中有 3,192 个含该表述，约 34.1%。clawsweeper:autogenerated 只占新 PR 的约 0.60%，说明大量 AI 使用来自贡献者或维护者自己的 Coding Agent，而不是 ClawSweeper 自动生成。

这组数字只适合回答“公开披露有多普遍”。没有披露不等于没有使用，重复或模板文本也可能影响结果，不能据此宣称 AI 代码占比。

这套机制真正值得学习的地方

OpenClaw 的特点不是 Skill 多，也不是 Workflow 多，而是把几种不同的不确定性放到了合适的位置：

规则靠近代码。 根规则只保留通用硬约束，目录规则描述局部责任，Skill 保存可重复的任务方法。
先让模型调查，再让模型修改。 Repair Doctrine 要求入口、Owner、相邻实现、历史、测试和依赖契约证据，禁止只看 Diff 或错误信息直接打补丁。
测试也接受审计。 回归测试必须能在修复前失败，Mock、弱断言、重复测试和只为测试增加的生产接口都会被检查。
模型没有最终写权限。 高风险外部动作由可信代码重新验证当前状态，模型输出只是受审计的提案或修复材料。
性能优化必须可比较。 同一基线前后执行、测试数不下降、路径不扩张，使“变快”成为可验证结果。
自动化按风险分层。 文档、翻译和小型性能优化可以在严格范围内自动提交；产品方向、安全、兼容性、关闭和发布保留更强门禁。

它也不是完整答案。45 个 Skill 会带来维护成本和发现成本；语义审查仍可能误判；真实行为证明昂贵；公开仓库中模型、基础设施和维护者权限并不完全可复现。更重要的是，OpenClaw 的制度建立在它自己的高变更量、开放贡献和维护基础设施上，其他项目不应照抄 Skill 数量或 Workflow 数量。

真正可迁移的原则只有一句：让 AI 承担高成本的阅读、实现和初审，让确定性系统掌握范围、状态和权限，让人保留目标、风险与最终授权。

来源与复核方式

计数方法：在固定 Commit 上执行 find .agents/skills -mindepth 2 -maxdepth 2 -name SKILL.md 和 find .github/workflows -maxdepth 1 -name '*.yml'。AI 服务通过检索 Codex Action、模型 API Key、定时/事件触发和对应脚本后逐项阅读确认；普通测试和发布 Workflow 没有因为出现 OPENAI_API_KEY 字样就被自动归为 AI 维护服务。

34 KiB Raw Blame History Unescape Escape