# 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:

```bash
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.