Back to Details

clawsweeper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ClawSweeper

ClawSweeper

ClawSweeper lives at 
~/Projects/clawsweeper
. It is the one OpenClaw maintenance bot for sweeping, commit review, repair jobs, and guarded fix PRs. Use this skill whenever Peter asks about reports, findings, dispatch health, repair/cloud PR creation, comment commands, automerge, permissions, or gates.
ClawSweeper 位于 
~/Projects/clawsweeper
，是 OpenClaw 的专属维护机器人，负责扫描、提交审查、修复任务以及受保护的修复PR。当Peter询问报告、检测结果、调度健康状态、修复/云端PR创建、评论命令、自动合并、权限或闸门相关问题时，使用此工具。

Start

启动

bash
cd ~/Projects/clawsweeper
git status --short --branch
git pull --ff-only
pnpm run build:all
Do not overwrite unrelated edits. If the tree is dirty, inspect first and keep read-only report work read-only unless Peter asked to commit.
bash
cd ~/Projects/clawsweeper
git status --short --branch
git pull --ff-only
pnpm run build:all
请勿覆盖无关的编辑内容。如果工作树处于未提交状态，需先检查内容；除非Peter要求提交，否则只读报告类工作需保持只读状态。

One Bot, One App

单机器人单应用

Use the ClawSweeper repo and the 
clawsweeper
GitHub App. Use only 
CLAWSWEEPER_*
configuration for this automation. Do not use legacy apps, variables, labels, or skills.
Required app setup:
  • CLAWSWEEPER_APP_CLIENT_ID
    : public app client ID for 
    clawsweeper
    .
  • CLAWSWEEPER_APP_PRIVATE_KEY
    : private key used only inside 
    actions/create-github-app-token
    steps.
  • Target app permissions: read target scan context; write issues and pull requests; contents write for report commits, repair branches, and workflow inputs; Actions write on 
    openclaw/clawsweeper
    for comment-router re-review dispatch, workflow dispatch, run cancellation, and self-heal; optional Checks write for commit Check Runs.
Token boundary:
  • Codex workers do not get mutation credentials.
  • Review workers run with stripped secret/token env.
  • Deterministic scripts own comments, labels, branch pushes, PR creation, closes, and merges through short-lived GitHub App tokens.
  • Merge and write gates default closed.
使用 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创建、关闭和合并操作。
  • 合并和写入闸门默认处于关闭状态。

Commit Reports

提交报告

Canonical commit reports:
text
records/<repo-slug>/commits/<40-char-sha>.md
Use the lister:
bash
pnpm commit-reports -- --since 6h
pnpm commit-reports -- --since "24 hours ago" --findings
pnpm commit-reports -- --since 7d --non-clean
pnpm commit-reports -- --repo openclaw/openclaw --author steipete --since 7d
pnpm commit-reports -- --since 24h --json
Results: 
nothing_found
, 
findings
, 
inconclusive
, 
failed
, 
skipped_non_code
. One report per SHA; reruns overwrite the SHA-named report.
Manual rerun/backfill:
bash
gh workflow run commit-review.yml --repo openclaw/clawsweeper \
  -f target_repo=openclaw/openclaw \
  -f commit_sha=<end-sha> \
  -f before_sha=<start-or-parent-sha> \
  -f create_checks=false \
  -f enabled=true
Use 
create_checks=true
only when Peter explicitly wants target commit Check Runs. Add 
-f additional_prompt="..."
for focused one-off review instructions.
标准提交报告路径：
text
records/<repo-slug>/commits/<40-char-sha>.md
使用列表工具：
bash
pnpm commit-reports -- --since 6h
pnpm commit-reports -- --since "24 hours ago" --findings
pnpm commit-reports -- --since 7d --non-clean
pnpm commit-reports -- --repo openclaw/openclaw --author steipete --since 7d
pnpm commit-reports -- --since 24h --json
结果类型：
nothing_found
、
findings
、
inconclusive
、
failed
、
skipped_non_code
。每个SHA对应一份报告；重新运行会覆盖同名SHA的报告。
手动重新运行/回填：
bash
gh workflow run commit-review.yml --repo openclaw/clawsweeper \
  -f target_repo=openclaw/openclaw \
  -f commit_sha=<end-sha> \
  -f before_sha=<start-or-parent-sha> \
  -f create_checks=false \
  -f enabled=true
仅当Peter明确要求生成目标提交检查运行记录时，才设置 
create_checks=true
。添加 
-f additional_prompt="..."
以提供针对性的一次性审查指令。

Sweep Reports

扫描报告

Issue/PR reports live at:
text
records/<repo-slug>/items/<number>.md
records/<repo-slug>/closed/<number>.md
Lead with counts, concrete findings, and report links. Do not post unsolicited GitHub comments from report-reading work. Public surfaces are markdown reports, durable ClawSweeper review comments, and optional checks.
PR reports include Codex 
/review
-style 
reviewFindings
with priority, confidence, repository-relative file, and line range. Public PR comments show a short 
Review findings:
list when findings exist; full review comments, evidence links, likely owners, and runtime details stay inside the collapsed 
Review details
block.
Useful commands:
bash
pnpm run status
pnpm run audit
pnpm run reconcile
pnpm run apply-decisions -- --dry-run
议题/PR报告存储路径：
text
records/<repo-slug>/items/<number>.md
records/<repo-slug>/closed/<number>.md
报告开头需包含统计数据、具体检测结果和报告链接。请勿从报告阅读工作中发布未经请求的GitHub评论。公开展示形式为Markdown报告、持久化的ClawSweeper审查评论以及可选的检查项。
PR报告包含Codex 
/review
风格的 
reviewFindings
，包含优先级、可信度、仓库相对文件和行范围。当存在检测结果时，公开PR评论会显示简短的「Review findings:」列表；完整的审查评论、证据链接、可能的负责人和运行时详情会放在折叠的「Review details」区块内。
实用命令：
bash
pnpm run status
pnpm run audit
pnpm run reconcile
pnpm run apply-decisions -- --dry-run

Create One Repair Job

创建单个修复任务

Create a job from issue/PR refs and a maintainer prompt:
bash
pnpm run repair:create-job -- \
  --repo openclaw/openclaw \
  --refs 123,456 \
  --prompt-file /tmp/clawsweeper-prompt.md
Create from an existing ClawSweeper report:
bash
pnpm run repair:create-job -- \
  --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md
The job creator checks for an existing open PR, body match, or remote 
clawsweeper/<cluster-id>
branch before writing another job. Use 
--dry-run
to inspect. Use 
--force
only after deciding the duplicate guard is stale.
Validate, commit, then dispatch:
bash
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-5.5
Do not dispatch a just-created job before the job file is committed and pushed; the workflow reads the job path from GitHub.
从议题/PR引用和维护者提示创建任务：
bash
pnpm run repair:create-job -- \
  --repo openclaw/openclaw \
  --refs 123,456 \
  --prompt-file /tmp/clawsweeper-prompt.md
从现有ClawSweeper报告创建任务：
bash
pnpm run repair:create-job -- \
  --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md
任务创建器会在创建新任务前检查是否存在已打开的PR、内容匹配或远程 
clawsweeper/<cluster-id>
分支。使用 
--dry-run
进行检查；仅在确认重复检查机制过时后，才使用 
--force
。
验证、提交然后调度：
bash
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-5.5
在任务文件提交并推送前，请勿调度刚创建的任务；工作流需从GitHub读取任务路径。

Replacement PRs

替代PR

For a useful but uneditable/stale/unsafe source PR, make the maintainer prompt explicit:
md
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.
The worker should emit 
repair_strategy=replace_uneditable_branch
and list the source PR URL in 
source_prs
. The deterministic executor opens or updates 
clawsweeper/<cluster-id>
, adds non-bot source authors as 
Co-authored-by
trailers, and closes superseded source PRs only after replacement exists.
对于有用但无法编辑/已过时/不安全的源PR，需明确维护者提示：
md
将#123视为有用的源工作。如果源分支因无法编辑、已过时、仅为草稿、无法合并或不安全而无法安全更新，请创建一个精简的ClawSweeper替代PR，而非等待。保留源PR作者为共同作者，在替代PR正文中注明源PR，并在替代PR打开后仅关闭该源PR。
工作者应输出 
repair_strategy=replace_uneditable_branch
并在 
source_prs
中列出源PR URL。确定性执行器会打开或更新 
clawsweeper/<cluster-id>
，添加非机器人源作者为 
Co-authored-by
尾部信息，并仅在替代PR存在后关闭被取代的源PR。

Gates

闸门控制

Open execution windows intentionally and close them after the run:
bash
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
Reset gates only when Peter asks; the active maintainer window may intentionally leave them at 
1
.
Important gates:
  • CLAWSWEEPER_ALLOW_EXECUTE
    : allows deterministic write lanes.
  • CLAWSWEEPER_ALLOW_FIX_PR
    : allows branch repair/replacement PRs.
  • CLAWSWEEPER_ALLOW_MERGE
    : allows merge-capable applicators.
  • CLAWSWEEPER_ALLOW_AUTOMERGE
    : allows comment-router automerge.
  • CLAWSWEEPER_COMMENT_ROUTER_EXECUTE
    : lets scheduled comment routing post replies and dispatch repair.
有意开启执行窗口，并在运行后关闭：
bash
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
仅当Peter要求时重置闸门；活跃的维护者窗口可能会有意将其保持为 
1
。
重要闸门：
  • CLAWSWEEPER_ALLOW_EXECUTE
    ：允许确定性写入通道。
  • CLAWSWEEPER_ALLOW_FIX_PR
    ：允许分支修复/替代PR。
  • CLAWSWEEPER_ALLOW_MERGE
    ：允许具备合并能力的应用器。
  • CLAWSWEEPER_ALLOW_AUTOMERGE
    ：允许评论路由自动合并。
  • CLAWSWEEPER_COMMENT_ROUTER_EXECUTE
    ：允许定时评论路由发布回复并调度修复。

Maintainer Mentions

维护者提及

Prefer 
@clawsweeper
comments for all maintainer-facing control. Slash commands still parse as compatibility aliases, but examples and live guidance should use mentions.
text
@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
Accepted aliases: 
review
, 
re-review
, 
rereview
, 
review again
, 
rerun review
, and 
run review
. 
review
and 
re-review
dispatch a fresh ClawSweeper issue/PR review without starting repair. 
fix ci
, 
address review
, and 
rebase
dispatch the repair worker only for ClawSweeper PRs or PRs opted into 
clawsweeper:autofix
or 
clawsweeper:automerge
. 
autofix
runs the bounded review/fix loop without merging. 
automerge
runs the bounded review/fix/merge loop, but draft PRs stay fix-only until GitHub marks them ready for review.
Freeform maintainer mentions such as 
@clawsweeper why did automerge stop?
or 
@clawsweeper: can you explain this failure?
dispatch a read-only assist review with the mention text as one-off instructions. The answer lands in the next public ClawSweeper review comment. Action-looking prose does not directly mutate GitHub; it must map to existing structured recommendations and pass the normal deterministic gates.
Default accepted maintainers: 
OWNER
, 
MEMBER
, 
COLLABORATOR
; fallback repository permission accepts 
admin
, 
maintain
, or 
write
. Contributor comments are ignored without a reply.
Run router manually:
bash
pnpm run repair:comment-router -- --repo openclaw/openclaw --lookback-minutes 180
pnpm run repair:comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity
Scheduled routing stays dry unless 
CLAWSWEEPER_COMMENT_ROUTER_EXECUTE=1
.
所有面向维护者的控制操作优先使用 
@clawsweeper
评论。斜杠命令仍会被解析为兼容别名，但示例和实时指导应使用提及方式。
text
@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议题/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
； fallback仓库权限接受 
admin
、
maintain
或 
write
。贡献者的评论会被忽略，不会回复。
手动运行路由：
bash
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
。

Trusted Autofix And Automerge

可信自动修复与自动合并

@clawsweeper autofix
opts an existing PR into the bounded review/fix loop. 
@clawsweeper automerge
opts an existing PR into the bounded review/fix/merge loop. The router:
  • verifies maintainer authorization;
  • labels the PR 
    clawsweeper:autofix
    or 
    clawsweeper:automerge
    ;
  • dispatches ClawSweeper review for the current head SHA;
  • creates or reuses a durable adopted job;
  • repairs at most the configured caps;
  • never merges autofix PRs or draft PRs;
  • merges automerge PRs only when ClawSweeper passed the exact current head, checks are green, GitHub says mergeable, no human-review label is present, the PR is not draft, required user-facing OpenClaw changelog entries are present, and both merge gates are open.
If ClawSweeper passes while merge gates are closed, it labels 
clawsweeper:merge-ready
and comments instead of merging. 
@clawsweeper stop
adds 
clawsweeper:human-review
.
When Peter asks Codex to create a PR and enable ClawSweeper automerge, do not leave his local OpenClaw checkout on the PR branch. After the PR is created, pushed, and the 
@clawsweeper automerge
request is posted or otherwise confirmed, return the local checkout to 
main
and fast-forward it when the working tree is clean:
bash
git switch main
git pull --ff-only
If unrelated local edits or an in-progress rebase prevent switching, report the blocker instead of stashing, deleting, or overwriting work.
Repair caps:
bash
CLAWSWEEPER_MAX_REPAIRS_PER_PR=10
CLAWSWEEPER_MAX_REPAIRS_PER_HEAD=1
@clawsweeper autofix
会将现有PR加入受限审查/修复循环。
@clawsweeper automerge
会将现有PR加入受限审查/修复/合并循环。路由会：
  • 验证维护者授权；
  • 为PR添加 
    clawsweeper:autofix
    或 
    clawsweeper:automerge
    标签；
  • 为当前头部SHA调度ClawSweeper审查；
  • 创建或复用持久化的已接管任务；
  • 修复次数不超过配置上限；
  • 绝不会合并自动修复PR或草稿PR；
  • 仅当ClawSweeper通过当前头部SHA的审查、检查项全部通过、GitHub标记为可合并、无人工审查标签、PR非草稿状态、存在所需的面向用户的OpenClaw变更日志条目，且两个合并闸门均处于打开状态时，才会合并自动合并PR。
如果ClawSweeper审查通过但合并闸门关闭，会添加 
clawsweeper:merge-ready
标签并发表评论，而非合并。
@clawsweeper stop
会添加 
clawsweeper:human-review
标签。
当Peter要求Codex创建PR并启用ClawSweeper自动合并时，请勿让他的本地OpenClaw检出停留在PR分支。PR创建、推送并确认 
@clawsweeper automerge
请求已发布后，将本地检出切换回 
main
分支，并在工作树干净时进行快进拉取：
bash
git switch main
git pull --ff-only
如果无关的本地编辑或正在进行的变基操作阻止切换，请报告阻塞问题，而非暂存、删除或覆盖工作内容。
修复上限：
bash
CLAWSWEEPER_MAX_REPAIRS_PER_PR=10
CLAWSWEEPER_MAX_REPAIRS_PER_HEAD=1

Security Boundary

安全边界

Do not stage unapproved security-sensitive work for ClawSweeper Repair. Route vulnerability reports, CVE/GHSA/advisory work, leaked secrets/tokens/keys, plaintext secret storage, SSRF, XSS, CSRF, RCE, auth bypass, privilege escalation, and sensitive data exposure to central OpenClaw security handling.
For PRs explicitly opted into 
clawsweeper:autofix
or 
clawsweeper:automerge
, security-sensitive review findings may dispatch bounded repair, but merge remains blocked until a later exact-head review is clean and the normal merge gates pass. Trust deterministic ClawSweeper security markers, labels, and job frontmatter; do not infer security handling from vague prose.
请勿为ClawSweeper Repair暂存未经批准的安全敏感工作。将漏洞报告、CVE/GHSA/公告工作、泄露的密钥/令牌/密钥、明文密钥存储、SSRF、XSS、CSRF、RCE、认证绕过、权限提升和敏感数据泄露等问题路由至OpenClaw中央安全处理流程。
对于明确选择 
clawsweeper:autofix
或 
clawsweeper:automerge
的PR，安全敏感的审查结果可能会调度受限修复，但合并仍会被阻止，直到后续的头部SHA审查无问题且常规合并闸门通过。信任确定性的ClawSweeper安全标记、标签和任务前置信息；请勿从模糊的表述中推断安全处理方式。

Monitoring

监控

Receiver workflows:
bash
gh run list --repo openclaw/clawsweeper --workflow "ClawSweeper Commit Review" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow "repair cluster worker" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow "repair comment router" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
Target dispatcher:
bash
gh run list --repo openclaw/openclaw --workflow "ClawSweeper Dispatch" \
  --event push --limit 8 --json databaseId,displayTitle,event,status,conclusion,headSha,url
Target commit check:
bash
gh api "repos/openclaw/openclaw/commits/<sha>/check-runs?per_page=100" \
  --jq '.check_runs[] | select(.name=="ClawSweeper Commit Review") | [.status,.conclusion,.details_url] | @tsv'
接收方工作流：
bash
gh run list --repo openclaw/clawsweeper --workflow "ClawSweeper Commit Review" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow "repair cluster worker" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
gh run list --repo openclaw/clawsweeper --workflow "repair comment router" \
  --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url
目标调度器：
bash
gh run list --repo openclaw/openclaw --workflow "ClawSweeper Dispatch" \
  --event push --limit 8 --json databaseId,displayTitle,event,status,conclusion,headSha,url
目标提交检查：
bash
gh api "repos/openclaw/openclaw/commits/<sha>/check-runs?per_page=100" \
  --jq '.check_runs[] | select(.name=="ClawSweeper Commit Review") | [.status,.conclusion,.details_url] | @tsv'

Reading Output

输出解读

For findings or failures, summarize:
  • target repo, item/PR/commit, run, report path
  • result, confidence, severity, and exact blocker
  • affected files or cluster refs
  • validation commands and whether they passed
  • whether mutation gates were open or closed
  • next deterministic action
Keep the broom small: one cluster, one branch, one PR, narrow proof, clear owner-visible evidence.
对于检测结果或失败情况，需总结：
  • 目标仓库、项目/PR/提交、运行记录、报告路径
  • 结果、可信度、严重性和确切阻塞点
  • 受影响的文件或集群引用
  • 验证命令及其是否通过
  • 变更闸门处于打开还是关闭状态
  • 下一步确定性操作
聚焦重点：单个集群、单个分支、单个PR、明确的证据、清晰的所有者可见信息。