Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix feat: allow subagents to load USER.md (shared user context for multi-agent setups) [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#53614•Fetched 2026-04-08 01:25:44
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
JackyCufeJackyCufe
Participants
JackyCufeJackyCufe

Fix Action

Fix / Workaround

Current workaround

Code Example

{
  "agents": {
    "defaults": {
      "loadUserMd": true
    }
  }
}
RAW_BUFFERClick to expand / collapse

Problem

When using multi-agent setups, USER.md is not loaded for subagent sessions. Per the docs:

Sub-agent context only injects AGENTS.md + TOOLS.md (no SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, or BOOTSTRAP.md)

This means each subagent has no knowledge of the user — their goals, preferences, or current priorities — unless the parent agent explicitly passes that context in the task description.

Real-world impact

I run 9 specialized agents (coding, social, research, trading, etc.) under OpenClaw. When I make a decision in one agent's session (e.g., "pausing project X, shifting focus to project Y"), other agents have no way to know unless I manually repeat it to each one.

Related: #9618 (cross-agent memory read allowlist) addresses the memory layer, but the simpler problem is that USER.md — which already exists for this purpose — is silently skipped for subagents.

Current workaround

I created workspace/shared/USER_CONTEXT.md and added a rule in AGENTS.md for every agent to read it at startup. This works but:

  • Relies on prompt-layer convention, not framework support
  • Requires manual rule injection into every agent's AGENTS.md
  • New agents won't have it unless explicitly configured

Proposed solution

Option A (minimal, no breaking change): Load USER.md for subagents by default.

Option B (opt-in config, safest):

{
  "agents": {
    "defaults": {
      "loadUserMd": true
    }
  }
}

Option B preserves existing behavior and lets users opt in. The USER.md file is already designed for this purpose ("Who the user is and how to address them") — it's unclear why subagents should be excluded from this context.

Environment

  • OpenClaw: 2026.3.13
  • macOS arm64
  • 9-agent setup with separate workspaces per agent

extent analysis

Fix Plan

To address the issue of USER.md not being loaded for subagent sessions, we will implement Option B (opt-in config). This approach preserves existing behavior and allows users to opt-in to loading USER.md for subagents.

Steps to Implement the Fix

  • Update the configuration file to include the loadUserMd option:
{
  "agents": {
    "defaults": {
      "loadUserMd": true
    }
  }
}
  • Modify the agent initialization code to check for the loadUserMd option and load USER.md if enabled:
import json

# Load configuration
with open('config.json') as f:
    config = json.load(f)

# Check if loadUserMd is enabled
if config.get('agents', {}).get('defaults', {}).get('loadUserMd', False):
    # Load USER.md for subagents
    with open('USER.md') as f:
        user_context = f.read()
    # Inject user context into subagent session
    # ... (implementation details depend on the specific framework)
  • Update the AGENTS.md file to remove any manual rules for loading USER.md, as this will now be handled by the framework.

Verification

To verify that the fix worked, create a new subagent session and check if the USER.md context is available. You can do this by:

  • Checking the subagent's logs for any errors or warnings related to loading USER.md
  • Verifying that the subagent's behavior reflects the user's goals, preferences, and priorities as defined in USER.md

Extra Tips

  • Make sure to update the documentation to reflect the new loadUserMd option and its behavior.
  • Consider adding a warning or error message if USER.md is not found or cannot be loaded, to help users troubleshoot any issues.

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…
#tool integration#LLM response#prompt template#agent execution#agent setup

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix feat: allow subagents to load USER.md (shared user context for multi-agent setups) [1 participants]