57 lines
3.3 KiB
Markdown
57 lines
3.3 KiB
Markdown
# 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.
|