Summary

• Problem: latest main already keeps execution-facing channel setup discovery on the trusted catalog path, but lower-level setup-only scoped plugin loads could still import and execute disabled workspace channel plugins when callers passed explicit onlyPluginIds.
• What changed: this PR restores the lower-level security boundary from Plugins: keep untrusted workspace channel shadows out of setup-time loads #64154 by blocking disabled workspace channel plugins before setup-only import, adds a registry backstop that rejects channel registration from disabled workspace plugins, and ports the complementary fix(plugins): guard registerChannel in setup-entry path with try/catch #85774 guard so a broken trusted setup-entry channel reports a diagnostic instead of aborting sibling plugin loading.
• What latest main already kept from Plugins: keep untrusted workspace channel shadows out of setup-time loads #64154: channels add, onboarding/setup resolution, and setup discovery now use trust-aware catalog helpers; untrusted workspace shadows fall back to bundled/non-workspace entries; workspace-only candidates remain visible only in the setup wizard discovery bucket; the raw catalog listing is kept behind an internal/deprecated helper.
• Remaining work before merge: no known Plugins: keep untrusted workspace channel shadows out of setup-time loads #64154 hardening gap remains in code after this PR. The remaining gates are CI plus any maintainer-requested live external-plugin proof.

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

• Replaces/supersedes Plugins: keep untrusted workspace channel shadows out of setup-time loads #64154
• Includes the valuable complementary setup-entry error-isolation fix from fix(plugins): guard registerChannel in setup-entry path with try/catch #85774
• This PR fixes a bug or regression

Current Main vs This PR

The #64154 design had two layers:

1. Catalog callers should resolve channels through trusted helpers so setup/add flows do not select untrusted workspace shadows.
2. The loader/registry should enforce the same trust boundary before any plugin module can execute, so lower-level callers cannot bypass the catalog layer.

Latest main still preserves the first layer. channels add, setup/onboarding, and channel setup plugin resolution use listTrustedChannelPluginCatalogEntries / getTrustedChannelPluginCatalogEntry; the setup wizard's installable display can still show workspace-only candidates through the lenient discovery helper without treating them as executable/installed.

This PR fills the second layer. It prevents explicit setup-only scoped loads from importing disabled workspace channel plugins, rejects disabled workspace channel registrations at the registry boundary, and keeps trusted workspace overrides working. It also ports #85774's try/catch around api.registerChannel(mergedSetupPlugin), which addresses a related but distinct resilience gap: trusted setup-entry plugins are allowed to load, but one malformed registration should not stop healthy sibling plugins from loading.

Diagram

graph TD
  SOURCES["Plugin source directories"] --> MANIFEST["Manifest registry<br/>(pluginId + origin + channels)"]

  MANIFEST -->|"setup / onboard / channels add"| TRUSTED["Trusted catalog helpers<br/>strict execution list<br/>untrusted workspace shadows fall back"]
  MANIFEST -->|"setup wizard display"| DISCOVERY["Setup discovery helper<br/>lenient display list<br/>workspace-only candidates visible"]
  MANIFEST -->|"gateway or explicit scoped setup load"| LOADER["loadOpenClawPlugins()"]

  TRUSTED --> SETUP["setup/add snapshot request"]
  DISCOVERY --> UI["installable UI bucket only<br/>not an execution decision"]
  SETUP --> LOADER

  LOADER --> GATE{"This PR:<br/>workspace channel plugin enabled?"}
  GATE -->|"disabled workspace"| BLOCK["reject before setup-only import<br/>no plugin code executes"]
  GATE -->|"trusted workspace or non-workspace"| IMPORT["import setup/runtime entry"]

  IMPORT --> REGISTER{"This PR + #85774:<br/>registerChannel succeeds?"}
  REGISTER -->|"yes"| REGISTRY["snapshot/runtime registry"]
  REGISTER -->|"throws"| DIAG["record plugin diagnostic<br/>continue loading siblings"]

  REGISTRY --> SNAPUSE["validateInput / applyAccountConfig<br/>write config / lifecycle callbacks"]
  REGISTRY --> RUNTIME["gateway/runtime channel lookup"]

  BLOCK:::fixed
  GATE:::fixed
  DIAG:::fixed
  TRUSTED:::kept
  DISCOVERY:::display
  UI:::display

  classDef fixed fill:#d4edda,stroke:#28a745,stroke-width:2px
  classDef kept fill:#d9edf7,stroke:#31708f,stroke-width:2px
  classDef display fill:#fff3cd,stroke:#ffc107,stroke-width:2px

The important boundary is now shared: catalog helpers decide which channel catalog entries are trusted for setup/add flows, and the loader/registry enforce the same rule before runtime code can execute. If a trusted setup-entry channel still fails during registration, the error is isolated to that plugin and sibling plugins continue loading.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: untrusted workspace channel plugins should not execute during setup-only scoped loads; disabled workspace channel registrations should be rejected at registry assembly; trusted setup-entry channel registration failures should not abort sibling plugin loading.
• Real environment tested: local Linux repo checkout on latest main after rebasing this PR.
• Exact steps or command run after this patch:
  • OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test src/plugins/loader.test.ts -- -t "blocks untrusted setup-only workspace channel plugins|keeps trusted setup-only workspace channel plugins available|records a diagnostic when registerChannel throws in the setup-entry path|keeps healthy sibling channel plugins loadable when a setup entry throws" --reporter=verbose
  • OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test src/plugins/registry.channel-guard.test.ts src/commands/channel-setup/trusted-catalog.test.ts src/commands/channels.add.test.ts src/commands/channel-setup/channel-plugin-resolution.test.ts src/commands/channel-setup/discovery.test.ts src/commands/channel-setup/workspace-shadow-bypass.test.ts src/commands/channel-setup/plugin-install.test.ts -- --reporter=verbose
  • pnpm check:changed
  • pnpm build
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main
• Evidence after fix: the targeted loader tests pass for untrusted/trusted workspace setup-only scoped loads and setup-entry registerChannel error isolation; the registry/catalog/channel setup tests pass across 65 channel setup cases; check:changed, build, and autoreview are clean.
• Observed result after fix: disabled workspace shadows no longer execute through scoped setup-only loads; trusted workspace overrides remain available; disabled workspace channel registrations are rejected as a registry backstop; malformed trusted setup-entry channel registration records a diagnostic and sibling plugins keep loading.
• What was not tested: live channel setup against a real external workspace plugin outside the loader test harness.
• Before evidence (optional but encouraged): the same minimal setup-only repro failed on latest origin/main before this branch because the marker file was created during scoped setup-only load.

Root Cause (if applicable)

• Root cause: the scoped setup-only loader path treated explicit onlyPluginIds as sufficient to load a disabled workspace channel plugin, so workspace trust was bypassed below the trusted-catalog call sites.
• Missing detection / guardrail: registry assembly still accepted channel registration from disabled workspace plugins if a lower-level caller imported one.
• Complementary fix(plugins): guard registerChannel in setup-entry path with try/catch #85774 root cause: the setup-entry loader loop caught surrounding registration failures, but api.registerChannel(mergedSetupPlugin) itself was unguarded, so one throwing trusted channel registration could abort sibling plugin loading.
• Contributing context: latest main already absorbed the higher-level channels add / trusted-catalog call-site fixes from Plugins: keep untrusted workspace channel shadows out of setup-time loads #64154, but not this lower-level loader/registry backstop or the setup-entry error-isolation guard.

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/plugins/loader.test.ts, src/plugins/registry.channel-guard.test.ts, src/commands/channel-setup/trusted-catalog.test.ts, and existing channel setup/add tests.
• Scenario the test should lock in: explicit scoped setup-only loads must reject disabled workspace channel plugins but keep trusted workspace channel plugins available; registry assembly must reject disabled workspace channel registrations; trusted setup-entry registration errors must be recorded without aborting healthy sibling plugins.
• Why this is the smallest reliable guardrail: the bugs live at loader/registry/catalog boundaries and require real plugin import behavior plus registration-mode assertions.
• Existing test that already covers this (if any): only setup-loads a disabled channel plugin when the caller scopes to the selected plugin still covers the non-workspace path.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Untrusted workspace channel shadows no longer execute during setup-only scoped loads.
• Trusted workspace channel plugins remain available to setup-time scoped loading.
• A broken trusted setup-entry channel registration now surfaces as a plugin diagnostic instead of stopping sibling plugin loading.

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: Linux
• Runtime/container: Node 22 local repo checkout
• Model/provider: N/A
• Integration/channel (if any): plugin loader / channel plugin registry / channel setup catalog
• Relevant config (redacted): workspace plugins enabled; untrusted plugin omitted from allowlist

Steps

1. Create a workspace channel plugin fixture with channels metadata and a side-effect marker write in register().
2. Load it through loadOpenClawPlugins({ includeSetupOnlyChannelPlugins: true, forceSetupOnlyChannelPlugins: true, onlyPluginIds: [...] }).
3. Compare disabled workspace behavior against trusted workspace behavior.
4. Load a setup-entry channel whose channel config getter throws during registerChannel alongside a healthy sibling plugin.

Expected

• Disabled workspace channel plugin stays disabled and does not execute.
• Trusted workspace channel plugin remains available to setup-only loading.
• A throwing trusted setup-entry channel records a diagnostic and does not prevent sibling plugins from loading.

Actual

• This branch matches the expected behavior.

Evidence

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

Human Verification (required)

• Verified scenarios: untrusted/trusted workspace scoped setup-only regressions, disabled workspace registry guard, trusted-catalog filtering semantics, channels add workspace shadow fallback, fix(plugins): guard registerChannel in setup-entry path with try/catch #85774 setup-entry registerChannel error isolation, pnpm check:changed, pnpm build, autoreview.
• Edge cases checked: trusted workspace override still loads in setup-only mode; non-workspace disabled plugin behavior stays unchanged; setup wizard discovery still keeps workspace-only install candidates visible without treating them as installed/executable.
• What you did not verify: a live end-to-end channel setup outside the loader test harness.

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

Risks and Mitigations

• Risk: a trusted workspace plugin could accidentally get blocked if the trust check were too broad.
• Mitigation: regression coverage explicitly keeps the trusted workspace scoped-load path green.
• Risk: setup discovery could accidentally hide workspace-only install candidates.
• Mitigation: trusted-catalog and discovery tests keep the strict execution list separate from the lenient setup wizard display list.

Proof 1: Pre-Fix Reproduction on origin/main

• Behavior addressed: Untrusted workspace channel plugin (evi1-channel-probe) executes its register() function via the setup-only scoped load path when includeSetupOnlyChannelPlugins: true is passed to loadOpenClawPlugins, bypassing the trust boundary.
• Real environment tested: Crabbox docker, provider=docker, container=391883b7652bcb464c523f64ddcabb9bcad47f92e434737b7cc5391f7bc0922f, run=cbx_6dadb5d505eb, checkout SHA=ead847f6065ac36031f9e7a95dd1ee90f171f79c (origin/main)
• Exact steps or command run after this patch: (1) git fetch --depth=1 origin main && git checkout FETCH_HEAD inside Crabbox container; (2) pnpm install --frozen-lockfile && pnpm build; (3) Deploy evi1-channel-probe plugin to /tmp/proof1-workspace/.openclaw/extensions/evi1-channel-probe/; (4) Confirm /tmp/openclaw-marker-evidence absent; (5) Run node probe-untrusted.mjs with onlyPluginIds=["evi1-channel-probe"], includeSetupOnlyChannelPlugins=true, activate=false, cache=false; (6) Check /tmp/openclaw-marker-evidence existence.
• Evidence after fix: Marker file /tmp/openclaw-marker-evidence CREATED with content "evi1-probe-executed\n". Plugin status="disabled" with channelSetups=[{id:"evi1-channel-probe"}] — the setup-only path imported and executed the untrusted workspace plugin code.
• Observed result after fix: On origin/main (pre-fix), the untrusted workspace channel plugin code ran despite being disabled. The plugin appeared in channelSetups (not channels), status was "disabled", yet register() executed and created the marker file. This confirms the bypass vulnerability.
• What was not tested: CLI blackbox path, real channels add flow

Proof 2: Post-Fix Verification on PR Head

• Behavior addressed: The PR fix blocks untrusted workspace channel plugins from executing during setup-only scoped loads; disabled workspace channel registrations are rejected at registry assembly; trusted workspace plugins with plugins.allow still work; broken trusted setup-entry registerChannel records a diagnostic without aborting sibling plugins.
• Real environment tested: Crabbox docker, provider=docker, container=df29879e2faef7ac8794cba519c1988aff410316a3718d90c6f638cd9977ce15, lease=cbx_0f687f5da081, checkout SHA=b05a7b14fe9bd6c119b3b7fe60a1967d0987804c (PR fix(plugins): block untrusted workspace setup-only channel loads #82579 head)
• Exact steps or command run after this patch: (1) git fetch origin pull/82579/head:pr-head && git checkout pr-head inside Crabbox container; (2) pnpm install --frozen-lockfile && pnpm build; (3) grep -r "channel registration rejected for disabled workspace plugin" dist/ — fix code found in dist/loader-DM-dphfh.js; (4) Deploy evi1-channel-probe (untrusted), confirm marker ABSENT after probe; (5) Deploy evi1-trusted-probe (with plugins.allow), confirm marker EXISTS; (6) Deploy evi1-broken-register + evi1-sibling-probe (with plugins.allow), confirm sibling marker EXISTS and diagnostic recorded; (7) Run focused tests: pnpm test src/plugins/loader.test.ts (142 pass), pnpm test src/plugins/registry.channel-guard.test.ts (2 pass), pnpm test src/commands/channel-setup/trusted-catalog.test.ts (5 pass), pnpm test src/commands/channel-setup/workspace-shadow-bypass.test.ts (6 pass); (8) pnpm check:changed — 0 errors.
• Evidence after fix: Untrusted probe: MARKER_ABSENT, exit code 0 (clean block, not crash). Plugin status="disabled", channelSetups=[]. Trusted probe: MARKER_EXISTS, content "evi1-probe-executed\n". Plugin status="loaded", channels and channelSetups populated. Error isolation: broken-register records diagnostic (level=error, pluginId=evi1-broken-register), process exit code 0. Sibling marker EXISTS, content "evi1-sibling-probe-executed\n".
• Observed result after fix: The fix blocks untrusted workspace channel plugin execution. Untrusted plugin stays disabled with empty channelSetups. Trusted workspace plugin with plugins.allow still loads and registers channels. Broken trusted registerChannel records a diagnostic and sibling plugins continue loading. All focused tests pass.
• What was not tested: CLI blackbox path, real channels add flow, 3 pre-existing test failures in channel-auth.test.ts (2) and channels.remove.test.ts (1) unrelated to this PR

Crabbox cross-reference: Proof 1 provider=docker, container=391883b7652bcb464c523f64ddcabb9bcad47f92e434737b7cc5391f7bc0922f, run=cbx_6dadb5d505eb, SHA=ead847f6065ac36031f9e7a95dd1ee90f171f79c (origin/main). Proof 2 provider=docker, container=df29879e2faef7ac8794cba519c1988aff410316a3718d90c6f638cd9977ce15, lease=cbx_0f687f5da081, SHA=b05a7b14fe9bd6c119b3b7fe60a1967d0987804c (PR #82579 head). Proof 1 SHA (ead847f) is an ancestor of Proof 2 SHA (b05a7b1) via the main branch lineage. Probe infrastructure file SHA-256 hashes are identical between both proofs (VAL-CROSS-01 confirmed).