Summary

The gateway silently truncates workspace bootstrap files (like HEARTBEAT.md) to 899 characters when injecting them into heartbeat context. This limit is undocumented and not configurable, leading to heartbeat agents silently losing most of their instructions.

Problem

I had a detailed HEARTBEAT.md (6343 chars) with 23 rotating health checks, thresholds, alert escalation rules, and state tracking. The gateway truncated it to 899 chars — the heartbeat agent only ever saw the first ~15 lines (a philosophy header), never the actual check instructions.

Gateway log showed the warning, but it's easy to miss:
\
[agent/embedded] workspace bootstrap file HEARTBEAT.md is 6343 chars (limit 899); truncating in injected context
\\

This means the heartbeat was essentially running blind for days. All the detailed rotating checks, thresholds, and escalation rules were invisible to the agent.

Impact

• Heartbeat agents silently receive incomplete instructions
• Users have no obvious way to discover the limit (no docs, no CLI warning)
• Detailed heartbeat configurations are silently broken

Suggestions

1. Document the limit — mention the 899-char limit in the docs for HEARTBEAT.md / workspace bootstrap files
2. Make it configurable — e.g. \�gents.defaults.heartbeat.maxBootstrapChars\ in config
3. Louder warning — surface the truncation warning in \openclaw status\ or \openclaw doctor\
4. Support references — allow HEARTBEAT.md to contain a pointer like \Read scripts/heartbeat-instructions.md\ (which the agent can resolve via the read tool) — this is the workaround I'm using now

Workaround

Trimmed HEARTBEAT.md to 515 chars with a pointer to the full instructions file:
\\markdown

HEARTBEAT — Quick Reference

Start: Read scripts/heartbeat-instructions.md for full instructions.

Always: session_status, session size >3.8MB, temp >85C

Rotate: 1 check per heartbeat from instructions.md

\\

Environment

• OpenClaw 2026.2.14
• Windows 10
• 23-item rotating heartbeat configuration