RFC 0016 addendum: portable core and harness profiles

[giodl73-repo]

Summary

This addendum updates merged RFC 0016 and both normative sidecar specifications in place to define a portable Claw core with namespaced, package-local harness profiles and an approved portable prompt body.

• keep CLAW.md and grouped JSON portable: agent identity and purpose stay in the core manifest
• define metadata as a string-to-string map, following the Agent Skills metadata precedent
• recognize metadata.openclaw.config as a safe package-relative pointer to a strict OpenClaw YAML profile
• use profiles/openclaw.yml as the conventional exported path while making the pointer normative
• treat a non-empty CLAW.md body as the portable agent prompt and materialize its exact bytes as managed SOUL.md
• allow frontmatter-only CLAW.md; reject a non-empty body when implicit SOUL.md conflicts exactly or hierarchically with an explicit workspace destination
• keep headings and task lists as prompt text, with no package-time executable semantics
• keep preview and ClawHub projections content-free: expose the SOUL capability and digest, not prompt text
• preserve host authority and exclude credentials, providers, bindings, local paths, arbitrary executable settings, and policy relaxation
• let applying OpenClaw resolve tools.profile from its current built-in registry; ClawHub validates shape without freezing that registry

Implementations

• OpenClaw lifecycle: openclaw/openclaw#113454
• ClawHub publication and hosted proof: openclaw/clawhub#3262, following the merged four-PR ClawHub track through #3092
• Agent profile implementation: openclaw/openclaw#112773

Portability model

Unknown metadata values remain opaque strings. A harness or registry validates and integrity-binds only profile-pointer keys it recognizes; it must not guess that arbitrary metadata strings are package paths. The portable core and harness profile therefore evolve independently without duplicating the manifest or embedding serialized configuration in metadata.

The Markdown body carries portable agent instructions. OpenClaw maps a non-empty body into its existing managed workspace lifecycle as SOUL.md; JSON manifests retain the explicit sidecar form. Export embeds managed SOUL content only when it is non-empty valid UTF-8 and the resulting CLAW.md stays within the source limit, otherwise it preserves the explicit sidecar.

The planned Control UI, pilots, authoring, graduation, standalone npx claws, and broader cross-harness standardization remain non-blocking follow-up tracks described by the RFC.

Generated with Codex.

[omarshahine]

This addendum finalizes portable per-agent tool, filesystem, and memory-search fields in experimental Claw schema v1 and extends the normative lifecycle/consent contract. These are the right documents to own that contract, but the proposed shape currently conflicts with canonical OpenClaw configuration and with its own security and disclosure guarantees.

LOC: +201/-19 (3 files)

Findings

1. Blocking: use the canonical per-agent memory shape before finalizing v1.

   rfcs/0016-claws.md:425 shows generated agent config using memorySearch, and rfcs/0016/claw-md-v1-spec.md:178 says these fields map directly to existing per-agent configuration. Current OpenClaw instead defines per-agent memory at memory.search (src/config/types.agents.ts:125-128) and explicitly treats agents.*.memorySearch as dead config.

   Prefer the canonical nested shape before graduation. If a distinct portable spelling is intentional, both sidecars must normatively define translation and output shape instead of claiming direct mapping.

2. Blocking: define the actual host-policy upper bound.

   rfcs/0016-claws.md:371-375 and rfcs/0016/claw-package-v1-spec.md:307-310 say global/operator policy cannot be widened by a Claw. Runtime, however, selects the per-agent profile over the global profile, and per-agent filesystem policy can override global workspaceOnly.

   Please choose and state the real contract: either enforce a non-overridable host ceiling during planning/apply, or say global profile/filesystem values are inherited defaults and enumerate the actual non-bypassable upper-bound layers such as hard allow/deny policy and sandbox enforcement.

3. Blocking: reconcile the Control UI disclosure contract with normative consent.

   rfcs/0016-claws.md:980-985 says the browser receives a redacted plan projection rather than the manifest. The normative package sidecar requires the applying client to make the exact grouped manifest available before consent and to disclose literal MCP arguments plus cron message/delivery behavior (rfcs/0016/claw-package-v1-spec.md:265-287).

   Give an authorized UI an expandable exact validated manifest and all required effects while withholding secret values and source-file bytes, or amend the normative sidecar to define a sufficient safe projection and exactly what may be omitted.

4. P2: separate RFC acceptance from experimental schema graduation.

   rfcs/0016-claws.md:7 remains status: draft with no implementation issue even though RFC RFC: Claws #27 is merged. The repository lifecycle says acceptance uses status: accepted plus an implementation issue. Keep the sidecars explicitly experimental, but make the parent RFC lifecycle state unambiguous.

Best-fix verdict: correct owner and timing, but internally inconsistent as written. Align the memory and policy contracts first, then keep detailed Control UI implementation mechanics in a non-normative plan or linked issue after its disclosure contract is resolved.

Specs/contracts read: full RFC 0016 and both normative sidecars; RFC repository guidance and #27 discussion; linked implementation PR #112773; canonical OpenClaw memory config, tool-policy, filesystem-policy, and security-audit owners.

Remaining uncertainty: this is a docs/spec review. I did not run contributor-controlled implementation code, and I did not inspect every line of the separate draft Control UI implementation PRs.

[giodl73-repo]

Added a non-blocking post-merge roadmap at signed head 6b9c2fc: first-party starter Claws and end-to-end product validation, selective export and publication authoring, explicit experimental graduation, a later separate cross-harness portability proposal (npx claws --agent ...), and evidence-driven lifecycle follow-ups.

@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: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30011159066
• Updated: 2026-07-23T13:26:28.784Z

[giodl73-repo]

Portability feedback is incorporated at signed head 8ac0203: the Claw manifest is now a harness-agnostic core with opaque string metadata, while metadata.openclaw.config points to a strict package-local OpenClaw profile. Other harnesses may ignore that key or define their own namespaced pointer; validators only interpret profile-pointer keys they recognize. The sidecar is integrity-bound and never becomes ordinary OpenClaw configuration.

Implementation is at openclaw/openclaw#112773. Final Codex review found no actionable correctness issues.

[giodl73-repo]

Aligned the RFC and sidecar spec with the reviewed implementation at signed head fa31caafedd4: heartbeat.skipWhenBusy is no longer part of the profile contract, and metadata.openclaw.config now explicitly requires forward-slash package-relative syntax with backslashes invalid. This keeps the portable manifest, OpenClaw profile, implementation, and ClawHub validation contract consistent.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 24, 2026, 8:44 PM ET / July 25, 2026, 00:44 UTC.

ClawSweeper review

What this changes

The branch revises RFC 0016 and its package and manifest sidecars so a portable Claw manifest can reference a strict, package-local OpenClaw harness profile through a namespaced metadata pointer.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep this PR open for maintainer review. It makes a substantial normative expansion of an accepted-but-still-experimental RFC, while the linked OpenClaw implementation is reported as closed and the available discussion does not establish that the proposed runtime contract has landed on current main.

Priority: P2
Reviewed head: e183d84eb654c263471dfd3fad75d25478dd2cd6
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The proposal is detailed and has incorporated several review rounds, but final implementation and safety-contract alignment is not demonstrated by the available evidence.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only RFC and specification documents, so contributor runtime proof is not required; implementation-backed contract confirmation is still necessary for maintainer acceptance.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only RFC and specification documents, so contributor runtime proof is not required; implementation-backed contract confirmation is still necessary for maintainer acceptance.
Evidence reviewed	5 items	Parent RFC provenance: The parent RFC was merged on July 21, 2026 at merge commit 13819ef; this PR is a follow-up normative change rather than an already-landed main-branch implementation. Substantial contract surface: The PR changes all three RFC 0016 documents, with 505 additions and 128 deletions, including portable metadata, a package-local profile pointer, validation, integrity, and consent semantics. Linked runtime work is not established as landed: The PR body points to openclaw/openclaw#112773 as implementation, while the supplied timeline identifies that PR as closed. The supplied review context does not prove a merged successor or current-main implementation for the normative profile contract.
Findings	None	None.
Security	Needs attention	Confirm enforceable host-policy and disclosure guarantees: The sidecars make host authority and safe disclosure normative, while the discussion identifies uncertainty around the actual runtime policy ceiling and UI projection. Merge only after the final specification is checked against an implementation that enforces those guarantees.

How this fits together

RFC 0016 defines the package contract that Claw authors, registries, and OpenClaw use when inspecting and applying agent packages. This addendum separates portable identity and prompt data from OpenClaw-specific settings, which then flow into validation, integrity checks, planning, consent, and host-policy enforcement.

flowchart LR
  Package[Claw package] --> Manifest[Portable CLAW manifest]
  Manifest --> Pointer[Recognized harness pointer]
  Pointer --> Profile[Package-local OpenClaw profile]
  Manifest --> Validation[Registry and harness validation]
  Profile --> Validation
  Validation --> Plan[Integrity-bound plan and consent]
  Plan --> Policy[Host policy enforcement]
  Policy --> Runtime[Managed OpenClaw agent]

Loading

Decision needed

Question	Recommendation
Should RFC 0016 now standardize the package-local OpenClaw profile contract, or should the addendum retain only the portable core and defer harness-specific normative requirements until a merged implementation is available?	Confirm and land the full contract: Confirm that a merged OpenClaw implementation and the corresponding ClawHub behavior match the final profile, host-policy, integrity, and disclosure semantics before merging this RFC addendum.

Why: The remaining question is not a mechanical documentation correction: it determines when an experimental cross-component contract becomes normative and what implementation evidence is sufficient for that decision.

Before merge

• Add real behavior proof - Not applicable: This PR changes only RFC and specification documents, so contributor runtime proof is not required; implementation-backed contract confirmation is still necessary for maintainer acceptance.
• Resolve security concern: Confirm enforceable host-policy and disclosure guarantees - The sidecars make host authority and safe disclosure normative, while the discussion identifies uncertainty around the actual runtime policy ceiling and UI projection. Merge only after the final specification is checked against an implementation that enforces those guarantees.
• Resolve merge risk (P1) - Merging would make the profile-pointer and profile-validation behavior normative without supplied proof that the linked OpenClaw implementation, or an equivalent successor, is merged and matches the final wording.
• Resolve merge risk (P1) - The proposed contract affects portability, host-policy authority, integrity binding, and consent disclosures; a mismatch between the sidecars and runtime/registry behavior could create incompatible package expectations or weaken an intended safety boundary.
• Complete next step (P2) - A maintainer must decide whether the OpenClaw-specific normative contract is ready to standardize and verify it against a merged implementation; there is no narrow automated repair to perform.

Findings

• [medium] Confirm enforceable host-policy and disclosure guarantees — rfcs/0016-claws.md:371

Agent review details

Security

Needs attention: This docs-only diff does not execute code, but it establishes security-relevant validation, integrity, policy, and consent guarantees whose implementation alignment remains unproven in the supplied review context.

Review metrics

Metric	Value	Why it matters
Normative documents	3 files changed	All RFC 0016 specification layers change together, so inconsistency with runtime and registry implementations would affect the same package contract from multiple entry points.
Specification churn	505 added, 128 removed	The change is large for an RFC addendum and covers validation and consent semantics rather than editorial wording alone.
Branch history	12 commits	The branch includes several rounds of contract revisions and one reverted prompt-body direction, so final implementation alignment matters more than a line-by-line reading alone.

Merge-risk options

Maintainer options:

1. Verify implementation-backed compatibility (recommended)
   Before merge, identify the merged OpenClaw and registry implementation commits and compare their profile parsing, integrity binding, host-policy ceiling, and upgrade behavior with the final sidecars.
2. Accept an RFC-first contract
   Maintainers may intentionally publish the contract ahead of implementation, but should explicitly own the compatibility and safety gap and assign the implementation follow-up.
3. Pause harness-specific wording
   Keep this PR open or narrow it to portable metadata if the implementation status and enforcement boundary cannot yet be demonstrated.

Technical review

Best possible solution:

Land the portable-core wording only after a maintainer confirms the OpenClaw profile contract against a merged implementation or deliberately narrows the RFC to defer the harness-specific normative requirements until that implementation is ready.

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

Not applicable: this is a normative RFC proposal, not a report of a failing runtime path. The relevant verification is implementation and contract comparison rather than bug reproduction.

Is this the best way to solve the issue?

Unclear: separating portable metadata from package-local harness profiles is a coherent direction, but the supplied evidence does not confirm that the final normative wording matches merged OpenClaw and ClawHub behavior.

AGENTS.md: unclear because the file could not be read completely.

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

Labels

Label changes:

• add P2: This is a significant experimental contract decision with limited immediate user impact but meaningful downstream implementation consequences.
• add merge-risk: 🚨 compatibility: The PR introduces a new portable metadata pointer and OpenClaw profile contract that registries, packages, and harnesses must interpret consistently.
• add merge-risk: 🚨 security-boundary: The normative text defines host-policy limits, validation, integrity, and consent behavior, so disagreement with the runtime could weaken intended safety guarantees.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.

Label justifications:

• P2: This is a significant experimental contract decision with limited immediate user impact but meaningful downstream implementation consequences.
• merge-risk: 🚨 compatibility: The PR introduces a new portable metadata pointer and OpenClaw profile contract that registries, packages, and harnesses must interpret consistently.
• merge-risk: 🚨 security-boundary: The normative text defines host-policy limits, validation, integrity, and consent behavior, so disagreement with the runtime could weaken intended safety guarantees.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.

Evidence

Security concerns:

• [medium] Confirm enforceable host-policy and disclosure guarantees — rfcs/0016-claws.md:371
  The sidecars make host authority and safe disclosure normative, while the discussion identifies uncertainty around the actual runtime policy ceiling and UI projection. Merge only after the final specification is checked against an implementation that enforces those guarantees.
  Confidence: 0.78

What I checked:

• Parent RFC provenance: The parent RFC was merged on July 21, 2026 at merge commit 13819ef; this PR is a follow-up normative change rather than an already-landed main-branch implementation. (rfcs/0016-claws.md:7, 13819ef73d3a)
• Substantial contract surface: The PR changes all three RFC 0016 documents, with 505 additions and 128 deletions, including portable metadata, a package-local profile pointer, validation, integrity, and consent semantics. (rfcs/0016/claw-package-v1-spec.md:114, e183d84eb654)
• Linked runtime work is not established as landed: The PR body points to feat(claws): separate portable and OpenClaw profiles openclaw#112773 as implementation, while the supplied timeline identifies that PR as closed. The supplied review context does not prove a merged successor or current-main implementation for the normative profile contract. (rfcs/0016/claw-md-v1-spec.md:13, e183d84eb654)
• Existing reviewer concern: The assigned reviewer identified a need to make the host-policy upper bound and Control UI disclosure contract enforceable rather than merely asserted. Subsequent contributor comments describe portability refinements, but the supplied context does not independently demonstrate the resulting runtime and disclosure behavior. (rfcs/0016-claws.md:371, e183d84eb654)
• Feature-history routing: The current RFC 0016 baseline originates in the merged parent RFC, and the proposed branch is a twelve-commit follow-up by the same feature author; the assigned reviewer has supplied the most detailed contract review in the discussion. (rfcs/0016-claws.md:1, e183d84eb654)

Likely related people:

• giodl73-repo: Authored the merged RFC 0016 baseline and this follow-up branch, including the portability and profile-contract revisions. (role: feature author; confidence: high; commits: 13819ef73d3a, 8ac0203b2f7c, e183d84eb654; files: rfcs/0016-claws.md, rfcs/0016/claw-md-v1-spec.md, rfcs/0016/claw-package-v1-spec.md)
• omarshahine: Was assigned during this PR and provided the detailed review of memory configuration, policy ceilings, disclosure, and RFC lifecycle alignment. (role: assigned contract reviewer; confidence: high; files: rfcs/0016-claws.md, rfcs/0016/claw-md-v1-spec.md, rfcs/0016/claw-package-v1-spec.md)

Rank-up moves

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

• Identify the merged OpenClaw and ClawHub implementation commits, or clearly mark the harness profile as deferred.
• Have the assigned reviewer confirm the final host-policy and consent wording against the implementation path.

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.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: RFC 0016 addendum: portable core and harness profiles 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]

The implementation evidence requested by the latest ClawSweeper review is now available: openclaw/openclaw#112773 merged as e9b3252ae8e5cad8be0b7d3d209365c5516aa1b8. Its final exact-head proof covered the portable manifest pointer, package-local OpenClaw profile parsing, profile integrity binding, agent settings projection, and focused lifecycle/profile/export tests. The broader experimental Claws lifecycle and CLAW.md support are also merged on current OpenClaw main.

The final RFC head retains host authority and exact consent disclosure as normative constraints; it does not make the browser projection the authority or permit a Claw profile to bypass host enforcement.

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.