RFC 0031: Claw application composition and clients

[giodl73-repo]

Status

Renumbered to RFC 0031; waiting for RFC #48.

• Exact head: 59b11e25acf4605771bced523f72083b19a8940f
• 0027 is already occupied on main; the proposal and implementation sidecar now use the next available identifier, 0031.
• Keep draft until RFC #48 and OpenClaw #121327 land.

Summary

RFC 0031 defines schema-v1 Claw application composition and consistent clients without reviving the superseded structured setup-v2 design.

A Claw composes one complete new agent from portable instructions, skills, direct MCP, managed content and assets, scheduled work, a conventional harness profile, and optional native first-run BOOTSTRAP.md. CLI, TUI, chat, automation, and Control UI remain clients of one canonical lifecycle.

Implementation Evidence

• OpenClaw #115237, #115962, and #115371
• Standalone Claws #1 and #3
• ClawHub #3328 and #3359
• Awesome Claws #1 and #5

Landing Order

Land OpenClaw #121327, merge RFC #48, then rebase and merge this RFC 0031 proposal. RFC #56 lands last.

[giodl73-repo]

@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: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30525775253
• Updated: 2026-07-30T08:13:11.413Z

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 11, 2026, 9:54 PM ET / August 12, 2026, 01:54 UTC.

ClawSweeper review

What this changes

Adds RFC 0031 and a sidecar plan for portable Claw applications using one lifecycle across CLI, TUI, chat, automation, and Control UI.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open: this remains a distinct draft RFC whose multi-client lifecycle direction depends on the open portable-profile RFC and requires maintainer product approval.

Priority: P3
Reviewed head: 59b11e25acf4605771bced523f72083b19a8940f
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The proposal is structured and follows the draft RFC shape, but its acceptance and final compatibility need maintainer review after prerequisites settle.
Proof confidence	🌊 off-meta tidepool	Not applicable: This is a documentation-only RFC proposal, so runtime after-fix proof is not applicable.
Patch quality	🦐 gold shrimp (3/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This is a documentation-only RFC proposal, so runtime after-fix proof is not applicable.
Evidence reviewed	4 items	Current main has no RFC 0031: Current main contains RFC 0027 and the RFC 0016 Claws foundation, but no RFC 0031 file or sidecar; the proposed document is not already implemented in this repository. Existing Claw foundation: RFC 0016 already defines a Claw as a distributable complete OpenClaw agent with composition and lifecycle ownership, making this proposal a dependent extension rather than a duplicate current-main RFC. RFC process: Repository guidance requires new RFCs to remain draft until accepted and to receive an implementation issue before merge; this PR is explicitly draft and names an open prerequisite RFC.
Findings	None	None.
Security	None	None.

How this fits together

Claw packages define portable agent content while OpenClaw owns planning, consent, mutation, status, and removal. The proposal requires each client to use that shared lifecycle instead of separate setup paths.

flowchart LR
A[Claw package] --> B[Canonical lifecycle]
C[Harness profile] --> B
D[Bootstrap instructions] --> B
B --> E[Plan and consent]
E --> F[CLI and TUI]
E --> G[Chat and automation]
E --> H[Control UI]

Loading

Decision needed

Question	Recommendation
After the portable-profile prerequisite lands, should OpenClaw standardize one Claw lifecycle across CLI, TUI, chat, automation, and Control UI?	Adopt after prerequisites: Keep this draft until the prerequisite contract and runtime implementation land, then review it as the canonical client-lifecycle direction.

Why: This establishes product and client-contract direction rather than repairing a defined existing behavior.

Before merge

• Add real behavior proof - Not applicable: This is a documentation-only RFC proposal, so runtime after-fix proof is not applicable.
• Resolve merge risk (P1) - Merging before RFC 0016: consolidate the Claws contract #48 and its referenced runtime work settles could commit incompatible lifecycle contracts.
• Resolve merge risk (P1) - The local partial clone could not materialize the full PR tree because its promisor fetch could not resolve github.com; this review relies on supplied PR metadata and the available current-main sources.
• Complete next step (P2) - A maintainer must choose the cross-client lifecycle direction and its prerequisite landing order before implementation can proceed.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	3 Markdown files; +715, -1 lines	The branch establishes a broad design contract and implementation plan without modifying runtime code.

Merge-risk options

Maintainer options:

1. Sequence prerequisite adoption (recommended)
   Review and merge only after the prerequisite RFC and runtime work establish the portable lifecycle contract, then rebase this proposal.
2. Approve the contract independently
   Maintainers may adopt this RFC first while accepting subsequent alignment work for the prerequisite contracts.

Technical review

Best possible solution:

After the prerequisite RFC and implementation are settled, rebase this RFC and decide whether its shared lifecycle should become the accepted contract for all listed clients.

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

Not applicable: this documentation-only PR proposes a product contract rather than reporting an executable defect.

Is this the best way to solve the issue?

Unclear: a shared lifecycle is coherent, but maintainers must decide whether it is the desired cross-client contract after the prerequisite work lands.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This is a draft RFC for future product direction, not a live production regression.
• merge-risk: 🚨 compatibility: The proposed shared lifecycle would set compatibility expectations for several existing and future OpenClaw clients.
• 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. A single lifecycle across agent clients could prevent divergent setup and ownership behavior as the Claw surface grows.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This is a documentation-only RFC proposal, so runtime after-fix proof is not applicable.

Evidence

What I checked:

• Current main has no RFC 0031: Current main contains RFC 0027 and the RFC 0016 Claws foundation, but no RFC 0031 file or sidecar; the proposed document is not already implemented in this repository. (rfcs/0027-openclaw-enterprise.md:1, af708f0ddb6f)
• Existing Claw foundation: RFC 0016 already defines a Claw as a distributable complete OpenClaw agent with composition and lifecycle ownership, making this proposal a dependent extension rather than a duplicate current-main RFC. (rfcs/0016-claws.md:16, 13819ef73d3a)
• RFC process: Repository guidance requires new RFCs to remain draft until accepted and to receive an implementation issue before merge; this PR is explicitly draft and names an open prerequisite RFC. (README.md:70, af708f0ddb6f)
• Branch scope: The supplied PR metadata identifies three Markdown-only paths: one RFC specification update plus the new RFC and implementation-plan sidecar. (rfcs/0031-claw-application-composition-and-clients.md:1, 59b11e25acf4)

Likely related people:

• giodl73-repo: The current-main Claws RFC was introduced by Gio Della-Libera in the merged RFC 0016 commit; the same contributor authored this proposal. (role: introduced the Claw RFC foundation and authored the dependent proposal; confidence: high; commits: 13819ef73d3a, 59b11e25acf4; files: rfcs/0016-claws.md, rfcs/0031-claw-application-composition-and-clients.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Rebase after the prerequisite RFC and referenced runtime work land, then request an exact-head design review.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

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

• reviewed 2026-08-09T14:17:39.001Z sha 1afb902 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T19:50:04.900Z sha 1afb902 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T21:50:05.772Z sha 04e7a71 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T23:13:06.944Z sha 04e7a71 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-09T23:19:14.388Z sha 04e7a71 :: needs real behavior proof before merge. :: [P1] Assign an unused RFC identifier
• reviewed 2026-08-10T01:41:39.016Z sha 59b11e2 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-11T03:13:36.531Z sha 59b11e2 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-11T21:15:58.256Z sha 59b11e2 :: needs real behavior proof before merge. :: none

[giodl73-repo]

Updated the RFC after a design review and live OpenClaw issue/source audit. The new head adds the explicit BOOTSTRAP.md boundary, honest secret-handling language, no-phantom configure semantics, reordered Control UI flow, issue evidence, and concrete v1-to-v2 transition rules. @clawsweeper re-review

[giodl73-repo]

@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: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31347836654
• Updated: 2026-08-10T01:43:27.420Z

[giodl73-repo]

Superseded by the consolidated RFC 0016 contract in #48.