openclaw - 💡(How to fix) Fix Per-agent bootstrap overrides + channel groupPolicy: schema/runtime/patch-CLI inconsistencies (5 gaps) [2 comments, 2 participants]

Summary

Five inconsistencies between the OpenClaw config schema, the runtime resolvers, and the openclaw config patch CLI in 2026.5.7. All five surfaced in sequence while implementing a per-role agent split (worker + coordinator). Per-agent bootstrap overrides are blocked or unreliable; channel groupPolicy/dmPolicy handling is inconsistent between validators; and one CLI write path silently drops fields it reports as applied.

These were caught with the standard --dry-run workflow, so nothing landed wrong, but the gaps blocked Phase 1 of the agent split until we worked around them. Documenting consolidated rather than filing five separate issues since they share a common shape.

Environment

• openclaw 2026.5.7 (commit eeef486)
• macOS 26.4 (arm64), Node 25.9.0
• Single-user install via npm/pnpm (/opt/homebrew/lib/node_modules/openclaw)
• Gateway: local loopback, LaunchAgent-supervised

Gap 1 — agents.list[].contextInjection silently no-ops

Schema: dist/zod-schema.agents.d.ts declares contextInjection on each agents.list[] item (alongside agents.defaults.contextInjection).

Resolver: dist/bootstrap-files-DsxWWYvi.js (resolver function resolveContextInjectionMode):

function resolveContextInjectionMode(config) {
  return config?.agents?.defaults?.contextInjection ?? "always";
}

Reads from agents.defaults only. The per-agent value validates against the schema but is never honored at runtime.

Repro:

1. Set agents.list[<some-agent>].contextInjection: "continuation-skip" via openclaw config patch.
2. openclaw config validate passes.
3. The agent's bootstrap is still injected on every turn — the per-agent value has no effect.

Suggested fix: Either honor per-agent value with fall-through to defaults, or remove contextInjection from the per-agent schema and document it as defaults-only.

Gap 2 — agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars silently no-op

Same pattern as Gap 1. Resolvers in dist/pi-embedded-helpers-Bk-yxMCZ.js:

function resolveBootstrapMaxChars(cfg) {
  const raw = cfg?.agents?.defaults?.bootstrapMaxChars;
  // ...
}
function resolveBootstrapTotalMaxChars(cfg) {
  const raw = cfg?.agents?.defaults?.bootstrapTotalMaxChars;
  // ...
}

Per-agent values are in the schema, validate fine, never honored.

Suggested fix: Same as Gap 1 — honor per-agent or remove from per-agent schema.

Gap 3 — agents.list[].skipBootstrap and skipOptionalBootstrapFiles not in per-agent schema

Schema: The per-agent items schema (agents.list[].properties) does NOT include skipBootstrap or skipOptionalBootstrapFiles. They exist only on agents.defaults.

Doc inconsistency: docs/gateway/config-agents.md examples reference per-agent override patterns in a way that implies skipBootstrap per-agent is supported. Users (and Anthropic-pattern agent architectures) reasonably expect to set this per-agent.

Repro:

1. openclaw config patch --replace-path agents.list --file <patch with agents.list[i].skipBootstrap: true>
2. Dry-run fails: agents.list.N: Unrecognized key: "skipBootstrap"

Impact: No way to slim bootstrap for one specialized agent (e.g. a stateless worker) without removing it from every agent including the primary chat agent.

Suggested fix: Add skipBootstrap and skipOptionalBootstrapFiles to the per-agent schema; have the resolver honor per-agent then fall through to defaults.

Gap 4 — config patch --dry-run rejects channels.discord.groupPolicy / telegram.dmPolicy / telegram.groupPolicy as required when zod schema marks them .optional()

Schema: All three fields are zod-.optional().default("allowlist").

Patch-CLI behavior: openclaw config patch --dry-run reports:

Error: Dry run failed: config schema validation failed.
- channels.discord.groupPolicy: must have required property 'groupPolicy'
- channels.telegram.dmPolicy:   must have required property 'dmPolicy'
- channels.telegram.groupPolicy: must have required property 'groupPolicy'

Runtime behavior: openclaw config validate correctly passes (these fields are optional at runtime).

The strict patch validator and the runtime validator disagree about the same schema.

Repro:

1. Live config has channels.discord and channels.telegram without these fields.
2. openclaw config validate → passes.
3. echo '{}' > /tmp/noop.json5 && openclaw config patch --file /tmp/noop.json5 --dry-run → fails on the three "required" fields.

Impact: All patch operations are blocked on a system that has been running fine for weeks. Forced us to use openclaw config set value-mode (which skips the strict validator) as a workaround, bypassing the dry-run safety gate for our actual changes.

Suggested fix: Align the patch-mode validator with the zod schema's .optional() declaration. Either fix the strict validator's interpretation, or share validator code between the two paths.

Gap 5 — config patch silently drops valid fields on apply while reporting them as successful updates

Observed: A patch containing four updates was reported as "4 updates applied" by openclaw config patch, but only 2 actually landed on disk:

• Landed: channels.telegram.dmPolicy, channels.telegram.allowFrom
• Silently dropped: channels.discord.groupPolicy, channels.telegram.groupPolicy

Both dropped values were "allowlist" strings (matching the schema enum). No error, no warning. Success message + missing writes.

Repro: Compose a patch that touches channels.discord.groupPolicy and channels.telegram.groupPolicy alongside other field updates. Apply via openclaw config patch. Compare on-disk config to the patch input — the groupPolicy values for both channels are missing while other updates landed.

Impact: This is the most concerning of the five. Success-message + dropped-writes is the worst combination of behaviors because operators have no signal to look more carefully. If we had assumed our patch worked, we would have continued building on an incorrect config state.

Suggested fix: Audit the patch-apply path for silent field-dropping logic. Either reject the patch with a clear error if a field can't be written, or warn explicitly about each dropped field.

Workaround used

For our Phase 1 worker-agent rollout we bypassed openclaw config patch entirely and used openclaw config set <path> <value> value-mode for each per-agent field. Value-mode explicitly skips strict schema validation per its --dry-run note ("value mode does not run schema/resolvability checks"), which let us write the worker entry's per-agent fields despite the Gap 4 blocker. The trade-off was losing the pre-write dry-run gate for our own changes; we used openclaw config validate + openclaw status post-write as the verification path instead.

This worked but isn't a robust pattern. Operators should be able to use config patch --dry-run to gate writes, and to trust that what config patch reports as applied actually landed.

Why this matters economically

We measured ~34% fresh-input token reduction for one worker invocation after applying just the per-agent levers that DO work (tools.profile: "minimal" + tools.alsoAllow + skills allowlist + skillsLimits/contextLimits). The schema-blocked levers (skipBootstrap per-agent, bootstrapTotalMaxChars per-agent, contextInjection: continuation-skip per-agent) would likely double those savings.

Per-agent bootstrap control is the architectural lever for the orchestrator/worker pattern that's becoming standard for multi-agent systems. The gaps above block that pattern in OpenClaw today.

Suggested priority

1. Gap 5 — silent field-drop on apply. Trust-breaking. Fix first.
2. Gap 4 — patch-CLI validator disagrees with zod schema. Blocks all patch workflows.
3. Gap 1 + Gap 2 — per-agent values in schema but ignored by resolver. Either honor or remove.
4. Gap 3 — add skipBootstrap to per-agent schema + resolver.

Happy to provide additional repro details, log snippets, or run validation tests if helpful. We have ~10 openclaw.json snapshots from today's work that demonstrate the various states across the five gaps.