clawsweeper

ClawSweeper

ClawSweeper 位于 ~/Projects/clawsweeper。它是用于扫描、修复任务和受控修复 PR 的唯一 OpenClaw 维护机器人。 当用户询问报告、发现项、派发健康状况、修复/云端 PR 创建、评论命令、自动合并、权限或门禁时，请使用此技能。

开始

在 ClawSweeper 工作区中检查 git status --short --branch。状态和报告请求保持只读：需要确保时效性时，使用当前报告和实时只读 API；不要仅为查看而拉取或构建。

对于已获授权的实现或执行，请更新一个干净且专用于该任务的工作区，并且仅在所选命令需要时构建。保留无关编辑，以及其他操作人员正在进行的工作流。

一个机器人，一个应用

使用 ClawSweeper 仓库和 clawsweeper GitHub App。此自动化只能使用 CLAWSWEEPER_* 配置。不要使用旧版应用、变量、标签或技能。

应用所需设置：

• CLAWSWEEPER_APP_CLIENT_ID：clawsweeper 的公开应用客户端 ID。
• CLAWSWEEPER_APP_PRIVATE_KEY：仅在 actions/create-github-app-token 步骤中使用的私钥。
• 目标应用权限：读取目标扫描上下文；写入议题和拉取请求； 对内容拥有写入权限，用于报告提交、修复分支和工作流输入；对 openclaw/clawsweeper 拥有 Actions 写入权限，用于评论路由器重新审查派发、工作流派发、运行取消和自愈。

令牌边界：

• Codex 工作人员不会获得变更凭据。
• 审查工作人员运行时会移除机密/令牌环境变量。
• 确定性脚本通过短期 GitHub App 令牌处理评论、标签、分支推送、PR 创建、关闭和合并。
• 合并和写入门禁默认关闭。

托管提交审查

托管的逐提交报告和提交 Check Runs 已停用。若要对已提交分支进行保留的离线审查，请使用 pnpm local-review -- --base main。 $autoreview --mode commit --commit <sha> 仍是单独的通用审查路径。

扫描报告

议题/PR 报告位于：

records/<repo-slug>/items/<number>.md
records/<repo-slug>/closed/<number>.md

请先列出数量、具体发现项和报告链接。不要在阅读报告时主动发布 GitHub 评论。公开内容包括 Markdown 报告、持久的 ClawSweeper 审查评论和可选检查。

PR 报告包含 Codex /review 风格的 reviewFindings，其中含优先级、置信度、仓库相对文件路径和行范围。存在发现项时，公开 PR 评论会显示简短的 Review findings: 列表；完整审查评论、证据链接、可能的负责人和运行时详情则保留在折叠的 Review details 区块中。

对于简单的状态请求，请读取现有报告和范围受限的实时工作流状态。仅在用户要求进行完整审计时，才使用 pnpm run audit。

协调操作是单独授权的变更：直接运行 pnpm run reconcile 会移动/删除报告和工作计划文件。只有在用户请求该维护任务时，才检查其试运行结果；读取状态/报告时不要运行协调操作。同样，apply-decisions 仅用于明确授权的应用工作流，并且应从试运行开始。

创建一个修复任务

根据议题/PR 引用和维护者提示词创建任务：

pnpm run repair:create-job -- \
  --repo openclaw/openclaw \
  --refs 123,456 \
  --prompt-file /tmp/clawsweeper-prompt.md

根据现有 ClawSweeper 报告创建任务：

pnpm run repair:create-job -- \
  --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md

任务创建器会在写入新任务前，检查是否已有打开的 PR、正文匹配项或远程 clawsweeper/<cluster-id> 分支。使用 --dry-run 进行检查。只有在确认重复项防护已过时后，才使用 --force。

验证、提交，然后派发：

pnpm run repair:validate-job -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md
pnpm run repair:dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \
  --mode autonomous \
  --runner blacksmith-4vcpu-ubuntu-2404 \
  --execution-runner blacksmith-16vcpu-ubuntu-2404 \
  --model gpt-6-astra

新建任务文件尚未提交并推送前，不要派发该任务；工作流会从 GitHub 读取任务路径。

替代 PR

对于有用但不可编辑、陈旧或不安全的源 PR，请让维护者提示 明确说明：

Treat #123 as useful source work. If the source branch cannot be safely updated
because it is uneditable, stale, draft-only, unmergeable, or unsafe, create a
narrow ClawSweeper replacement PR instead of waiting. Preserve the source PR
author as co-author, credit the source PR in the replacement PR body, and close
only that source PR after the replacement PR is opened.

工作者应输出 repair_strategy=replace_uneditable_branch，并在 source_prs 中列出源 PR URL。确定性执行器会打开或更新 clawsweeper/<cluster-id>，将源 PR 的非机器人作者添加为 Co-authored-by 尾注，并仅在替代 PR 存在后关闭被取代的源 PR。

门控

仅在对该窗口拥有明确授权时更改执行门控。更改前，记录原始状态 以及任何约定的恢复操作：

gh variable set CLAWSWEEPER_ALLOW_EXECUTE --repo openclaw/clawsweeper --body 1
gh variable set CLAWSWEEPER_ALLOW_FIX_PR --repo openclaw/clawsweeper --body 1
gh variable set CLAWSWEEPER_ALLOW_MERGE --repo openclaw/clawsweeper --body 1
gh variable set CLAWSWEEPER_ALLOW_AUTOMERGE --repo openclaw/clawsweeper --body 1

仅当授权窗口包含该恢复操作，且 其所有权和状态仍匹配时，才恢复门控。否则保持不变；另一个活跃的 维护者窗口可能有意将其保持为 1。绝不要将所有门控作为 通用清理全部重置。

重要门控：

• CLAWSWEEPER_ALLOW_EXECUTE：允许确定性写入通道。
• CLAWSWEEPER_ALLOW_FIX_PR：允许分支修复/替代 PR。
• CLAWSWEEPER_ALLOW_MERGE：允许执行合并的应用器运行。
• CLAWSWEEPER_ALLOW_AUTOMERGE：允许评论路由器自动合并。
• CLAWSWEEPER_COMMENT_ROUTER_EXECUTE：允许定时评论路由 发布回复并分派修复。

维护者提及

所有面向维护者的控制操作都应优先使用 @clawsweeper 评论。斜杠 命令仍会按兼容性别名解析，但示例和运行时指引应使用提及。

@clawsweeper status
@clawsweeper re-review
@clawsweeper review
@clawsweeper fix ci
@clawsweeper address review
@clawsweeper rebase
@clawsweeper autofix
@clawsweeper automerge
@clawsweeper approve
@clawsweeper explain
@clawsweeper stop
@clawsweeper <question or safe action request>
@clawsweeper[bot] re-review
@openclaw-clawsweeper fix ci
@openclaw-clawsweeper[bot] fix ci

接受的别名：review、re-review、rereview、review again、 rerun review 和 run review。review 和 re-review 会分派一次全 新的 ClawSweeper Issue/PR 审查，而不会启动修复。fix ci、 address review 和 rebase 仅会为 ClawSweeper PR 或选择启用 clawsweeper:autofix 或 clawsweeper:automerge 的 PR 分派修复工作者。autofix 会运行有界的 审查/修复循环，但不合并。automerge 会运行有界的审查/修复/合并 循环，但草稿 PR 在 GitHub 标记为可供审查之前会保持仅修复状态。

自由形式的维护者提及，如 @clawsweeper why did automerge stop? 或 @clawsweeper: can you explain this failure?，会分派一次只读辅助审查， 并将提及文本作为一次性指令。答复会进入下一条公开的 ClawSweeper 审查评论。看似会执行操作的文本不会直接修改 GitHub；它必须映射到现有的 结构化建议并通过常规确定性门控。

默认接受的维护者：OWNER、MEMBER、COLLABORATOR；回退时，接受 admin、 maintain 或 write 仓库权限。贡献者 评论会被忽略，不作回复。

手动运行路由器：

pnpm run repair:comment-router -- --repo openclaw/openclaw --lookback-minutes 180
pnpm run repair:comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity

定时路由会保持为演练模式，除非 CLAWSWEEPER_COMMENT_ROUTER_EXECUTE=1。

可信的自动修复与自动合并

@clawsweeper autofix 会将现有 PR 加入有边界的审查/修复循环。 @clawsweeper automerge 会将现有 PR 加入有边界的审查/修复/合并 循环。路由器会：

• 验证维护者权限；
• 为 PR 添加 clawsweeper:autofix 或 clawsweeper:automerge 标签；
• 针对当前 head SHA 派发 ClawSweeper 审查；
• 创建或复用持久化的已接管任务；
• 最多按配置的上限执行修复；
• 绝不合并 autofix PR 或草稿 PR；
• 仅当 ClawSweeper 已针对完全一致的当前 head 审查通过、检查全部通过、GitHub 判定可合并、没有人工审查标签、PR 不是草稿，且两个合并门控均已开启时，才合并 automerge PR。

缺少变更日志绝不会成为审查问题或合并阻碍。CHANGELOG.md 仅用于发布；应在 PR 正文或 squash 消息中记录面向用户的发布说明，绝不要为了常规修复而编辑变更日志。

如果 ClawSweeper 审查通过时合并门控尚未开启，它会添加 clawsweeper:merge-ready 标签并发表评论，而不是合并。@clawsweeper stop 会添加 clawsweeper:human-review。

如果被要求创建 PR 并启用 ClawSweeper 自动合并，不要让本地 OpenClaw 检出停留在 PR 分支上。创建并推送 PR，且发布或以其他方式确认 @clawsweeper automerge 请求后，如果工作树干净，应将本地检出切回 main 并快进：

git switch main
git pull --ff-only

如果无关的本地编辑或正在进行的变基操作导致无法切换，请报告阻碍，不要暂存、删除或覆盖工作。

修复上限：

CLAWSWEEPER_MAX_REPAIRS_PER_PR=10
CLAWSWEEPER_MAX_REPAIRS_PER_HEAD=1

安全边界

不要为 ClawSweeper Repair 暂存未经批准的安全敏感工作。漏洞报告、CVE/GHSA/安全公告相关工作、泄露的密钥/令牌/密钥材料、明文存储密钥、SSRF、XSS、CSRF、RCE、绕过身份验证、权限提升以及敏感数据泄露，都应交由 OpenClaw 中央安全流程处理。

对于明确选择加入 clawsweeper:autofix 或 clawsweeper:automerge 的 PR，安全敏感的审查发现可以派发有边界的修复，但在后续针对完全一致的 head 进行的审查通过且常规合并门控通过之前，仍禁止合并。应信任 ClawSweeper 的确定性安全标记、标签和任务 frontmatter；不要根据含糊的文字推断安全处理方式。

监控

接收器工作流：

gh run list --repo openclaw/clawsweeper --workflow sweep.yml \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow repair-cluster-worker.yml \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow repair-comment-router.yml \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow github-activity.yml \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url

目标派发器：

gh run list --repo openclaw/openclaw --workflow "ClawSweeper Dispatch" \
  --limit 8 --json databaseId,displayTitle,event,status,conclusion,headSha,url

阅读输出

对于发现的问题或失败，请总结：

• 目标仓库、项目/PR、运行记录、报告路径
• 结果、置信度、严重程度和具体阻碍
• 受影响的文件或集群引用
• 验证命令及其是否通过
• 修改门控是开启还是关闭
• 下一步确定性操作

保持清扫范围小：一个集群、一个分支、一个 PR、范围明确的验证，以及清晰且对负责人可见的证据。