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