Project and contributing

Pull request review flow

This page explains the review flow after you open or update an OpenClaw pull request: what Barnacle and ClawSweeper do, how to improve the PR from their feedback, and what to check when automation stays quiet.

Barnacle and ClawSweeper help maintainers keep the review queue usable. They do not replace maintainer judgment.

Local review before a PR

Choose one local review route before asking for review. Complete the change and its focused validation first, then address actionable review findings together.

Author	Review route
Maintainer	Run local ClawSweeper on the final committed range. If it is unavailable, run local autoreview, then request one hosted ClawSweeper review when the PR is ready.
Contributor	Local autoreview is strongly encouraged. Local ClawSweeper is an optional alternative with its own setup and model usage.

For this route, maintainers are organization owners or people with effective repository maintain or admin access. Organization membership or repository write access alone does not qualify.

A completed local ClawSweeper review does not require routine autoreview or a duplicate hosted review. This route does not replace required independent review, CI, security approval, release review, or the native maintainer workflow. Maintainers may request missing review or validation evidence before reviewing a contributor PR.

Set up a local reviewer

Autoreview: follow the public shared setup and autoreview skill. Read the full installed skill. After source updates, reinstall copy-mode skills using that setup guide. The helper's --version identifies its content, not a release or trusted proof of execution.
ClawSweeper: use the public source-checkout setup and local skill. Its committed-range mode requires a clean checkout. Follow the documented target-directory and base selection instead of changing the branch under review. This is a source workflow, not an npm or Homebrew package installation.

Both tools use the configured model service. Send only material you are authorized to share with that service. Local review also works from fork checkouts without adding fork workflows, labels, or repository configuration.

Report the actual review

In the PR's Evidence section, name the tool, reviewed base and head or local change snapshot, effective priority or coverage, outcome, and remaining findings. A smoke run, filtered result, failed run, or incomplete review is not a clean review of the complete change. Describe unavailable tools and remaining gaps instead of claiming success. Never switch tools to hide findings or bypass a refusal.

Local summaries are self-reported evidence. A hash or version does not attest that a review ran or replace separately required hosted checks. Keep credentials, private paths, and unrelated report contents out of public PRs.

Check for a queued or running review of the current range before requesting one. Batch fixes, tests, and PR-body updates before requesting another review. A small edit alone is not a reason to start another hosted run. When the reviewed code or base changes, check what the existing result still covers and refresh the applicable review before claiming it covers the new range.

Barnacle

Barnacle applies fixed rules to GitHub triage. It looks for known queue-management cases and responds with labels, comments, or closures.

Barnacle may act when:

a PR body is mostly empty or missing problem context;
a PR has no useful evidence;
a docs-only, test-only, refactor-only, CI-only, or infra change lacks linked maintainer context;
a change looks like it belongs in ClawHub or a plugin instead of core;
a branch carries unrelated work;
an author has more than 20 open PRs.

Barnacle runs from trusted repository workflow code. It does not check out or run contributor code.

Most routing labels are maintainer or automation signals, so contributors do not need to add labels themselves.

ClawSweeper

ClawSweeper is the AI-assisted review and maintenance bot for OpenClaw repositories. It can review PRs, evaluate proof, and leave durable review comments. Repair and automerge commands are retired.

A positive ClawSweeper result is supporting evidence, not maintainer approval. Maintainers still decide whether and when a PR is ready to merge.

ClawSweeper is queue-based. When the repository enables automatic review, it posts a short receipt when you open a non-draft PR or mark a draft ready for review. The review itself still waits for a queue slot. Do not expect an immediate review after opening a PR or adding a review request. Label updates after a ClawSweeper run can also take time.

The initial automatic review runs once. Later pushes, description edits, and reopens do not start another review on their own.

A successful source-event workflow does not prove that a review started or covers the current head. Intake can return deduped: true with dedupe_reason: review_request_required after the automatic review allowance is consumed. That refusal occurs before allocating a new queue revision. Check for a separate active request instead of treating this response as a queued review.

Maintainers can also request a review with commands. When the selected route, a maintainer, or the user requires another hosted review, complete the branch, PR description, and proof first. Request it with one new PR comment:

text

@clawsweeper re-review

PR authors can also use @clawsweeper re-run; users with repository write access can use either command on any open item. The plain @clawsweeper review command is maintainer-only. Be patient: asking again before the requested changes are present just adds queue noise.

When the user explicitly requires hosted review, check that the resulting review covers the current head and PR description. Intake success alone does not satisfy that request. Otherwise, follow the native workflow's advisory ClawSweeper policy.

When ClawSweeper leaves review conversations, treat them like normal review feedback and use the follow-up checklist below.

If a human contributor or maintainer has taken over the PR and is actively working on it, do not summon ClawSweeper or otherwise work on the PR at the same time. Let the human review or repair finish first. If activity stops, check whether the author was asked to provide proof or make other updates.

Improve a PR during review

Once Barnacle, ClawSweeper, or a maintainer responds, use that feedback as the next-step checklist for the PR.

Read ClawSweeper's Rank-up moves: and Proof guidance: as the action list for that PR. Ratings and labels are review signals, not fixed merge targets.
Push the requested code or docs change, and update the PR description when the problem, solution, user impact, or evidence has changed.
Add the requested proof, using evidence that matches the change.
Resolve addressed review conversations yourself. Reply and leave a conversation open only when you need maintainer or reviewer judgment.
Ask for a re-review only when needed and after the branch, PR description, evidence, and relevant CI results are current. Check for a pending request first.
Keep discussion on the PR when possible. Move to #clawtributors on Discord only when the PR needs maintainer coordination, automation appears blocked, or the next decision is hard to settle in GitHub comments. Include the PR link, current status, and the specific question or remaining evidence.

Keep the PR body current. Comments help with discussion, but the PR description is the durable summary maintainers and automation revisit.

status: ⏳ waiting on author means the next action is with the PR author: update the branch, PR description, proof, or reply with the missing context before asking for another review.

Useful evidence includes focused test output, CI results, screenshots, recordings, terminal output, live observations, redacted logs, or artifact links. For visual changes, include before and after screenshots when practical. For proof files, prefer linking CI artifacts, GitHub-uploaded screenshots or recordings, or a short redacted log excerpt. Do not commit generated proof files unless they are part of the actual docs, tests, or product change.

For behavioral changes, use the boundary-proof guide to review production-path, provider-request, and failure/reconstruction evidence.

Redacting sensitive data is the contributor's responsibility. Remove secrets, tokens, private URLs, user data, and unrelated logs before posting proof.

OpenClaw also uses a separate Barnacle inactivity lifecycle. Its human-activity clock, full notice grace and durable holds apply independently of advisory review labels. Coordinate with the maintainer working on an active item.

Maintainer review artifacts

scripts/pr review-artifacts-init <PR> writes .local/review.json for the current reviewed head. Its defaults are structurally valid and explicitly unfinished: NEEDS WORK, performed: false, empty evidence arrays, and tests.result: "not_run". Initialization preserves an existing artifact stamped for the same PR and head, so it does not rewrite an older or partially filled review.

Fill the JSON with review findings and evidence, then run scripts/pr review-validate-artifacts <PR>. JSON owns the review; validation prints its summary, and an existing .local/review.md is not authoritative. Keep enum values bare, without annotations such as (allowed: ...):

Field	Accepted values
`recommendation`	`READY FOR /prepare-pr`, `NEEDS WORK`, `NEEDS DISCUSSION`, `NOT USEFUL (CLOSE)`
`findings[].severity`	`BLOCKER`, `IMPORTANT`, `NIT`
`nitSweep.status` (optional sweep)	`none`, `has_nits`
`issueValidation.source`	`linked_issue`, `pr_body`, `both`
`issueValidation.status`	`valid`, `unclear`, `invalid`, `already_fixed_on_main`
`behavioralSweep.status`	`pass`, `needs_work`, `not_applicable`
`behavioralSweep.silentDropRisk`	`none`, `present`, `unknown`
`tests.result`	`pass`, `fail`, `not_run`
`docs`	`up_to_date`, `missing`, `not_applicable`
`changelog`	`required`, `not_required`

nitSweep is optional and omitted from a fresh template. If supplied, it requires performed: true, a status consistent with the NIT findings, and a non-empty summary. Required issue and behavior summaries must also be non-empty, and each finding needs a severity. Structural validity does not authorize preparation: READY FOR /prepare-pr still requires completed issue and behavior review, resolved substantive findings, and the applicable runtime proof.

When a bounded investigation cannot establish or complete a safe fix for a local test failure, preserve tests.result: "fail" and record tests.investigatedLocalFailures. Its head must be the exact reviewed commit. Its nonempty failures array records each original failure, nonempty string arrays of reproductionAttempts and evidence, and a nonempty remainingUncertainty. Describe the commands and observed outcomes, and reference the evidence recorded in the PR. A passing replay does not prove a fix.

This completed investigation can accompany a READY recommendation without turning the failed proof into a pass. Substantive findings, behavioral review, required CI, security checks, and enforced reviews remain independent gates. Use tests.preExistingCi only for its separate, attributed CI-failure workflow; local investigation does not authorize a CI exception.

When automation stays quiet

Automation may stay quiet when a maintainer is already handling the item, a review request is still queued, the event is routine, or the ClawSweeper lane is not configured for the requested action.

It may also avoid action when a trusted workflow would need to run untrusted contributor code. In that case, maintainers use normal review or a safer workflow instead.

Troubleshooting

Maintainers can set OPENCLAW_PR_TOOLING_ROOT to a full checkout of this repository to source materialized scripts/pr dependencies independently of a primary checkout parked on another branch. The environment setting takes precedence over git config openclaw.pr.toolingRoot /path/to/tooling-checkout in the primary checkout; without either, dependency sourcing stays unchanged. Versions must match the wrapper's trust-anchor manifest. On mismatch, a separate clean main tooling checkout is fetched, fast-forwarded, and installed with pnpm install --frozen-lockfile once, then rechecked. Dirty or non-main tooling checkouts are refused with repair guidance; the primary checkout is never refreshed. The setting applies at both dependency materialization handoffs; in-place wrappers keep their checkout's dependency context. Wrapper code selection and trust stay unchanged.

Set OPENCLAW_PR_GIT to an absolute Git executable path if the host's default Git is broken. The wrapper checks Git with a 10-second deadline and prints the selected path and Xcode recovery hint on failure. API rate-limit failures identify the resource used and show both GraphQL and REST core balances and reset times.

If ClawSweeper does not respond immediately, wait before retrying. The service is queue-based, and repeated comments or label changes can make the thread harder to review without making the queue faster.

Before asking for help, check:

the PR description is current;
the latest commit contains the requested change;
CI has finished, or the PR body explains why any remaining failure is unrelated to the PR;
the latest review request was made as a PR comment: @clawsweeper re-review;
a maintainer or contributor is not already actively working on the PR;
the latest request is not still within the normal ClawSweeper queue delay.

If there is still no ClawSweeper response several hours after the PR is current, or if the PR appears blocked by automation, ask in #clawtributors on Discord. Include the PR link, what you expected, when you asked, and what changed since the last bot comment.

Forking the automation

Projects that want similar review automation can study or fork ClawSweeper:

Was this useful?