PR #75212: feat(agents): add minimal bootstrap tier

• Repository: openclaw/openclaw
• Author: sahilsatralkar
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75212

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: Default workspace bootstrap context can stay large for constrained loopback local models, and existing doctor checks only warned near configured truncation limits.
• Why it matters: Small/local tool-calling models can degrade under prompt pressure even when bootstrap files are technically under the global character budgets.
• What changed: Added agents.defaults.bootstrapTier with standard default and opt-in minimal, plus a doctor warning for loopback local models with large bootstrap context.
• What did NOT change (scope boundary): Did not lower global bootstrap budgets, change default behavior, rewrite templates, alter provider/tool-call parsing, or add per-agent bootstrap profiles.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #75189
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Bootstrap file injection had only size-budget controls, not a file-selection profile for constrained local models.
• Missing detection / guardrail: Doctor warned on truncation/near-limit only, so large but under-budget bootstrap context on loopback local models was not surfaced.
• Contributing context (if known): localModelLean reduced heavyweight tools, but did not reduce always-injected workspace bootstrap files.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
  • Target test or file: src/agents/workspace.test.ts, src/agents/bootstrap-files.test.ts, src/commands/doctor-bootstrap-size.test.ts
  • Scenario the test should lock in: standard preserves existing bootstrap behavior, minimal filters ordinary-session bootstrap files, and doctor warns only for large loopback local-model bootstrap context.
  • Why this is the smallest reliable guardrail: The issue is deterministic at config/filtering and doctor-analysis seams; no live model call is required to prove the new control and warning.
  • Existing test that already covers this (if any): Existing workspace tests covered standard subagent/cron filtering and full ordinary-session injection.
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

• New config: agents.defaults.bootstrapTier
  • standard default: preserves current behavior.
  • minimal: injects only AGENTS.md, TOOLS.md, IDENTITY.md, USER.md, and BOOTSTRAP.md for ordinary sessions.
• Doctor can now warn when a loopback local model has large bootstrap context and recommend bootstrapTier: "minimal".

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

  Before:
  [loopback local model + large bootstrap] -> [under global budget] -> [no doctor guidance]

  After:
  [loopback local model + large bootstrap] -> [doctor warning] -> [operator can set bootstrapTier=minimal]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local dev machine
• Runtime/container: Node 22 / local repo checkout
• Model/provider: No live model used; config-level loopback provider covered by tests
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.bootstrapTier, loopback models.providers.<id>.baseUrl

Steps

1. Configure a loopback local model as the primary model.
2. Use a workspace with large bootstrap context under the global truncation limits.
3. Run doctor/bootstrap-size analysis.

Expected

• Doctor recommends agents.defaults.bootstrapTier: "minimal" for loopback local-model prompt pressure.
• standard keeps existing bootstrap behavior.
• minimal reduces ordinary-session bootstrap injection.

Actual

• Implemented and covered by targeted tests.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • bootstrapTier schema accepts minimal and standard, rejects unknown values.
  • standard preserves ordinary-session bootstrap behavior.
  • minimal filters ordinary-session bootstrap files to the expected set.
  • BOOTSTRAP.md prompt-prefix helper behavior remains covered.
  • Doctor warns for large loopback local-model bootstrap context and stays silent for hosted models or minimal.
• Edge cases checked:
  • Missing bootstrapTier resolves to standard.
  • Unknown runtime tier value falls back to standard.
  • Hosted provider with large bootstrap context does not get the local-model warning.
• What you did not verify:
  • Live vLLM/Hermes reproduction from #75189.
  • Blacksmith/Testbox pnpm check:changed was not run.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? Yes
• Migration needed? No
• If yes, exact upgrade steps: Optional only. Constrained local-model users can set agents.defaults.bootstrapTier to "minimal".

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: Minimal bootstrap may omit persona, heartbeat, or memory context some users expect.
  • Mitigation: standard remains the default; minimal is opt-in and doctor only recommends it for loopback local-model prompt pressure.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/.generated/config-baseline.sha256 (modified, +2/-2)
• docs/concepts/experimental-features.md (modified, +4/-0)
• docs/concepts/system-prompt.md (modified, +5/-0)
• docs/gateway/config-agents.md (modified, +16/-0)
• docs/gateway/doctor.md (modified, +1/-1)
• docs/gateway/local-models.md (modified, +5/-1)
• src/agents/bootstrap-files.test.ts (modified, +26/-0)
• src/agents/bootstrap-files.ts (modified, +6/-1)
• src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts (modified, +23/-0)
• src/agents/pi-embedded-helpers.ts (modified, +2/-0)
• src/agents/pi-embedded-helpers/bootstrap.ts (modified, +6/-0)
• src/agents/workspace.test.ts (modified, +29/-0)
• src/agents/workspace.ts (modified, +15/-2)
• src/commands/doctor-bootstrap-size.test.ts (modified, +94/-0)
• src/commands/doctor-bootstrap-size.ts (modified, +101/-0)
• src/config/schema.base.generated.ts (modified, +20/-0)
• src/config/schema.help.ts (modified, +2/-0)
• src/config/schema.labels.ts (modified, +1/-0)
• src/config/types.agent-defaults.ts (modified, +4/-2)
• src/config/zod-schema.agent-defaults.test.ts (modified, +11/-0)
• src/config/zod-schema.agent-defaults.ts (modified, +2/-3)

PR #75248: fix(agents): reorder workspace AGENTS.md template to put load-bearing rules first

• Repository: openclaw/openclaw
• Author: lonexreb
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75248

Description (problem / solution / changelog)

Bug being fixed

Closes #75187

The auto-generated docs/reference/templates/AGENTS.md (used by the workspace bootstrap to seed ~/.openclaw/workspace/AGENTS.md) ordered content with personality/onboarding guidance at the top and the load-bearing ## Red Lines, ## External vs Internal, and ## Tools guidance at the bottom.

When a user lowers agents.defaults.bootstrapMaxChars (typical for small/mid local models — Hermes-3 8B, Qwen3 8B — to fit a tight context budget), bootstrap-budget head-truncates the file. With the old order, that stripped exactly the safety + tool-dispatch rules the model needed, while preserving the less operationally-critical Memory/Group Chats/Heartbeats sections. The reporter's vLLM repro showed 0 structured tool_call events vs. 1 successful structured tool call after manually rewriting AGENTS.md to put tool-use guidance at the top — same model, same parser, same bootstrapMaxChars, content order was the only difference.

Fix

Reorder docs/reference/templates/AGENTS.md so the section sequence is:

1. First Run
2. Session Startup
3. Red Lines (was #4)
4. External vs Internal (was #5)
5. Tools (was #7)
6. Memory (was #3)
7. Group Chats (was #6)
8. Heartbeats (was #8)
9. Make It Yours

Section content is unchanged byte-for-byte — only the H2 ordering moves. Path #1 ("Quickest win — reorder the auto-generated AGENTS.md template content") in the issue's recommended resolution order.

This aligns the seeded workspace template with the existing post-compaction priority contract: agents.defaults.compactionAgentsMdReinjectionSections already names Session Startup and Red Lines as the priority sections to re-inject after compaction. Putting them at the top of the seeded file means head-truncation now matches that same priority instead of fighting it.

Why this is the best fix

• Smallest blast radius: a docs-only template content change. No runtime, schema, or budget logic touched.
• Existing users: their already-customized AGENTS.md files are not rewritten; this only affects newly-seeded workspaces (and openclaw doctor --fix --regenerate-bootstrap-files flows when applicable).
• Doesn't preempt larger work: orthogonal to #75189 (verbose default content) and #22438 / #22439 (tiered bootstrap loading); paths #2 and #3 in the issue's recommended order remain valid future work on top of this base fix.
• Aligns with existing contract: matches the post-compaction reinjection priority in agents.defaults.compactionAgentsMdReinjectionSections.

Test plan

• pnpm test src/agents/workspace-templates.test.ts — 4 new regression tests pass (Red Lines / External vs Internal / Tools all assert ahead of Memory + Group Chats; First Run / Session Startup stay at the top).
• pnpm test src/agents/workspace.test.ts src/agents/system-prompt-stability.test.ts — 25 + 4 existing tests pass.
• pnpm exec oxfmt --check — clean.
• pnpm tsgo:core + pnpm tsgo:core:test — clean.
• Lint (pnpm lint:core) failure on oxlint config is pre-existing on origin/main (Rule 'no-underscore-dangle' not found in plugin 'eslint'), unrelated to this PR.

https://github.com/openclaw/openclaw/issues/75187

Changed files

• docs/reference/templates/AGENTS.md (modified, +17/-33)
• src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts (modified, +36/-0)
• src/agents/workspace-templates.test.ts (modified, +50/-0)