#20493: feat(agents): add compaction model override for compaction runs

## Summary Describe the problem and fix in 2–5 bullets: - Problem: compaction always used the session model, so users could not route compaction to a cheaper configured model. - Why it matters: auto/manual compaction can add avoidable cost on premium session models. - What changed: added `agents.defaults.compaction.model` config + validation, added compaction model selection/auth fallback helper, wired compaction runtime to use selected effective model, and documented the new field. - What did NOT change (scope boundary): compaction prompt content/flow/threshold logic and the existing hard-fail behavior when the session model itself cannot resolve/authenticate. ## Change Type (select all) - [ ] Bug fix - [x] Feature - [ ] Refactor - [x] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [x] Gateway / orchestration - [x] Skills / tool execution - [x] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [x] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes openclaw/openclaw#7926 - Closes openclaw/openclaw#15826 - Closes openclaw/openclaw#17461 - Closes openclaw/openclaw#19501 - Related openclaw/openclaw#15927 ## User-visible / Behavior Changes - New optional config: `agents.defaults.compaction.model`. - Accepted format: `provider/model` or configured alias from `agents.defaults.models`. - If override resolves + authenticates, compaction runs on override model and logs: - `[compaction] using override model <provider/model> (session model: <provider/model>)` - If override is invalid/unconfigured/unresolvable/unauthenticated, compaction logs warning and falls back to session model. - If `compaction.model` is unset, behavior is unchanged. ## Security Impact (required) - New permissions/capabilities? (`Yes/No`) No - Secrets/tokens handling changed? (`Yes/No`) No (reuses existing `getApiKeyForModel()` path) - New/changed network calls? (`Yes/No`) No new external surfaces; uses existing provider auth/model calls - Command/tool execution surface changed? (`Yes/No`) No - Data access scope changed? (`Yes/No`) No - If any `Yes`, explain risk + mitigation: ## Repro + Verification ### Environment - OS: macOS 26.3 (Build 25D125) - Runtime/container: Node v25.6.0, pnpm 10.23.0, Bun 1.3.9 - Model/provider: compaction selection tests cover alias/provider-model/session-provider combinations - Integration/channel (if any): N/A - Relevant config (redacted): - `agents.defaults.models` includes target model key/alias - `agents.defaults.compaction.model` set to alias or `provider/model` ### Steps 1. Configure `agents.defaults.compaction.model` to a configured alias or `provider/model` in `agents.defaults.models`. 2. Trigger compaction path (`/compact` or auto-compaction overflow). 3. Observe compaction model-selection logs and resulting compaction behavior. ### Expected - Override model used when valid + authenticated. - Session model fallback when override fails selection/auth. ### Actual - Matches expected; override and fallback paths verified with focused tests and local checks. ## Evidence Attach at least one: - [ ] Failing test/log before + passing after - [x] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) Trace/log snippet covered by tests: - `[compaction] using override model anthropic/claude-sonnet-4-6 (session model: anthropic/claude-opus-4-6)` - Fallback warnings include reason and session target. ## Human Verification (required) What you personally verified (not just CI), and how: - Verified scenarios: - `pnpm check` - `pnpm protocol:check` - `pnpm build` - `pnpm check:docs` - `pnpm canvas:a2ui:bundle && bunx vitest run --config vitest.unit.config.ts` - `CLAWDBOT_INSTALL_URL=https://openclaw.ai/install.sh CLAWDBOT_INSTALL_CLI_URL=https://openclaw.ai/install-cli.sh CLAWDBOT_NO_ONBOARD=1 CLAWDBOT_INSTALL_SMOKE_SKIP_CLI=1 CLAWDBOT_INSTALL_SMOKE_SKIP_NONROOT=1 CLAWDBOT_INSTALL_SMOKE_SKIP_PREVIOUS=1 pnpm test:install:smoke` - Edge cases checked: - unset override - alias override - explicit provider/model override - override not in configured catalog - override resolve failure - override auth failure - different-provider override auth-profile behavior - What you did **not** verify: - Windows CI lane execution in local Windows environment ## Compatibility / Migration - Backward compatible? (`Yes/No`) Yes - Config/env changes? (`Yes/No`) Yes (new optional config key) - Migration needed? (`Yes/No`) No - If yes, exact upgrade steps: ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: - Remove/unset `agents.defaults.compaction.model` to restore session-model compaction behavior. - Files/config to restore: - Config: remove `agents.defaults.compaction.model` - Known bad symptoms reviewers should watch for: - Override configured but always warning/falling back due to model catalog mismatch or auth mismatch. ## Risks and Mitigations List only real risks for this PR. Add/remove entries as needed. If none, write `None`. - Risk: misconfigured/providerless override strings unexpectedly ignored. - Mitigation: strict validation + explicit warning logs + fallback to session model. - Risk: cross-provider override could accidentally force wrong auth profile. - Mitigation: same-provider keeps session profile; different-provider resolves auth without locking to session profile. ## Original Prompt (verbatim) ```text Implement a compaction.model config override for OpenClaw so auto-compaction can use a different (cheaper) model than the session's primary model. ## What to change 1. **Config schema** (types.ts or wherever CompactionConfig is defined): - Add optional model?: string field to the compaction config (format: "provider/model" or alias) - Example: agents.defaults.compaction.model: "anthropic/claude-sonnet-4-6" 2. **Compaction runner** (compact.ts): - In compactEmbeddedPiSessionDirect(), check if config.agents.defaults.compaction.model is set - If set, resolve that model (using the existing resolveModel() helper) instead of using the session's params.provider/params.model - The resolved model needs a valid API key — use the same getApiKeyForModel() path - Fall back to the session model if the compaction model fails to resolve or authenticate 3. **Config reference docs** (configuration-reference.md): - Document the new compaction.model field under agents.defaults.compaction - Note: format is "provider/model" or a configured alias 4. **Logging**: Log which model is being used for compaction so users can verify it's working: [compaction] using override model anthropic/claude-sonnet-4-6 (session model: anthropic/claude-opus-4-6) ## Key files - compact.ts — main compaction logic - model.ts — resolveModel() - src/config/ — config types and validation - configuration-reference.md — docs ## Constraints - When compaction.model is unset, behavior is unchanged (use session model) - The compaction model must be in the configured model catalog (agents.defaults.models) - Auth resolution should use the same profile as the session unless the model requires a different provider - Don't change the compaction prompt/logic itself, only which model runs it Closes openclaw/openclaw#7926, #15826, #17461, #19501 ``` ## Original Codex Plan (verbatim) ```text ## Compaction model override (`agents.defaults.compaction.model`) ### Summary Add a new optional config field so compaction can run on a cheaper model, while preserving current behavior when unset. The compaction runner will try the override model first, require it to map to configured catalog entries, authenticate via existing auth resolution, and gracefully fall back to the session model if override resolution/auth fails. ### Public interface/type changes 1. Update `/Users/pasta/workspace/openclaw/src/config/types.agent-defaults.ts`: - Add `model?: string` to `AgentCompactionConfig`. - Docstring: accepts `provider/model` or configured alias. 2. Update `/Users/pasta/workspace/openclaw/src/config/zod-schema.agent-defaults.ts`: - Add `model: z.string().optional()` under `agents.defaults.compaction`. 3. Update docs in `/Users/pasta/workspace/openclaw/docs/gateway/configuration-reference.md`: - Add `model` in the `agents.defaults.compaction` example. - Add bullet describing accepted format (`provider/model` or alias from configured models). ### Runtime implementation plan 1. In `/Users/pasta/workspace/openclaw/src/agents/pi-embedded-runner/compact.ts`, introduce a small model-selection/auth block before the existing compaction session setup: - Keep `sessionProvider/sessionModel` from `params.provider` + `params.model`. - Read `compaction.model` override from config. - Resolve override model ref using existing model-selection helpers (alias support + normalized provider/model). - Enforce “must be in `agents.defaults.models`” by checking resolved key against configured model keys. - If override passes validation: - Call existing `resolveModel()` for override provider/model. - Authenticate via existing `getApiKeyForModel()` path. - Profile behavior: - Same provider as session: reuse `params.authProfileId`. - Different provider: use provider-specific auth resolution (no locked session profile). - On success, use this override model/provider/modelId for the rest of compaction run. - On any override resolve/auth failure, log fallback reason and continue with session model path. - If session model resolution/auth fails, preserve current hard-fail behavior. 2. Ensure all downstream compaction runtime uses the selected effective model variables: - Tool creation metadata (`modelProvider`, `modelId`, auth mode). - Runtime info/system prompt metadata. - Transcript policy and sanitization provider/model arguments. - Extension/runtime guards relying on provider/model. 3. Keep compaction prompt logic unchanged: - No changes to compaction instructions, summariza...