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 rebased on upstream/main 98b8e85bebdc5438e9ea5718af5749be0cc742fb; PR head 9bfc1ca3c0e4e80fd5ae8a10d16a32b8dc4af972.
• Exact steps or command run after this patch:
  • pnpm docs:list
  • pnpm test src/commands/onboard-channels.e2e.test.ts -- --reporter=verbose
  • pnpm test src/plugins/loader.test.ts src/plugins/registry.channel-guard.test.ts src/commands/channel-setup/trusted-catalog.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 src/commands/channels.add.test.ts -- --reporter=verbose
  • pnpm build
  • pnpm check:changed
• Evidence after fix: src/commands/onboard-channels.e2e.test.ts passed 16/16 after exposing listRawChannelPluginCatalogEntries through the same mock/actual fallback as the old catalog helper; the focused loader/registry/catalog/channel setup tests passed after the 2026-06-01 rebase; pnpm build passed on PR head 9bfc1ca3c0e4e80fd5ae8a10d16a32b8dc4af972. pnpm check:changed first could not delegate because the local Crabbox binary is 0.15.0 and the Testbox wrapper requires >=0.22.0; the local child run reached typecheck and failed only in untouched extensions/phone-control/index.test.ts extension-test mocks. CHANGELOG.md and stale transcripts tool-display metadata are no longer in the final branch diff.
• 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, onboarding channel setup e2e catalog mock compatibility, channels add workspace shadow fallback, fix(plugins): guard registerChannel in setup-entry path with try/catch #85774 setup-entry registerChannel error isolation, and pnpm build after the 2026-06-01 rebase. pnpm check:changed has a current local proof gap in untouched extensions/phone-control/index.test.ts extension-test typecheck.
• 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) No. This is an intentional security hardening break for disabled workspace channel plugins that were previously reachable through setup-only scoped loads.
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No automatic migration. Operators who intentionally develop or run a workspace/linked channel plugin must explicitly enable/trust that plugin before setup-time code can run.
• If yes, exact upgrade steps: use the normal plugin enable/trust flow for the workspace plugin before running channel setup. The behavior is documented in docs/cli/plugins.md.

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.
• Risk: an existing disabled workspace channel plugin that relied on setup-only execution now fails closed.
• Mitigation: this is the intended security behavior; the docs now state that workspace-origin plugins are not imported or executed until explicitly enabled/trusted.

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 head at time of test; refreshed fix(plugins): block untrusted workspace setup-only channel loads #86953 head is 9bfc1ca3c0e4e80fd5ae8a10d16a32b8dc4af972)
• 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 (#82579 head; superseded by #86953, refreshed head 2a9a2d79fd498be5fc62e83634a544f873b67b4c). 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).

Blackbox Verification Evidence (2026-06-01)

PR Head SHA Tested

00f3c695439a7211d293b6f6ce203e4c0bea3a9f

Exact Commands Run

Blackbox probe (Linux, local worktree):

cd /tmp/proof-86953
pnpm install --frozen-lockfile
pnpm build
node blackbox-channel-guard-probe.mjs

Whitebox unit tests:

node scripts/run-vitest.mjs src/plugins/registry.channel-guard.test.ts --reporter=verbose
node scripts/run-vitest.mjs 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
git diff --check

Marker-File Before/After Evidence

Whether Disabled Workspace Setup Code Executed

No. In TEST1 and TEST3, the disabled workspace channel plugin (evil-workspace-probe, evil-registry-probe) was discovered but not enabled or allowlisted. After the loadOpenClawPlugins call with includeSetupOnlyChannelPlugins: true, forceSetupOnlyChannelPlugins: true, onlyPluginIds: [...]:

• No marker file was written — module top-level code did not execute
• No register() callback ran — no register-executed marker
• Plugin status was "disabled" with origin: "workspace"
• channelSetups and channels were both empty — no channel registration occurred

The loader-level guard (canLoadScopedSetupOnlyChannelPlugin requiring candidate.origin !== "workspace" || enableState.enabled) correctly blocks disabled workspace plugins before module import. The registry defense-in-depth guard at registerChannel was not reached because the module was never imported.

Whether Enabled/Allowlisted Setup Still Worked

Yes.

• Allowlisted (plugins.allow): TEST2 confirmed the allowlisted workspace plugin loaded with status "loaded", channelSetups populated, and marker file written.
• Explicit entries enablement (plugins.entries.*.enabled = true): TEST5 confirmed the explicitly enabled workspace plugin loaded with status "loaded" and marker file written.
• Error isolation: TEST4 confirmed a broken registerChannel in one allowlisted plugin records a diagnostic but does not prevent a healthy sibling from loading.

Whitebox Unit Test Results

src/plugins/registry.channel-guard.test.ts: 3 passed (3 total)
src/plugins/loader.test.ts (focused): 4 passed | 148 skipped (4 matched)

Tests verified:

• blocks untrusted setup-only workspace channel plugins when explicitly scoped ✓
• keeps trusted setup-only workspace channel plugins available when explicitly scoped ✓
• records a diagnostic when registerChannel throws in the setup-entry path ✓
• keeps healthy sibling channel plugins loadable when a setup entry throws ✓

Registry guard tests:

• rejects channel registration from disabled workspace plugins ✓

• rejects disabled workspace registration before reading channel data ✓

• keeps channel registration available for trusted workspace plugins ✓

• git diff --check: clean, no whitespace errors.

Gaps or Skipped Checks

• No CLI blackbox path tested: The probe used loadOpenClawPlugins() directly rather than openclaw channels add or openclaw onboard CLI commands. The programmatic API exercises the same loader/registry guard code path; the CLI path is a thin wrapper calling the same loadChannelSetupPluginRegistrySnapshotForChannel / loadChannelSetupPluginRegistry entry points.
• No plugins.load.paths testing: Per the prompt, this is a separate follow-up hardening topic and was explicitly excluded.
• No live external workspace plugin: The probe used synthetic fixture plugins rather than an externally installed npm workspace plugin. The origin detection code uses filesystem path (origin: "workspace" from .openclaw/extensions/), which the fixtures exercise correctly.
• Test4 broken-register probe uses listAccountIds getter throwing. The actual fix(plugins): guard registerChannel in setup-entry path with try/catch #85774 guard also covers api.registerChannel(mergedSetupPlugin) throwing; this is covered by the whitebox unit test records a diagnostic when registerChannel throws in the setup-entry path.