PR #66277: fix(channels): guard broken bundled channel loads

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/66277

Description (problem / solution / changelog)

Summary

• Problem: partially present bundled channel artifacts can throw out of loadChannelPlugin() and take down channels.status / gateway auth-bypass path discovery instead of degrading gracefully.
• Why it matters: issue #66129 showed this with the private qa-channel bundle path, which made status probes fail for an otherwise usable install.
• What changed: bundled channel/plugin setup loads now catch activation-time failures, cache the broken entry as unavailable, and skip it; added a regression test for the broken-entry path.
• What did NOT change (scope boundary): this PR does not change the npm packaging policy for private QA bundles.

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 #66129
• Related #66129
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the bundled channel loader already guarded entry-module resolution, but it let entry.loadChannelPlugin() / entry.loadSetupPlugin() exceptions escape. A partial bundled plugin surface could therefore crash callers that enumerate bundled channels.
• Missing detection / guardrail: there was no regression test for a bundled channel entry that resolves successfully but throws during plugin activation.
• Contributing context (if known): private QA bundles are intentionally kept out of the published npm pack, so a partial/broken bundled surface needs to fail closed instead of propagating through shared runtime paths.

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/channels/plugins/bundled.shape-guard.test.ts
• Scenario the test should lock in: a bundled channel entry that loads but throws from loadChannelPlugin() is skipped and cached as unavailable instead of throwing to callers.
• Why this is the smallest reliable guardrail: it exercises the exact shared loader seam used by channels.status and gateway auth-bypass path discovery without needing a full packaged install repro.
• Existing test that already covers this (if any): none found.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• channels.status and gateway HTTP auth-bypass path discovery now degrade gracefully when a bundled channel entry is partially present or broken instead of failing the whole request.

Diagram (if applicable)

N/A

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:

Repro + Verification

Environment

• OS: macOS 15 / darwin 25.3.0
• Runtime/container: local repo checkout, plus direct inspection of the published [email protected] tarball
• Model/provider: N/A
• Integration/channel (if any): bundled channel loader / qa-channel
• Relevant config (redacted): N/A

Steps

1. Inspect the published [email protected] tarball and confirm the private qa-channel public entry files are not shipped.
2. Follow the shared bundled channel runtime path used by channels.status / gateway auth-bypass discovery.
3. Simulate a bundled channel entry that resolves but throws while loading the actual channel plugin.

Expected

• Shared runtime callers skip the broken bundled channel and continue serving the request.

Actual

• The thrown error escaped from the bundled channel loader and could fail shared runtime callers.

Evidence

Attach at least one:

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

Human Verification (required)

• Verified scenarios: inspected the v2026.4.12 packaging state, confirmed the runtime loader path, ran the new guard test, reran the nearest npm-release QA-pack test, and ran pnpm check plus pnpm build.
• Edge cases checked: repeated broken bundled plugin lookups stay cached as unavailable instead of retrying and rethrowing.
• What you did not verify: a full globally installed repro invoking the gateway over HTTP.

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:

Risks and Mitigations

• Risk: a genuinely broken bundled channel now gets skipped rather than surfacing as a hard failure to the caller.
  • Mitigation: the loader still emits a warning log, and this matches the existing fail-open behavior for broken entry-module discovery.

Additional Context

• Testing run:
  • pnpm test src/channels/plugins/bundled.shape-guard.test.ts
  • pnpm test test/openclaw-npm-release-check.test.ts -t 'private qa artifacts'
  • pnpm check
  • pnpm build
• AI assistance: Cursor was used for implementation and verification; the final diff and runtime path were reviewed manually before opening this PR.

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/channels/plugins/bundled.shape-guard.test.ts (modified, +172/-0)
• src/channels/plugins/bundled.ts (modified, +77/-20)