OpenClaw Optimization

Appearance

Light Context Mode ​

Config: lightContext: true on cron jobs and heartbeats
CLI: --light-context flag on openclaw cron add / openclaw cron edit
Area: Token cost reduction / Bootstrap optimization

What It Does ​

Light context mode skips the injection of workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, MEMORY.md) into the session's system prompt.

Normal mode (default): Every cron run and heartbeat gets the full workspace file set injected — often 10,000–15,000+ tokens before the agent processes a single word of the actual task.

Light context mode: The bootstrap payload is empty for cron jobs, or limited to only HEARTBEAT.md for heartbeat runs.

What gets injected ​

FileNormal modeLight context (cron)Light context (heartbeat)
AGENTS.md✅❌❌
SOUL.md✅❌❌
TOOLS.md✅❌❌
IDENTITY.md✅❌❌
USER.md✅❌❌
MEMORY.md✅❌❌
HEARTBEAT.md✅❌✅
System prompt (runtime)✅✅✅
Cron message/prompt✅✅✅

The runtime system prompt (tool definitions, model instructions, available skills list) is still injected — light context only strips the workspace files.

When to Use It ​

Light context is safe when the cron prompt is self-contained — it provides all the instructions the agent needs without relying on AGENTS.md, SOUL.md, or TOOLS.md for behavioral guidance.

Good candidates ​

  • Script runners — crons that execute a specific script and report the result. The prompt says exactly what to run and how to report. No personality, no standing orders, no memory needed.
  • Stateless monitors — check an API endpoint, compare against a threshold, alert if exceeded. All logic is in the prompt.
  • Dispatch-only executors — read a queue (GitHub issues, etc.), spawn subagents for each item, exit. The executor doesn't need to know who it "is" — it just needs to follow the dispatch instructions.
  • Data collection crons — fetch data, format it, write to a file or post to a channel. No judgment, no personality, no prior context needed.
  • Simple relay crons — check an inbox, forward new items to a channel. Mechanical task with no decision-making.

Bad candidates ​

  • Governance / judgment tasks — voting on proposals, writing forum comments, evaluating opportunities. These need SOUL.md for voice and AGENTS.md for decision frameworks.
  • Interactive-style crons — anything that should "feel like" the agent (morning briefings, social media engagement). Personality requires SOUL.md.
  • Crons that reference standing orders — if the prompt assumes knowledge of rules in AGENTS.md (e.g., "follow the circuit breaker protocol"), light context strips those rules.
  • Memory-dependent tasks — anything that needs MEMORY.md for prior context (e.g., "check if this was already handled").
  • Heartbeats with complex checklists — if HEARTBEAT.md references patterns or rules that live in other bootstrap files, light context breaks the references. (Note: heartbeats in light mode still get HEARTBEAT.md.)

Configuration ​

Cron jobs (isolated agentTurn) ​

json
{
  "name": "check-api-health",
  "schedule": { "kind": "cron", "expr": "*/15 * * * *" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Run `curl -s https://api.example.com/health` and report the status. If non-200, post to #alerts. Otherwise return NO_REPLY.",
    "model": "anthropic/claude-sonnet-4-6",
    "lightContext": true
  },
  "delivery": { "mode": "announce", "channel": "discord", "to": "channel:123456" }
}

Heartbeats ​

json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        lightContext: true,  // only HEARTBEAT.md injected
        target: "last"
      }
    }
  }
}

CLI ​

bash
# Add a new cron with light context
openclaw cron add \
  --name "health-check" \
  --cron "*/15 * * * *" \
  --session isolated \
  --message "Check API health..." \
  --light-context

# Enable light context on an existing cron
openclaw cron edit <job-id> --light-context

Cost Impact ​

Bootstrap files are typically 10,000–15,000 tokens. With prompt caching, cached input tokens are cheaper but still counted. Light context eliminates this entirely.

Example savings at scale:

ScenarioRuns/dayBootstrap tokens/runDaily token savings
15-min health check96~12,000~1,152,000 input tokens
Hourly executor24~12,000~288,000 input tokens
30-min heartbeat48~12,000~576,000 input tokens

Even with prompt caching reducing effective cost, eliminating unnecessary context frees up the context window for actual task processing and reduces the risk of attention dilution on the real instructions.

Tradeoffs ​

BenefitRisk
Significant token savings per runAgent has no personality, standing orders, or memory
Cleaner context = better instruction followingPrompt must be completely self-contained
Faster model response (less to process)Can't reference rules from AGENTS.md
Lower risk of attention dilutionAgent won't follow workspace conventions (NO_REPLY patterns, etc.)

Key insight: Light context shifts the burden of instruction from workspace files to the cron prompt itself. If the prompt doesn't say "return NO_REPLY when there's nothing to report," the agent won't know to do that — even if AGENTS.md says it.

Migration Checklist ​

Before enabling light context on an existing cron:

  • [ ] Read the cron prompt end-to-end. Does it reference any behavior defined in AGENTS.md, SOUL.md, or TOOLS.md?
  • [ ] Does the prompt explicitly define the output format (NO_REPLY for no-ops, alert format, etc.)?
  • [ ] Does the prompt include all necessary context (API endpoints, thresholds, channel targets)?
  • [ ] Is the task mechanical (script execution, data fetch, relay) or judgment-based (evaluation, voting, engagement)?
  • [ ] Run the cron once with lightContext: true and verify output quality matches expectations

TIP

When migrating, the safest approach is to copy behavioral instructions that the cron depends on (like the NO_REPLY contract) directly into the cron prompt, rather than hoping they'll be inherited from workspace files.

Built with OpenClaw 🤖