PR #59425: fix(matrix): restore guided setup wizard registration

• Repository: openclaw/openclaw
• Author: luoyanglang
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59425

Description (problem / solution / changelog)

Summary

• register the Matrix onboarding wizard on the channel plugin again so openclaw channels add can drive guided setup
• add a regression test that asserts the Matrix channel still exposes configureInteractive

Testing

• pnpm.cmd test -- extensions/matrix/src/channel.setup.test.ts
• pnpm.cmd test -- extensions/matrix/src/onboarding.test.ts
• pnpm.cmd test -- extensions/matrix/src/channel.directory.test.ts

Closes #59415

Changed files

• extensions/matrix/src/channel.setup.test.ts (modified, +7/-0)
• extensions/matrix/src/channel.ts (modified, +2/-0)
• extensions/matrix/src/onboarding.test-harness.ts (modified, +2/-1)
• extensions/matrix/src/onboarding.ts (modified, +5/-50)
• src/channels/plugins/setup-wizard-types.ts (modified, +1/-1)
• src/channels/plugins/types.plugin.ts (modified, +2/-0)
• src/commands/channel-setup/registry.ts (modified, +5/-2)
• src/plugin-sdk/setup.ts (modified, +1/-0)

PR #59462: fix(matrix): restore guided setup flow

• Repository: openclaw/openclaw
• Author: gumadeiras
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/59462

Description (problem / solution / changelog)

Summary

• Problem: openclaw channels add and openclaw configure --section channels fell back to matrix does not support guided setup yet. even though Matrix still had guided onboarding logic.
• Why it matters: Matrix users lost the interactive setup path and could not complete onboarding from the shared channel setup flow.
• What changed: restored Matrix on the canonical setupWizard seam, taught the setup registry to accept either declarative or adapter-shaped setupWizard, and added registry + end-to-end regression coverage.
• What did NOT change (scope boundary): no new public setupWizardAdapter field, no changes to Matrix setup behavior outside the broken guided path.

Change Type (select all)

• Bug fix
• 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 #59415
• Related #59425
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: the interactive channel setup flow resolves guided onboarding from plugin.setupWizard, but Matrix no longer exposed its existing guided adapter there.
• Missing detection / guardrail: we had no setup-registry or setupChannels regression test proving Matrix still resolved a guided setup adapter.
• Prior context (git blame, prior PR, issue, or refactor if known): Matrix onboarding logic still existed; the break was registration drift after refactor work around the setup surfaces.
• Why this regressed now: Matrix kept setup but lost the guided setup registration that the interactive flow actually uses.
• If unknown, what was ruled out: ruled out missing onboarding implementation; the prompts/bootstrap logic was still present.

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/commands/channel-setup/registry.test.ts, src/commands/onboard-channels.e2e.test.ts, extensions/matrix/src/channel.setup.test.ts
• Scenario the test should lock in: Matrix resolves a guided setup adapter through the shared registry and setupChannels runs the guided flow without hitting the fallback error.
• Why this is the smallest reliable guardrail: the bug lived at the seam between plugin registration and the shared interactive flow, not inside Matrix prompt logic itself.
• Existing test that already covers this (if any): Matrix plugin-local setup tests covered pieces of setup but not registry resolution.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Matrix guided setup works again in the shared interactive onboarding flow.
• Custom adapter-shaped plugin wizards continue to work through the same setupWizard property.

Diagram (if applicable)

Before:
[user selects Matrix in setupChannels] -> [registry finds no guided adapter] -> [fallback error]

After:
[user selects Matrix in setupChannels] -> [registry resolves Matrix setupWizard] -> [guided prompts run] -> [config written]

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): Matrix
• Relevant config (redacted): interactive channel setup with Matrix selected

Steps

1. Start interactive channel setup.
2. Select Matrix.
3. Continue through the guided prompts.

Expected

• Matrix guided prompts run and write config.

Actual

• Before fix: setup fell back to matrix does not support guided setup yet.
• After fix: Matrix resolves through the shared guided setup registry and completes setup.

Evidence

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

Human Verification (required)

• Verified scenarios: Matrix plugin exposes guided setup; registry resolves both declarative and adapter-shaped setupWizard; setupChannels Matrix quickstart path no longer falls back.
• Edge cases checked: adapter-shaped setupWizard passthrough in registry helper; declarative wizard caching still works.
• What you did not verify: full manual TTY run of openclaw channels add; full repo pnpm check is currently blocked by unrelated local Telegram worktree errors.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: setupWizard now explicitly accepts both declarative and adapter-shaped guided setup surfaces.
  • Mitigation: registry tests cover both shapes, and the interactive Matrix e2e covers the real broken path.

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/matrix/src/channel.setup.test.ts (modified, +6/-0)
• extensions/matrix/src/channel.ts (modified, +2/-0)
• extensions/matrix/src/onboarding.test-harness.ts (modified, +6/-1)
• extensions/matrix/src/onboarding.ts (modified, +5/-50)
• extensions/whatsapp/src/shared.ts (modified, +6/-3)
• src/channels/plugins/types.plugin.ts (modified, +4/-1)
• src/commands/channel-setup/registry.test.ts (added, +58/-0)
• src/commands/channel-setup/registry.ts (modified, +34/-2)
• src/commands/onboard-channels.e2e.test.ts (modified, +135/-0)
• test/helpers/plugins/matrix-setup.ts (added, +1/-0)
• test/helpers/plugins/setup-wizard.ts (modified, +29/-7)