PR #73877: fix(plugins): beta blocker - Workspace plugin HTTP routes return 404

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

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Workspace plugin HTTP routes register successfully but the HTTP dispatcher returns a 404 for all requests to the registered path.
• Why it matters: It blocks plugins from receiving inbound webhooks (e.g., Stripe, Gmail push notifications, Slack callbacks) since the gateway silently fails to dispatch them to the plugin.
• What changed: Removed the unconditional pinActivePluginHttpRouteRegistry(params.pluginRegistry) in createGatewayRuntimeState so the HTTP route registry surface can properly sync and accept runtime updates.
• What did NOT change (scope boundary): The channel registry pinning remains intact. No changes were made to how routes are parsed, authorized, or executed.

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

Root Cause (if applicable)

• Root cause: The gateway runtime was unconditionally pinning the HTTP route registry surface at startup. When dynamic plugins loaded later, setActivePluginRegistry triggered syncTrackedSurface, which explicitly bails out if surface.pinned is true. As a result, the dispatcher always resolved the empty/stale startup route registry.
• Missing detection / guardrail: There was no integration test validating that dynamically loaded plugins (which register routes post-startup) have their HTTP routes correctly resolved by the gateway HTTP dispatcher.
• Contributing context (if known): Likely copied from or related to the channel registry pinning logic, which is necessary to prevent config-schema reads from evicting channel plugins.

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/gateway/server-plugin-bootstrap.dynamic-routes.integration.test.ts
• Scenario the test should lock in: Ensure that if a plugin registers an HTTP route after createGatewayRuntimeState is run (i.e. dynamic plugin initialization), resolveActivePluginHttpRouteRegistry returns the updated registry containing the new route.
• Why this is the smallest reliable guardrail: It specifically verifies that the registry syncing logic (setActivePluginRegistry) propagates routes to the active dispatcher state.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: New test was added.

User-visible / Behavior Changes

None (Restores intended documented API functionality for workspace plugins).

Diagram (if applicable)

N/A

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: Ubuntu 24.04 (Host)
• Runtime/container: Docker, Node 24.14.0
• Model/provider: N/A
• Integration/channel (if any): Workspace Plugin
• Relevant config (redacted): N/A

Steps

1. Create a workspace plugin that registers an HTTP route on startup using api.registerHttpRoute({ path: "/plugins/webhooks/gmail-push", auth: "plugin", match: "exact", handler })
2. Start OpenClaw in Docker.
3. Make a POST request to /plugins/webhooks/gmail-push.

Expected

• The plugin handler receives the request and executes correctly.

Actual

• The gateway responds with 404 Not Found.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: I verified the gateway dispatch resolution logic manually using scripts that simulate the request path context logic to confirm the route registry wasn't being updated due to pinning.
• Edge cases checked: Verified that removing the pinning doesn't impact pinActivePluginChannelRegistry, which correctly remains conditionally pinned.
• What you did not verify: I didn't verify an end-to-end webhook provider (e.g. Stripe webhook), but verified that the dispatcher maps the route registry successfully.

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: HTTP routes might be swapped or cleared unexpectedly if another registry reset happens.
  • Mitigation: The HTTP route registry is designed to be hot-swappable dynamically Workspace plugin unloads/reloads will resync the correct surface registry.

Changed files

• src/gateway/server-plugin-bootstrap.dynamic-routes.integration.test.ts (added, +88/-0)
• src/gateway/server-runtime-state.ts (modified, +0/-1)