Summary

• Problem: messages.queue.byChannel.matrix was rejected by config validation even though Matrix is an active OpenClaw channel.
• Why it matters: Matrix deployments could not tune inbound queue behavior independently from the global queue mode.
• What changed: Added matrix to the queue by-channel runtime schema and exported queue provider type, kept googlechat/mattermost schema/type drift aligned, and added regression coverage for validation and schema lookup.
• What did NOT change (scope boundary): This does not relax the schema into an arbitrary provider record; unknown provider keys still fail validation.

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

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

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Matrix-specific queue overrides now validate under messages.queue.byChannel.
• Real environment tested: local OpenClaw checkout on macOS, Node v24.15.0, pnpm v10.33.2.
• Exact steps or command run after this patch:

node --import tsx - <<'NODE'
import { validateConfigObject } from './src/config/validation.ts';
import { buildConfigSchema, lookupConfigSchema } from './src/config/schema.ts';
for (const [name, cfg] of Object.entries({
  matrixSteer: { messages: { queue: { byChannel: { matrix: 'steer' } } } },
  matrixInterrupt: { messages: { queue: { byChannel: { matrix: 'interrupt' } } } },
  googlechat: { messages: { queue: { byChannel: { googlechat: 'queue' } } } },
  mattermost: { messages: { queue: { byChannel: { mattermost: 'queue' } } } },
  unknown: { messages: { queue: { byChannel: { unknown: 'queue' } } } },
})) {
  const r = validateConfigObject(cfg);
  console.log(name, r.ok, r.ok ? '' : r.issues.map((i) => `${i.path}: ${i.message}`).join(' | '));
}
const lookup = lookupConfigSchema(buildConfigSchema(), 'messages.queue.byChannel');
console.log('lookup_has_matrix', lookup?.children.some((child) => child.key === 'matrix'));
NODE

• Evidence after fix:

matrixSteer true
matrixInterrupt true
googlechat true
mattermost true
unknown false messages.queue.byChannel: Unrecognized key: "unknown"
lookup_has_matrix true

• Observed result after fix: Matrix queue overrides validate, schema lookup lists Matrix, and unknown provider keys remain rejected.
• What was not tested: A live Matrix inbound message queue flow; this PR is limited to config schema/type acceptance.
• Before evidence (optional but encouraged): The same config shape failed validation before this change with messages.queue.byChannel: Unrecognized key: "matrix".

Root Cause (if applicable)

• Root cause: The queue by-channel schema was a closed object and did not include Matrix even though Matrix is a supported channel.
• Missing detection / guardrail: There was no regression test asserting Matrix queue overrides validate or that schema lookup lists Matrix.
• Contributing context (if known): The exported queue provider type and runtime schema had already drifted (googlechat vs mattermost), so this PR also aligns those keys while keeping the fix focused.

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/config/config.schema-regressions.test.ts, src/config/schema.test.ts
• Scenario the test should lock in: messages.queue.byChannel.matrix validates for steer and interrupt; schema lookup lists matrix; unknown queue provider keys remain rejected.
• Why this is the smallest reliable guardrail: The bug is in config validation/schema exposure, so focused config schema tests exercise the failing contract directly.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Operators can now configure Matrix-specific queue behavior with messages.queue.byChannel.matrix.

Diagram (if applicable)

Before:
messages.queue.byChannel.matrix -> config validation error

After:
messages.queue.byChannel.matrix -> validates -> Matrix can use per-channel queue mode

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node v24.15.0 / pnpm v10.33.2
• Model/provider: N/A
• Integration/channel (if any): Matrix config schema
• Relevant config (redacted):

{
  "messages": {
    "queue": {
      "byChannel": {
        "matrix": "steer"
      }
    }
  }
}

Steps

1. Validate a config object containing messages.queue.byChannel.matrix.
2. Look up messages.queue.byChannel in the generated config schema.
3. Verify an unknown queue provider key is still rejected.

Expected

• Matrix validates.
• Schema lookup lists Matrix.
• Unknown provider keys remain rejected.

Actual

• Matrix validates.
• Schema lookup lists Matrix.
• Unknown provider keys remain rejected.

Evidence

Attach at least one:

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

Additional local verification:

pnpm exec vitest run --config test/vitest/vitest.runtime-config.config.ts src/config/config.schema-regressions.test.ts src/config/schema.test.ts --maxWorkers=1
✓ 2 files / 58 tests passed

pnpm build:plugin-sdk:dts
✓ passed

pnpm check
✓ passed

pnpm build
✓ passed

pnpm check:changed
✓ passed

codex review --base origin/main
✓ no regression found in the modified path

Human Verification (required)

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

• Verified scenarios: Matrix steer, Matrix interrupt, googlechat, and mattermost queue overrides validate; unknown queue provider keys remain rejected; schema lookup includes Matrix.
• Edge cases checked: Unknown provider rejection is preserved.
• What you did not verify: Live Matrix message delivery/queue behavior, because this PR changes schema/type acceptance only.

AI-assisted: yes. I understand the change: it extends the closed queue provider schema/type keys and adds direct regression coverage for the config contract.

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/No) Yes
• Config/env changes? (Yes/No) Yes — existing configs may now use messages.queue.byChannel.matrix.
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Expanding the closed provider key list could accidentally permit unintended keys.
  • Mitigation: The schema remains strict, and a regression test asserts unknown provider keys still fail.