A plugin I installed broke OpenClaw. How to recover.

A newly installed plugin that breaks OpenClaw is one of the most disruptive things that can happen to a running deployment. The gateway refuses to start, critical tools stop working, or the agent behaves in ways it was not behaving before the install, often with no immediately obvious connection to the plugin you just added. The good news is that plugin-induced failures are almost always recoverable without data loss, and the core recovery path is the same regardless of which plugin caused the problem. This article covers how to isolate the specific failure, disable or remove the offending plugin, restore normal operation, and then decide whether the plugin is worth fixing or whether you are better off without it.

Throughout this article you will see indented blocks like the ones below. Each one is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. If the gateway is down, in which case you will need SSH access to the server. The SSH steps are clearly marked.

Immediate triage: what broke?

The first step in any plugin recovery is identifying exactly how things are broken and what specifically stopped working. The recovery path differs depending on whether the gateway is still running or has stopped entirely. Start here:

• Gateway won’t start: You installed the plugin, restarted the gateway, and now it will not come back up. You have no agent access at all. You need SSH access to recover.
• Gateway starts but agent is broken: The gateway is running and you can send messages, but the agent is not responding correctly, tools are failing, or behavior has changed in a way that breaks your workflow.
• Specific tool stopped working: A tool that worked before the install now returns errors or does nothing. Other tools still work.
• Memory or channel integration broken: The plugin conflicts with a specific system: memory recall fails, Telegram stops receiving messages, Discord goes quiet.

Check the current gateway status. Run: openclaw gateway status. Is the gateway running? If it is running, check the plugin list: show me all currently loaded plugins and whether each one initialized successfully. If any plugin shows an initialization error, that is likely the cause of the breakage.

If the agent is completely unreachable, skip to the SSH recovery section below. If the agent is reachable, the triage commands below will help you confirm that the newly installed plugin is the actual cause of the problem before you take any irreversible recovery action.

Check the logs before touching anything

Before disabling or removing the plugin, read the gateway logs. The logs almost always contain the exact error that explains what the plugin broke and why it broke it. Reading the logs first means you understand the problem well enough to fix it properly rather than just turning the plugin off and hoping the next attempt goes better without knowing what went wrong the first time.

Show me the gateway logs from the last 15 minutes. I am looking for any errors that appeared after I installed a new plugin. Run: journalctl -u openclaw -n 200 --no-pager. Show me the full output. I want to see the exact error messages, not a summary.

Common plugin error patterns in the logs:

• Module not found: The plugin requires an npm package that is not installed. The log shows Cannot find module 'package-name'.
• Config validation failed: The plugin requires a config key that is missing or in the wrong format.
• Port conflict: The plugin tries to bind to a port that is already in use by another process.
• Tool registration conflict: Two plugins are trying to register the same tool name, causing one to fail.
• Uncaught exception during init: The plugin threw an unhandled error during initialization. The stack trace in the log shows where.

In the gateway logs, find the first error that appeared after the plugin install. Show me: the exact error message, the plugin name it is associated with, and any stack trace. Tell me what the error means in plain terms and what the likely fix is before I take any recovery action.

Recovery: gateway is still running

If the gateway is running and you can still talk to the agent, the recovery is relatively straightforward. Disable the broken plugin in the config, restart the gateway cleanly, and then confirm that normal behavior is fully restored before doing anything else. Do not try to diagnose the root cause while the plugin is still enabled and potentially causing ongoing instability.

I need to disable the plugin I just installed. Read my openclaw.json and find the plugins.entries section. Show me the entry for [plugin name]. I want to set its enabled field to false. Do not remove it yet, just disable it. Show me the change before applying it.

After confirming the change looks correct:

Apply the config change to disable [plugin name] by setting enabled to false. Use the config.patch approach to make a targeted change rather than rewriting the full config. After applying, restart the gateway and wait for it to come back up. Then show me the gateway status and confirm the plugin is no longer loaded.

Once the gateway is back up with the plugin disabled, verify that the behavior that was broken before is now working again. Do not assume the disable fixed everything. Test the specific things that broke.

The plugin has been disabled and the gateway is back up. Run a quick recovery check: (1) List all loaded plugins and confirm the disabled plugin is not in the list, (2) Run the tool or behavior that was broken before and confirm it works now, (3) Check the gateway logs for any new errors after the restart. Report pass or fail for each check.

Recovery: gateway won’t start (SSH required)

If the gateway is not starting, you cannot use the agent to fix the problem because there is no agent to talk to. You need direct SSH access to the server to edit the config file manually and restart the service. This situation is the single most important reason to always keep SSH access working, to store your server credentials securely where you can find them at 2am, and to verify SSH access is operational before installing any plugin on a production instance.

SSH recovery steps (run these on the server, not in the agent chat):

[SSH RECOVERY: run this in your terminal, not the agent chat] Connect to the server: ssh [email protected]. Then check the gateway error: journalctl -u openclaw -n 50 --no-pager. This shows the startup error. Note the plugin name in the error before editing anything.

[SSH RECOVERY] Edit the config to disable the broken plugin: nano ~/.openclaw/openclaw.json. Find the plugins.entries section, locate the plugin that caused the error, and change "enabled": true to "enabled": false. Save the file with Ctrl+X, then Y, then Enter. Then restart: systemctl restart openclaw. Watch the status: systemctl status openclaw.

If you are not comfortable editing JSON directly in a terminal text editor, an alternative approach is to rename the plugin’s config entry key so OpenClaw does not load it:

[SSH RECOVERY alternative] If editing the JSON directly feels risky, use Python to safely disable the plugin: python3 -c "import json; c=json.load(open('/home/node/.openclaw/openclaw.json')); c['plugins']['entries']['PLUGIN_NAME']['enabled']=False; json.dump(c,open('/home/node/.openclaw/openclaw.json','w'),indent=2); print('done')". Replace PLUGIN_NAME with the actual plugin key. Then restart: systemctl restart openclaw.

After the gateway restarts successfully following your SSH edits, reconnect to the agent through your normal channel (Discord, Telegram, etc.) and confirm it is responding to messages. Then check the startup logs to confirm the most recent gateway start was clean with no remaining plugin errors.

Identifying what the plugin actually broke

With normal OpenClaw operation fully restored, the next step is understanding exactly what the plugin did to break things and why. This knowledge determines whether you can fix the plugin config and re-enable it, or whether the plugin itself is the problem.

Now that the gateway is running normally again, help me understand what the plugin broke. Review the error from the logs we captured earlier. Based on that error, what specifically did the plugin do wrong? Was it: (1) a missing config key I need to add, (2) a missing npm dependency I need to install, (3) a conflict with another plugin, (4) a bug in the plugin itself, or (5) something else? Tell me which category this falls into and what the specific fix would be for each.

The root cause determines the next step:

• Missing config key: Add the required config to openclaw.json under the plugin’s config block, then re-enable and restart. Check the plugin’s documentation for required fields.
• Missing npm dependency: Install the dependency manually (npm install package-name in the OpenClaw directory), then re-enable and restart.
• Plugin conflict: Two plugins cannot coexist. Decide which one you need more and keep only that one enabled.
• Plugin bug: The plugin itself has a code defect. Options are: wait for a fix from the author, report the bug to the author, or remove the plugin entirely.

For the root cause identified: walk me through the fix step by step. Do not apply any changes yet. Show me the complete plan including what files need to change, what commands need to run, and what verification step confirms the fix worked. I want to review the plan before we execute it.

Fixing missing plugin configuration

The most common fixable plugin failure is missing required configuration. Most plugins require at least a few config keys to be present in openclaw.json under their entry’s config block. If those keys are missing, the plugin fails to initialize and the gateway either crashes or loads without the plugin.

Show me the current config entry for [plugin name] in openclaw.json. Then show me what config the plugin requires based on its documentation or SKILL.md. What required keys are missing from my current config? List every missing key and what value format it expects.

Add the missing config values before re-enabling the plugin. If any required value is an API key or credential, retrieve it from the service before making the config change so the plugin can be tested immediately after enabling.

Add the missing config keys to the [plugin name] entry in openclaw.json. Use config.patch to make a targeted update rather than rewriting the full config. After adding the config, re-enable the plugin (set enabled to true), restart the gateway, and check the logs to confirm the plugin initialized successfully this time.

Diagnosing and resolving plugin conflicts

Some plugins conflict with each other because they try to register the same tool name, use the same internal event, or manipulate the same part of the agent’s context. A conflict typically surfaces as one plugin initializing successfully while the other fails with a registration error, or both loading but one silently overriding the other’s behavior.

I suspect a plugin conflict. Show me all enabled plugins and the tools each one registers. Are there any duplicate tool names registered by more than one plugin? Are there any plugins that claim to handle the same event or capability? If so, which plugin was working before the new install and which is the new one?

When two plugins conflict, the resolution is almost always to keep one and disable the other. The exception is when a plugin is a newer version of an older one, in which case the older one should be disabled and fully removed to avoid the conflict. This is the exact situation described in AGENTS.md for the memory plugin pair: the stock memory-lancedb must stay disabled because it shadows the pro version’s tool registrations.

For the plugin conflict I am seeing: which plugin is the one I need and which is the one causing the conflict? Confirm which one was working correctly before the new install. Then: disable the conflicting plugin, verify the needed one is still enabled and correctly configured, restart the gateway, and confirm the tool or behavior that was broken is now working again.

Removing a plugin completely

If the plugin cannot be fixed (it has a bug the author has not addressed, it is fundamentally incompatible with your setup, or it does not do what you needed), the clean path is full removal rather than leaving it disabled in the config.

I want to fully remove [plugin name] from my OpenClaw installation. Show me: (1) the current plugin entry in openclaw.json that needs to be removed, (2) the npm package name if it was installed as an npm package, (3) any files or directories the plugin may have created in the workspace. Then show me the removal plan before executing it.

Plugin removal involves three distinct steps: removing the config entry from openclaw.json, uninstalling the npm package if the plugin was installed via npm, and cleaning up any files or directories the plugin created during its operation. All three steps are needed for a genuinely clean removal. Leaving the npm package installed after removing the config entry is harmless in terms of functionality but wastes disk space and creates confusion during future audits. Leaving plugin-created files is usually harmless unless the plugin wrote to a shared location that another plugin, the memory system, or another system component also uses.

Execute the plugin removal: (1) Remove the [plugin name] entry from plugins.entries in openclaw.json, (2) If the plugin was installed as an npm package, run the uninstall command, (3) Check for any files the plugin created and remove them if safe to do so. After each step, confirm it completed before moving to the next. Then restart the gateway and verify clean startup with no plugin-related errors.

Preventing plugin breakage in the future

The three-review protocol in AGENTS.md (Ghost manual review, Gambit review, Advisor review) exists specifically to catch these problems before a plugin is ever installed on a live instance. Beyond following that protocol rigorously, several additional practices reduce the practical risk of a new plugin taking down a running deployment even when the reviews look clean.

Test in a staging environment first. If you have access to a second server or even a local OpenClaw install on your own machine, test every new plugin there before installing it on your production instance. A plugin that breaks a staging environment costs nothing except the time to recover the staging box. A plugin that breaks production costs your agent’s uptime, your own time to recover it via SSH, and any tasks or workflows that depended on the agent being available during the outage.

Read the plugin source before installing. The AGENTS.md security audit protocol requires running the security scanner against any new plugin before install. Beyond the automated scan, reading the plugin’s initialization code directly is worth the few minutes it takes. The first 100 lines of index.ts or index.js tell you what the plugin does on startup, what external resources it requires, and whether it interacts with any parts of OpenClaw that your other plugins already depend on.

Back up openclaw.json before installing. A simple copy of the config file before any plugin install gives you a clean rollback target. If the install breaks things, you can restore the backup and restart rather than manually editing a broken config.

Before I install any future plugin: create a backup of openclaw.json. Copy it to ~/.openclaw/openclaw.json.backup-YYYY-MM-DD with today’s date. Also show me the current list of enabled plugins so I have a reference for what was working before the install. I want this snapshot before any future plugin change.

What to do if you have no SSH access

If the gateway is down and you do not have SSH access to the server, your options narrow significantly. The correct response to this situation is to restore SSH access first rather than trying to recover the gateway remotely. There is no path to recovering a non-starting gateway without either SSH access or physical access to the machine.

If you are running on a cloud VPS (DigitalOcean, Vultr, Hetzner, Linode, etc.), all providers offer a browser-based console or recovery console in their control panel that does not require SSH. Log into the provider’s control panel and use the web console to access the server directly. The commands are the same as SSH once you are in the console.

[SSH RECOVERY via cloud console] Access your VPS provider’s web console for this server. Once you have a terminal prompt, run: journalctl -u openclaw -n 50 --no-pager to see the startup error. Then edit the config: python3 -c "import json; c=json.load(open('/home/node/.openclaw/openclaw.json')); [c['plugins']['entries'].update({k: {**v, 'enabled': False}}) for k,v in c['plugins']['entries'].items() if v.get('enabled')]; json.dump(c,open('/home/node/.openclaw/openclaw.json','w'),indent=2)". This disables ALL plugins as a recovery measure. Then restart: systemctl restart openclaw.

Disabling all plugins at once as an emergency recovery measure gets the gateway back online quickly, at the cost of losing all plugin functionality temporarily until you re-enable the safe ones. Once you are back online and can talk to the agent through your normal interface, re-enable plugins one at a time, with a gateway restart and health check between each, to identify which specific plugin caused the crash without risking another full outage.

The gateway is back online after I disabled all plugins. Now I need to re-enable them one at a time to find which one caused the crash. List all plugins currently in my config, show me which ones are disabled, and tell me the order in which to re-enable them (lowest risk first). I will re-enable one, restart the gateway, and confirm it starts before moving to the next.

Recovering from a partial or failed plugin install

Sometimes a plugin install fails partway through the process. The npm package downloads but does not fully install, the config entry gets written but with malformed JSON due to an interrupted write, or the plugin directory exists in node_modules but is missing files and therefore incomplete. These partial install states produce confusing errors that look quite different from a clean install failure, which makes them harder to diagnose without knowing to check for partial state specifically.

I may have a partial plugin install. Check for signs of an incomplete installation: (1) Is the plugin entry in openclaw.json complete and valid JSON? (2) If the plugin was installed as an npm package, does its directory exist in node_modules and is it complete (has package.json, has an entry point file)? (3) Are there any temp files or lock files from the install that might indicate it was interrupted? Show me what you find.

A partial npm install can be fixed by running the install again from a clean state. The clean state requires removing the incomplete package directory and the package-lock.json entry before reinstalling:

For a partial npm plugin install: (1) Navigate to the OpenClaw installation directory. (2) Remove the incomplete plugin package: rm -rf node_modules/[package-name]. (3) Remove the package from package.json dependencies if it was added. (4) Run npm install to clean up the lock file. (5) Then reinstall the plugin properly: npm install [package-name]. After the clean reinstall, check whether the install is complete before adding the config entry.

Checking plugin health after recovery

After recovering from a plugin-induced failure and disabling or removing the offending plugin, it is worth doing a broader health check on the remaining installed plugins. A crash caused by one plugin can sometimes leave other plugins in a temporarily inconsistent state, particularly if the crashing plugin was interacting with shared OpenClaw resources such as the memory database, the tool registry, or the session state at the moment the crash occurred.

Run a plugin health check after the recovery. For each enabled plugin: (1) confirm it appears in the plugin list as successfully loaded, (2) run one tool call that exercises that plugin’s core functionality and confirm it returns the expected result, (3) check the gateway logs for any warnings from that plugin since the last restart. Report pass or fail for each plugin.

Pay particular attention to the memory plugin after any unclean gateway shutdown. The memory database (LanceDB) writes to disk continuously during normal operation, and an unclean shutdown caused by a plugin crash can occasionally leave the database in a state that produces errors or unexpected empty results until the database is repaired or rebuilt. The symptom to watch for is memory recall returning empty results or explicit database errors immediately after recovery, even when you have memories that were stored before the crash and should still be present.

After recovering from the plugin crash, verify the memory system is intact. Run memory_stats and confirm the record count looks reasonable. Run a memory_recall query for something I have stored recently and confirm it returns results. If memory_stats returns zero records or recall returns empty when memories should exist, the database may need attention. Report what you find.

Documenting the incident

A plugin-induced gateway crash is worth documenting carefully in the workspace, both for your own future reference and because clear documentation helps avoid a repeat of the exact same incident when you consider a similar plugin in the future. The bug log entry for this incident should capture what happened in enough detail that a future reader (including yourself three months from now) understands the cause, the impact, and the fix.

Document this plugin incident in memory/bug-log.md. Create the file if it does not exist. Add an entry with: date and time of the incident, plugin name and version, what the plugin was supposed to do, what actually happened (exact error from logs), how long the gateway was down, how it was recovered, the root cause, and whether the plugin is now disabled, fixed and re-enabled, or removed. This is for my records.

Also update AGENTS.md if the incident revealed a gap in the existing install protocol. If you installed the plugin without following the full three-review protocol and that shortcut contributed to the failure, document that explicitly: the protocol exists because of exactly this kind of incident. If the crash revealed a new category of plugin conflict to watch for during future reviews, add a note to the protocol so the same conflict pattern gets flagged during review of the next plugin candidate rather than being discovered the hard way a second time.

When to fix vs. when to remove a broken plugin

After recovering from a plugin failure, you face a decision: invest time fixing the plugin config or dependency issue so it works correctly, or remove the plugin and accept that the functionality it was supposed to provide is not available in your setup. The right answer depends on how much you need what the plugin does and how tractable the root cause is.

Fix and re-enable when:

• The root cause is a missing config key that you can provide
• The root cause is a missing npm dependency that you can install
• The plugin author has confirmed the bug and a fix is available or imminent
• The plugin provides functionality you cannot get another way

Remove when:

• The plugin has a code bug the author has not addressed and is not actively maintaining the plugin
• The plugin conflicts with another plugin you need more
• The plugin installs correctly but does not do what you needed it to do
• The security audit revealed concerns you are not comfortable with
• A ClawHub crisis report (like the March 2026 incident) has flagged the plugin as malicious

Help me decide whether to fix or remove [plugin name]. Based on the root cause we identified: is this fixable with changes I can make, or does it require a fix from the plugin author? Does the functionality it provides justify the time to fix it? Is there an alternative (a different plugin or a skill that does the same thing) that I should use instead?

Using a skill instead of a broken plugin

Some plugins can be functionally replaced by skills, which are Markdown-based prompt instructions rather than executable code. Skills have no initialization phase, no npm dependencies, and no capability to crash the gateway because they are not code at all. If the functionality you wanted from the broken plugin is primarily about how the agent behaves, what it prioritizes, or how it structures its output, rather than about adding a genuinely new tool that calls an external API or runs a system command, a skill is almost always a better choice and worth trying as the replacement.

The plugin I was trying to install was supposed to do: [describe what the plugin was for]. Is there a skill in my current workspace or on ClawHub that provides similar functionality without requiring a plugin? List any skills that cover this use case. Also tell me: could this be implemented directly in SOUL.md or AGENTS.md as a behavioral instruction rather than requiring a plugin at all?

The guiding principle is straightforward: code-level plugins should be reserved for functionality that genuinely requires a new tool call, an external API integration, or system-level access that the agent cannot achieve through existing tools. Behavioral changes, workflow instructions, persona adjustments, and output formatting preferences do not need plugins. They need well-written instructions in SOUL.md, AGENTS.md, or a skill file. A plugin that exists only to instruct the agent to behave differently is a plugin you almost certainly do not need, and replacing it with a skill eliminates the crash risk entirely.

Frequently asked questions

Look for the plugin name in the error message or stack trace. OpenClaw log entries typically include the component or plugin name. If the error is in a stack trace, look for file paths that contain the plugin’s package name. If the log is not specific enough, disable all non-essential plugins simultaneously, restart, and confirm the gateway starts clean. Then re-enable plugins one at a time (with a restart after each) until the error reappears. The plugin you re-enabled immediately before the error returned is the cause.

Not as a first step. Reinstalling without addressing the root cause typically produces the same failure. Disable the plugin first, restore normal operation, read the logs to understand the specific error, fix that error (missing config, missing dependency, etc.), and then re-enable rather than reinstall. Reinstalling is only appropriate when the plugin package itself is corrupted or an incomplete install left broken files, which is rare.

Possibly. Some plugins interact with the memory system either directly (by writing memories) or indirectly (by consuming context in ways that affect recall). The most common memory-related plugin conflict is a second memory plugin being installed alongside the existing one, causing one to shadow the other’s tool registrations. Check whether the new plugin has any memory-related tools (memory_store, memory_recall, memory_list) and compare against your existing memory plugin. If both register the same tools, disable the new one.

Report it to the plugin author first, not ClawHub directly. Find the plugin’s repository (usually linked in its ClawHub listing) and open an issue there with the error from your gateway logs, your OpenClaw version, and what you were trying to do when the error occurred. If the plugin appears to be malicious rather than just broken (exfiltrating data, running unexpected commands, making external network calls that were not disclosed), report it to the ClawHub security team immediately rather than waiting for the author to respond.

Most cross-installation plugin failures come down to one of three things: a different OpenClaw version (the plugin was built and tested against a version you are not running), a different operating system (a Linux plugin on macOS, or vice versa), or a different configuration (the other person has a config key set that your install does not have). Ask the person it worked for to share their OpenClaw version, OS, and the relevant section of their plugin config. Compare against yours to find the difference.

Those are stale log entries from before the removal. Gateway logs persist across restarts unless they are explicitly cleared. The entries you are seeing are from when the plugin was still installed. Check the timestamp on those log entries: if they predate the plugin removal, they are historical records, not current errors. The reliable signal for a clean removal is a gateway startup log (the lines generated at the most recent restart) that contains no errors related to the removed plugin.

Three steps before any install: (1) Run the security audit scanner from AGENTS.md against the plugin’s SKILL.md or source: python3 skills/agents-skill-security-audit/audit.py. Review every flagged line manually, the scanner has false positives but also catches real issues. (2) Read the plugin initialization code (first 100 lines of index.ts). Look for external network calls, file writes outside the workspace, and exec calls. (3) Check whether the plugin requires any permissions beyond what its stated purpose needs. A text processing plugin that requires exec access to the full system is suspicious. A messaging plugin that requires network access is not.

Go deeper