From fabdd488770b6f14383ccaacf50a2fc40dfae499 Mon Sep 17 00:00:00 2001
From: Santhosh Janardhanan <santhoshj@gmail.com>
Date: Sat, 11 Apr 2026 22:50:04 -0400
Subject: [PATCH] docs: add troubleshooting guide for misleading openclaw.hooks
 error

---
 .../MISSING_OPENCLAW_HOOKS_ERROR.md           | 56 +++++++++++++++++++
 package.json                                  |  2 +-
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/troubleshooting/MISSING_OPENCLAW_HOOKS_ERROR.md

diff --git a/docs/troubleshooting/MISSING_OPENCLAW_HOOKS_ERROR.md b/docs/troubleshooting/MISSING_OPENCLAW_HOOKS_ERROR.md
new file mode 100644
index 0000000..ab58dd4
--- /dev/null
+++ b/docs/troubleshooting/MISSING_OPENCLAW_HOOKS_ERROR.md
@@ -0,0 +1,56 @@
+# 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.
diff --git a/package.json b/package.json
index 214391b..d294a79 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "main": "dist/index.js",
   "type": "module",
   "openclaw": {
-    "extensions": "./dist/index.js"
+    "extensions": ["./dist/index.js"]
   },
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --format=esm --external:@lancedb/lancedb --external:@lancedb/lancedb-darwin-arm64 --external:fsevents --external:chokidar",