Inspect and diagnose an OpenClaw plugin from the CLI before enabling it

A plugin can look like a small package with a short README. In OpenClaw, the important question is larger: what will this code be able to register, read, call, or change once it is loaded by the Gateway?

The safest answer comes from an inspection record, not from a marketplace name or a successful install. OpenClaw separates a cold plugin inspection from runtime inspection. The first reads identity, source, manifest capabilities, policy state, and diagnostics without importing the plugin runtime by default. The second loads the module and reports what it actually registers. The official inspect and diagnose reference documents both modes.

Evidence status. The OpenClaw commands below come from the current documentation. The file listings, checksum, and narrow runtime observations are proposed operator tests, not hands-on results from this article. No plugin run or safety certification is claimed.

What the inspection should establish

Before enablement, you should be able to answer five plain questions:

• Did I receive the exact package, repository, archive, or local directory I intended to review?
• What does the plugin declare, and which credentials, files, services, or tools does that imply?
• What does OpenClaw see before loading the runtime?
• What does the plugin register when it is loaded in a disposable environment?
• What is the smallest environment in which I am willing to enable it, and how will I disable or remove it?

A native plugin deserves particular care. OpenClaw’s security policy places plugins and extensions inside the Gateway’s trusted computing base. Installing or enabling one gives it the trust level of local code running on that Gateway host. That is a trust-boundary statement, not a claim that every plugin is malicious. It does mean that a model sandbox or a narrow agent tool policy does not automatically contain in-process plugin code.

Prepare a boundary for the review

Use a disposable OpenClaw profile, workspace, operating-system user, or host when the plugin is unfamiliar. Keep production mailboxes, browser sessions, channel accounts, repositories, and long-lived credentials out of the first run. If the plugin needs a credential to start, create a test credential with the narrowest scope available, or stop the review.

Have the OpenClaw CLI available, the candidate’s exact source locator, and enough disk space to preserve the package and its inspection output. The plugin management documentation treats installation and enablement as separate operations, but installation still changes local state and may require capability consent.

Classify the artifact before you inspect its contents. A native OpenClaw plugin normally carries openclaw.plugin.json. Compatible Agent Plugins, Codex, Claude, and Cursor bundles use different manifest layouts. The manifest reference explains that OpenClaw reads the native manifest before loading plugin code and uses it for configuration validation. This makes the manifest useful evidence, but not a complete description of every runtime behavior.

1. Record the source and artifact

Start with provenance. Write down the publisher or repository owner, the exact package name, version, tag or commit, source type, download location, and date of review. Prefer an exact version or commit for the first trial. A moving tag makes it harder to prove that the files you reviewed are the files you later enabled.

OpenClaw supports npm, ClawHub, Git, local paths, archives, and marketplace sources. Its install reference documents explicit locators such as these:

openclaw plugins install clawhub:<package>
openclaw plugins install npm:<package>
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path-or-archive>

Do not treat the install command as the review itself. For a Git source, record the requested ref and the resolved commit if OpenClaw reports one. For an archive, keep the original file and record a SHA-256 checksum with the tool available on your system:

shasum -a 256 candidate.tgz

That checksum identifies the bytes you examined. It does not establish that the publisher is trustworthy.

Before unpacking an archive, list its contents without running anything:

tar -tf candidate.tgz | sed -n '1,200p'

The install documentation says native plugin archives need a valid openclaw.plugin.json at the extracted plugin root. An archive that contains only package.json is not enough for a native plugin install. That is a useful early failure because you can stop before the package becomes part of the managed plugin state.

2. Capture the cold baseline

Run the inventory before adding the candidate. Use the machine-readable form when you want to compare results later:

openclaw --version
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins doctor --json

Save the outputs after removing tokens, private paths, account identifiers, and message content. The list reference describes --verbose as the view that exposes format, source, origin, version, and activation metadata. Its JSON output also includes dependency status and registry diagnostics.

Keep warnings that existed before installation. A stale plugin entry, an unreadable registry, or a Gateway problem should remain labelled as a baseline condition. Otherwise, a later failure can be blamed on the candidate without evidence.

Use the read-only Doctor posture when you want a broader report. The Doctor CLI reference distinguishes advisory JSON and lint modes from ordinary guided Doctor runs. Ordinary Doctor may offer migrations or repairs, so do not use it as a supposedly read-only command when you are only trying to establish a baseline.

3. Inspect the candidate without importing its runtime

After installation or discovery, begin with the cold inspection:

openclaw plugins inspect <id> --json

According to the official diagnostic reference, this reports identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and detected MCP or LSP support without importing the plugin runtime by default. The JSON report can expose manifest contracts such as trusted tool policies before you enable or restart the plugin.

Read the result as a set of decisions, not as a score:

Do not read enabled as proof that the running Gateway has imported the module. OpenClaw documents plugins list as a cold inventory check. The same distinction applies to the default human-readable inspection result.

4. Compare the manifest with the files

Open the candidate’s metadata before asking the runtime to register anything:

sed -n '1,240p' <plugin-root>/openclaw.plugin.json
sed -n '1,240p' <plugin-root>/package.json
sed -n '1,240p' <plugin-root>/README.md
find <plugin-root> -maxdepth 2 -type f -print | sort

The first three reads are proposed static checks. They do not execute an entry point. Compare the manifest’s id, display name, configuration schema, entry metadata, setup requirements, provider environment variables, CLI declarations, channels, tools, hooks, MCP servers, and compatibility hints with the package contents and README.

Then search for operations that change the review boundary:

rg -n 'child_process|spawn|exec|fetch|https?://|process\.env|readFile|writeFile|unlink|install|upload|webhook' <plugin-root>

This search is a triage aid, not a security scanner. A match may be legitimate, and no match does not prove that the code is harmless. Generated files, dynamic imports, native dependencies, and code in transitive packages can sit outside a simple text search.

The manifest has an important limit. OpenClaw’s documentation says it is pre-runtime metadata and also says that runtime hooks and the full plugin entry point belong elsewhere. Treat it as a declaration to compare with code, not as an attestation that the code will do only what the declaration says.

5. Review external trust signals and capability consent

If the candidate comes from ClawHub, open its release audit and record the exact release, audit status, risk level, and findings. The ClawHub security-audit documentation says the review covers items such as plugin metadata, declared environment variables and permissions, install instructions, included files, and compatibility or capability metadata.

Read the result carefully. A Pass means that no visible issue above the documented low-risk threshold was found. It does not mean that the release is risk-free. Review, Warn, Pending, and Error are different states, and a higher risk level describes potential authority rather than proving malicious intent. Record the publisher, source, version, changelog, and any findings beside the audit result.

OpenClaw also presents capability consent for third-party plugins. The consent view can identify the plugin, version, source, integrity information, and declared channels, providers, tools, hooks, MCP servers, CLI commands, backends, skills, and dangerous configuration flags. Do not pass --accept-capabilities until the list matches the task you wrote down. Do not use --force as a substitute for that review; source confirmation and capability consent answer different questions.

If the plugin asks for a broad filesystem path, a long-lived credential, host command execution, or an unexplained network destination, the burden is on the task to justify that access. If you cannot reduce the access, keep the plugin disabled or reject it for a sensitive Gateway.

6. Load it only in a disposable runtime

Once the cold evidence is coherent, run the module-level checks in the disposable environment:

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

The runtime flag deliberately loads the plugin module and reports registered hooks, tools, commands, services, Gateway methods, and HTTP routes. Doctor reports load errors, manifest and discovery diagnostics, compatibility notices, and stale configuration references, but it does not query the running Gateway. That makes these useful checks, not a complete live test.

Compare the runtime registration list with the cold manifest and your task. If the plugin registers a CLI root, run the exact command path shown by the inspection report against dummy input. Do not invent a shorter command based on the package name. If the plugin creates a file, call an external service, sends a message, or launches a process, record the input, output, exit status, destination, and resulting files.

For a running Gateway, use a separate check:

openclaw gateway status --deep --require-rpc
openclaw health

A restart may be needed after changing plugin code or load paths. The documented inventory is not proof that the active Gateway imported the new runtime. Verify the actual Gateway process that serves the channel, particularly in a container or remote setup.

Keep the first live test narrow. A dummy Markdown file and a temporary output directory tell you more than a real mailbox does when the question is whether a summarizer writes outside its work area. Network observation through a test endpoint, local proxy, firewall log, or documented integration log can add evidence, but a quiet terminal is not proof that no network request occurred.

7. Build an evidence packet

A review is easier to challenge and repeat when the files have stable names:

plugin-review/
  metadata.txt
  baseline-list.json
  baseline-doctor.json
  inspect-cold.json
  manifest.txt
  file-list.txt
  static-search.txt
  inspect-runtime.json
  runtime-test.txt
  decision.md

In metadata.txt, record the plugin id, version, source locator, resolved commit or package version, checksum, OpenClaw version, operating system, profile, and review date. In decision.md, separate three labels:

• Documented: what the OpenClaw or plugin documentation says.
• Observed: what your commands and disposable test actually returned.
• Proposed: checks you have not run yet.

Keep the original output where it is safe, and create a redacted copy for sharing. Never include API tokens, cookies, OAuth material, full environment output, private transcripts, or production URLs merely to make the packet look complete.

When to enable, hold, or reject

Enable the plugin in the disposable environment only when its identity is clear, its authority is proportionate to the task, its runtime registrations match the cold evidence, and you have a recovery path. Promote it to a sensitive Gateway only after a separate decision about the host, credentials, data, and people who can reach that Gateway.

Hold the review when the source is moving or ambiguous, the manifest is missing or inconsistent, dependencies do not resolve, runtime registration reveals an undocumented capability, the audit is pending, or the first test needs real data. A missing fact is not evidence that the plugin lacks a capability. It is a reason to investigate or narrow the decision.

Reject the candidate when the artifact does not match the source you intended, the requested authority is unrelated to the task, the documentation conflicts with observed behavior, or the only usable test requires sensitive access you cannot justify. Popularity, a green audit, and a clean text search can all improve confidence without turning the plugin into trusted code.

Failure paths and rollback

If plugins inspect cannot find the id, start with openclaw plugins list --verbose and confirm the active profile and state directory. Do not guess an id from a display name.

If runtime inspection reports an SDK incompatibility or missing dependency, preserve the error and the cold report. The diagnostic reference points to updating the plugin or contacting its author; runtime inspection does not install dependencies or repair the package for you.

If Doctor reports that a plugin is present but blocked by path-safety checks, fix the preceding ownership or permission diagnostic and rerun the registry check. Do not delete the plugin entry simply because the loader refused the path.

If the cold inventory says the plugin is enabled but the running Gateway does not show its registrations, restart the Gateway that actually serves the channel and run the health check again. The difference is often a process-state problem, not proof that the manifest is wrong.

If the test produces an unexpected side effect, disable the plugin before investigating further:

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

The uninstall and update reference documents the dry run as a preview that makes no changes. The keep-files option can preserve the tracked managed directory while removing the plugin’s managed settings and install record, which is useful when evidence still needs to be examined. Save logs and checksums before cleanup, and do not confuse removal with proof that no earlier side effect occurred.

What this workflow cannot prove

Inspection cannot prove that a plugin will behave safely on every input or after every update. It cannot replace review of transitive dependencies, native modules, delayed network behavior, or the accounts and files already reachable by the Gateway. ClawHub audits are a useful signal, not a guarantee, and a native plugin remains trusted host code under OpenClaw’s documented model.

The point of the packet is narrower and more useful: before enablement, you can show what you received, what OpenClaw saw, what the module registered in a disposable environment, what you deliberately tested, and what remains unknown. That is enough to make a bounded operating decision. It is not a reason to stop asking questions.

Sources

• Inspect and diagnose plugins for cold inspection, runtime inspection, Doctor, and registry behavior.
• List installed plugins for inventory flags, dependency status, and the cold versus live distinction.
• Install plugins for source locators, archive requirements, Git installs, and local paths.
• Manage plugins for capability consent and trust information.
• OpenClaw plugin manifest for pre-runtime metadata, schemas, and bundle manifests.
• ClawHub security audits for audit status, risk levels, findings, and their limits.
• OpenClaw security policy for the trusted plugin boundary.
• Run Doctor for read-only advisory and lint postures.
• Uninstall and update plugins for dry runs, file preservation, and cleanup behavior.