Clawsweeper

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:

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:

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

Create from an existing ClawSweeper report:

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:

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:

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:

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.