PR #64263: feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64263

Description (problem / solution / changelog)

Why

This is the core feature PR for model-aware AGENTS bootstrap selection.

It moves the old plugin-only AGENTS swap idea into OpenClaw core so teams can:

• keep a broader orchestrator prompt for the main agent
• give sub-agents a narrower worker file such as SUBAGENTS.md
• tune prompt shape by model without rewriting the workspace's primary AGENTS.md

That matters most for workflows where different models do better with different instruction density or structure. For example, a team may want a broader planning-oriented file for anthropic/claude-opus-4-6, but a shorter, stricter worker file for openai/gpt-5.4.

What Changed

• add schema-backed config for main-agent and sub-agent AGENTS source selection
• support exact model-keyed overrides via canonical provider/model refs
• resolve the effective AGENTS source after runtime model normalization for both embedded and CLI paths
• thread modelProviderId and modelId through bootstrap hook context
• keep continuation signatures aligned with the hook-adjusted AGENTS source
• harden path handling, warning labels, and fallback behavior for invalid overrides
• make the bootstrap-signature expectations cross-platform
• avoid building full contextFiles just to confirm a continuation signature

Config Surface

{
  agents: {
    defaults: {
      agentsFile: "AGENTS.opus.md",
      agentsFilesByModel: {
        "openai/gpt-5.4": "AGENTS.gpt-5.4.md",
        "anthropic/claude-opus-4-6": "AGENTS.opus.md",
      },
      subagents: {
        agentsFile: "SUBAGENTS.md",
        agentsFilesByModel: {
          "openai/gpt-5.4": "SUBAGENTS.gpt-5.4.md",
        },
      },
    },
    list: [
      {
        id: "research",
        agentsFile: "AGENTS.research.md",
        agentsFilesByModel: {
          "openai/gpt-5.4": "AGENTS.research.gpt-5.4.md",
        },
        subagents: {
          agentsFile: "SUBAGENTS.research.md",
        },
      },
    ],
  },
}

Selection order is:

1. determine whether the run is main or subagent
2. resolve the actual runtime model used for the run
3. try the per-agent model-specific override
4. try the defaults model-specific override
5. try the per-agent base override
6. try the defaults base override
7. fall back to workspace AGENTS.md

How To Review

1. Review the schema/config surface for agentsFile and agentsFilesByModel on defaults and per-agent overrides.
2. Review src/agents/bootstrap-files.ts for the effective-file selection, fallback order, warning text, and bootstrap signature handling.
3. Review src/agents/workspace.ts for guarded file loading and workspace-relative path handling.
4. Review the embedded/CLI plumbing and tests for resolved-model behavior and continuation-skip parity.

Acceptance Criteria

• main runs can select a model-specific AGENTS file
• sub-agent runs can use a different AGENTS base file than the main agent
• exact provider/model overrides win when present
• invalid paths warn and fall back safely
• continuation-skip notices AGENTS-source drift correctly
• hook-adjusted AGENTS selection does not break signature matching

Validation

• pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts
• pnpm build

Merge Order

This is PR 1 of 3.

• this PR first
• #64264 second
• #64265 third
• #64504 tracks the full stack

Links

• Closes #31070
• Closes #64247
• Part of #64248
• Followed by #64264 and #64265
• Tracked by #64504

Changed files

• src/agents/agent-scope.ts (modified, +7/-0)
• src/agents/bootstrap-files.test.ts (modified, +368/-0)
• src/agents/bootstrap-files.ts (modified, +338/-9)
• src/agents/bootstrap-hooks.ts (modified, +4/-0)
• src/agents/cli-runner.spawn.test.ts (modified, +33/-1)
• src/agents/cli-runner.test-support.ts (modified, +8/-1)
• src/agents/cli-runner/prepare.ts (modified, +3/-0)
• src/agents/pi-embedded-runner/compact.ts (modified, +8/-0)
• src/agents/pi-embedded-runner/extensions.ts (modified, +11/-0)
• src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts (modified, +21/-5)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-engine.test.ts (modified, +35/-0)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts (modified, +53/-2)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.test-support.ts (modified, +27/-4)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +54/-11)
• src/agents/pi-hooks/compaction-safeguard-runtime.ts (modified, +8/-0)
• src/agents/workspace.test.ts (modified, +22/-0)
• src/agents/workspace.ts (modified, +49/-14)
• src/auto-reply/reply/agent-runner-memory.ts (modified, +1/-0)
• src/auto-reply/reply/commands-compact.ts (modified, +1/-0)
• src/config/schema.base.generated.ts (modified, +114/-2)
• src/config/schema.help.ts (modified, +17/-1)
• src/config/schema.labels.ts (modified, +8/-0)
• src/config/types.agent-defaults.ts (modified, +33/-0)
• src/config/types.agents.ts (modified, +12/-1)
• src/config/zod-schema.agent-defaults.test.ts (modified, +17/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +3/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +7/-0)
• src/gateway/server-methods/sessions.ts (modified, +1/-0)
• src/hooks/internal-hooks.ts (modified, +2/-0)
• src/shared/avatar-policy.test.ts (modified, +1/-0)
• src/shared/avatar-policy.ts (modified, +4/-4)

PR #64265: docs(agents): document model-aware AGENTS and SUBAGENTS migration

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64265

Description (problem / solution / changelog)

Why

This PR documents the shipped core feature in plain English and engineering terms.

The goal is to make the model-aware AGENTS behavior understandable to three audiences:

• end users who just want to configure different prompt files for different models
• maintainers reviewing the runtime behavior and security implications
• AI-agent users trying to understand why they might want a different worker prompt for GPT-5.4 than for Claude/Opus-style orchestrator runs

What Changed

• document the new agentsFile and agentsFilesByModel keys for main agents and sub-agents
• document the per-agent override surface under agents.list[] and agents.list[].subagents
• explain selection order and fallback behavior
• explain why sub-agents should keep a narrowed AGENTS source through compaction/reinjection
• add migration guidance from plugin-only SubAgent Context Limiter setups
• add examples, scenarios, and Mermaid diagrams in the subagents and system prompt docs

Docs Included

• docs/tools/subagents.md
• docs/concepts/system-prompt.md
• docs/gateway/configuration-reference.md

How To Review

GitHub only allows upstream PRs to use base branches that exist in openclaw/openclaw itself. Because the staging branches in this stack live on the fork, this PR still targets main upstream even though it is logically PR 3 of 3.

Recommended review path:

1. review #64263 first
2. review #64264 second
3. then review the docs-only delta here: parity -> docs compare

User Scenarios Covered

• main orchestrator on anthropic/claude-opus-4-6, workers on openai/gpt-5.4
• narrower SUBAGENTS.md for workers as a security/least-privilege boundary
• model-specific worker variants such as SUBAGENTS.gpt-5.4.md
• exact-match fallback behavior when no model-specific override exists
• prompt-shape tuning by model without rewriting the team's primary workspace AGENTS.md

Validation

• pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts

Merge Order

This is PR 3 of 3.

• #64263 first
• #64264 second
• this PR third
• #64504 tracks the full stack

After the earlier PRs merge, GitHub will automatically shrink this PR down to the docs-only remainder.

Links

• Part of #64248
• Documents #64247 and #64246
• Tracked by #64504

Changed files

• docs/concepts/system-prompt.md (modified, +35/-2)
• docs/gateway/configuration-reference.md (modified, +86/-1)
• docs/tools/subagents.md (modified, +140/-1)
• src/agents/agent-scope.ts (modified, +7/-0)
• src/agents/bootstrap-files.test.ts (modified, +368/-0)
• src/agents/bootstrap-files.ts (modified, +338/-9)
• src/agents/bootstrap-hooks.ts (modified, +4/-0)
• src/agents/cli-runner.spawn.test.ts (modified, +33/-1)
• src/agents/cli-runner.test-support.ts (modified, +8/-1)
• src/agents/cli-runner/prepare.ts (modified, +3/-0)
• src/agents/pi-embedded-runner/compact.ts (modified, +8/-0)
• src/agents/pi-embedded-runner/extensions.ts (modified, +11/-0)
• src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts (modified, +21/-5)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts (modified, +53/-2)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +54/-11)
• src/agents/pi-hooks/compaction-safeguard-runtime.ts (modified, +8/-0)
• src/agents/pi-hooks/compaction-safeguard.test.ts (modified, +55/-0)
• src/agents/pi-hooks/compaction-safeguard.ts (modified, +39/-22)
• src/agents/workspace.test.ts (modified, +22/-0)
• src/agents/workspace.ts (modified, +49/-14)
• src/auto-reply/reply/agent-runner-memory.ts (modified, +9/-0)
• src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts (modified, +80/-1)
• src/auto-reply/reply/agent-runner.ts (modified, +7/-2)
• src/auto-reply/reply/commands-compact.ts (modified, +1/-0)
• src/auto-reply/reply/post-compaction-context.test.ts (modified, +51/-0)
• src/auto-reply/reply/post-compaction-context.ts (modified, +48/-20)
• src/config/schema.base.generated.ts (modified, +114/-2)
• src/config/schema.help.ts (modified, +17/-1)
• src/config/schema.labels.ts (modified, +8/-0)
• src/config/types.agent-defaults.ts (modified, +33/-0)
• src/config/types.agents.ts (modified, +12/-1)
• src/config/zod-schema.agent-defaults.test.ts (modified, +17/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +3/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +7/-0)
• src/gateway/server-methods/sessions.ts (modified, +1/-0)
• src/hooks/internal-hooks.ts (modified, +2/-0)
• src/shared/avatar-policy.test.ts (modified, +1/-0)
• src/shared/avatar-policy.ts (modified, +4/-4)

PR #64266: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64266

Description (problem / solution / changelog)

Purpose

This is the real non-draft umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

• core model-aware AGENTS selection
• sub-agent-specific AGENTS narrowing
• compaction/reinjection parity
• docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

• keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
• give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
• keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

This is not a benchmark claim about one model being universally better than another. It is a prompt-control feature: different models often respond better to different context density, output constraints, and task framing.

Review Order

Because I only have READ permission on openclaw/openclaw, GitHub will not let me stack these upstream PRs on fork-only base branches. So the child PRs all target main, and later PRs temporarily include prerequisite commits until earlier PRs merge.

Recommended review order:

1. #64263
2. #64264
3. #64265
4. this PR for the final integrated view

Helpful delta links:

• bootstrap -> parity: compare view
• parity -> docs: compare view

Rollout Diagram

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Select AGENTS source from base + model overrides"]
    D --> E["Apply agent:bootstrap hooks"]
    E --> F["Inject project context"]
    F --> G["Reuse same effective AGENTS source for continuation / compaction / reinjection"]

Child PRs

• #64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
  • core config, runtime model plumbing, bootstrap signature behavior
• #64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
  • parity for compaction/post-compaction paths so narrowed worker AGENTS files stay narrowed
• #64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
  • plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

• main/orchestrator runs can use a model-specific AGENTS file
• sub-agents can use a different AGENTS base file than the main agent
• exact provider/model overrides work for both main and sub-agent runs
• invalid overrides warn and fall back safely
• continuation, compaction, and reinjection reuse the same effective AGENTS source
• docs explain the feature clearly for users and maintainers

Local Validation

• pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts
• pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
• pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
• pnpm build

Issue Tree

• Umbrella: #64248
• Reused upstream issue: #31070
• Child issue: #64246
• Child issue: #64247
• Related upstream issue: #46595
• Related upstream issue: #45413

Related Upstream Work

• Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
• PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

• .oxfmtrc.jsonc (modified, +2/-2)
• .oxlintrc.json (modified, +4/-5)
• CHANGELOG.md (modified, +46/-1)
• docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
• docs/concepts/qa-e2e-automation.md (modified, +4/-0)
• docs/concepts/system-prompt.md (modified, +35/-2)
• docs/gateway/cli-backends.md (modified, +8/-0)
• docs/gateway/configuration-reference.md (modified, +89/-4)
• docs/gateway/security/index.md (modified, +4/-4)
• docs/help/testing.md (modified, +4/-0)
• docs/plugins/manifest.md (modified, +25/-0)
• docs/reference/templates/AGENTS.md (modified, +0/-3)
• docs/tools/browser.md (modified, +2/-2)
• docs/tools/skills.md (modified, +7/-0)
• docs/tools/subagents.md (modified, +140/-1)
• extensions/acpx/package.json (modified, +1/-1)
• extensions/active-memory/index.test.ts (modified, +20/-20)
• extensions/amazon-bedrock/package.json (modified, +1/-1)
• extensions/anthropic/stream-wrappers.test.ts (modified, +5/-5)
• extensions/browser/index.test.ts (modified, +1/-1)
• extensions/browser/src/browser-tool.ts (modified, +1/-1)
• extensions/browser/src/browser/bridge-server.auth.test.ts (modified, +10/-1)
• extensions/browser/src/browser/bridge-server.ts (modified, +12/-7)
• extensions/browser/src/browser/cdp.helpers.test.ts (added, +65/-0)
• extensions/browser/src/browser/cdp.helpers.ts (modified, +45/-10)
• extensions/browser/src/browser/cdp.test.ts (modified, +23/-6)
• extensions/browser/src/browser/cdp.ts (modified, +2/-1)
• extensions/browser/src/browser/chrome-mcp.snapshot.ts (modified, +1/-1)
• extensions/browser/src/browser/chrome-mcp.ts (modified, +1/-1)
• extensions/browser/src/browser/chrome.test.ts (modified, +2/-2)
• extensions/browser/src/browser/chrome.ts (modified, +14/-6)
• extensions/browser/src/browser/client-actions-core.ts (modified, +2/-87)
• extensions/browser/src/browser/client-actions.types.ts (added, +87/-0)
• extensions/browser/src/browser/client-fetch.ts (modified, +14/-12)
• extensions/browser/src/browser/client.ts (modified, +2/-19)
• extensions/browser/src/browser/client.types.ts (added, +19/-0)
• extensions/browser/src/browser/config.test.ts (modified, +15/-4)
• extensions/browser/src/browser/config.ts (modified, +4/-4)
• extensions/browser/src/browser/errors.test.ts (modified, +26/-1)
• extensions/browser/src/browser/errors.ts (modified, +21/-1)
• extensions/browser/src/browser/form-fields.ts (modified, +1/-1)
• extensions/browser/src/browser/local-dispatch.runtime.ts (added, +20/-0)
• extensions/browser/src/browser/navigation-guard.test.ts (modified, +88/-0)
• extensions/browser/src/browser/navigation-guard.ts (modified, +40/-1)
• extensions/browser/src/browser/profiles-service.test.ts (modified, +3/-1)
• extensions/browser/src/browser/profiles-service.ts (modified, +5/-5)
• extensions/browser/src/browser/pw-session.create-page.navigation-guard.test.ts (modified, +51/-1)
• extensions/browser/src/browser/pw-session.ts (modified, +71/-13)
• extensions/browser/src/browser/pw-tools-core.interactions.navigation-guard.test.ts (modified, +563/-2)
• extensions/browser/src/browser/pw-tools-core.interactions.ts (modified, +132/-42)
• extensions/browser/src/browser/pw-tools-core.test-harness.ts (modified, +19/-0)
• extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts (added, +385/-0)
• extensions/browser/src/browser/routes/agent.act.normalize.ts (modified, +1/-1)
• extensions/browser/src/browser/routes/agent.act.ts (modified, +223/-63)
• extensions/browser/src/browser/routes/tabs.test.ts (added, +112/-0)
• extensions/browser/src/browser/routes/tabs.ts (modified, +6/-0)
• extensions/browser/src/browser/server-context.loopback-direct-ws.test.ts (modified, +22/-0)
• extensions/browser/src/browser/server-context.remote-profile-tab-ops.playwright.test.ts (modified, +45/-3)
• extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts (modified, +3/-3)
• extensions/browser/src/browser/server-context.selection.ts (modified, +15/-2)
• extensions/browser/src/browser/server-context.tab-ops.ts (modified, +22/-6)
• extensions/browser/src/browser/server-context.ts (modified, +1/-8)
• extensions/browser/src/browser/server-context.types.ts (modified, +1/-2)
• extensions/browser/src/browser/server-middleware.ts (modified, +16/-1)
• extensions/browser/src/browser/server.control-server.test-harness.ts (modified, +1/-0)
• extensions/device-pair/index.test.ts (modified, +1/-1)
• extensions/device-pair/openclaw.plugin.json (modified, +6/-0)
• extensions/diffs/assets/viewer-runtime.js (modified, +48/-48)
• extensions/diffs/package.json (modified, +1/-1)
• extensions/diffs/src/language-hints.ts (modified, +8/-1)
• extensions/diffs/src/viewer-payload.ts (modified, +4/-1)
• extensions/discord/package.json (modified, +1/-1)
• extensions/discord/src/monitor/thread-title.generate.test.ts (modified, +4/-4)
• extensions/discord/src/monitor/thread-title.ts (modified, +6/-1)
• extensions/discord/src/voice/manager.e2e.test.ts (modified, +3/-1)
• extensions/feishu/src/bot.broadcast.test.ts (modified, +4/-1)
• extensions/feishu/src/client.ts (modified, +46/-3)
• extensions/feishu/src/monitor.account.ts (modified, +12/-22)
• extensions/feishu/src/monitor.bot-menu.test.ts (modified, +1/-1)
• extensions/feishu/src/probe.test.ts (modified, +7/-6)
• extensions/feishu/src/probe.ts (modified, +15/-14)
• extensions/feishu/src/reply-dispatcher.test.ts (modified, +1/-1)
• extensions/feishu/src/sequential-key.test.ts (added, +72/-0)
• extensions/feishu/src/sequential-key.ts (added, +25/-0)
• extensions/feishu/src/sequential-queue.test.ts (added, +64/-0)
• extensions/feishu/src/sequential-queue.ts (added, +15/-0)
• extensions/feishu/src/streaming-card.ts (modified, +6/-1)
• extensions/feishu/src/tool-account-routing.test.ts (modified, +1/-1)
• extensions/github-copilot/stream.test.ts (modified, +3/-3)
• extensions/google/oauth.test.ts (modified, +20/-4)
• extensions/google/package.json (modified, +1/-1)
• extensions/google/video-generation-provider.test.ts (modified, +0/-4)
• extensions/imessage/src/media-contract.ts (modified, +1/-1)
• extensions/irc/src/channel.ts (modified, +1/-5)
• extensions/lobster/package.json (modified, +1/-1)
• extensions/matrix/SPEC-SUPPORT.md (added, +116/-0)
• extensions/matrix/package.json (modified, +1/-1)
• extensions/matrix/src/actions.account-propagation.test.ts (modified, +41/-0)
• extensions/matrix/src/actions.test.ts (modified, +26/-0)
• extensions/matrix/src/actions.ts (modified, +9/-4)

PR #64502: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64502

Description (problem / solution / changelog)

Purpose

This is the live non-draft umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

• core model-aware AGENTS selection
• sub-agent-specific AGENTS narrowing
• compaction/reinjection parity
• docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

• keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
• give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
• keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

This is not a benchmark claim about one model being universally better than another. It is a prompt-control feature: different models often respond better to different context density, output constraints, and task framing.

What Changed Across The Stack

• add schema-backed model-aware AGENTS file selection for both main and sub-agent runs
• support exact provider/model overrides for both base AGENTS files and narrowed sub-agent files
• resolve the effective AGENTS source after runtime model normalization
• preserve the same effective AGENTS source through continuation, compaction, retry, and reinjection
• document the feature in plain English, engineering terms, and migration scenarios from plugin-only SubAgent Context Limiter setups

Review Order

GitHub only allows upstream PRs to retarget branches that exist in openclaw/openclaw itself. Because these staging branches exist on the fork, the child PRs still target main upstream even though they form a logical stack.

Recommended review order:

1. #64263
2. #64264
3. #64265
4. this PR for the integrated final view

Helpful delta links:

• bootstrap -> parity: compare view
• parity -> docs: compare view
• docs -> umbrella: compare view

Mental Model

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Pick base AGENTS file for that role"]
    D --> E["Apply exact model override if configured"]
    E --> F["Apply bootstrap hooks and inject context"]
    F --> G["Reuse the same effective AGENTS source for continuation / compaction / reinjection"]

Scenarios

GPT-5.4 worker scenario

A team can keep a broad orchestrator file for a planning-oriented main agent, but give openai/gpt-5.4 workers a more explicit SUBAGENTS.gpt-5.4.md with shorter instructions, tighter scope, and stricter output expectations.

Opus / Claude orchestrator scenario

A team can keep anthropic/claude-opus-4-6 on a broader orchestration-oriented AGENTS variant that includes more planning context and delegation guidance, without forcing every worker model to carry that same context.

Security / least-privilege scenario

A sub-agent can start with SUBAGENTS.md instead of full AGENTS.md, and compaction will continue to reuse that narrowed source rather than silently broadening the worker's instructions later.

Child PRs

• #64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
  • core config, runtime model plumbing, bootstrap signature behavior
• #64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
  • compaction/post-compaction parity so narrowed worker AGENTS files stay narrowed
• #64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
  • plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

• main/orchestrator runs can use a model-specific AGENTS file
• sub-agents can use a different AGENTS base file than the main agent
• exact provider/model overrides work for both main and sub-agent runs
• invalid overrides warn and fall back safely
• continuation, compaction, and reinjection reuse the same effective AGENTS source
• docs explain the feature clearly for users and maintainers

Local Validation

• pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts
• pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
• pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
• pnpm build

Issue Tree

• Umbrella: #64248
• Reused upstream issue: #31070
• Child issue: #64246
• Child issue: #64247
• Related upstream issue: #46595
• Related upstream issue: #45413

Related Upstream Work

• Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
• PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

• .oxfmtrc.jsonc (modified, +2/-2)
• .oxlintrc.json (modified, +4/-5)
• CHANGELOG.md (modified, +46/-1)
• INCIDENT_RESPONSE.md (added, +52/-0)
• docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
• docs/concepts/qa-e2e-automation.md (modified, +4/-0)
• docs/concepts/system-prompt.md (modified, +35/-2)
• docs/gateway/cli-backends.md (modified, +8/-0)
• docs/gateway/configuration-reference.md (modified, +89/-4)
• docs/gateway/security/index.md (modified, +4/-4)
• docs/help/testing.md (modified, +4/-0)
• docs/plugins/manifest.md (modified, +25/-0)
• docs/reference/templates/AGENTS.md (modified, +0/-3)
• docs/tools/browser.md (modified, +2/-2)
• docs/tools/skills.md (modified, +7/-0)
• docs/tools/subagents.md (modified, +140/-1)
• extensions/acpx/package.json (modified, +1/-1)
• extensions/active-memory/index.test.ts (modified, +20/-20)
• extensions/amazon-bedrock/package.json (modified, +1/-1)
• extensions/anthropic/stream-wrappers.test.ts (modified, +5/-5)
• extensions/browser/index.test.ts (modified, +1/-1)
• extensions/browser/src/browser-tool.ts (modified, +1/-1)
• extensions/browser/src/browser/bridge-server.auth.test.ts (modified, +10/-1)
• extensions/browser/src/browser/bridge-server.ts (modified, +12/-7)
• extensions/browser/src/browser/cdp.helpers.test.ts (added, +65/-0)
• extensions/browser/src/browser/cdp.helpers.ts (modified, +59/-14)
• extensions/browser/src/browser/cdp.test.ts (modified, +23/-6)
• extensions/browser/src/browser/cdp.ts (modified, +2/-1)
• extensions/browser/src/browser/chrome-mcp.snapshot.ts (modified, +1/-1)
• extensions/browser/src/browser/chrome-mcp.ts (modified, +1/-1)
• extensions/browser/src/browser/chrome.test.ts (modified, +2/-2)
• extensions/browser/src/browser/chrome.ts (modified, +14/-6)
• extensions/browser/src/browser/client-actions-core.ts (modified, +2/-87)
• extensions/browser/src/browser/client-actions.types.ts (added, +87/-0)
• extensions/browser/src/browser/client-fetch.ts (modified, +14/-12)
• extensions/browser/src/browser/client.ts (modified, +2/-19)
• extensions/browser/src/browser/client.types.ts (added, +19/-0)
• extensions/browser/src/browser/config.test.ts (modified, +15/-4)
• extensions/browser/src/browser/config.ts (modified, +4/-4)
• extensions/browser/src/browser/errors.test.ts (modified, +26/-1)
• extensions/browser/src/browser/errors.ts (modified, +21/-1)
• extensions/browser/src/browser/form-fields.ts (modified, +1/-1)
• extensions/browser/src/browser/local-dispatch.runtime.ts (added, +20/-0)
• extensions/browser/src/browser/navigation-guard.test.ts (modified, +88/-0)
• extensions/browser/src/browser/navigation-guard.ts (modified, +40/-1)
• extensions/browser/src/browser/profiles-service.test.ts (modified, +3/-1)
• extensions/browser/src/browser/profiles-service.ts (modified, +5/-5)
• extensions/browser/src/browser/pw-session.create-page.navigation-guard.test.ts (modified, +51/-1)
• extensions/browser/src/browser/pw-session.ts (modified, +71/-13)
• extensions/browser/src/browser/pw-tools-core.interactions.navigation-guard.test.ts (modified, +563/-2)
• extensions/browser/src/browser/pw-tools-core.interactions.ts (modified, +132/-42)
• extensions/browser/src/browser/pw-tools-core.test-harness.ts (modified, +19/-0)
• extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts (added, +385/-0)
• extensions/browser/src/browser/routes/agent.act.normalize.ts (modified, +1/-1)
• extensions/browser/src/browser/routes/agent.act.ts (modified, +223/-63)
• extensions/browser/src/browser/routes/tabs.test.ts (added, +112/-0)
• extensions/browser/src/browser/routes/tabs.ts (modified, +6/-0)
• extensions/browser/src/browser/server-context.loopback-direct-ws.test.ts (modified, +22/-0)
• extensions/browser/src/browser/server-context.remote-profile-tab-ops.playwright.test.ts (modified, +45/-3)
• extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts (modified, +3/-3)
• extensions/browser/src/browser/server-context.selection.ts (modified, +17/-2)
• extensions/browser/src/browser/server-context.tab-ops.ts (modified, +31/-8)
• extensions/browser/src/browser/server-context.ts (modified, +1/-8)
• extensions/browser/src/browser/server-context.types.ts (modified, +1/-2)
• extensions/browser/src/browser/server-middleware.ts (modified, +16/-1)
• extensions/browser/src/browser/server.control-server.test-harness.ts (modified, +1/-0)
• extensions/device-pair/index.test.ts (modified, +1/-1)
• extensions/device-pair/openclaw.plugin.json (modified, +6/-0)
• extensions/diffs/assets/viewer-runtime.js (modified, +48/-48)
• extensions/diffs/package.json (modified, +1/-1)
• extensions/diffs/src/language-hints.ts (modified, +8/-1)
• extensions/diffs/src/viewer-payload.ts (modified, +4/-1)
• extensions/discord/package.json (modified, +1/-1)
• extensions/discord/src/monitor/thread-title.generate.test.ts (modified, +4/-4)
• extensions/discord/src/monitor/thread-title.ts (modified, +6/-1)
• extensions/discord/src/voice/manager.e2e.test.ts (modified, +3/-1)
• extensions/feishu/src/bot.broadcast.test.ts (modified, +4/-1)
• extensions/feishu/src/client.ts (modified, +46/-3)
• extensions/feishu/src/monitor.account.ts (modified, +12/-22)
• extensions/feishu/src/monitor.bot-menu.test.ts (modified, +1/-1)
• extensions/feishu/src/probe.test.ts (modified, +7/-6)
• extensions/feishu/src/probe.ts (modified, +15/-14)
• extensions/feishu/src/reply-dispatcher.test.ts (modified, +1/-1)
• extensions/feishu/src/sequential-key.test.ts (added, +72/-0)
• extensions/feishu/src/sequential-key.ts (added, +25/-0)
• extensions/feishu/src/sequential-queue.test.ts (added, +64/-0)
• extensions/feishu/src/sequential-queue.ts (added, +15/-0)
• extensions/feishu/src/streaming-card.ts (modified, +6/-1)
• extensions/feishu/src/tool-account-routing.test.ts (modified, +1/-1)
• extensions/github-copilot/stream.test.ts (modified, +3/-3)
• extensions/google/oauth.test.ts (modified, +20/-4)
• extensions/google/package.json (modified, +1/-1)
• extensions/google/video-generation-provider.test.ts (modified, +0/-4)
• extensions/imessage/src/media-contract.ts (modified, +1/-1)
• extensions/irc/src/channel.ts (modified, +1/-5)
• extensions/lobster/package.json (modified, +1/-1)
• extensions/matrix/SPEC-SUPPORT.md (added, +116/-0)
• extensions/matrix/package.json (modified, +1/-1)
• extensions/matrix/src/actions.account-propagation.test.ts (modified, +41/-0)
• extensions/matrix/src/actions.test.ts (modified, +26/-0)

PR #64504: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64504

Description (problem / solution / changelog)

Purpose

This is the umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

• core model-aware AGENTS selection
• sub-agent-specific AGENTS narrowing
• compaction/reinjection parity
• docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

• keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
• give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
• keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

This is not a benchmark claim about one model being universally better than another. It is a prompt-control feature: different models often respond better to different context density, output constraints, and task framing.

What Changed Across The Stack

• add schema-backed model-aware AGENTS file selection for both main and sub-agent runs
• support exact provider/model overrides for both base AGENTS files and narrowed sub-agent files
• resolve the effective AGENTS source after runtime model normalization
• preserve the same effective AGENTS source through continuation, compaction, retry, and reinjection
• document the feature in plain English, engineering terms, and migration scenarios from plugin-only SubAgent Context Limiter setups

Review Order

GitHub only allows upstream PRs to retarget branches that exist in openclaw/openclaw itself. Because these staging branches exist on the fork, the child PRs still target main upstream even though they form a logical stack.

Recommended review order:

1. #64263
2. #64264
3. #64265
4. this PR for the integrated final view

Helpful delta links:

• bootstrap -> parity: compare view
• parity -> docs: compare view
• docs -> umbrella: compare view

Mental Model

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Pick base AGENTS file for that role"]
    D --> E["Apply exact model override if configured"]
    E --> F["Apply bootstrap hooks and inject context"]
    F --> G["Reuse the same effective AGENTS source for continuation / compaction / reinjection"]

Scenarios

GPT-5.4 worker scenario

A team can keep a broad orchestrator file for a planning-oriented main agent, but give openai/gpt-5.4 workers a more explicit SUBAGENTS.gpt-5.4.md with shorter instructions, tighter scope, and stricter output expectations.

Opus / Claude orchestrator scenario

A team can keep anthropic/claude-opus-4-6 on a broader orchestration-oriented AGENTS variant that includes more planning context and delegation guidance, without forcing every worker model to carry that same context.

Security / least-privilege scenario

A sub-agent can start with SUBAGENTS.md instead of full AGENTS.md, and compaction will continue to reuse that narrowed source rather than silently broadening the worker's instructions later.

Child PRs

• #64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
  • core config, runtime model plumbing, bootstrap signature behavior
• #64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
  • compaction/post-compaction parity so narrowed worker AGENTS files stay narrowed
• #64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
  • plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

• main/orchestrator runs can use a model-specific AGENTS file
• sub-agents can use a different AGENTS base file than the main agent
• exact provider/model overrides work for both main and sub-agent runs
• invalid overrides warn and fall back safely
• continuation, compaction, and reinjection reuse the same effective AGENTS source
• docs explain the feature clearly for users and maintainers

Local Validation

• pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
• pnpm build

Issue Tree

• Umbrella: #64248
• Reused upstream issue: #31070
• Child issue: #64246
• Child issue: #64247
• Related upstream issue: #46595
• Related upstream issue: #45413

Related Upstream Work

• Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
• PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

• docs/concepts/system-prompt.md (modified, +35/-2)
• docs/gateway/configuration-reference.md (modified, +86/-1)
• docs/tools/subagents.md (modified, +140/-1)
• src/agents/agent-scope.ts (modified, +7/-0)
• src/agents/bootstrap-files.test.ts (modified, +397/-0)
• src/agents/bootstrap-files.ts (modified, +355/-9)
• src/agents/bootstrap-hooks.ts (modified, +4/-0)
• src/agents/cli-runner.spawn.test.ts (modified, +33/-1)
• src/agents/cli-runner.test-support.ts (modified, +8/-1)
• src/agents/cli-runner/prepare.ts (modified, +3/-0)
• src/agents/pi-embedded-runner/compact.ts (modified, +8/-0)
• src/agents/pi-embedded-runner/extensions.ts (modified, +11/-0)
• src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts (modified, +21/-5)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts (modified, +53/-2)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +54/-11)
• src/agents/pi-hooks/compaction-safeguard-runtime.ts (modified, +8/-0)
• src/agents/pi-hooks/compaction-safeguard.test.ts (modified, +96/-0)
• src/agents/pi-hooks/compaction-safeguard.ts (modified, +43/-22)
• src/agents/workspace.test.ts (modified, +39/-0)
• src/agents/workspace.ts (modified, +57/-14)
• src/auto-reply/reply/agent-runner-memory.ts (modified, +9/-0)
• src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts (modified, +80/-1)
• src/auto-reply/reply/agent-runner.ts (modified, +7/-2)
• src/auto-reply/reply/commands-compact.ts (modified, +1/-0)
• src/auto-reply/reply/post-compaction-context.test.ts (modified, +86/-0)
• src/auto-reply/reply/post-compaction-context.ts (modified, +52/-20)
• src/config/schema.base.generated.ts (modified, +114/-2)
• src/config/schema.help.ts (modified, +17/-1)
• src/config/schema.labels.ts (modified, +8/-0)
• src/config/types.agent-defaults.ts (modified, +33/-0)
• src/config/types.agents.ts (modified, +12/-1)
• src/config/zod-schema.agent-defaults.test.ts (modified, +17/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +3/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +7/-0)
• src/gateway/server-methods/sessions.ts (modified, +1/-0)
• src/hooks/internal-hooks.ts (modified, +2/-0)
• src/shared/avatar-policy.test.ts (modified, +1/-0)
• src/shared/avatar-policy.ts (modified, +4/-4)