RFC: Claws

[giodl73-repo]

Summary

Signing-history note (2026-07-19): signed-history head 89312305c60c is a history-only rewrite of d17fab4034bd with identical tree 68edccecf222. The RFC and sidecar contents are unchanged; all three commits are signed and GitHub-verified as giodl73-repo.

• Defines one Claw package as one complete new OpenClaw agent for one job.
• Makes claws add create a new agents.list[] entry and workspace; existing agent/workspace collisions fail closed.
• Uses grouped agent, workspace, packages, mcpServers, and cronJobs ownership boundaries.
• Supports CLAW.md and equivalent grouped JSON under the same experimental Claws gate; export emits CLAW.md.
• Keeps skills, plugins, MCP servers, heartbeat, and Gateway cron on their existing OpenClaw owner surfaces.
• Uses enclosing package.json plus authenticated publishing for package identity, version, and publisher ownership.
• Excludes models, providers, credentials, channel bindings, agent.skills, and generic connectors from the portable contract.
• Gates the draft CLI behind OPENCLAW_EXPERIMENTAL_CLAWS=1; when disabled, the command is unregistered and absent from help and completions. The hosted experimental guide remains public but cannot enable the local runtime.

Implementer specifications

• Claw Package v1 defines package and publication validation, exact artifact resolution, owner delegation, provenance, consent, update, and removal semantics.
• CLAW.md v1 defines the shared grouped schema, YAML-frontmatter envelope, and equivalent JSON representation.

CLAW.md is deliberately a thin reader/export adapter over the grouped schema. It adds no separate lifecycle, ownership, or provenance behavior and no new package dependency. While Claws remain experimental, the envelope can still be revised or removed before graduation.

The RFC remains the product rationale, ownership model, and rollout plan. The sidecars provide the shared implementation contracts for OpenClaw and ClawHub.

Lifecycle and safety

The lifecycle is inspect, add, status, update, remove, and export. Read-only plans precede mutation; add, update, and remove require --yes plus the exact --plan-integrity digest from the reviewed dry run. Capability escalations are disclosed as separate records and human plan lines. OpenClaw uses one exact integrity confirmation that binds both the disclosed capability set and ordinary content; hosts may present those records separately or aggregate them. Unsupported, blocked, drifted, or ambiguous ownership fails closed.

Grouped update uses the source recorded in provenance unless --from overrides it. It rebuilds its plan immediately before mutation, checks expected owner state, advances root provenance last, and compensates completed owners in reverse order. Uncertain config/Gateway calls and package installs without artifact rollback are reported as partial rather than cross-owner atomic.

Remove selects unchanged managed resources for canonical cleanup and releases referenced dependency edges by default. --remove-unused and repeatable --remove-referenced select stronger cleanup in both preview and apply; --force-referenced explicitly acknowledges remaining dependents, independent owners, or pre-existing origin. Cleanup decisions use current canonical owner state and dependency edges, not refcounts or an ownership-history ledger. A confirmed ordinary uninstall remains authoritative and leaves affected Claws degraded and diagnosable.

Control UI alignment

openclaw/openclaw#103176 remains the Control UI surface for plugin inventory, installation, enablement/disablement, removal, and curated MCP connector discovery. Claws add package references and shared uninstall warnings to that lifecycle rather than creating a second package ownership system.

Portable MCP declarations remain direct validated mcp.servers configuration and do not create a feed-backed connector identity or replace the Control UI's curated connector shelf.

Implementation stack

The experimental OpenClaw landing is an ordered twelve-PR stack. Public experimental documentation begins with the first command in #101328 and each later PR documents only its newly implemented behavior; #111391 adds only CLAW.md authoring and canonical-export documentation.

1. #101328 grouped schema, inspect, add planning, and initial guide
2. #101755 agent/root install
3. #101973 managed workspace files
4. #102228 ClawHub packages and shared uninstall warnings
5. #102296 status/remove and owner cleanup
6. #102306 portable export
7. #102383 Gateway cron ownership
8. #102406 stdio/remote MCP ownership
9. #102427 lifecycle diagnostics
10. #102959 grouped update planning
11. #102982 consented grouped update apply
12. #111391 thin CLAW.md input/export adaptation and grouped JSON compatibility (supersedes #106888)

The dependent ClawHub track remains a separately gated four-PR experimental stack:

1. #3089 shared Claw schema and storage model
2. #3090 publication plus fail-closed reads and public-manifest redaction
3. #3091 enabled search, detail, and version APIs with safe summary projection
4. #3092 gated hosted feed, safe archive handling, and published-package E2E through real OpenClaw add dry-run

ClawHub accepts CLAW.md and equivalent grouped JSON behind its existing CLAWHUB_EXPERIMENTAL_CLAWS=1 gate. There is no second format-specific flag.

Validation

• git diff --check
• repository-required RFC section structure
• field-by-field comparison with the cumulative twelve-PR OpenClaw implementation
• package, provenance, lifecycle, registry, and feed comparison with the cumulative ClawHub track
• staged-documentation audit against every command-owning PR
• manual runtime-owner, operator, security, newcomer, and repository-boundary review; Codex terminology finding resolved by defining capability-neutral resource origin

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 20, 2026, 12:10 AM ET / 04:10 UTC.

Summary
This PR adds RFC 0016 plus experimental Claw Package v1 and CLAW.md v1 specifications for portable packages that create and manage a complete new OpenClaw agent.

Reproducibility: not applicable. This PR proposes a new experimental product and lifecycle contract, rather than reporting a failing current behavior.

Review metrics: 2 noteworthy metrics.

• Specification surface: 3 files added, 1,966 lines. The change defines a substantial long-lived contract rather than a small documentation clarification.
• Dependent delivery plan: 12 OpenClaw PRs and 4 ClawHub PRs referenced. The proposed behavior depends on coordinated implementation and ownership outside this RFC repository.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Obtain explicit maintainer sponsorship or a narrowing decision for the experimental Claws contract.
• [P2] If sponsored, add a short maintainer-approved acceptance boundary and owner for the linked implementation sequence.

Risk before merge

• [P1] Merging would establish a broad portable-agent package, lifecycle, provenance, and ownership contract before maintainers confirm that this capability belongs in the core OpenClaw direction.
• [P1] The proposal spans OpenClaw and ClawHub and introduces compatibility-sensitive expectations for agent creation, package resolution, MCP configuration, scheduling, updates, and removal; those commitments need an owner and an accepted rollout boundary.

Maintainer options:

1. Confirm and scope the contract before merge (recommended)
   Obtain explicit maintainer sponsorship, a named implementation owner, and a bounded experimental compatibility commitment before accepting the RFC.
2. Pause for product direction
   Keep the RFC unmerged until maintainers decide whether portable complete-agent packages are part of OpenClaw’s core product boundary.

Next step before merge

• [P1] A maintainer must decide whether to sponsor, narrow, or defer the new portable-agent package direction; no mechanical repair can make that decision.

Maintainer decision needed

• Question: Should OpenClaw adopt the proposed experimental Claw-package model for portable, complete agents and its cross-owner lifecycle across OpenClaw and ClawHub?
• Rationale: This is a new user-facing capability with an enduring package and compatibility contract. Source inspection can assess coherence, but cannot determine whether maintainers want to own this product direction.
• Likely owner: Kevin Rose — The current-main RFC template and contribution policy make this the strongest available routing candidate for an acceptance decision.
• Options:
  • Sponsor the experimental contract (recommended): Accept a bounded experimental Claws direction and designate an owner to validate and land the dependent implementation stack incrementally.
  • Narrow to approved primitives: Revise the RFC to describe only presently accepted extension surfaces and defer portable-agent lifecycle commitments.
  • Defer core adoption: Pause the RFC until a maintainer-sponsored roadmap decision establishes whether this package model belongs in core.

Security
Cleared: This documentation-only RFC diff adds no executable code, dependency, workflow, secret-handling, or supply-chain change.

Review details

Best possible solution:

Obtain maintainer sponsorship for a narrowly scoped experimental Claws contract, with explicit ownership of the OpenClaw and ClawHub landing sequence; otherwise narrow the RFC to an already-approved extension boundary.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR proposes a new experimental product and lifecycle contract, rather than reporting a failing current behavior.

Is this the best way to solve the issue?

Unclear: the proposal is detailed and scoped, but only maintainers can determine whether a portable complete-agent package contract is the right long-term product boundary.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 2d213ae23462.

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed files are RFC/specification documentation, so external runtime proof is not required for this documentation-only PR.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

• P3: This is an exploratory product RFC with no current user-facing regression, emergency, or confirmed release blocker.
• merge-risk: 🚨 compatibility: Accepting the package, lifecycle, provenance, and configuration contract could create durable compatibility expectations across OpenClaw and ClawHub.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The proposal offers an unusually comprehensive safety and ownership model for distributing purpose-built agents without replacing existing subsystem owners.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All changed files are RFC/specification documentation, so external runtime proof is not required for this documentation-only PR.

Evidence reviewed

What I checked:

• New product contract: The active branch adds three documentation/specification files that define a new portable-agent package model, CLI lifecycle, ownership boundaries, provenance, update, and removal behavior; this is feature direction rather than an implementation-alignment cleanup. (rfcs/0016-claws.md:1, e9c2bb478179)
• RFC policy and ownership context: The repository’s RFC template and contribution guidance on current main establish that RFCs require a clear proposal, rationale, alternatives, migration considerations, and implementation considerations. Git history attributes those central policy surfaces to Kevin Rose, while Patrick-Erichsen’s review discussion raised the naming and MCP/package-boundary questions that this RFC must resolve. (rfcs/0000-template.md:1, f4fdf38f4717)
• Dependent implementation remains outside this RFC: The PR body describes a twelve-PR OpenClaw implementation stack and a four-PR ClawHub stack, including an open CLAW.md implementation slice; this RFC therefore remains the governing product decision rather than work already superseded by current main. (rfcs/0016/claw-md-v1-spec.md:1, e9c2bb478179)
• Latest review continuity: Earlier completed ClawSweeper cycles found no discrete line-level correctness defect, but repeatedly identified missing maintainer direction. The newest head adds documentation-only clarification rather than evidence that the core product decision has been made. (bb6b3e506056)

Likely related people:

• Kevin Rose: Current-main history for the RFC template and contributor guidance ties the repository’s proposal and review boundary to this author. (role: template and contribution-policy author; confidence: medium; commits: f4fdf38f4717, bbb4058da234, e366ea9825a4; files: rfcs/0000-template.md, .github/PULL_REQUEST_TEMPLATE.md, CONTRIBUTING.md)
• Patrick-Erichsen: Their review comments directly raised the unresolved naming and MCP/package-surface questions central to the proposed contract. (role: early boundary reviewer; confidence: medium; files: rfcs/0016-claws.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (54 earlier review cycles; latest 8 shown)

• reviewed 2026-07-18T14:05:05.829Z sha 51c0ccd :: needs maintainer review before merge. :: none
• reviewed 2026-07-19T16:16:14.072Z sha d17fab4 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-19T16:58:20.970Z sha d17fab4 :: needs maintainer review before merge. :: none
• reviewed 2026-07-19T17:52:00.849Z sha 8931230 :: needs maintainer review before merge. :: none
• reviewed 2026-07-19T18:13:13.213Z sha 8931230 :: needs maintainer review before merge. :: none
• reviewed 2026-07-19T21:19:53.119Z sha 9924dec :: needs maintainer review before merge. :: none
• reviewed 2026-07-19T22:01:19.841Z sha 9924dec :: needs real behavior proof before merge. :: none
• reviewed 2026-07-20T01:50:38.576Z sha bb6b3e5 :: needs real behavior proof before merge. :: none

[giodl73-repo]

Updated the RFC and both sidecars in 892c60f for the agreed one-gate incubation model. CLAW.md and grouped JSON now share the existing Claws experimental gate; CLAW.md is a thin reader/export adapter with no separate lifecycle, ownership, provenance, or package dependency. #106888 is restored as PR 12 in the landing stack, and ClawHub uses its existing Claws gate rather than a format-specific flag. Final Codex review found no actionable contradictions. @clawsweeper re-review

[giodl73-repo]

Final implementation-alignment pass pushed at 7eef448. The RFC now matches the progressive public documentation stack, exact plan-integrity consent, provenance-default update source, explicit referenced-resource cleanup modes, and the final managed/referenced ownership vocabulary. Both implementer sidecars remain normative and aligned; the package sidecar status is now explicitly experimental draft. The PR body and commit-stable sidecar links have been refreshed.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Waiting
• Detail: Another exact-head review is already active. The durable queue will retry after its lease expires.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29695333855
• Updated: 2026-07-19T16:41:45.549Z

[giodl73-repo]

Follow-up at 59e031d: Codex review correctly identified that artifact origin was too narrow for mutable MCP declarations. The RFC and package sidecar now define capability-neutral resource origin (claw-introduced or pre-existing) and require MCP provenance to include origin plus current non-Claw ownership. The exact two-commit Codex rerun found no remaining contradiction.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The durable review comment was published and its verdict was queued for target-serialized routing.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/29696157012
• Updated: 2026-07-19T17:10:49.633Z

[giodl73-repo]

Signed-history update: RFC #27 moved from d17fab4034bd to signed head 89312305c60c with identical Git tree 68edccecf222cbe37e5eae8680eb4712d1c560de. The iterative history was compacted into three logical commits (RFC, package spec, and CLAW.md spec); content is unchanged, and all commits are GitHub-verified as giodl73-repo. The PR body's immutable sidecar links now point at the new head.

[giodl73-repo]

Independent review refresh applied at 9924dec5a67e. RFC 0016 and both normative sidecars now match the accepted consent/effect binding, package trust revalidation, release-only update removal, partial provenance, canonical live cron drift checks, bounded reads, and strict CLAW.md YAML decisions. The implementation stack was restacked and pushed in order; no merge performed.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: RFC: Claws This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[giodl73-repo]

Landed RFC 0016 as squash commit 13819ef73d3ae980b362e2a88ccb3cba90faa21d from reviewed source head e9c2bb478179822132bff54876ff60613d2d4665.

The merge preserves the bounded experimental contract and current immutable sidecar links. The dependent OpenClaw implementation stack will now be prepared and landed incrementally in the documented order.