docs: add Agent Profiles RFC

[vincentkoc]

Status: In progress. A manual pass over the full RFC is still pending after the Schemator-guided naming update and Agent Profiles rename.

Summary

• Proposes RFC 0009, Agent Profiles.
• Replaces the binary local-model Lean direction with a versioned, deterministic profile registry.
• Structures profiles with spec.common for harness-agnostic behavior and domain-owned sections such as spec.openclaw.ai for harness-specific behavior.
• Separates model identity, Agent Profiles, provider drivers, and future managed-local Serving Presets.
• Defines phase-one migration for Lean, GPT-5 response-style settings, and Claude/Opus thinking defaults, plus hosted-provider KV/cache non-regression boundaries.
• Defines phase two as the ClawHub-backed Agent Profile distribution and discovery layer.

Scope

This is an RFC only. It does not change OpenClaw runtime behavior or add a configuration surface in this PR.

Verification

• git diff --check
• Targeted terminology search for stale pre-rename/model profile/profile/recipe naming
• Manual review of RFC metadata, schema shape, phase boundaries, and PR-facing summary

RFC Lifecycle

• Status: draft
• Implementation issue: not created
• Maintainer discussion thread: pending

[clawsweeper]

Codex review: found issues before merge. Reviewed August 15, 2026, 4:54 PM ET / 20:54 UTC.

ClawSweeper review

What this changes

The PR adds a draft Agent Profiles RFC proposing a versioned registry for model-specific agent-harness behavior and future profile distribution.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open. This member-authored draft is not ready to merge because it reuses RFC 0009, already assigned to Hosted Feeds on current main, and its required maintainer-discussion thread remains pending.

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

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The draft is substantial but needs its RFC identity and governance prerequisites resolved before it is ready for acceptance.
Proof confidence	🌊 off-meta tidepool	Not applicable: This documentation-only RFC does not require runtime behavior proof.
Patch quality	🦐 gold shrimp (3/6)	2 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This documentation-only RFC does not require runtime behavior proof.
Evidence reviewed	5 items	RFC 0009 is already assigned: Current main has RFC 0009 for Hosted Feeds, whose frontmatter links the merged Hosted Feeds PR; the proposed file path reuses that identifier for a different RFC. Identifier also owns sidecar namespace: Current main contains the existing RFC 0009 document plus its 0009 sidecar directory, while repository guidance reserves a sibling directory named exactly after an RFC identifier. RFC lifecycle requires discussion: The repository requires every new RFC to have a maintainer-discussion thread; the PR body explicitly says that discussion is pending.
Findings	2 actionable findings	[P2] Assign an unused RFC identifier [P2] Open the required maintainer discussion
Security	None	None.

How this fits together

The RFC repository records proposed OpenClaw contracts before runtime implementation. This document would guide how model metadata and provider capabilities select agent-harness behavior.

flowchart LR
A[Model metadata] --> B[Profile selection]
B --> C[Agent profile registry]
C --> D[Provider capability checks]
D --> E[Agent harness behavior]
C --> F[Future profile distribution]

Loading

Decision needed

Question	Recommendation
Should Agent Profiles be sponsored for formal RFC review after the identifier conflict is corrected?	Sponsor formal RFC review: Correct the identifier and open the required discussion to evaluate the proposed contract.

Why: The draft proposes future public configuration, migration, and distribution semantics that require maintainer product ownership beyond documentation review.

Before merge

• Assign an unused RFC identifier (P2) - Current main already assigns 0009 to Hosted Feeds and contains its rfcs/0009/ sidecar assets. Rename this RFC and every internal reference to an unused identifier so future sidecars and links cannot become ambiguous.
• Open the required maintainer discussion (P2) - The repository lifecycle requires a maintainer-discussion thread for each new RFC, while the PR body says that thread is pending. Open and link the discussion before this draft is considered for merge.
• Resolve merge risk (P1) - Renaming the RFC alone would not validate the proposed future configuration and migration contract; it still needs the repository-required maintainer discussion before merge.
• Complete next step (P2) - The remaining blocker is maintainer sponsorship of a compatibility-sensitive design direction, not a safe autonomous repair.

Findings

• [P2] Assign an unused RFC identifier — rfcs/0009-agent-profiles.md:1-11
• [P2] Open the required maintainer discussion — rfcs/0009-agent-profiles.md:1-11

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC scope	1 file added, 1,046 lines	The change is a substantial new design contract, making identifier and lifecycle correctness material before merge.

Merge-risk options

Maintainer options:

1. Resolve the contract before merge (recommended)
   Use an unused RFC identifier and obtain maintainer review of the future configuration and migration contract.

Technical review

Best possible solution:

Assign an unused RFC identifier, update all internal references, and use the maintainer-discussion thread to decide whether Agent Profiles should become an OpenClaw compatibility contract.

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

Not applicable: this PR is a design RFC and does not claim to repair a runnable current behavior.

Is this the best way to solve the issue?

No: the document cannot enter the RFC sequence while it reuses an existing identifier and lacks the required maintainer discussion.

Full review comments:

• [P2] Assign an unused RFC identifier — rfcs/0009-agent-profiles.md:1-11
  Current main already assigns 0009 to Hosted Feeds and contains its rfcs/0009/ sidecar assets. Rename this RFC and every internal reference to an unused identifier so future sidecars and links cannot become ambiguous.
  Confidence: 0.99
• [P2] Open the required maintainer discussion — rfcs/0009-agent-profiles.md:1-11
  The repository lifecycle requires a maintainer-discussion thread for each new RFC, while the PR body says that thread is pending. Open and link the discussion before this draft is considered for merge.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a non-emergency but compatibility-sensitive proposed product direction.
• merge-risk: 🚨 compatibility: The RFC defines proposed migration and configuration behavior that could affect existing user setups if adopted.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This documentation-only RFC does not require runtime behavior proof.

Evidence

What I checked:

• RFC 0009 is already assigned: Current main has RFC 0009 for Hosted Feeds, whose frontmatter links the merged Hosted Feeds PR; the proposed file path reuses that identifier for a different RFC. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:2, af708f0ddb6f)
• Identifier also owns sidecar namespace: Current main contains the existing RFC 0009 document plus its 0009 sidecar directory, while repository guidance reserves a sibling directory named exactly after an RFC identifier. (README.md:47, af708f0ddb6f)
• RFC lifecycle requires discussion: The repository requires every new RFC to have a maintainer-discussion thread; the PR body explicitly says that discussion is pending. (README.md:83, af708f0ddb6f)
• Current RFC 0009 provenance: The most recent local history for the existing RFC 0009 is Gio Della-Libera's addendum commit, confirming that the identifier remains actively owned on main. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:1, 2d213ae23462)
• PR branch scope: Provided PR metadata identifies the sole added file as rfcs/0009-agent-profiles.md at head 02df4b5, which establishes the conflicting identifier even though this partial clone could not retrieve the PR object after its remote DNS lookup failed. (rfcs/0009-agent-profiles.md:1, 02df4b53ab14)

Likely related people:

• giodl73-repo: The existing current-main RFC 0009 is linked to their merged Hosted Feeds PR, and recent history shows continued work on its sidecar specifications. (role: recent RFC 0009 contributor; confidence: high; commits: 2d213ae23462, f9ac10e91384; files: rfcs/0009-hosted-feeds-for-plugins-and-skills.md, rfcs/0009/hosted-feed-v1-spec.md)
• osolmaz: They authored the latest Agent Profiles RFC revisions and recorded that a manual wording pass and maintainer discussion were still pending. (role: recent RFC contributor; confidence: medium; commits: 02df4b53ab14; files: rfcs/0009-agent-profiles.md)

Rank-up moves

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

• Rename the RFC to an unused identifier and update its references.
• Open the required maintainer-discussion thread and record the outcome.

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 (49 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T19:49:43.459Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Create the required maintainer discussion
• reviewed 2026-08-09T22:01:10.113Z sha 02df4b5 :: found issues before merge. :: [P2] Use an unused RFC identifier | [P2] Create the required maintainer discussion
• reviewed 2026-08-09T23:10:37.321Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion
• reviewed 2026-08-11T03:13:30.018Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion
• reviewed 2026-08-12T01:54:00.872Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion
• reviewed 2026-08-13T23:22:26.319Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion
• reviewed 2026-08-14T07:15:32.140Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion
• reviewed 2026-08-14T12:09:44.882Z sha 02df4b5 :: found issues before merge. :: [P2] Assign an unused RFC identifier | [P2] Open the required maintainer discussion

[osolmaz]

Applied a Schemator-guided naming simplification pass to the model profile RFC. This kept the corrected stable vocabulary like extends, settings, toolExposure, contextPosture, and profile, while tightening names such as promptRecipe -> promptPreset, reasoningDefault -> reasoningMode, and the GPT setting shape around responseStyle.

Next I will do a manual pass over the full document to catch product-language issues, naming consistency, and any places where the automated schema review should not drive the final RFC wording.