When an OpenClaw Plugin Changes: A Scan, Trial, and Rollback Runbook

June 16, 2026 · OpenClawBlog Team

A plugin can appear harmless because its visible job is small. It may format a document, add a channel, or expose one command. The code still runs inside the environment that owns the Gateway, with whatever files, credentials, network access, and host permissions that environment already has.

The useful question is therefore narrower than whether a plugin is trusted in general: what changed, what can the plugin reach here, and can the operator return to a known-good state if the answer is wrong?

This runbook focuses on behavior drift after a plugin has been downloaded, enabled, updated, or edited. It combines a cold inspection, a disposable canary run, an evidence record, and a layered rollback. The commands are documentation-derived examples. No OpenClaw runtime was operated for this article.

The boundary comes before the scan

OpenClaw's security policy treats native plugins as part of the Gateway's trusted computing base. Installing or enabling one gives it the trust level of local code on that Gateway host. Native plugins run in process, so an agent-side sandbox does not turn the plugin itself into an unprivileged process. The policy's trusted plugin guidance is the starting point for this decision.

That is different from a skill or a tool policy. OpenClaw's sandbox and tool-policy documentation separates the place where tools run from the tools an agent is allowed to call. Those controls matter for the agent workflow, but they do not change the operating-system privileges of in-process plugin code. If the plugin is unfamiliar, use a separate operating-system user, disposable host, container, or virtual machine for the trial. A separate Gateway is the cleaner boundary when the operators or data are not mutually trusted.

There is also an install-time boundary. OpenClaw's tool-permissions documentation says that installing or updating a plugin runs executable code and that arbitrary npm, Git, local, archive, and marketplace sources can produce an installation warning. Passing --force acknowledges a reviewed source; it does not bypass the remaining install policy or safety checks. Treat the install directory as code before the plugin has loaded.

Two historical advisories explain why this distinction is worth writing down. The February 21, 2026 advisory for plugin runtime command execution lists OpenClaw versions through 2026.2.17 as affected and versions from 2026.2.19 as patched. Its important point is that runtime helpers do not create an extra sandbox boundary. The March 27, 2026 advisory for local plugin and hook installation describes arbitrary code execution through an attacker-controlled .npmrc, a Git dependency, and the installer path; its record lists versions through 2025.3.23 as affected and 2026.3.24 as fixed.

Those ranges belong to the advisory records. They are not a current diagnosis of your installation. Check openclaw --version, the current advisories, and the source path you intend to use before beginning a trial.

Prepare a disposable lane

Write the boundary before copying the package. A useful trial has:

a fixed plugin source, version, tag, commit, or digest;
a disposable Gateway and workspace, preferably under a separate host or operating-system account for a native plugin;
synthetic files and test accounts rather than customer data, browser profiles, production repositories, or long-lived tokens;
the smallest tool policy and filesystem exposure that can answer the test question;
a clean baseline of the configuration, plugin inventory, workspace, processes, and relevant logs;
a named stop condition, such as an unexplained upload, a secret request, an undocumented hook, or a write outside the test boundary.

Keep a copy of the exact artifact. For an npm package, use an exact version or the documented pinning option. For Git, record the requested ref and the resolved commit. OpenClaw's plugin installation reference records source and integrity information for later updates and uses a staging directory before an accepted package replaces the installed one. That helps with recovery, but it does not remove the need to inspect the source.

Make a baseline that another operator could understand. Save the output of a plugin inventory, the active version, the source locator, the configuration hash, the test workspace tree, and the process or network observations you intend to compare. Redact tokens, cookies, private paths, message contents, and account identifiers before sharing the record.

Start with a cold inspection

Do not begin by importing the runtime on a trusted Gateway. OpenClaw's CLI distinguishes a cold inspection from a runtime inspection:

openclaw plugins list --enabled --verbose --json
openclaw plugins inspect <plugin-id> --json

The --json inspection is the first inventory of identity, source, manifest data, policy state, install metadata, and diagnostics. Read it as a set of questions, not as a safety score. Check the plugin ID, source type, version, enabled state, declared tools, hooks, channels, providers, services, configuration fields, environment variables, MCP entries, and any dangerous or privileged capability.

Compare the manifest with the package. Read the entry point, package metadata, lockfile, install scripts, post-install hooks, build scripts, and every file named by the manifest. A declaration is not an attestation. The runtime may import transitive packages, construct URLs dynamically, read environment variables, or invoke a helper that the manifest does not make obvious.

A small static triage can make this comparison repeatable:

shasum -a 256 ./plugin-archive.tgz
find ./plugin -maxdepth 3 -type f -print
rg -n 'child_process|spawn|exec|eval|fetch|axios|http|https|process\.env|\.npmrc|install|postinstall' ./plugin

These are search aids, not a security scanner. A match may be necessary for the plugin's job, and a clean result does not rule out generated code, native modules, delayed network activity, or behavior in dependencies. Record each finding with its file, purpose, destination, and relationship to the task.

Classify the result before proceeding:

Bounded: the behavior is documented and fits the disposable authority you prepared.
Broad but explainable: the plugin may be useful, but the workspace, account, or tool policy must become narrower.
Unexplained: the source or documentation does not account for the behavior. Hold the trial.
Unsafe to test here: installation or startup needs production secrets, destructive access, or an unreviewable external action. Reject the environment, not necessarily the author's intent.

Use runtime inspection only in the canary

OpenClaw documents openclaw plugins inspect <plugin-id> --runtime --json as the path that loads the plugin module and reports runtime registrations such as tools, hooks, services, Gateway methods, and plugin-owned commands. That makes it valuable evidence. It also means it is code execution.

Run it only in the disposable lane, after the cold inspection:

openclaw plugins inspect <plugin-id> --runtime --json

Compare the runtime result with the cold manifest and the task contract. An extra registration is not automatically malicious, but it is a capability change that needs an explanation. A missing registration may indicate a build, dependency, compatibility, or configuration problem. Preserve both reports; deleting the failed package too early removes the comparison that explains what happened.

If the source or manifest has changed in a local development checkout, OpenClaw documents a plugin reload operation. For a package install or update, make sure the Gateway that serves the real channel has applied the change. Depending on how the Gateway is managed, that may mean an automatic restart or an explicit openclaw gateway restart. Verify the serving process, not only the cold CLI output. The plugin management documentation describes reload application state and the way failed runtime application remains visible.

Run a canary that can fail safely

The first functional test should be deliberately uninteresting. Give the plugin a fixed fixture with a known expected result. Then add cases that test the boundary rather than merely the happy path:

a normal input that should finish without asking for new authority;
an empty, malformed, or unavailable input that should produce a bounded error;
content containing an instruction that tries to redirect the agent or request a secret;
a request that would require a tool, file, account, or network destination outside the declared contract;
a repeated run from a clean workspace, so you can see whether the first run left state that the second run silently depends on.

These are proposed acceptance tests, not hands-on results from this article. Observe more than the final answer. Record files created or modified, permissions, child processes, network destinations, authentication prompts, Gateway logs, generated configuration, and external messages. If the plugin calls a service, use a test endpoint or account and record the data category sent. A correct-looking answer with an unexplained side effect is a failed boundary test.

Keep the tool policy separate from the plugin trust decision. OpenClaw's tool-policy documentation says that deny rules win and that tool policy filters callable tools by name; it does not inspect every side effect inside an allowed exec call. A read-only agent therefore needs a policy and a filesystem or host boundary that actually enforces read-only behavior. Do not label the canary isolated because one control says sandbox.

Define what counts as behavior drift

A plugin has drifted when the artifact, capability surface, or side effects no longer match the recorded approval. Useful triggers include:

a changed archive hash, resolved commit, dependency lockfile, or install source;
a new manifest capability, environment variable, hook, route, provider, tool, or service;
a new process launch, filesystem path, network destination, or outbound data category;
a different result after an update, even when the visible feature still works;
a runtime registration that was absent from the cold inspection;
a new request for a credential or permission that was not part of the task contract.

When an update is planned, preview it first:

openclaw plugins update <plugin-id> --dry-run

Review the source, selector, integrity information, dependency changes, and capability differences before allowing the replacement. OpenClaw's update reference says tracked updates reuse the selected source and that ambiguous ownership fails closed without changing package files, configuration, or the installed index. That is useful protection against a confused update, but it does not tell you whether the new code is appropriate for your workload.

Contain first, investigate second

If the canary or a production review shows unexpected behavior, stop the next invocation:

openclaw plugins disable <plugin-id>

Preserve the suspect artifact, cold and runtime reports, logs, configuration diff, process evidence, and test inputs. Do not overwrite the package with a hurried reinstall before recording what changed. If the plugin started a process, stop it using the host's normal process controls. If a credential was exposed, sent, or used unexpectedly, revoke or rotate it through the issuing provider.

Then confirm that the active Gateway has applied the disabled state. A plugin that remains loaded in a running process is not contained merely because the configuration file changed. Use the documented reload or restart path and check the actual Gateway generation or health result.

Choose the smallest rollback that works

There are several different recoveries, and they should not be collapsed into one command.

Revert the package. For a tracked npm plugin, preview and install the known-good exact version through the tracked update path:

openclaw plugins update @example/openclaw-plugin@1.4.1 --dry-run
openclaw plugins update @example/openclaw-plugin@1.4.1

For a Git source, review and reinstall the known-good commit using the same source family. An explicit source acknowledgement may be required. Do not silently move from Git to npm or from one publisher to another. The goal is to restore the artifact you reviewed, not merely to make the plugin name appear again.

Remove the package while keeping evidence. Preview removal before changing the install:

openclaw plugins uninstall <plugin-id> --dry-run
openclaw plugins uninstall <plugin-id> --keep-files

The uninstall and update reference documents the dry run, ownership checks, and --keep-files option. Uninstalling settings and package records can stop future loading, but it does not undo a file write, a database change, a message, or a request already sent to a provider.

Restore state. If the plugin changed OpenClaw configuration, SQLite state, workspace files, or other durable material, use the verified recovery point created before the change. OpenClaw's backup documentation describes a verified archive and restoration into a new, empty staging directory:

openclaw backup create --output <protected-backup-directory> --verify
openclaw backup verify <archive>
openclaw backup restore <archive> --target <new-empty-directory>

The archive can contain credentials, authentication profiles, sessions, and workspace data, so protect it like live state. Restoration is intentionally not an in-place merge. It is also time travel: approvals and delivery state roll back, and channel credentials with ratchet state may need relinking. Review the manifest, paths, ownership, and provider state before activating a restored Gateway.

Do not use a core-package downgrade as a shortcut for every plugin problem. OpenClaw's rollback and recovery guide says that downgrading the package does not reverse configuration or database migrations. A matching verified pre-update backup is required when state has moved beyond the older release's supported format. Keep the Gateway and other writers stopped while restoring, and preserve the current state separately first.

Failure paths that deserve a hard stop

Runtime inspection needs the trusted host: move the test to the disposable Gateway. Do not grant a native plugin production credentials to find out what it registers.
The install displays a warning: read the source and findings. Do not add --force as a reflex. If the warning cannot be explained, defer the install.
The plugin appears in the inventory but not in the serving Gateway: check the actual process, reload or restart it, and keep the cold and runtime evidence separate.
Ownership is ambiguous: let the documented fail-closed behavior stand. Refresh the registry or repair the stale state before attempting update or uninstall again.
An external effect already happened: local rollback is incomplete. Inspect provider logs, revoke exposed credentials, and identify recipients or records that may need manual repair.
Several operators share one Gateway: do not use a plugin, skill folder, or approval prompt as a multi-tenant security boundary. Split the Gateway, host, or operating-system account according to the trust relationship.

The decision record to keep

For each plugin, keep one short record containing the source and digest, OpenClaw version, Gateway host, workspace and account boundary, cold inspection, runtime registration, test fixture, observed side effects, decision, rollback location, and review owner. Mark each conclusion as documented, observed in your own environment, or proposed for a future test.

I would approve a plugin only for the workload that the evidence covers. A clean canary is not permission to move the same artifact into a broader workspace. A green registry or audit signal is useful context, but OpenClaw's security policy explicitly describes multiple static and runtime validation layers rather than one scanner that establishes the boundary.

The reliable promise is modest: a fixed artifact, a small test lane, a visible capability change, and a recovery path make mistakes easier to contain. They do not prove that a plugin will behave safely on every input or after every update. That remaining uncertainty is the reason to keep the plugin's authority narrow and the rollback evidence intact.

Sources

Sources accessed 2026-09-13. Official documentation pages do not list publication dates; advisory publication dates are recorded below.