Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Core: model-aware AGENTS/SUBAGENTS bootstrap selection [5 pull requests, 3 comments, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#64248•Fetched 2026-04-11 06:15:39
View on GitHub
Comments
3
Participants
1
Timeline
9
Reactions
0
Author
100yenadmin100yenadmin
Participants
100yenadmin100yenadmin
Timeline (top)
cross-referenced ×6commented ×3

This umbrella tracks upstreaming model-aware AGENTS/SUBAGENTS bootstrap selection into core OpenClaw.

Goal:

  • let main runs and subagent runs use different AGENTS-source files
  • let either path override that file by exact resolved model
  • keep orchestrator prompts broader while subagents receive narrowed AGENTS context by default
  • keep the effective AGENTS source stable across retries, compaction, and reinjection

This replaces the plugin-only SubAgentMD swap pattern with a core bootstrap feature.

Root Cause

Different models respond differently to prompt structure and context density. Users want to keep their core agent prompts intact while supplying model-optimized AGENTS variants and safer subagent-specific AGENTS files.

This is also a security / scope-control feature: subagents should not silently regain the full orchestrator AGENTS instructions after prompt refreshes.

Fix Action

Fixed

PR fix notes

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

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 #64264: fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection

Description (problem / solution / changelog)

Why

This PR keeps model-aware AGENTS selection intact after the first bootstrap pass.

Without this layer, sub-agents can start with a narrowed worker file such as SUBAGENTS.md, but later compaction or post-compaction refresh paths can silently fall back to the main workspace AGENTS.md. That breaks the least-privilege goal and makes model-specific tuning inconsistent over time.

What Changed

  • switch post-compaction reinjection to the same effective AGENTS source selected during bootstrap
  • switch compaction-safeguard summaries to the same effective AGENTS source
  • reuse already-loaded AGENTS content where possible instead of reopening the same file
  • thread the agent/session/model context needed to resolve the correct AGENTS source in compaction paths
  • keep sub-agent AGENTS narrowing intact after continuation, compaction, retry, and reinjection flows

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 2 of 3.

Recommended review path:

  1. review #64263 first
  2. then review the parity-only delta here: bootstrap -> parity compare
  3. then look at the compaction-specific files in this PR

Key files:

Acceptance Criteria

  • a sub-agent that starts with SUBAGENTS.md or SUBAGENTS.gpt-5.4.md keeps that effective AGENTS source after compaction
  • post-compaction refresh does not reread hardcoded workspace AGENTS.md
  • compaction-safeguard summary generation does not reread hardcoded workspace AGENTS.md
  • already-loaded AGENTS content is reused when available

Validation

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

Merge Order

This is PR 2 of 3.

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

After #64263 merges, GitHub will automatically shrink this PR down to the parity-only remainder.

Links

  • Closes #64246
  • Part of #64248
  • Related to #63216
  • Related to #25369
  • Related to #53706
  • 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-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, +45/-0)
  • src/agents/workspace.ts (modified, +60/-22)
  • 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 #64265: docs(agents): document model-aware AGENTS and SUBAGENTS migration

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

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

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:

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

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:

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)

Code Example

agents:
  defaults:
    agentsFile: AGENTS.md
    agentsFilesByModel:
      openai/gpt-5.4: AGENTS.gpt-5.4.md
    subagents:
      agentsFile: SUBAGENTS.md
      agentsFilesByModel:
        openai/gpt-5.4: SUBAGENTS.gpt-5.4.md
RAW_BUFFERClick to expand / collapse

Summary

This umbrella tracks upstreaming model-aware AGENTS/SUBAGENTS bootstrap selection into core OpenClaw.

Goal:

  • let main runs and subagent runs use different AGENTS-source files
  • let either path override that file by exact resolved model
  • keep orchestrator prompts broader while subagents receive narrowed AGENTS context by default
  • keep the effective AGENTS source stable across retries, compaction, and reinjection

This replaces the plugin-only SubAgentMD swap pattern with a core bootstrap feature.

Why this matters

Different models respond differently to prompt structure and context density. Users want to keep their core agent prompts intact while supplying model-optimized AGENTS variants and safer subagent-specific AGENTS files.

This is also a security / scope-control feature: subagents should not silently regain the full orchestrator AGENTS instructions after prompt refreshes.

Current review stack

  1. #64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
  2. #64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
  3. #64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
  4. #64504 feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

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, the child PRs still target main even though they form a logical stack.

Helpful compare views:

Task list

Child issues

  • Resolved-model bootstrap plumbing via existing issue #31070
  • Core config + docs / migration for model-aware AGENTS selection #64247
  • Effective AGENTS-source parity across compaction / retry / reinjection #64246
  • Related workspace-resolution issue #45413
  • Existing workspace-resolution context issue #46595

Child PRs

  • #64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
  • #64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
  • #64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration

Umbrella PR

  • #64504 feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection
  • #64266 closed/superseded after GitHub stopped reflecting the live umbrella branch head

Planned config shape

agents:
  defaults:
    agentsFile: AGENTS.md
    agentsFilesByModel:
      openai/gpt-5.4: AGENTS.gpt-5.4.md
    subagents:
      agentsFile: SUBAGENTS.md
      agentsFilesByModel:
        openai/gpt-5.4: SUBAGENTS.gpt-5.4.md

With matching overrides under agents.list[] and agents.list[].subagents.

Related upstream work

Issues

  • Related #31070
  • Related #46595
  • Related #45413
  • Related #50263
  • Related #22438
  • Related #50876
  • Related #59900
  • Related #63216
  • Related #56029

PRs

  • Related #62264
  • Related #42781
  • Related #44862
  • Related #39284
  • Related #31901
  • Related #9977
  • Related #22439
  • Related #53706
  • Related #29404

Scope notes

  • v1 focuses on standard embedded / CLI bootstrap flows
  • v1 does not redesign the full bootstrap allowlist for every workspace file
  • current upstream already gives subagents a reduced bootstrap allowlist broader than the old AGENTS.md + TOOLS.md shorthand implied; this stack narrows AGENTS exposure without redesigning every injected file
  • ACP parity can be tracked separately if needed once the core path lands

Investigation note

Issue #46595 appears to be already fixed on current upstream/main; it remains linked here as upstream context, but there is no separate workspace-resolution code delta in this stack.

extent analysis

TL;DR

The most likely fix involves configuring the agents section in the YAML file to correctly specify model-aware AGENTS file selection for main runs and subagent runs.

Guidance

  • Review the planned config shape in the YAML file to ensure it matches the desired AGENTS file selection behavior for main runs and subagent runs.
  • Verify that the agentsFilesByModel section is correctly configured to override the default agentsFile for specific models.
  • Check the subagents section to ensure it is correctly configured to use a different AGENTS file than the main run.
  • Test the configuration by running the application with different models and verifying that the correct AGENTS files are being used.

Example

agents:
  defaults:
    agentsFile: AGENTS.md
    agentsFilesByModel:
      openai/gpt-5.4: AGENTS.gpt-5.4.md
  subagents:
    agentsFile: SUBAGENTS.md
    agentsFilesByModel:
      openai/gpt-5.4: SUBAGENTS.gpt-5.4.md

Notes

The provided configuration shape and related issues suggest that the fix involves correctly configuring the agents section in the YAML file. However, without more information about the specific error or issue being encountered, it is difficult to provide a more detailed solution.

Recommendation

Apply the workaround by configuring the agents section in the YAML file to correctly specify model-aware AGENTS file selection for main runs and subagent runs. This should allow the application to use the correct AGENTS files for different models and subagents.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#response parsing#generation error#database connection#vector store#embedding generation

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING