openclaw - 💡(How to fix) Fix Configurable Workspace File Load Order in System Prompt Assembly [1 participants]

Summary

Allow users to configure the injection order of workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) into the system prompt via config/default.json or per-agent config.

Problem to solve

OpenClaw hardcodes AGENTS.md as the first workspace file injected into the system prompt context (confirmed in resolveBootstrapContextForRun()). There is no configuration option to reorder file injection.

This matters because of a well-documented phenomenon in LLM attention patterns. Liu et al. (2023), "Lost in the Middle: How Language Models Use Long Contexts" (TACL, arXiv:2307.03172), demonstrated that language models exhibit a U-shaped attention curve: tokens at the beginning and end of the context window receive significantly stronger attention than those in the middle. This was confirmed across GPT-4, Claude, Gemini, and LongChat architectures. Subsequent research — including Anthropic's own context engineering documentation (2025) and Breunig & Sriraman (2026) — confirms the pattern persists in current-generation models.

For agents where persona and identity are critical to output quality, placing SOUL.md at position zero in the system prompt would give identity content the strongest possible attention weight. Currently, AGENTS.md occupies that position, pushing identity tokens into a weaker attention zone.

Proposed solution

Proposed Solution

A config option to specify load order:

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

Or per-agent:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "bootstrapFileOrder": ["SOUL.md", "AGENTS.md", "TOOLS.md"]
      }
    ]
  }
}

Default behavior remains unchanged (AGENTS.md first) for backward compatibility. Files not listed in the array fall back to current default ordering.

Implementation Notes

The change is in resolveBootstrapContextForRun() — the function that assembles contextFiles for injection. Instead of a hardcoded file list, it reads the configured order and falls back to the current default when no config is present.

This is a low-risk, backward-compatible change. Existing users see no difference. Users who care about prompt architecture get control over the single most impactful variable in their agent's output quality.

Related Issues

• #9491 — Configurable Bootstrap Files (adding files, not reordering; closed)
• #56110 — Add STATE.md to auto-loaded workspace bootstrap files
• #7928 — Documented discrepancies in bootstrap file list vs. source

Research References

• Liu et al. (2023), "Lost in the Middle: How Language Models Use Long Contexts," TACL. arXiv:2307.03172
• Anthropic, "Context Engineering Guide" (2025)
• Breunig & Sriraman, "How Long Contexts Fail" (2026)
• Zhang et al. (2025), ACE Framework. arXiv:2510.04618

Alternatives considered

Current Workaround

Users merge SOUL.md content directly into AGENTS.md to get identity tokens into the primacy position. This works but creates dual-source-of-truth maintenance problems, requires sync scripts, and defeats the purpose of having separate workspace files.

Impact

Affected: all users Severity: strictly limits usage compared to optimal file-load organization Frequency: all loads across all openclaw users Consequence: Suboptimal soul.md loads causes degradation in output quality compared to user expectations

Evidence/examples

No response

Additional information

No response