mirror of
https://github.com/openclaw/openclaw.git
synced 2026-09-28 05:54:09 +08:00
Vincent KocandVincent Koc
f72699f858
* docs: STE pass on terminology consistency and run-on sentences
Closes a batch of ASD-STE100 audit findings grouped by the two most
objectively checkable rules in .audit/ste-policy.md: one word / one
meaning (scan-checklist item 1) and run-on sentences joined by
semicolons (item 5, Rule 8.1).
Terminology:
- Normalize the component name to "Gateway" in prose on
announcements/bluebubbles-imessage, channels/line, gateway/discovery,
install/docker, install/digitalocean, install/northflank,
platforms/android, platforms/ios, platforms/mac/remote.
Hyphenated attributive compounds (per-gateway, gateway-host,
gateway-side) stay lowercase, matching the tree and the
user@gateway-host placeholder mandated by docs/AGENTS.md.
- gateway/discovery: "Node Gateway" -> "Gateway" (used once).
- platforms/mac/remote: "Web Chat" -> "WebChat" (157:7 in the tree).
The "## Web Chat" heading becomes "## WebChat" with an
<a id="web-chat" /> stub so the published id survives.
- platforms/android, platforms/ios: one arrow form for menu paths (->
and > become the dominant ->).
- providers/moonshot: "Kimi Code K3" -> "Kimi Coding K3" in prose;
vendor product names in link labels are unchanged.
- tools/diffs: one plugin name in the page ("Diff Viewer Language
Pack plugin", the label in official-external-plugin-catalog.json).
Run-on sentences (Rule 8.1) split into separate sentences on
cli/hooks, cli/webhooks, channels/matrix-push-rules, channels/a2a,
plugins/plugin-permission-requests, plugins/llama-cpp,
platforms/mac/canvas, platforms/mac/health, plugins/teams-meetings,
plugins/zoom-meetings, providers/mistral, tools/diffs,
gateway/secrets-plan-contract, concepts/session-pruning.
The two scrub passes in gateway/secrets-plan-contract and the
changed-files summary card in tools/diffs become lists.
Concrete defects:
- gateway/telemetry: drop the dangling "and applies".
- plugins/zalouser: the opening sentence fragment gets a subject and
a verb.
- tools/exa-search: the intro named "keyword" and "hybrid" modes that
the mode table does not list; it now names the table's own ids.
- concepts/session-pruning: state the real ttl default (5 minutes when
cache-ttl mode is on with no ttl set, per
resolveCacheTtlPruningSettings) instead of "default 5 minutes when
set manually".
No fact, hedge, scope qualifier or number changed. No anchor id was
dropped: ids enumerated with parseDocsDocument before and after are
identical across all 28 files except remote.md, which gains "webchat"
and keeps "web-chat".
* docs: turn the diffs baseUrl rules into a list
Three validation rules were joined by two semicolons on one line
(Rule 8.1, and the policy's 'lists for 3 or more conditions'). The
rules and their order are unchanged.
* docs: drop the secrets-plan-contract edit from this PR
.github/CODEOWNERS routes docs/gateway/secrets-plan-contract.md to
@openclaw/openclaw-secops, and this PR has no secops involvement to
point at. ClawSweeper blocked on that and offered omitting the
restricted-path edit as the alternative. The file is back to its
merge-base blob; audit finding r5-0018 is deferred to a secops-routed
PR.
---------
Co-authored-by: Vincent Koc <vincent@openclaw.org>
298 lines
14 KiB
Markdown
298 lines
14 KiB
Markdown
---
|
|
summary: "CLI reference for internal hook discovery, eligibility, enablement, and hook packs"
|
|
read_when:
|
|
- You want to inspect internal hooks on a local or remote Gateway
|
|
- You want to enable or disable a hook in local config
|
|
- You need hook command flags or JSON report fields
|
|
title: "Hooks CLI"
|
|
doc-schema-version: 1
|
|
---
|
|
|
|
# `openclaw hooks`
|
|
|
|
Inspect and configure [internal hooks](/automation/hooks): handlers for command,
|
|
message, session, and Gateway events. Bare `openclaw hooks` runs the same report
|
|
as `openclaw hooks list`. These commands do not manage HTTP
|
|
[Webhooks](/automation/cron-jobs#webhooks) or the typed `api.on(...)` hook catalog in
|
|
[Plugin hooks](/plugins/hooks).
|
|
|
|
## Target and scope
|
|
|
|
Read-only reports (`hooks`, `list`, `info`, `check`) first call `hooks.status` on
|
|
the selected Gateway. Configured remote Gateways and explicit
|
|
`OPENCLAW_GATEWAY_URL` targets are authoritative: missing remote URLs,
|
|
connection/authentication failures, and unsupported methods fail instead of
|
|
showing client-local hooks. An implicitly selected local Gateway can fall back
|
|
to local discovery when unavailable or when its hook-report method/agent
|
|
parameter is unsupported. Other errors are not silently replaced with local
|
|
inventory.
|
|
|
|
**Enable, disable, install, and update mutate local files/config/state.** They do
|
|
not change a remote Gateway over RPC. To change the server, run the command on
|
|
that host using its profile/config. Enable, disable, and config written by a new
|
|
install or link can activate immediately in the default `hybrid`
|
|
[reload mode](/gateway/configuration#reload-modes). `off` requires a manual
|
|
restart. Hook files and metadata are not watched. Restart after editing them or
|
|
updating existing hook code.
|
|
|
|
`--agent <id>` selects the agent workspace used for inspection. It is required
|
|
when configured agents do not have an implicit owner. Blank or unknown IDs
|
|
fail. The option works before or after `list`, `info`, `check`, `enable`, and
|
|
`disable`. It does not scope the persisted hook entry to that agent and is not
|
|
supported on install/update. See
|
|
[Local, remote, and agent scope](/automation/hooks#local-remote-and-agent-scope)
|
|
for the distinction between workspace inventory and Gateway loading.
|
|
|
|
## List hooks
|
|
|
|
```bash
|
|
openclaw hooks [--agent <id>] [--json]
|
|
openclaw hooks list [--agent <id>] [--eligible] [--json] [-v|--verbose]
|
|
```
|
|
|
|
Discovery includes bundled hooks, active plugin hooks, managed hooks, extra
|
|
directories, and the selected workspace. Hook-name collisions follow the
|
|
[source policy](/automation/hooks/configuration#hook-discovery).
|
|
|
|
| Option | Meaning |
|
|
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
| `--agent <id>` | Select the workspace to inspect. |
|
|
| `--eligible` | Show only `loadable` hooks: enabled by per-hook/source policy, requirements satisfied, and at least one declared event. |
|
|
| `--json` | Write structured JSON directly to stdout. Also accepted on the parent `hooks` command. |
|
|
| `-v, --verbose` | Add the Missing column to the human-readable table. |
|
|
|
|
Human output is a table with Status, Hook, Description, and Source columns,
|
|
preceded by `Hooks (<ready>/<total> ready)`. Plugin-managed sources appear as
|
|
`plugin:<id>`.
|
|
|
|
<Note>
|
|
`ready`, `eligible`, and `loadable` are inventory results, not a live handler
|
|
registration check. The report does not apply the Gateway's master switch or
|
|
configured-name selection, import the handler to prove it works, or verify that
|
|
the event has run. A bundled hook can appear ready while the internal hook
|
|
system is off. Enable the intended hook and
|
|
[verify its real side effect](/automation/hooks#quick-start).
|
|
</Note>
|
|
|
|
### List JSON
|
|
|
|
The root object contains `workspaceDir`, `managedHooksDir`, and `hooks`.
|
|
Each hook includes:
|
|
|
|
- Identity/display: `name`, `description`, `source`, optional `pluginId`,
|
|
`emoji`, `homepage`, and `managedByPlugin`.
|
|
- Status: `enabledByConfig`, `requirementsSatisfied`, `loadable`, optional
|
|
`blockedReason`, plus compatibility aliases `eligible` (`loadable`) and
|
|
`disabled` (`!enabledByConfig`).
|
|
- Events/requirements: `events`, `unknownEvents`, and `missing`, whose arrays
|
|
are `bins`, `anyBins`, `env`, `config`, and `os`.
|
|
|
|
`blockedReason` can be `disabled in config`, `workspace hook (disabled by default)`,
|
|
`missing requirements`, or `no events defined`. Unknown events are
|
|
advisory: they do not by themselves make a hook unloadable.
|
|
|
|
## Get hook info
|
|
|
|
```bash
|
|
openclaw hooks info <name> [--agent <id>] [--json]
|
|
```
|
|
|
|
Accepts a hook name or its metadata `hookKey`. Exact hook names take precedence
|
|
over matching keys. A key must identify a single hook. Shows source, descriptor
|
|
and handler paths, homepage, events, unknown-event warnings, blocked reason, and
|
|
per-requirement status. A missing or ambiguous hook exits with code 1. An
|
|
ambiguous selector lists candidates so you can choose a unique name or key.
|
|
|
|
JSON includes the list fields plus `filePath`, `baseDir`, `handlerPath`,
|
|
`hookKey`, `always`, `requirements`, `configChecks`, and normalized `install`
|
|
options. Each config check has `path` and `satisfied`. Each install option has
|
|
`id`, `kind`, `label`, and `bins`. Install options are descriptive metadata, not
|
|
a command to install dependencies automatically.
|
|
|
|
## Check eligibility
|
|
|
|
```bash
|
|
openclaw hooks check [--agent <id>] [--json]
|
|
```
|
|
|
|
Prints totals for ready/not-ready hooks and lists blocking reasons. JSON has
|
|
`total`, `eligible`, `notEligible`, and `hooks` containing an `eligible` name
|
|
array and a `notEligible` array of `{ name, blockedReason?, missing }` objects.
|
|
|
|
A successful report exits with code 0 even when hooks are not ready. For an
|
|
automated eligibility gate, inspect the JSON counts rather than treating the
|
|
exit code as an all-hooks-ready result. This still does not test actual loading.
|
|
|
|
## Enable a hook
|
|
|
|
```bash
|
|
openclaw hooks enable <name> [--agent <id>]
|
|
```
|
|
|
|
Discovers the hook locally, then writes
|
|
`hooks.internal.entries.<hookKey>.enabled = true` and
|
|
`hooks.internal.enabled = true` in local config. Other fields in that entry are
|
|
preserved. Exact hook names take precedence over matching keys. Ambiguous key
|
|
matches fail without writing.
|
|
|
|
Enable fails for a missing hook, a plugin-managed hook, or unmet runtime
|
|
requirements. It can enable a currently disabled workspace hook. This does not
|
|
prove a valid module export or event subscription. Inspect `info` and the
|
|
Gateway logs too.
|
|
|
|
The entry is **global**, even with `--agent`: it applies wherever that key is
|
|
discovered. Adding named entries can narrow a previously open-ended directory
|
|
selection. See [Configuration](/automation/hooks/configuration#configuration).
|
|
|
|
The running Gateway reloads the selection in `hybrid` mode. If a selected hook
|
|
cannot load, it keeps the previous handlers. Inspect Gateway logs. Reload does
|
|
not replay `gateway:startup`, so `boot-md` runs on the next Gateway start.
|
|
|
|
## Disable a hook
|
|
|
|
```bash
|
|
openclaw hooks disable <name> [--agent <id>]
|
|
```
|
|
|
|
Writes `hooks.internal.entries.<hookKey>.enabled = false`. It does not remove the
|
|
hook files or change the master switch. Missing/ambiguous and plugin-managed
|
|
hooks are rejected. Missing runtime requirements do not prevent disabling.
|
|
In `hybrid` mode, subsequent events use the updated selection. An event already
|
|
running finishes with its original handlers.
|
|
|
|
Plugin-managed hooks cannot be toggled by these commands. Enable or disable the
|
|
owning plugin through [`openclaw plugins`](/cli/plugins).
|
|
|
|
## Install and update hook packs
|
|
|
|
Use the unified plugin installer for reviewed hook packs:
|
|
|
|
```bash
|
|
openclaw plugins install npm:<package>
|
|
openclaw plugins install npm:<package>@<version> --pin
|
|
openclaw plugins install ./my-hook-pack
|
|
openclaw plugins install ./my-hook-pack.tgz
|
|
|
|
openclaw plugins update <id> --dry-run
|
|
openclaw plugins update <id>
|
|
```
|
|
|
|
A pack declares hook directories in `package.json` under `openclaw.hooks`.
|
|
A local directory without `package.json` can contain a single `HOOK.md` and
|
|
handler. Copied hook packs are installed into `<stateDir>/hooks/<id>`. Their
|
|
hooks are enabled in config and install provenance is recorded in shared SQLite
|
|
state. That config can activate the hooks immediately in `hybrid` mode. Do not author
|
|
`hooks.internal.installs` in `openclaw.json`.
|
|
|
|
For the npm hook-pack path, specs are registry-only: package name with an
|
|
optional exact version or dist-tag. Git/URL/file specs, npm aliases, and semver
|
|
ranges are not npm registry specs. Bare specs and `@latest` stay on the stable
|
|
track. A prerelease resolution requires an explicit prerelease version or a
|
|
non-latest tag such as `@beta` or `@rc`. Use `npm:` to select npm explicitly. The
|
|
unified installer supports other plugin sources described in
|
|
[`openclaw plugins`](/cli/plugins).
|
|
|
|
Supported local archives are `.zip`, `.tgz`, `.tar.gz`, and `.tar`. Copied hook
|
|
packs resolve runtime packages from `dependencies` and `optionalDependencies`,
|
|
including packs with only optional dependencies. Packages listed only in
|
|
`devDependencies` are omitted. npm pack and dependency installation use
|
|
`--ignore-scripts`. This does not sandbox the installed handler.
|
|
The download always creates an archive in OpenClaw's temporary workspace,
|
|
regardless of npm's `dry-run` or `pack-destination` settings.
|
|
|
|
### Install options and trust
|
|
|
|
| Option | Effect for hook packs |
|
|
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `-l, --link` | Add the exact local hook or pack root to `hooks.internal.load.extraDirs` instead of copying it. Single hooks and nested pack layouts work. |
|
|
| `--pin` | Record the resolved exact npm `name@version` in install state when available; does not apply to local paths. |
|
|
| `--force` | Acknowledge a non-ClawHub source and allow replacement of an existing copied install. For links it acknowledges the source without copying. |
|
|
| `--acknowledge-install-policy-warning` | Acknowledge an operator `security.installPolicy` warning without its prompt. Blocks and policy failures still stop the install. |
|
|
|
|
Interactive non-ClawHub installs ask you to confirm trust. Noninteractive
|
|
installs require `--force`. Neither `plugins install` nor the `hooks install`
|
|
alias accepts a `--yes` flag. `--force` is also not a substitute for
|
|
acknowledging an install-policy warning. Review the source before supplying
|
|
either acknowledgement.
|
|
|
|
<Warning>
|
|
A linked hook runs directly from the supplied path. Linking does not copy it
|
|
or create a symlink. A single-hook root loads its own `HOOK.md` and handler.
|
|
A pack loads only the hook directories listed in `openclaw.hooks`, including
|
|
nested paths such as `./hooks/my-hook`. Declared paths must stay inside the
|
|
pack and point directly to hooks. Discovery does not recurse into nested packs
|
|
or collections, or scan unlisted children, even when all declared paths are rejected.
|
|
|
|
Only link trusted code. Extra directories still make directory-hook name
|
|
selection open-ended across discovery sources, not just within the linked
|
|
pack. Linking can activate the hooks immediately in `hybrid` mode. Restart after
|
|
editing existing hook code or metadata, check `hooks list`, and
|
|
[verify the handler's actual side effect](/automation/hooks#quick-start).
|
|
</Warning>
|
|
|
|
### Update behavior
|
|
|
|
Updates use tracked npm install records. A tracked hook-pack ID uses its stored
|
|
spec. A matching npm package spec can select a new version/tag. Local path and
|
|
archive records are not refreshed by the npm hook updater.
|
|
|
|
`--dry-run` reports what would change without installing or rewriting config.
|
|
`--all` selects **both plugins and hook packs** in the unified updater, including
|
|
when reached through the deprecated alias. It is not a hooks-only bulk command.
|
|
|
|
When an applicable stored integrity hash differs from the downloaded artifact,
|
|
the updater warns and asks for confirmation in the terminal. No CLI flag answers
|
|
that prompt: neither `plugins update` nor the `hooks update` alias accepts
|
|
`--yes`, and `--acknowledge-install-policy-warning` covers only install-policy
|
|
warnings. `--dry-run` reports the drift without prompting.
|
|
|
|
### Deprecated aliases
|
|
|
|
These commands print a deprecation warning and forward to the unified owners:
|
|
|
|
```bash
|
|
openclaw hooks install <path-or-spec> [-l|--link] [--pin] [--force] [--acknowledge-install-policy-warning]
|
|
openclaw hooks update [id] [--all] [--dry-run] [--acknowledge-install-policy-warning]
|
|
```
|
|
|
|
For update, provide `id` or `--all`. The aliases do not accept `--agent` and are
|
|
not the preferred interface for new automation.
|
|
|
|
## Bundled hooks
|
|
|
|
The maintained catalog, event subscriptions, options, and verification notes
|
|
are in [Bundled hooks](/automation/hooks/bundled-hooks). This includes
|
|
`boot-md`, `bootstrap-extra-files`, `command-logger`, `compaction-notifier`, and
|
|
`session-memory` (manual **and automatic** reset capture).
|
|
|
|
### command-logger log file
|
|
|
|
On the Gateway host, with the default state directory:
|
|
|
|
```bash
|
|
tail -n 20 ~/.openclaw/logs/commands.log
|
|
jq . ~/.openclaw/logs/commands.log
|
|
jq 'select(.action == "new")' ~/.openclaw/logs/commands.log
|
|
```
|
|
|
|
Use `<stateDir>/logs/commands.log` for a custom state directory. These records
|
|
contain session and sender identifiers. Protect access and arrange retention or
|
|
rotation. The hook does not rotate them.
|
|
|
|
## Notes
|
|
|
|
Report commands support `--json`. Success JSON goes directly to stdout. Failures
|
|
use the standard [CLI JSON failure envelope](/cli#json-failures), and missing
|
|
hook info also includes the requested `hook` name. Reports do not execute a hook
|
|
as a test.
|
|
|
|
The hidden `hooks relay` command is reserved for generated native harness
|
|
integration. It is not an internal-hook testing or manual event-trigger command.
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|
|
- [Automation hooks](/automation/hooks)
|
|
- [Plugin hooks](/plugins/hooks)
|
|
- [Plugins CLI](/cli/plugins)
|