Plugin Runtime Guardian

Indexed Reference Map

• @[SKILL.md#L1-L95] Frontmatter + trigger + SOP + output contract
• @[references/runbook.md#L1-L72] Generic diagnostic matrix + fix decision tree
• @[scripts/verify_plugin_backend.sh#L1-L67] Runtime verification script (plugin-aware)

Scope

• In-scope:
  • Plugin runtime backend is not READY.
  • Log signatures: runtime setup failed, command not found, parseable version, plugin-local ... mismatch, requires gateway restart ... deferring.
  • Standardize command executable path + wrapper discipline.
• Out-of-scope:
  • Change plugin/OpenClaw upstream code.
  • Fix channel/provider error unrelated to backend runtime plugin.

Hard Rules

• Temp verify artifacts, filtered logs, wrapper probes must be in workspace/.ops/tmp/<task-id>/.
• Metadata/checkpoint/report files must be in workspace/.ops/state/<task-id>/.
• Before any restart/status conclusion, the local Android module contract must be reconciled; prioritize openclaw.service ... when the lifecycle action is absolutely necessary.
• Do not report PASS if the new status is only registered but not ready after the actual restart/apply.
• If the runtime issue follows a plugin shadow/update flow, do not assume --profile proved plugin filesystem isolation; verify the resolved install/discovery path before treating the shadow candidate as valid evidence.

Trigger Rules

• Positive:
  • User provides startup plugin log with runtime setup failed.
  • User requests to fix backend plugin (acpx or similar plugin) that failed verification.
  • Plugin registered but no ready.
• Negative:
  • Just install the regular package, without the runtime backend plugin.
  • Only performance/health warnings are not related to backend init.
• Escalation:
  • If you need to operate outside the workspace or network write beyond the required user range, checkpoint approval is required.

SOP

1. Snapshot runtime
   • openclaw status --deep
   • Collect the most recent log from the canonical runtime log path; temp captures saved under workspace/.ops/tmp/<task-id>/.
2. Classify failure signature (according to references/runbook.md):
   • A) plugin-local binary unavailable/mismatched
   • B) command not found at <path-or-string>
   • C) --version output did not include a parseable version
   • D) config change requires gateway restart ... deferring
   • E) shadow/plugin isolation mismatch (config/state looked isolated, but install/discovery path still touched live plugin root)
3. Enforce command contract (critical)
   • Plugin command must be single executable path.
   • Do not set string commands with args.
   • If CLI needs fixed args => create separate executable wrapper.
4. Create canonical wrapper (when needed)
   • Standard shell shebang (#!/system/bin/sh on Android).
   • exec <absolute-runtime-binary> <absolute-cli-entry> "$@".
   • chmod 755.
   • Verify <wrapper> --version returns parseable semver (x.y.z).
5. Patch config deterministic
   • plugins.entries.<plugin>.enabled = true
   • plugins.entries.<plugin>.config.command = <wrapper-or-binary-absolute-path>
   • plugins.entries.<plugin>.config.expectedVersion = <installed-version> (if plugin has verified version)
   • If the backend depends on a separate subsystem (e.g. acp), then the corresponding subsystem verify key is enabled.
6. Restart semantics
   • If the log has requires gateway restart ... deferring, the status is PENDING_RESTART.
   • Before restart/status, compare against the local Android module contract; prioritize openclaw.service ... if applicable.
   • Only conclude PASS after restart + verify again.
7. Post-restart verification (required)
   • There is runtime backend registered with the new command.
   • There is runtime backend ready.
   • There are no new runtime setup failed errors for that plugin.
   • openclaw status --deep is still healthy.

Error Handling

• command not found after patch:
  • Re-check absolute path, executable bit, shebang compatibility.
• version parse fail:
  • Avoid JS wrapper/echo noise; use pure exec shell, clean stdout.
• registered but not ready:
  • Check the latest runtime/plugin-specific env dependency and log stack.
• deferred restart:
  • Return status PENDING_RESTART, do not report PASS early.
• invalid-isolation / profile-only shadow leftover:
  • Do not debug it as a normal runtime readiness bug first.
  • Classify it separately, remove or quarantine the incomplete shadow artifact, then retest with a dedicated shadow home.

Output Contract

• Deliverable:
  • Root cause category (A/B/C/D).
  • Config keys changed + old/new.
  • Wrapper path + --version test output.
  • Temp/state artifact paths if available.
  • Log evidence before/after (registered/ready/failed).
• Validation:
  • PASS: has registered + ready, no new failures.
  • PENDING_RESTART: config is correct but not restarted/applied completely.
  • FAIL: restarted but still failed.
• Compliance Verdict:
  • PASS|PENDING_RESTART|FAIL + short, unambiguous reason.