clawhub install does not register skill hooks automatically

[alissonaguiar]

Summary

When installing a skill that includes an OpenClaw hook (e.g. hooks/openclaw/HOOK.md), clawhub install copies the skill files to the workspace but does not register the hook with the gateway. The user sees the skill as "installed" in the UI but the hook silently does nothing.

Steps to Reproduce

1. Install a skill that has hooks: clawhub install self-improving-agent
2. Check openclaw hooks list — the hook is not listed
3. The skill appears installed in the UI/workspace, but the hook never fires

Expected Behavior

clawhub install should detect hooks/openclaw/HOOK.md (or hooks/openclaw/handler.{js,ts}) in the skill and automatically run the equivalent of:

openclaw plugins install <skill-path>/hooks/openclaw

This would register the hook with the gateway so it actually works after installation.

Actual Behavior

The hook files sit in ~/.openclaw/workspace/skills/<skill>/hooks/openclaw/ but are never registered. The user has no indication that an extra manual step is needed.

Workaround

After clawhub install, manually run:

openclaw plugins install ~/.openclaw/workspace/skills/<skill>/hooks/openclaw
systemctl restart openclaw  # or restart the gateway

Impact

This is a silent failure — the user installs a skill via UI or CLI, it appears to work, but hook-dependent features (like bootstrap injection) never activate. There's no warning or error.

Environment

• OpenClaw: 2026.5.12 (f066dd2)
• ClawHub CLI: v0.15.0
• Affected skill: self-improving-agent (has hooks/openclaw/HOOK.md with agent:bootstrap event)

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 24, 2026, 4:06 PM ET / 20:06 UTC.

Summary
Keep open. Current main and the v0.23.0-era CLI path still install or update skill files and metadata only; automatic hook discovery, disclosure, consent, scanner coverage, and OpenClaw gateway registration remain missing and security/product-sensitive.

Reproducibility: yes. at source level. Current cmdInstall and cmdUpdate extract skill content and write metadata without hook detection, gateway handoff, or plugin registration; I did not run a live OpenClaw gateway reproduction.

Root-cause cluster
Relationship: canonical
Canonical: #2295
Summary: This issue is the specific remaining hook-registration request; the active-session handoff issue is adjacent, and the broader hook-format RFC was closed stale rather than implemented.

Members:

• partial_overlap: Feature: Inject post-install/update system event into active session #792 - It covers post-install/update active-session handoff, which should align with hook registration but does not itself implement OpenClaw hook bundle discovery or registration.
• partial_overlap: RFC: Document and secure hooks field in skill format spec #707 - It covered the broader hook metadata, documentation, security, and disclosure contract; it was closed as stale, not as an implemented canonical fix for this install registration gap.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
Manual review is needed because the remaining blocker is the hook permission, scanner/disclosure, and OpenClaw gateway handoff contract rather than a narrow CLI-only repair.

Security
Needs attention: The requested behavior is security-sensitive because it would auto-register skill-provided hook code with the local OpenClaw runtime.

Review details

Best possible solution:

Define an explicit, consent-aware hook capability contract, then implement discovery, disclosure, scanner coverage, install/update registration, docs, tests, and real OpenClaw gateway validation together.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level. Current cmdInstall and cmdUpdate extract skill content and write metadata without hook detection, gateway handoff, or plugin registration; I did not run a live OpenClaw gateway reproduction.

Is this the best way to solve the issue?

Unclear as requested. Automatic registration addresses the activation gap, but the maintainable solution should not be an unconditional shell-out; it needs explicit consent, scanner/disclosure coverage, and a ClawHub/OpenClaw handoff policy first.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Automatically registering skill-shipped hooks could activate publisher-provided code without a settled consent, scanner, and disclosure boundary.
• The ClawHub CLI does not currently expose a clear authenticated OpenClaw gateway/session target, so a narrow shell-out could produce ambiguous or unsafe partial setup.
• The adjacent active-session handoff work should be aligned so hook registration, declarative metadata, and install onboarding do not become competing setup mechanisms.

Codex review notes: model internal, reasoning high; reviewed against 61efe0657f8d.

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a meaningful install/setup reliability issue with security implications, but no emergency outage, data loss, or confirmed active bypass is shown.
• impact:security: The requested behavior would automatically register skill-provided hook code that can affect local OpenClaw runtime behavior.
• impact:session-state: Missing registration leaves hook-dependent bootstrap or lifecycle behavior inactive after the skill appears installed.

Evidence reviewed

Security concerns:

• [medium] Define consent before automatic hook registration
  Automatically registering hooks/openclaw content during install could activate lifecycle behavior from a skill bundle, so maintainers should require explicit user/operator approval and scanner coverage before implementation.
  Confidence: 0.9
• [medium] Avoid ambiguous gateway handoff
  A ClawHub-to-OpenClaw registration path needs a clear target gateway/session contract so unrelated local processes or partial setups cannot create trusted-looking hook activation state.
  Confidence: 0.84

What I checked:

• Live issue context: The issue remains open with external author association, prior ClawSweeper source-repro review, and related but non-replacing issues about hook metadata and active-session handoff.
• Current install path lacks hook registration: cmdInstall resolves, downloads/extracts, hashes files, writes origin and lockfile metadata, reports telemetry, and prints success; no hooks/openclaw discovery, HOOK.md/handler detection, or openclaw plugins install handoff is present. (packages/clawhub/src/cli/commands/skills.ts:254, 61efe0657f8d)
• Current update path has the same gap: cmdUpdate replaces or refreshes installed skill content and metadata through the same extraction flow without hook discovery or gateway registration. (packages/clawhub/src/cli/commands/skills.ts:404, 61efe0657f8d)
• Skill metadata schema has no hook contract: ClawdisSkillMetadataSchema contains requirements, install specs, config, env vars, dependencies, author, and links, but no lifecycle-hook or hook-directory field for safe install-time handling. (packages/schema/src/schemas.ts:917, 61efe0657f8d)
• Parser does not normalize hooks: parseClawdisMetadata parses known OpenClaw/Clawdis metadata fields and validates that object; it does not read top-level or metadata.openclaw hook declarations. (convex/lib/skills/index.ts:69, 61efe0657f8d)
• Approved install UX avoids direct handoff: The skill install surface spec explicitly keeps OpenClaw setup to inspectable copyable prompts and lists direct handoff or automatic execution into OpenClaw as non-goals. (specs/superpowers/2026-04-22-skill-install-surface-design.md:23, 61efe0657f8d)

Likely related people:

• Patrick-Erichsen: Current blame ties the central CLI install path, metadata schema, and parser to the v0.23.0 release-root commit, and GitHub PR metadata shows Patrick authored and merged that release baseline. (role: release integrator and product discussion participant; confidence: high; commits: a128c101adca, 2f0cedec71eb; files: packages/clawhub/src/cli/commands/skills.ts, packages/schema/src/schemas.ts, convex/lib/skills/index.ts)
• vyctorbrzezowski: Recent merged work changed the skill install UI surface that currently exposes the CLI/prompt install path and would need to present any future hook disclosure or consent copy. (role: recent adjacent install surface contributor; confidence: medium; commits: 2bf8113ef13b, a1f52e240981; files: src/components/SkillInstallSurface.tsx, src/components/skillDetailUtils.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.