Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Matrix channel: doctor --fix fails with 'must NOT have additional properties' before it can migrate config [1 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#71757•Fetched 2026-04-26 05:08:46
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
0
Author
aweikeraweiker
Participants
aweikeraweikergumadeirasgumadeiras
Timeline (top)
closed ×1commented ×1

Error Message

Error: Config validation failed: channels.matrix: invalid config: must NOT have additional properties

Root Cause

Note: this is tricky because the gateway's config auto-recovery reverts manual edits if the gateway is still running.

Fix Action

Workaround

Manually edit ~/.openclaw/openclaw.json while the gateway is stopped:

  • Remove dm object
  • Add "dmPolicy": "open" and "allowFrom": ["*"] at the matrix channel level

Note: this is tricky because the gateway's config auto-recovery reverts manual edits if the gateway is still running.

Code Example

Error: Config validation failed: channels.matrix: invalid config: must NOT have additional properties

---

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "accessToken": "...",
      "dm": { "policy": "open" },
      "autoJoin": "always"
    }
  }
}
RAW_BUFFERClick to expand / collapse

Bug

openclaw doctor and openclaw gateway status report:

Error: Config validation failed: channels.matrix: invalid config: must NOT have additional properties

The Matrix config was created via openclaw channels add or manual setup and contains the legacy dm.policy nested format:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.example.org",
      "accessToken": "...",
      "dm": { "policy": "open" },
      "autoJoin": "always"
    }
  }
}

doctor correctly identifies the migration needed (dm.policy → dmPolicy + allowFrom), but doctor --fix fails with the same validation error before it can apply the fix. Chicken-and-egg: the config is invalid, but the tool that fixes it rejects invalid configs.

Expected behavior

doctor --fix should migrate the old format without validation blocking it. Either:

  1. Run migration transforms before validation, or
  2. Skip validation during --fix mode and validate after applying fixes

Workaround

Manually edit ~/.openclaw/openclaw.json while the gateway is stopped:

  • Remove dm object
  • Add "dmPolicy": "open" and "allowFrom": ["*"] at the matrix channel level

Note: this is tricky because the gateway's config auto-recovery reverts manual edits if the gateway is still running.

Environment

  • OpenClaw 2026.4.23 (a979721)
  • Matrix channel (bundled plugin)
  • Continuwuity homeserver (self-hosted)
  • Ubuntu 24.04

extent analysis

TL;DR

The doctor --fix command fails to migrate the legacy Matrix config format due to validation errors, and a manual workaround is required to update the config.

Guidance

  • The issue is caused by the doctor command validating the config before applying fixes, which prevents it from migrating the legacy format.
  • To verify the issue, run openclaw doctor and check for the "Config validation failed" error message.
  • A temporary workaround is to manually edit the ~/.openclaw/openclaw.json file while the gateway is stopped, removing the dm object and adding the new dmPolicy and allowFrom properties.
  • To mitigate the issue, consider stopping the gateway before running doctor --fix to prevent config auto-recovery from reverting manual edits.

Example

No code snippet is provided as the issue is related to configuration and not code.

Notes

The provided workaround is specific to the OpenClaw 2026.4.23 version and may not apply to other versions. Additionally, the manual edit requires the gateway to be stopped to prevent config auto-recovery from interfering with the changes.

Recommendation

Apply the manual workaround to update the config, as there is no clear indication of a fixed version that addresses this issue. This is because the workaround provides a direct solution to the problem, allowing users to migrate their config to the new format.

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…

FAQ

Expected behavior

doctor --fix should migrate the old format without validation blocking it. Either:

  1. Run migration transforms before validation, or
  2. Skip validation during --fix mode and validate after applying fixes
#authentication setup#request error#file not found#serialization error#model compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix Matrix channel: doctor --fix fails with 'must NOT have additional properties' before it can migrate config [1 comments, 2 participants]