mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-20 00:57:29 +00:00
ab71fdf821
* feat: add before_compaction and before_reset plugin hooks with session context - Pass session messages to before_compaction hook - Add before_reset plugin hook for /new and /reset commands - Add sessionId to plugin hook agent context * feat: extraBootstrapFiles config with glob pattern support Add extraBootstrapFiles to agent defaults config, allowing glob patterns (e.g. "projects/*/TOOLS.md") to auto-load project-level bootstrap files into agent context every turn. Missing files silently skipped. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(status): show custom memory plugins as enabled, not unavailable The status command probes memory availability using the built-in memory-core manager. Custom memory plugins (e.g. via plugin slot) can't be probed this way, so they incorrectly showed "unavailable". Now they show "enabled (plugin X)" without the misleading label. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use async fs.glob and capture pre-compaction messages - Replace globSync (node:fs) with fs.glob (node:fs/promises) to match codebase conventions for async file operations - Capture session.messages BEFORE replaceMessages(limited) so before_compaction hook receives the full conversation history, not the already-truncated list * fix: resolve lint errors from CI (oxlint strict mode) - Add void to fire-and-forget IIFE (no-floating-promises) - Use String() for unknown catch params in template literals - Add curly braces to single-statement if (curly rule) * fix: resolve remaining CI lint errors in workspace.ts - Remove `| string` from WorkspaceBootstrapFileName union (made all typeof members redundant per no-redundant-type-constituents) - Use type assertion for extra bootstrap file names - Drop redundant await on fs.glob() AsyncIterable (await-thenable) * fix: address Greptile review — path traversal guard + fs/promises import - workspace.ts: use path.resolve() + traversal check in loadExtraBootstrapFiles() - commands-core.ts: import fs from node:fs/promises, drop fs.promises prefix Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: resolve symlinks before workspace boundary check Greptile correctly identified that symlinks inside the workspace could point to files outside it, bypassing the path prefix check. Now uses fs.realpath() to resolve symlinks before verifying the real path stays within the workspace boundary. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address Greptile review — hook reliability and type safety 1. before_compaction: add compactingCount field so plugins know both the full pre-compaction message count and the truncated count being fed to the compaction LLM. Clarify semantics in comment. 2. loadExtraBootstrapFiles: use path.basename() for the name field so "projects/quaid/TOOLS.md" maps to the known "TOOLS.md" type instead of an invalid WorkspaceBootstrapFileName cast. 3. before_reset: fire the hook even when no session file exists. Previously, short sessions without a persisted file would silently skip the hook. Now fires with empty messages array so plugins always know a reset occurred. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: validate bootstrap filenames and add compaction hook timeout - Only load extra bootstrap files whose basename matches a recognized workspace filename (AGENTS.md, TOOLS.md, etc.), preventing arbitrary files from being injected into agent context. - Wrap before_compaction hook in a 30-second Promise.race timeout so misbehaving plugins cannot stall the compaction pipeline. - Clarify hook comments: before_compaction is intentionally awaited (plugins need messages before they're discarded) but bounded. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: make before_compaction non-blocking, add sessionFile to after_compaction - before_compaction is now true fire-and-forget — no await, no timeout. Plugins that need full conversation data should persist it themselves and return quickly, or use after_compaction for async processing. - after_compaction now includes sessionFile path so plugins can read the full JSONL transcript asynchronously. All pre-compaction messages are preserved on disk, eliminating the need to block compaction. - Removes Promise.race timeout pattern that didn't actually cancel slow hooks (just raced past them while they continued running). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add sessionFile to before_compaction for parallel processing The session JSONL already has all messages on disk before compaction starts. By providing sessionFile in before_compaction, plugins can read and extract data in parallel with the compaction LLM call rather than waiting for after_compaction. This is the optimal path for memory plugins that need the full conversation history. sessionFile is also kept on after_compaction for plugins that only need to act after compaction completes (analytics, cleanup, etc.). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: move bootstrap extras into bundled hook --------- Co-authored-by: Solomon Steadman <solstead@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Clawdbot <clawdbot@alfie.local> Co-authored-by: Peter Steinberger <steipete@gmail.com>
5.6 KiB
5.6 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| CLI reference for `openclaw hooks` (agent hooks) |
|
hooks |
openclaw hooks
Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup).
Related:
List All Hooks
openclaw hooks list
List all discovered hooks from workspace, managed, and bundled directories.
Options:
--eligible: Show only eligible hooks (requirements met)--json: Output as JSON-v, --verbose: Show detailed information including missing requirements
Example output:
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Run BOOT.md on gateway startup
📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
📝 command-logger ✓ - Log all command events to a centralized audit file
💾 session-memory ✓ - Save session context to memory when /new command is issued
Example (verbose):
openclaw hooks list --verbose
Shows missing requirements for ineligible hooks.
Example (JSON):
openclaw hooks list --json
Returns structured JSON for programmatic use.
Get Hook Information
openclaw hooks info <name>
Show detailed information about a specific hook.
Arguments:
<name>: Hook name (e.g.,session-memory)
Options:
--json: Output as JSON
Example:
openclaw hooks info session-memory
Output:
💾 session-memory ✓ Ready
Save session context to memory when /new command is issued
Details:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/hooks#session-memory
Events: command:new
Requirements:
Config: ✓ workspace.dir
Check Hooks Eligibility
openclaw hooks check
Show summary of hook eligibility status (how many are ready vs. not ready).
Options:
--json: Output as JSON
Example output:
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
Enable a Hook
openclaw hooks enable <name>
Enable a specific hook by adding it to your config (~/.openclaw/config.json).
Note: Hooks managed by plugins show plugin:<id> in openclaw hooks list and
can’t be enabled/disabled here. Enable/disable the plugin instead.
Arguments:
<name>: Hook name (e.g.,session-memory)
Example:
openclaw hooks enable session-memory
Output:
✓ Enabled hook: 💾 session-memory
What it does:
- Checks if hook exists and is eligible
- Updates
hooks.internal.entries.<name>.enabled = truein your config - Saves config to disk
After enabling:
- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
Disable a Hook
openclaw hooks disable <name>
Disable a specific hook by updating your config.
Arguments:
<name>: Hook name (e.g.,command-logger)
Example:
openclaw hooks disable command-logger
Output:
⏸ Disabled hook: 📝 command-logger
After disabling:
- Restart the gateway so hooks reload
Install Hooks
openclaw hooks install <path-or-spec>
Install a hook pack from a local folder/archive or npm.
What it does:
- Copies the hook pack into
~/.openclaw/hooks/<id> - Enables the installed hooks in
hooks.internal.entries.* - Records the install under
hooks.internal.installs
Options:
-l, --link: Link a local directory instead of copying (adds it tohooks.internal.load.extraDirs)
Supported archives: .zip, .tgz, .tar.gz, .tar
Examples:
# Local directory
openclaw hooks install ./my-hook-pack
# Local archive
openclaw hooks install ./my-hook-pack.zip
# NPM package
openclaw hooks install @openclaw/my-hook-pack
# Link a local directory without copying
openclaw hooks install -l ./my-hook-pack
Update Hooks
openclaw hooks update <id>
openclaw hooks update --all
Update installed hook packs (npm installs only).
Options:
--all: Update all tracked hook packs--dry-run: Show what would change without writing
Bundled Hooks
session-memory
Saves session context to memory when you issue /new.
Enable:
openclaw hooks enable session-memory
Output: ~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md
See: session-memory documentation
bootstrap-extra-files
Injects additional bootstrap files (for example monorepo-local AGENTS.md / TOOLS.md) during agent:bootstrap.
Enable:
openclaw hooks enable bootstrap-extra-files
See: bootstrap-extra-files documentation
command-logger
Logs all command events to a centralized audit file.
Enable:
openclaw hooks enable command-logger
Output: ~/.openclaw/logs/commands.log
View logs:
# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log
# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .
# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
See: command-logger documentation
boot-md
Runs BOOT.md when the gateway starts (after channels start).
Events: gateway:startup
Enable:
openclaw hooks enable boot-md