Clawsweeper
Use for all ClawSweeper work: OpenClaw issue/PR sweep reports, repair jobs, cloud fix PRs, @clawsweeper maintainer mention commands, trusted ClawSweeper-reviewed autofix/automerge, GitHub Actions monitoring, permissions, gates, and manual backfills.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Clawsweeper when an AI agent needs a reusable SKILL.md workflow for this job: Use for all ClawSweeper work: OpenClaw issue/PR sweep reports, repair jobs, cloud fix PRs, @clawsweeper maintainer mention commands, trusted ClawSweeper-reviewed autofix/automerge, GitHub Actions monitoring, permissions, gates, and manual backfills.
When not to use it
Skip Clawsweeper when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/clawsweeper # Save SKILL.md to ~/.claude/skills/clawsweeper/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/clawsweeper/SKILL.md. For a shared project, commit the folder at .claude/skills/clawsweeper/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Clawsweeper skill for this task: Use Clawsweeper when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# ClawSweeper
ClawSweeper lives at `~/Projects/clawsweeper`. It is the one OpenClaw maintenance bot for sweeping, repair jobs, and guarded fix PRs. Use this skill whenever asked about reports, findings, dispatch health, repair/cloud PR creation, comment commands, automerge, permissions, or gates.
## Start
Inspect `git status --short --branch` in the ClawSweeper checkout. Status and report requests stay read-only: use current reports and live read APIs when freshness matters, without pulling or building just to inspect them.
For authorized implementation or execution, update a clean task-owned checkout and build only when the selected command needs it. Preserve unrelated edits and other operators' active workflows.
## 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.
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.
## Hosted Commit Reviews
Hosted per-commit reports and commit Check Runs are retired. For the retained offline review of a committed branch, use `pnpm local-review -- --base main`. `$autoreview --mode commit --commit <sha>` remains a separate general-purpose review path.
## 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.
For a simple status request, read existing reports and bounded live workflow state. Use `pnpm run audit` only for a requested full audit.
Reconciliation is a separate authorized mutation: bare `pnpm run reconcile` moves/deletes report and work-plan files. Inspect its dry-run only when that maintenance task is requested; do not run reconciliation during status/report reads. Likewise, `apply-decisions` belongs to an explicitly authorized apply workflow, beginning with its 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-6-astra ```
Do not dispatch a just-created job before the job file is committed and pushed; the workflow reads the job path from GitHub.
## Replacement PRs
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.
## Gates
Change execution gates only under explicit authority for that window. Record the original state and any agreed restoration before changing it:
```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 ```
Restore a gate only when the authorized window includes that restoration and its ownership/state still match. Otherwise leave it unchanged; another active maintainer window may intentionally keep it at `1`. Never reset all gates as generic cleanup.
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.
## 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`.
## 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, and both merge gates are open.
Missing changelog is never a review finding or merge blocker. `CHANGELOG.md` is release-only; record user-facing release-note context in the PR body or squash message, never edit the changelog for normal repairs.
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 asked to create a PR and enable ClawSweeper automerge, do not leave the 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 ```
## 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.
## Monitoring
Receiver workflows:
```bash 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 ```
Target dispatcher:
```bash gh run list --repo openclaw/openclaw --workflow "ClawSweeper Dispatch" \ --limit 8 --json databaseId,displayTitle,event,status,conclusion,headSha,url ```
## Reading Output
For findings or failures, summarize:
- target repo, item/PR, 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.
Intended uses
- Use Clawsweeper when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.