PR #43908: fix(config): expose heartbeat lightContext and other options in config help

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/43908

Description (problem / solution / changelog)

Summary

• Problem: In src/config/schema.help.ts and src/config/schema.labels.ts, multiple heartbeat configuration options (such as lightContext, includeReasoning, every, activeHours, etc.) were missing. While fully implemented in the Zod schema and runtime runner, they were invisible to users via /config help or autocomplete.
• Why it matters: Users could not discover these options, leading to confusion. Specifically for lightContext, users mistakenly placed lightContext: true directly in HEARTBEAT.md instead of openclaw.json, resulting in unbounded context growth and excessive API credit consumption. This is a high-impact regression (Fixes #43767).
• What changed:
  • src/config/schema.help.ts: Added missing agents.defaults.heartbeat.*, agents.list.*.heartbeat.*, and agents.list[].heartbeat.* options.
  • Comprehensive Audit: Aligned all 15 heartbeat fields across all three variants (defaults, list.*, list[]) to ensure 100% parity.
  • Operational Guidance: Added critical edge-case documentation based on bot reviews:
    • Documented every: "0m" as the correct path to disable heartbeats, alongside a warning about the default agent's fallback behavior.
    • Added warnings that to and accountId are only read when target is set.
    • Added a warning that heartbeat.session is ignored when session.scope is global.
    • Added a security note to includeReasoning.
  • Removed the static help text for heartbeat.target to allow dynamic channel list generation via applyHeartbeatTargetHints.
  • src/config/schema.labels.ts: Added all corresponding UI labels to satisfy the keeps labels in parity for all help keys quality test.
• What did NOT change: The runtime logic in heartbeat-runner.ts and the schema definitions in zod-schema.agent-runtime.ts remain completely untouched.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Config / Schema

Linked Issue/PR

Fixes #43767

Test Plan

• Verified all schema.help.quality.test.ts tests pass (including label parity and operational guidance checks).
• Verified schema.test.ts passes (specifically fixing the adds heartbeat target hints with dynamic channels test by removing static help text).
• Verified vitest run src/config/ passes completely.
• Verified vitest run src/infra/heartbeat-runner passes to ensure no runtime regressions.
• Verified vitest run src/cron/ passes to ensure no cron scheduling regressions.

AI-Assisted Contribution

• AI Usage: This PR was developed with AI assistance.
• Human Review: I have personally reviewed, designed, and fully understand all the code changes.
• Testing: Fully tested locally with my OpenClaw instance.
• Prompt Context: The AI was instructed to perform a deep root-cause analysis of the heartbeat visibility issue, implement the initial fix, and then perform a comprehensive audit across all three schema variants (defaults, list.*, list[]) to address all bot review feedback (Codex & Greptile), ensuring 100% documentation parity and accurate edge-case warnings without touching runtime logic.

Changed files

• src/config/schema.help.ts (modified, +83/-0)
• src/config/schema.labels.ts (modified, +41/-0)

PR #46634: Heartbeat: add isolatedSession option for fresh session per heartbeat run

• Repository: openclaw/openclaw
• Author: odysseus0
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/46634

Description (problem / solution / changelog)

Summary

• Problem: Heartbeat runs accumulate turns in the main session. Over time (hours/days), the full conversation history is re-sent to the LLM on every heartbeat tick, burning ~100K tokens per run.
• Why it matters: Users running frequent heartbeats (every 5–60 min) face massive token costs and eventual context window exhaustion, with no built-in escape hatch.
• What changed: Added heartbeat.isolatedSession boolean config option. When true, each heartbeat run gets a fresh session (no prior conversation history) using the existing resolveCronSession pattern with forceNew. Reduces per-heartbeat token cost from ~100K to ~2-5K tokens.
• What did NOT change (scope boundary): Delivery routing still uses the main session's lastChannel/lastTo. The main session transcript is untouched. Default behavior (isolatedSession: false) is unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #20011
• Related #20649
• Related #7957
• Related #21597
• Related #43767

User-visible / Behavior Changes

• New config key: heartbeat.isolatedSession (boolean, default false).
• When enabled, heartbeat runs use a fresh <sessionKey>:heartbeat session each time (no prior conversation history).
• Combine with lightContext: true for maximum token savings.
• Docs updated: docs/gateway/heartbeat.md, docs/gateway/configuration-reference.md.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Bun/Node 22
• Model/provider: Any
• Relevant config (redacted):

agents:
  defaults:
    heartbeat:
      every: "5m"
      target: "last"
      isolatedSession: true
      lightContext: true

Steps

1. Set heartbeat.isolatedSession: true in config
2. Run heartbeat (or wait for scheduled tick)
3. Observe session key used in heartbeat run

Expected

• Heartbeat uses <sessionKey>:heartbeat (fresh, no history)
• Token usage ~2-5K per run

Actual

• Confirmed via test: isolated session key is <sessionKey>:heartbeat
• Non-isolated run uses original <sessionKey> (unchanged default)

Evidence

• Failing test/log before + passing after
• Two new tests: "uses isolated session key when isolatedSession is enabled" and "uses main session key when isolatedSession is not set"

Human Verification (required)

• Verified scenarios: Both tests pass, existing heartbeat tests still pass
• Edge cases checked: Default behavior unchanged when isolatedSession not set; delivery routing still reads main session for lastChannel/lastTo
• What you did not verify: Live multi-day heartbeat run with real provider

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? New optional isolatedSession key (default false)
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert: Set isolatedSession: false or omit the key
• Known bad symptoms: heartbeat using wrong session key, delivery routing failing

Risks and Mitigations

• Risk: Isolated session discards all prior heartbeat context; heartbeat prompt must be self-contained.
  • Mitigation: This is the intended behavior — matches cron sessionTarget: "isolated" semantics. Documented in config reference and heartbeat docs.

Changed files

• docs/.generated/config-baseline.json (modified, +22/-2)
• docs/.generated/config-baseline.jsonl (modified, +5/-3)
• docs/gateway/configuration-reference.md (modified, +2/-0)
• docs/gateway/heartbeat.md (modified, +12/-4)
• src/config/legacy.migrations.part-3.ts (modified, +1/-0)
• src/config/types.agent-defaults.ts (modified, +7/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +1/-0)
• src/infra/heartbeat-runner.model-override.test.ts (modified, +68/-0)
• src/infra/heartbeat-runner.ts (modified, +30/-4)

PR #57136: fix(heartbeat): clear sessionFile on new isolated session to prevent context accumulation

• Repository: openclaw/openclaw
• Author: lubao515
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/57136

Description (problem / solution / changelog)

Problem

When isolatedSession: true is configured for heartbeats, resolveCronSession is called with forceNew: true and correctly generates a new sessionId (UUID) on every heartbeat tick.

However, the new session entry was spread from the prior entry (...entry), which preserved the old sessionFile path from the previous run.

resolveSessionFilePath has this logic:

function resolveSessionFilePath(sessionId, entry, opts) {
  const candidate = entry?.sessionFile?.trim();
  if (candidate) return resolvePathWithinSessionsDir(...);  // prefers entry.sessionFile!
  return resolveSessionTranscriptPathInDir(sessionId, sessionsDir);  // only fallback
}

So every heartbeat continued appending to the same old transcript file, even though a new sessionId was assigned. This caused unbounded context growth that eventually triggered model fallbacks and failed heartbeat runs — despite isolatedSession: true being set.

Observed: context grew from ~18K tokens to 190K+ tokens over 24 hours, causing repeated Gemini API errors and fallback to backup models.

Fix

Clear sessionFile when isNewSession is true, so resolveSessionFilePath falls through to derive a fresh path from the new sessionId.

...(isNewSession && { sessionFile: undefined }),

This is analogous to the existing cleanup of lastChannel, lastTo, deliveryContext, etc. that was already done on new session rollover.

Testing

• Verified locally with isolatedSession: true + 1h heartbeat interval: each heartbeat now creates a new <uuid>.jsonl transcript file, starting at ~18K tokens instead of inheriting prior session history.
• Existing session.test.ts passes.

Related

Fixes #43767

Changed files

• src/cron/isolated-agent/session.ts (modified, +1/-0)

PR #60776: fix: pass bootstrapContextMode/RunKind to runEmbeddedAttempt

• Repository: openclaw/openclaw
• Author: domage
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/60776

Description (problem / solution / changelog)

Summary

• Problem: lightContext: true on cron jobs had no effect — all 5 workspace bootstrap files were still injected into the LLM system prompt, inflating the token usage from.
• Why it matters: lightContext exists specifically to reduce cost and latency for simple automated cron jobs that don't need workspace context. It was completely non-functional.
• What changed: Added 2 lines in pi-embedded-runner/run.ts to pass bootstrapContextMode and bootstrapContextRunKind from params through to the runEmbeddedAttempt() call. These fields were already defined on the params type and consumed by the attempt function — they just were never wired at the call site.
• What did NOT change (scope boundary): No changes to bootstrap resolution logic, cron gateway, system prompt building, or session/config handling. The filter logic was already correct — only the plumbing was missing.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related: lightContext support for cron jobs
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: runEmbeddedPiAgent() in pi-embedded-runner/run.ts manually enumerates every field when calling runEmbeddedAttempt() (~80 fields). When bootstrapContextMode and bootstrapContextRunKind were added to RunEmbeddedPiAgentParams, they were wired into the compaction paths but not the primary runEmbeddedAttempt() call. The attempt function received undefined for both, causing applyContextModeFilter() to default to "full".
• Missing detection / guardrail: No test verifies that runEmbeddedPiAgent propagates bootstrap context fields to the attempt. The explicit field-by-field call pattern (vs. spreading) makes omissions silent — TypeScript won't flag a missing optional field.
• Contributing context: The field-by-field destructuring pattern across ~80 fields in the call site makes it easy to miss new additions during review.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: pi-embedded-runner/run.test.ts or equivalent
• Scenario the test should lock in: When runEmbeddedPiAgent is called with bootstrapContextMode: "lightweight" and bootstrapContextRunKind: "cron", the inner runEmbeddedAttempt call must receive those same values (not undefined).
• Why this is the smallest reliable guardrail: A seam test that spies on the attempt call params catches the plumbing bug without needing a full LLM round-trip.
• If no new test is added, why not: This PR is a minimal hotfix. A follow-up test PR is recommended.

User-visible / Behavior Changes

Cron jobs with lightContext: true in their agentTurn payload now correctly skip workspace bootstrap file injection. Observed impact on a real cron job:

• injectedWorkspaceFiles: 5 → 0
• projectContextChars: 12,304 → 0
• totalTokens: ~16–19k → ~4.5k

Diagram (if applicable)

Before:
  cron gateway (bootstrapContextMode: "lightweight")
    -> runEmbeddedPiAgent(params)
      -> runEmbeddedAttempt({...80 fields...})  // bootstrapContextMode: undefined
        -> resolveBootstrapContextForRun(contextMode: undefined)  // defaults to "full"
          -> returns 5 workspace files

After:
  cron gateway (bootstrapContextMode: "lightweight")
    -> runEmbeddedPiAgent(params)
      -> runEmbeddedAttempt({...80 fields + 2 new...})  // bootstrapContextMode: "lightweight"
        -> resolveBootstrapContextForRun(contextMode: "lightweight")
          -> returns []

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux 6.17.0-1009-oracle (Ubuntu)
• Runtime/container: Node.js, OpenClaw v2026.3.28
• Model/provider: google/gemini-2.5-flash
• Integration/channel: Cron (isolated session, Telegram delivery)
• Relevant config: jobs.json entry with payload.lightContext: true

Steps

1. Configure a cron job with lightContext: true in the agentTurn payload
2. Wait for or trigger the cron run
3. Inspect the session JSONL — check first system message for "# Project Context" section and token count

Expected

• No "# Project Context" section in system prompt
• injectedWorkspaceFiles: [], projectContextChars: 0
• Total tokens ~4–5k (prompt-only, no bootstrap overhead)

Actual

• "# Project Context" with 5 files injected
• projectContextChars: 12304, total tokens 16–19k

Evidence

Attach at least one:

• Trace/log snippets

Before fix (session from earlier cron runs):

projectContextChars = 12304
injectedWorkspaceFiles = 5
totalTokens = 16k–19k+

After fix (session 4dd55883-bc95-4ce8-a205-33c145821c97.jsonl):

projectContextChars = 0
injectedWorkspaceFiles = []
systemPrompt.chars = 11006
totalTokens = 4548

Fix was verified by patching the minified production bundle (pi-embedded-BYdcxQ5A.js:39742) at runtime, restarting the gateway, and observing the next cron execution

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Live cron run with lightContext: true on production gateway after hot-patching the bundled JS. Confirmed zero injected workspace files and ~75% token reduction.
• Edge cases checked: Confirmed the bootstrap filter logic itself (applyContextModeFilter) was already correct for all three run kinds (default/heartbeat/cron) — only the passthrough was missing.
• What I did NOT verify: Other callers of runEmbeddedPiAgent (auto-reply, memory flush, followup runner) — those have separate call sites with their own field enumeration and may have similar omissions for different fields.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — adds two previously-omitted optional fields to an internal function call. No config, API, or schema changes.

Changed files

• src/agents/pi-embedded-runner/run.overflow-compaction.test.ts (modified, +18/-0)
• src/agents/pi-embedded-runner/run.ts (modified, +2/-0)