obsidian-rag/docs/troubleshooting/MISSING_OPENCLAW_HOOKS_ERROR.md

Troubleshooting: "missing openclaw.hooks" Error

Symptoms

When installing a plugin using openclaw plugins install --link <path>, the following error appears:

package.json missing openclaw.hooks; update the plugin package to include openclaw.extensions (for example ["./dist/index.js"]). See https://docs.openclaw.ai/help/troubleshooting#plugin-install-fails-with-missing-openclaw-extensions
Also not a valid hook pack: Error: package.json missing openclaw.hooks

Root Cause

This error message is a misleading fallback cascade that occurs when the plugin installation fails for a different reason. The error message suggests the problem is a missing openclaw.hooks field, but this is actually a secondary error that appears because the primary plugin installation failed.

How the Error Cascade Works

1. When --link is used with a local plugin path, OpenClaw first attempts to install the plugin via installPluginFromPath()
2. The installation flow calls installPluginFromDir() → installPluginFromSourceDir() → detectNativePackageInstallSource()
3. If detectNativePackageInstallSource() returns false (e.g., due to a dangerous code scan failure), it falls through to installPluginFromPackageDir()
4. When that also fails (e.g., due to child_process usage being flagged), the code falls back to tryInstallHookPackFromLocalPath()
5. The hook pack installer calls ensureOpenClawHooks(), which expects a hooks array in the manifest
6. Since your plugin has no hooks field, it throws "missing openclaw.hooks"

Primary vs Secondary Errors

The primary error blocking installation is:

Plugin "obsidian-rag" installation blocked: dangerous code patterns detected: Shell command execution detected (child_process)

The secondary error ("missing openclaw.hooks") is a fallback diagnostic that appears because:

• The plugin installation path failed
• OpenClaw tried to interpret the path as a hook pack as a last resort
• Hook packs require a hooks field, which normal plugins don't have

Common Primary Errors

1. Dangerous code patterns detected: Plugins using child_process, eval(), file system operations, or network requests may be blocked
2. Plugin ID mismatch: The id in openclaw.plugin.json doesn't match expected values
3. Missing openclaw.extensions: The extensions array is missing or malformed

Solution

The "missing openclaw.hooks" error can be safely ignored once the primary installation error is resolved. For the dangerous code blocking issue, use the --dangerously-force-unsafe-install flag:

openclaw plugins install --link --dangerously-force-unsafe-install /path/to/plugin/

Why This Matters for AI Analysis

When analyzing this error, focus on the first error shown, not the secondary hook-related message. The OpenClaw installer attempts multiple installation strategies in sequence, and the final "missing openclaw.hooks" error is a diagnostic artifact from the fallback path, not the actual problem.

If the primary error is about dangerous code patterns, the plugin is functioning correctly from a technical standpoint—it simply uses APIs (like child_process) that OpenClaw's security scanning flags as potentially unsafe. Whether this is acceptable depends on the plugin's use case and trust level.