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 June 25, 2026, 12:21 AM ET / 04:21 UTC.

Summary
Adds a single draft RFC document proposing Agent Profiles, including schema and selection rules, Lean/GPT/Claude migration, Serving Presets, verification requirements, and a future ClawHub distribution phase.

Reproducibility: not applicable. this is an RFC/documentation PR, not a runtime bug report. The high-confidence checks are the PR diff, README lifecycle rules, current RFC inventory, and potential merge tree.

Review metrics: 3 noteworthy metrics.

• RFC diff: 1 file added, 1046 additions, 0 deletions. This is a large product-design document, so manual RFC review is the main confidence gate.
• Merge-tree RFC ids: 2 rfcs/0009-* files. The potential merge result would publish duplicate RFC ids unless this draft is renumbered.
• Lifecycle state: draft status, blank issue, discussion pending. The repository lifecycle blocks merging draft RFCs before discussion and acceptance.

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:

• Renumber the RFC to a free id and update self-references.
• [P2] Add or link the maintainer-discussion thread before moving out of draft.
• Update status and issue only after maintainer acceptance.

Risk before merge

• [P1] Merging the latest head would publish two rfcs/0009-* documents, making RFC references ambiguous.
• [P1] The RFC is still marked draft with a blank implementation issue, and the PR body says the maintainer discussion thread is pending.
• [P1] The RFC proposes future profile selectors, settings, migration behavior, Serving Presets, and ClawHub distribution boundaries, so maintainers need to accept the product direction before merge.

Maintainer options:

1. Finish RFC Lifecycle Before Merge (recommended)
   Assign a free RFC id, link the maintainer discussion, and merge only after maintainer acceptance and implementation tracking are reflected in the metadata.
2. Keep Drafting In This PR
   Leave the PR open as a draft while naming, config scope, and ClawHub phase boundaries get the pending manual pass.
3. Pause If Direction Is Unsponsored
   If maintainers do not want to sponsor Agent Profiles now, pause or close the draft rather than publishing unresolved RFC text.

Next step before merge

• [P2] This member-authored draft RFC needs author and maintainer action for RFC id selection, discussion linkage, and product acceptance rather than an automated repair.

Security
Cleared: The diff adds a Markdown RFC only and does not change executable code, workflows, dependencies, package metadata, secrets handling, or release scripts.

Review findings

• [P2] Renumber this RFC before merge — rfcs/0009-agent-profiles.md:1-2
• [P2] Keep the draft RFC out of main until lifecycle is complete — rfcs/0009-agent-profiles.md:8-9

Review details

Best possible solution:

Keep this as the active draft, assign a free RFC id, add or link the maintainer discussion, coordinate the ClawHub phase with #19, and update lifecycle metadata only after acceptance.

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

Not applicable: this is an RFC/documentation PR, not a runtime bug report. The high-confidence checks are the PR diff, README lifecycle rules, current RFC inventory, and potential merge tree.

Is this the best way to solve the issue?

No, not as a merge candidate yet: the RFC is a reasonable vehicle for the product decision, but it needs renumbering, lifecycle metadata, discussion linkage, and maintainer acceptance before merge.

Full review comments:

• [P2] Renumber this RFC before merge — rfcs/0009-agent-profiles.md:1-2
  The potential merge tree contains both current main's rfcs/0009-hosted-feeds-for-plugins-and-skills.md and this added rfcs/0009-agent-profiles.md, so landing would leave duplicate RFC ids. Pick a free id and update the filename plus self-references before merge.
  Confidence: 0.97
• [P2] Keep the draft RFC out of main until lifecycle is complete — rfcs/0009-agent-profiles.md:8-9
  The README lifecycle says draft RFCs should not merge and each new RFC needs a maintainer-discussion thread. This file still has status: draft with a blank issue, and the PR body says the discussion thread is pending.
  Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.93

AGENTS.md: not found in the target repository.

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

Label changes

Label justifications:

• P3: This is low-risk RFC/documentation work with no immediate runtime behavior change.
• merge-risk: 🚨 other: Merging as-is would publish unresolved RFC direction and duplicate the current RFC 0009 id, which normal CI does not settle.
• 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 is a member-authored RFC-only documentation PR with no runtime behavior change, so after-fix real behavior proof is not required.

Evidence reviewed

What I checked:

• Target AGENTS.md check: No AGENTS.md was found under the target repository git root, so no target-specific AGENTS policy applied. (89cf322325b0)
• PR metadata: GitHub reports the PR is open, draft, member-authored, mergeable clean, and adds one Markdown file with 1046 additions. (02df4b53ab14)
• Added RFC lifecycle state: The added RFC frontmatter still has status: draft and a blank issue. (rfcs/0009-agent-profiles.md:8, 02df4b53ab14)
• RFC lifecycle rule: README says new RFCs should not merge while draft, need a maintainer-discussion thread, and should merge only after acceptance with an implementation issue. (README.md:80, e366ea9825a4)
• Merge-tree RFC id collision: The potential merge tree contains both rfcs/0009-agent-profiles.md and rfcs/0009-hosted-feeds-for-plugins-and-skills.md. (rfcs/0009-agent-profiles.md:1, 580163fdf442)
• Current main RFC 0009: Current main already has rfcs/0009-hosted-feeds-for-plugins-and-skills.md. (rfcs/0009-hosted-feeds-for-plugins-and-skills.md:1, 89cf322325b0)

Likely related people:

• kevinlin-openai: Blame and history show this person authored the README lifecycle rules used to evaluate draft status, discussion-thread readiness, and accepted RFC metadata. (role: RFC process author; confidence: high; commits: e366ea9825a4, bbb4058da234, f4fdf38f4717; files: README.md, rfcs/0000-template.md)
• Dallin Romney: Recent history shows this person clarified RFC sidecar and layout guidance in the README and template. (role: recent RFC layout contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)
• giodl73-repo: The merged hosted-feeds RFC on current main occupies RFC id 0009 and overlaps this proposal's future ClawHub distribution phase. (role: adjacent RFC author; confidence: medium; commits: 89cf322325b0; files: rfcs/0009-hosted-feeds-for-plugins-and-skills.md)
• osolmaz: PR commits and discussion show this person drove the Agent Profiles rename/schema pass and noted that manual product-language review remains pending. (role: active RFC co-author and reviewer; confidence: high; commits: 0a41e99fb644, 8b4d35090cf1, 02df4b53ab14; files: rfcs/0009-agent-profiles.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.

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