Summary

OpenClaw splits workspace bootstrap files into "stable" (before OPENCLAW_CACHE_BOUNDARY) and "dynamic" (after) for Anthropic prompt cache optimization. Currently, only HEARTBEAT.md is classified as dynamic (DYNAMIC_CONTEXT_FILE_BASENAMES), and the injection order is hardcoded in CONTEXT_FILE_ORDER.

Operators who use additional workspace files (e.g., SESSION_HANDOFF.md, RECENT_SESSIONS.md, STATE.md) that change frequently have no way to:

1. Mark them as dynamic so they go after the cache boundary
2. Control the injection order for cache-prefix stability

Proposal

Option A: Config-based dynamic file list

{
  "agents": {
    "defaults": {
      "bootstrapDynamicFiles": ["SESSION_HANDOFF.md", "RECENT_SESSIONS.md"]
    }
  }
}

Files listed here would be added to DYNAMIC_CONTEXT_FILE_BASENAMES at runtime, placing them after the cache boundary.

Option B: Full injection order control

{
  "agents": {
    "defaults": {
      "bootstrapFileOrder": [
        "SOUL.md", "IDENTITY.md", "USER.md", "TOOLS.md",
        "AGENTS.md", "MEMORY.md", "BOOTSTRAP.md"
      ],
      "bootstrapDynamicFiles": ["HEARTBEAT.md", "SESSION_HANDOFF.md"]
    }
  }
}

Why this matters

With cacheRetention: "long", the stable prefix of the system prompt gets cached at 90% discount on Anthropic. Frequently-changing files that land before the boundary invalidate the cache on every change, causing full-price re-reads of the entire prefix. For deployments with large bootstrap contexts (50K+ chars), this can mean $10-30/month in unnecessary cache invalidation costs.

Current behavior (source refs)

• CONTEXT_FILE_ORDER: hardcoded Map in system-prompt-*.js (AGENTS=10, SOUL=20, IDENTITY=30, USER=40, TOOLS=50, BOOTSTRAP=60, MEMORY=70)
• DYNAMIC_CONTEXT_FILE_BASENAMES: hardcoded Set containing only heartbeat.md
• isDynamicContextFile(): checks membership in the above set
• Files not in CONTEXT_FILE_ORDER get MAX_SAFE_INTEGER priority (alphabetical tiebreak), placed before cache boundary as stable

Environment

• OpenClaw v2026.4.11
• Anthropic Claude Opus 4.6 with cacheRetention: "long"
• 10 workspace bootstrap files totaling ~24KB after optimization