Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: Gateway clients could inspect plugin UI descriptors, but plugin management actions were still effectively CLI-only.
• Why it matters: Remote control-plane clients need typed plugin list, inspect, registry refresh, install, update, uninstall, enable, and disable operations without shelling out on the Gateway host.
• What changed: Added typed plugins.* Gateway RPC params/validators/handlers, extracted CLI plugin-management persistence and registry refresh logic into reusable src/plugins/* services, updated Operator scopes/rate limits, regenerated Swift protocol models, and documented the new protocol surface.
• What did NOT change (scope boundary): This does not add client-file upload for plugin installs, marketplace browsing RPCs, plugin deps repair RPCs, or per-agent/plugin management selectors. plugins.install path requests resolve on the Gateway host.

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

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: N/A.
• Missing detection / guardrail: N/A.
• Contributing context (if known): Existing plugin management behavior lived behind CLI orchestration that mixed terminal formatting, config writes, install records, and registry refresh side effects, so the Gateway had no safe reusable service layer for the same operations.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• 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-methods/plugins.test.ts, src/plugins/management.test.ts, src/gateway/method-scopes.test.ts, src/gateway/server-methods.control-plane-rate-limit.test.ts.
• Scenario the test should lock in: Gateway handlers validate and route plugin management requests, map service errors, serialize plugin config mutations, use the canonical plugin extensions directory, return partial update success when appropriate, and rate-limit mutating plugin management methods.
• Why this is the smallest reliable guardrail: The new behavior is a Gateway/service seam over existing plugin install/update/uninstall primitives, so handler and service-level tests cover the newly introduced contract without relying on external package registries.
• Existing test that already covers this (if any): Existing CLI/plugin tests cover lower-level plugin install/update/uninstall machinery; this PR adds coverage for the new Gateway-facing service layer.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Operators can now call Gateway plugin management RPCs: plugins.list, plugins.inspect, plugins.doctor, plugins.registry.status, plugins.registry.refresh, plugins.install, plugins.update, plugins.uninstall, plugins.enable, and plugins.disable.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before:
[remote client] -> [Gateway] -> [no plugin management RPC]
[operator shell] -> [openclaw plugins ...] -> [plugin config/install records/registry]

After:
[remote client] -> [Gateway plugins.* RPC] -> [shared plugin management service] -> [plugin config/install records/registry]
[operator shell] -> [openclaw plugins ...] -> [same shared persistence/registry helpers]

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes.
• Secrets/tokens handling changed? (Yes/No) No.
• New/changed network calls? (Yes/No) Yes.
• Command/tool execution surface changed? (Yes/No) Yes.
• Data access scope changed? (Yes/No) Yes.
• If any Yes, explain risk + mitigation: The new RPCs expose plugin management over the Gateway control plane. Mutating methods are scoped to operator.admin, covered by the control-plane write rate limit, and use the existing plugin installer safety checks. Metadata-returning list/inspect/registry methods are admin-scoped except plugins.doctor, because they can expose Gateway-host plugin paths or diagnostics. plugins.install local paths resolve on the Gateway host and do not upload client files.

Repro + Verification

Environment

• OS: macOS local checkout; GitHub Actions will provide CI parity after PR creation.
• Runtime/container: Node 22+ project tooling via pnpm.
• Model/provider: N/A.
• Integration/channel (if any): Gateway plugin management RPC surface.
• Relevant config (redacted): N/A.

Steps

1. Call one of the new plugins.* Gateway RPC methods with validated params.
2. For read methods, inspect plugin status/diagnostics/registry state.
3. For mutating methods, install/update/uninstall/enable/disable plugins through the shared service layer.

Expected

• Requests validate against the generated protocol schemas.
• Read methods return structured plugin management payloads.
• Mutating methods require operator.admin, are rate-limited, and persist plugin config/install-record changes through the shared helpers.

Actual

• Verified by targeted handler/service/scope/rate-limit tests and protocol generation checks.

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: pnpm test src/gateway/server-methods/plugins.test.ts src/plugins/management.test.ts src/gateway/method-scopes.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts; pnpm protocol:check; targeted pnpm exec oxfmt --check --threads=1 on changed TypeScript files; pnpm format:docs:check; git diff --cached --check before commit; staged CJK added-line gate; pre-ship committed-diff review.
• Edge cases checked: missing install source fields, service not-found/conflict/error mapping, registry status routing, enable conflict handling, serialized concurrent plugin config mutations, uninstall canonical extensions dir, partial update success after commit, and plugin management write rate limiting.
• What you did not verify: Live npm/ClawHub install/update/uninstall against external registries and full pnpm check:changed locally. External contributors on this machine do not have Blacksmith Testbox org access; CI parity is expected to run from GitHub Actions on this PR branch.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

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

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: Remote plugin management can change Gateway plugin state without a shell session.
  • Mitigation: Mutating methods are admin-scoped, write-rate-limited, validate params, and reuse existing plugin install/update/uninstall safety checks.
• Risk: Live registry/package-manager behavior may differ from mocked service tests.
  • Mitigation: This PR keeps the Gateway layer thin and reuses existing lower-level plugin management primitives; GitHub Actions should run the broader changed/CI gates on the PR.