Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Feature: support per-agent compaction overrides [2 pull requests, 2 comments, 2 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#69985•Fetched 2026-04-23 07:30:42
View on GitHub
Comments
2
Participants
2
Timeline
4
Reactions
0
Author
scottgl9scottgl9
Participants
rafiki270rafiki270scottgl9scottgl9
Timeline (top)
commented ×2cross-referenced ×2

Support per-agent compaction overrides, including agent-specific customInstructions.

Root Cause

Alternatives considered

  • Keep compaction instructions global-only: simpler, but too coarse for mixed-agent deployments.
  • Add a separate customCompactionInstructions field on agents instead of a full compaction block: smaller schema change, but inconsistent and less extensible.
  • Override compaction only in prompt/system prompt logic: weaker because the runtime compaction pipeline still needs structured config resolution.

Fix Action

Fix / Workaround

The current workaround is to choose one global instruction set that is "good enough" for every agent, which is lossy and makes compaction less trustworthy for specialized agents.

PR fix notes

PR #69987: feat(config): support per-agent compaction overrides

Description (problem / solution / changelog)

Summary

  • Problem: compaction overrides were supported only at agents.defaults.compaction, so all agents had to share the same compaction instructions and runtime settings.
  • Why it matters: specialized agents need different compaction guidance to preserve the right context during long-running sessions.
  • What changed: added optional agents.list[].compaction support, merged it over defaults, and threaded effective per-agent compaction config through embedded runtime compaction paths.
  • What did NOT change (scope boundary): default-only behavior remains unchanged when per-agent overrides are omitted; this PR does not redesign the broader config resolution model beyond compaction.

Change Type (select all)

  • Feature
  • Refactor required for the fix

Scope (select all touched areas)

  • Gateway / orchestration
  • API / contracts
  • UI / DX

Linked Issue/PR

  • Closes #69985
  • Related #
  • This PR fixes a bug or regression

Root Cause (if applicable)

  • Root cause: compaction config existed only on the agent defaults surface, and runtime compaction paths read only agents.defaults.compaction.
  • Missing detection / guardrail: there was no config/runtime path for agent-scoped compaction resolution.
  • Contributing context (if known): upstream already had a mature compaction config shape, so the missing behavior was override placement and runtime wiring rather than compaction capability itself.

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:
    • src/agents/agent-scope.test.ts
    • src/agents/pi-settings.test.ts
    • src/agents/pi-embedded-runner/extensions.test.ts
  • Scenario the test should lock in:
    • per-agent compaction config merges over defaults
    • per-agent customInstructions wins over default customInstructions
    • runtime compaction setup consumes the effective agent-specific config
  • Why this is the smallest reliable guardrail:
    • these tests cover both config resolution and the embedded runtime handoff where compaction instructions are actually consumed
  • Existing test that already covers this (if any): config schema and runtime-config suites cover the broader config surface
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

  • OpenClaw now accepts optional agents.list[].compaction entries.
  • Per-agent compaction fields inherit from agents.defaults.compaction and override defaults when set.
  • agents.list[].compaction.customInstructions now lets each agent provide its own compaction guidance.

Diagram (if applicable)

Before:
[agent run] -> [agents.defaults.compaction only] -> [shared compaction behavior for every agent]

After:
[agent run] -> [agents.list[].compaction if present] -> [fallback to agents.defaults.compaction] -> [agent-specific compaction behavior]

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)
  • If any Yes, explain risk + mitigation:

Repro + Verification

Environment

  • OS: Linux
  • Runtime/container: local OpenClaw dev environment
  • Model/provider: N/A (config/runtime path change)
  • Integration/channel (if any): N/A
  • Relevant config (redacted): multi-agent config with agents.defaults.compaction plus agents.list[].compaction

Steps

  1. Configure agents.defaults.compaction.customInstructions.
  2. Add agents.list[].compaction.customInstructions for a specific agent.
  3. Run config validation and embedded compaction/runtime tests.

Expected

  • Config validates.
  • Effective compaction settings for that agent use the per-agent override.
  • Other agents continue inheriting defaults.

Actual

  • Verified locally.

Evidence

Attach at least one:

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

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

  • Verified scenarios:
    • staged typecheck/lint/import-cycle guards passed
    • generated schema baseline updated and validated
    • runtime-config and agents test suites passed in the changed-file gate
    • per-agent compaction merge and runtime precedence covered by added tests
  • Edge cases checked:
    • per-agent override with inherited default fields
    • no per-agent override preserves prior defaults-only behavior
    • shared schema extraction did not leave runtime import cycles
  • What you did not verify:
    • manual end-to-end interactive compaction against a live chat session

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)
  • Config/env changes? (No)
  • Migration needed? (No)
  • If yes, exact upgrade steps:

Risks and Mitigations

  • Risk: per-agent compaction schema could drift from defaults compaction schema over time.
    • Mitigation: this PR extracts the shared compaction schema into a dedicated config schema module and reuses it in both places.
  • Risk: runtime compaction paths could accidentally keep reading defaults-only config.
    • Mitigation: this PR threads agentId through the affected embedded runtime setup paths and adds tests around the effective runtime behavior.

Changed files

  • .github/workflows/ci-check-testbox.yml (modified, +2/-2)
  • src/agents/agent-scope-config.ts (modified, +6/-0)
  • src/agents/agent-scope.test.ts (modified, +28/-0)
  • src/agents/pi-embedded-runner/compact.ts (modified, +3/-0)
  • src/agents/pi-embedded-runner/compact.types.ts (modified, +1/-0)
  • src/agents/pi-embedded-runner/extensions.test.ts (modified, +38/-3)
  • src/agents/pi-embedded-runner/extensions.ts (modified, +11/-4)
  • src/agents/pi-embedded-runner/run/attempt.ts (modified, +3/-0)
  • src/agents/pi-project-settings.ts (modified, +2/-0)
  • src/agents/pi-settings.test.ts (modified, +35/-0)
  • src/agents/pi-settings.ts (modified, +19/-4)
  • src/config/schema.base.generated.ts (modified, +147/-0)
  • src/config/types.agents.ts (modified, +3/-0)
  • src/config/zod-schema.agent-compaction.ts (added, +50/-0)
  • src/config/zod-schema.agent-defaults.ts (modified, +2/-47)
  • src/config/zod-schema.agent-runtime.ts (modified, +2/-0)

PR #69988: feat(config): support per-agent compaction overrides

Description (problem / solution / changelog)

Summary

  • Problem: compaction overrides were supported only at agents.defaults.compaction, so all agents had to share the same compaction instructions and runtime settings.
  • Why it matters: specialized agents need different compaction guidance to preserve the right context during long-running sessions.
  • What changed: added optional agents.list[].compaction support, merged it over defaults, and threaded effective per-agent compaction config through embedded runtime compaction paths.
  • What did NOT change (scope boundary): default-only behavior remains unchanged when per-agent overrides are omitted; this PR does not redesign the broader config resolution model beyond compaction.

Change Type (select all)

  • Feature
  • Refactor required for the fix

Scope (select all touched areas)

  • Gateway / orchestration
  • API / contracts
  • UI / DX

Linked Issue/PR

  • Closes #69985
  • Related #69987
  • This PR fixes a bug or regression

Root Cause (if applicable)

  • Root cause: compaction config existed only on the agent defaults surface, and runtime compaction paths read only agents.defaults.compaction.
  • Missing detection / guardrail: there was no config/runtime path for agent-scoped compaction resolution.
  • Contributing context (if known): upstream already had a mature compaction config shape, so the missing behavior was override placement and runtime wiring rather than compaction capability itself.

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:
    • src/agents/agent-scope.test.ts
    • src/agents/pi-settings.test.ts
    • src/agents/pi-embedded-runner/extensions.test.ts
  • Scenario the test should lock in:
    • per-agent compaction config merges over defaults
    • per-agent customInstructions wins over default customInstructions
    • runtime compaction setup consumes the effective agent-specific config
  • Why this is the smallest reliable guardrail:
    • these tests cover both config resolution and the embedded runtime handoff where compaction instructions are actually consumed
  • Existing test that already covers this (if any): config schema and runtime-config suites cover the broader config surface
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

  • OpenClaw now accepts optional agents.list[].compaction entries.
  • Per-agent compaction fields inherit from agents.defaults.compaction and override defaults when set.
  • agents.list[].compaction.customInstructions now lets each agent provide its own compaction guidance.

Diagram (if applicable)

Before:
[agent run] -> [agents.defaults.compaction only] -> [shared compaction behavior for every agent]

After:
[agent run] -> [agents.list[].compaction if present] -> [fallback to agents.defaults.compaction] -> [agent-specific compaction behavior]

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)
  • If any Yes, explain risk + mitigation:

Repro + Verification

Environment

  • OS: Linux
  • Runtime/container: local OpenClaw dev environment
  • Model/provider: N/A (config/runtime path change)
  • Integration/channel (if any): N/A
  • Relevant config (redacted): multi-agent config with agents.defaults.compaction plus agents.list[].compaction

Steps

  1. Configure agents.defaults.compaction.customInstructions.
  2. Add agents.list[].compaction.customInstructions for a specific agent.
  3. Run config validation and embedded compaction/runtime tests.

Expected

  • Config validates.
  • Effective compaction settings for that agent use the per-agent override.
  • Other agents continue inheriting defaults.

Actual

  • Verified locally.

Evidence

Attach at least one:

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

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

  • Verified scenarios:
    • staged typecheck/lint/import-cycle guards passed
    • generated schema baseline updated and validated
    • runtime-config and agents test suites passed in the changed-file gate
    • per-agent compaction merge and runtime precedence covered by added tests
  • Edge cases checked:
    • per-agent override with inherited default fields
    • no per-agent override preserves prior defaults-only behavior
    • shared schema extraction did not leave runtime import cycles
  • What you did not verify:
    • manual end-to-end interactive compaction against a live chat session

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)
  • Config/env changes? (No)
  • Migration needed? (No)
  • If yes, exact upgrade steps:

Risks and Mitigations

  • Risk: per-agent compaction schema could drift from defaults compaction schema over time.
    • Mitigation: this PR extracts the shared compaction schema into a dedicated config schema module and reuses it in both places.
  • Risk: runtime compaction paths could accidentally keep reading defaults-only config.
    • Mitigation: this PR threads agentId through the affected embedded runtime setup paths and adds tests around the effective runtime behavior.

Changed files

  • src/agents/agent-scope-config.ts (modified, +25/-0)
  • src/agents/agent-scope.test.ts (modified, +28/-0)
  • src/agents/pi-embedded-runner/compact.ts (modified, +4/-0)
  • src/agents/pi-embedded-runner/compact.types.ts (modified, +1/-0)
  • src/agents/pi-embedded-runner/extensions.test.ts (modified, +38/-3)
  • src/agents/pi-embedded-runner/extensions.ts (modified, +12/-4)
  • src/agents/pi-embedded-runner/run/attempt.ts (modified, +3/-0)
  • src/agents/pi-project-settings.ts (modified, +2/-0)
  • src/agents/pi-settings.test.ts (modified, +35/-0)
  • src/agents/pi-settings.ts (modified, +22/-4)
  • src/config/schema.base.generated.ts (modified, +135/-0)
  • src/config/types.agents.ts (modified, +3/-0)
  • src/config/zod-schema.agent-compaction.ts (added, +49/-0)
  • src/config/zod-schema.agent-defaults.ts (modified, +2/-47)
  • src/config/zod-schema.agent-runtime.ts (modified, +2/-0)

Code Example

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "customInstructions": "Preserve durable decisions."
      }
    },
    "list": [
      {
        "id": "general-agent",
        "compaction": {
          "customInstructions": "Preserve OpenClaw config decisions, agent wiring, and unresolved infra blockers."
        }
      }
    ]
  }
}
RAW_BUFFERClick to expand / collapse

Summary

Support per-agent compaction overrides, including agent-specific customInstructions.

Problem to solve

Today OpenClaw supports compaction instructions only at agents.defaults.compaction.*. That means all agents inherit the same compaction behavior even when they have very different summarization needs. In practice, infrastructure, personal, work, and research agents often need different compaction guidance to preserve the right details during long-running sessions.

The current workaround is to choose one global instruction set that is "good enough" for every agent, which is lossy and makes compaction less trustworthy for specialized agents.

Proposed solution

Add optional per-agent compaction overrides at agents.list[].compaction, using the same shape as agents.defaults.compaction.

Desired behavior:

  • agents.defaults.compaction remains the global default.
  • agents.list[].compaction becomes an optional override layer.
  • Per-agent customInstructions should override the default value for that agent.
  • Other compaction fields should inherit from defaults when omitted and override defaults when provided.
  • Embedded runtime compaction paths should resolve the effective compaction config using agent-specific values first, then defaults.

Example:

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "customInstructions": "Preserve durable decisions."
      }
    },
    "list": [
      {
        "id": "general-agent",
        "compaction": {
          "customInstructions": "Preserve OpenClaw config decisions, agent wiring, and unresolved infra blockers."
        }
      }
    ]
  }
}

Alternatives considered

  • Keep compaction instructions global-only: simpler, but too coarse for mixed-agent deployments.
  • Add a separate customCompactionInstructions field on agents instead of a full compaction block: smaller schema change, but inconsistent and less extensible.
  • Override compaction only in prompt/system prompt logic: weaker because the runtime compaction pipeline still needs structured config resolution.

Impact

Affected: multi-agent OpenClaw users running specialized agents with different compaction needs Severity: medium Frequency: common in multi-agent setups and long-running sessions Consequence: lower compaction fidelity, more manual prompt compromise, and loss of agent-specific important context during summarization

Evidence/examples

  • Upstream already supports agents.defaults.compaction.customInstructions, so the missing piece is per-agent override support.
  • Multi-agent installs often separate work/personal/infra/research agents with distinct memory and summarization priorities.

Additional information

This should remain backward-compatible:

  • existing configs using only agents.defaults.compaction should behave exactly as before
  • agents.list[].compaction should be entirely optional

extent analysis

TL;DR

To support per-agent compaction overrides, add an optional compaction block to each agent in agents.list[] with the same shape as agents.defaults.compaction, allowing for agent-specific overrides of compaction instructions.

Guidance

  • Introduce a new compaction field in the agents.list[] schema to store per-agent compaction overrides, ensuring it has the same structure as agents.defaults.compaction.
  • Update the compaction resolution logic to prioritize agent-specific compaction values over global defaults when resolving the effective compaction configuration.
  • Ensure that the customInstructions field within each agent's compaction block overrides the default value for that agent, while other compaction fields inherit from defaults when omitted.
  • Verify that existing configurations using only agents.defaults.compaction remain unaffected and behave as before, maintaining backward compatibility.

Example

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "customInstructions": "Preserve durable decisions."
      }
    },
    "list": [
      {
        "id": "general-agent",
        "compaction": {
          "customInstructions": "Preserve OpenClaw config decisions, agent wiring, and unresolved infra blockers."
        }
      },
      {
        "id": "research-agent",
        "compaction": {
          "mode": "preserve",
          "customInstructions": "Keep all research-related data."
        }
      }
    ]
  }
}

Notes

The introduction of per-agent compaction overrides should improve compaction fidelity in multi-agent setups by allowing for more tailored summarization behaviors. However, careful testing is necessary to ensure that the new logic correctly resolves effective compaction configurations and maintains backward compatibility.

Recommendation

Apply the proposed solution by adding optional per-agent compaction overrides, as it provides a flexible and extensible way to manage compaction behaviors across different agents without compromising the simplicity of the global default configuration.

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…
#api#ssr#vector store#embedding generation#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