feat: unify hooks installs and webhooks

This commit is contained in:
Peter Steinberger
2026-01-17 07:08:04 +00:00
parent 5dc87a2ed4
commit 3a6ee5ee00
33 changed files with 2235 additions and 829 deletions

View File

@@ -92,13 +92,13 @@ under `hooks.transformsDir` (see [Webhooks](/automation/webhook)).
Use the Clawdbot helper to wire everything together (installs deps on macOS via brew):
```bash
clawdbot hooks gmail setup \
clawdbot webhooks gmail setup \
--account clawdbot@gmail.com
```
Defaults:
- Uses Tailscale Funnel for the public push endpoint.
- Writes `hooks.gmail` config for `clawdbot hooks gmail run`.
- Writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
Path note: when `tailscale.mode` is enabled, Clawdbot automatically sets
@@ -124,7 +124,7 @@ Gateway auto-start (recommended):
Manual daemon (starts `gog gmail watch serve` + auto-renew):
```bash
clawdbot hooks gmail run
clawdbot webhooks gmail run
```
## One-time setup
@@ -191,7 +191,7 @@ Notes:
- `--hook-url` points to Clawdbot `/hooks/gmail` (mapped; isolated run + summary to main).
- `--include-body` and `--max-bytes` control the body snippet sent to Clawdbot.
Recommended: `clawdbot hooks gmail run` wraps the same flow and auto-renews the watch.
Recommended: `clawdbot webhooks gmail run` wraps the same flow and auto-renews the watch.
## Expose the handler (advanced, unsupported)

View File

@@ -96,7 +96,7 @@ Mapping options (summary):
- TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
- Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
(`channel` defaults to `last` and falls back to WhatsApp).
- `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
- `clawdbot webhooks gmail setup` writes `hooks.gmail` config for `clawdbot webhooks gmail run`.
See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow.
## Responses

View File

@@ -1,28 +1,21 @@
---
summary: "CLI reference for `clawdbot hooks` (internal hooks + Gmail Pub/Sub + webhook helpers)"
summary: "CLI reference for `clawdbot hooks` (internal hooks)"
read_when:
- You want to manage internal agent hooks
- You want to wire Gmail Pub/Sub events into Clawdbot hooks
- You want to run the gog watch service and renew loop
- You want to install or update internal hooks
---
# `clawdbot hooks`
Webhook helpers and hook-based integrations.
Manage internal agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
Related:
- Internal Hooks: [Internal Agent Hooks](/internal-hooks)
- Webhooks: [Webhook](/automation/webhook)
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
## Internal Hooks
Manage internal agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
### List All Hooks
## List All Hooks
```bash
clawdbot hooks internal list
clawdbot hooks list
```
List all discovered internal hooks from workspace, managed, and bundled directories.
@@ -45,7 +38,7 @@ Ready:
**Example (verbose):**
```bash
clawdbot hooks internal list --verbose
clawdbot hooks list --verbose
```
Shows missing requirements for ineligible hooks.
@@ -53,15 +46,15 @@ Shows missing requirements for ineligible hooks.
**Example (JSON):**
```bash
clawdbot hooks internal list --json
clawdbot hooks list --json
```
Returns structured JSON for programmatic use.
### Get Hook Information
## Get Hook Information
```bash
clawdbot hooks internal info <name>
clawdbot hooks info <name>
```
Show detailed information about a specific hook.
@@ -75,7 +68,7 @@ Show detailed information about a specific hook.
**Example:**
```bash
clawdbot hooks internal info session-memory
clawdbot hooks info session-memory
```
**Output:**
@@ -96,10 +89,10 @@ Requirements:
Config: ✓ workspace.dir
```
### Check Hooks Eligibility
## Check Hooks Eligibility
```bash
clawdbot hooks internal check
clawdbot hooks check
```
Show summary of hook eligibility status (how many are ready vs. not ready).
@@ -117,10 +110,10 @@ Ready: 2
Not ready: 0
```
### Enable a Hook
## Enable a Hook
```bash
clawdbot hooks internal enable <name>
clawdbot hooks enable <name>
```
Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
@@ -131,7 +124,7 @@ Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
**Example:**
```bash
clawdbot hooks internal enable session-memory
clawdbot hooks enable session-memory
```
**Output:**
@@ -148,10 +141,10 @@ clawdbot hooks internal enable session-memory
**After enabling:**
- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
### Disable a Hook
## Disable a Hook
```bash
clawdbot hooks internal disable <name>
clawdbot hooks disable <name>
```
Disable a specific hook by updating your config.
@@ -162,7 +155,7 @@ Disable a specific hook by updating your config.
**Example:**
```bash
clawdbot hooks internal disable command-logger
clawdbot hooks disable command-logger
```
**Output:**
@@ -174,6 +167,53 @@ clawdbot hooks internal disable command-logger
**After disabling:**
- Restart the gateway so hooks reload
## Install Hooks
```bash
clawdbot hooks install <path-or-spec>
```
Install a hook pack from a local folder/archive or npm.
**What it does:**
- Copies the hook pack into `~/.clawdbot/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 to `hooks.internal.load.extraDirs`)
**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
**Examples:**
```bash
# Local directory
clawdbot hooks install ./my-hook-pack
# Local archive
clawdbot hooks install ./my-hook-pack.zip
# NPM package
clawdbot hooks install @clawdbot/my-hook-pack
# Link a local directory without copying
clawdbot hooks install -l ./my-hook-pack
```
## Update Hooks
```bash
clawdbot hooks update <id>
clawdbot 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
@@ -183,7 +223,7 @@ Saves session context to memory when you issue `/new`.
**Enable:**
```bash
clawdbot hooks internal enable session-memory
clawdbot hooks enable session-memory
```
**Output:** `~/clawd/memory/YYYY-MM-DD-slug.md`
@@ -197,7 +237,7 @@ Logs all command events to a centralized audit file.
**Enable:**
```bash
clawdbot hooks internal enable command-logger
clawdbot hooks enable command-logger
```
**Output:** `~/.clawdbot/logs/commands.log`
@@ -216,12 +256,3 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
```
**See:** [command-logger documentation](/internal-hooks#command-logger)
## Gmail
```bash
clawdbot hooks gmail setup --account you@example.com
clawdbot hooks gmail run
```
See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.

View File

@@ -40,6 +40,7 @@ This page describes the current CLI behavior. If commands change, update this do
- [`dns`](/cli/dns)
- [`docs`](/cli/docs)
- [`hooks`](/cli/hooks)
- [`webhooks`](/cli/webhooks)
- [`pairing`](/cli/pairing)
- [`plugins`](/cli/plugins) (plugin commands)
- [`channels`](/cli/channels)
@@ -212,6 +213,14 @@ clawdbot [--dev] [--profile <name>] <command>
console
pdf
hooks
list
info
check
enable
disable
install
update
webhooks
gmail setup|run
pairing
list
@@ -414,12 +423,12 @@ Subcommands:
- `pairing list <channel> [--json]`
- `pairing approve <channel> <code> [--notify]`
### `hooks gmail`
### `webhooks gmail`
Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).
Subcommands:
- `hooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)
- `hooks gmail run` (runtime overrides for the same flags)
- `webhooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--tailscale-target`, `--push-endpoint`, `--json`)
- `webhooks gmail run` (runtime overrides for the same flags)
### `dns setup`
Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).

View File

@@ -28,11 +28,19 @@ clawdbot plugins update --all
### Install
```bash
clawdbot plugins install <npm-spec>
clawdbot plugins install <path-or-spec>
```
Security note: treat plugin installs like running code. Prefer pinned versions.
Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
```bash
clawdbot plugins install -l ./my-plugin
```
### Update
```bash

23
docs/cli/webhooks.md Normal file
View File

@@ -0,0 +1,23 @@
---
summary: "CLI reference for `clawdbot webhooks` (webhook helpers + Gmail Pub/Sub)"
read_when:
- You want to wire Gmail Pub/Sub events into Clawdbot
- You want webhook helper commands
---
# `clawdbot webhooks`
Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
Related:
- Webhooks: [Webhook](/automation/webhook)
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
## Gmail
```bash
clawdbot webhooks gmail setup --account you@example.com
clawdbot webhooks gmail run
```
See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.

View File

@@ -2757,7 +2757,7 @@ Mapping notes:
- If there is no prior delivery route, set `channel` + `to` explicitly (required for Telegram/Discord/Slack/Signal/iMessage/MS Teams).
- `model` overrides the LLM for this hook run (`provider/model` or alias; must be allowed if `agents.defaults.models` is set).
Gmail helper config (used by `clawdbot hooks gmail setup` / `run`):
Gmail helper config (used by `clawdbot webhooks gmail setup` / `run`):
```json5
{

View File

@@ -13,7 +13,7 @@ Internal hooks provide an extensible event-driven system for automating actions
Hooks are small scripts that run when something happens. There are two kinds:
- **Internal hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
- **Web-based hooks**: external HTTP webhooks that let other systems trigger work in Clawdbot. See [Webhook Hooks](/automation/webhook).
- **Web-based hooks**: external HTTP webhooks that let other systems trigger work in Clawdbot. See [Webhook Hooks](/automation/webhook) or use `clawdbot webhooks` for Gmail helper commands.
Common uses:
- Save a memory snapshot when you reset a session
@@ -43,25 +43,25 @@ Clawdbot ships with two bundled hooks that are automatically discovered:
List available hooks:
```bash
clawdbot hooks internal list
clawdbot hooks list
```
Enable a hook:
```bash
clawdbot hooks internal enable session-memory
clawdbot hooks enable session-memory
```
Check hook status:
```bash
clawdbot hooks internal check
clawdbot hooks check
```
Get detailed information:
```bash
clawdbot hooks internal info session-memory
clawdbot hooks info session-memory
```
### Onboarding
@@ -76,6 +76,8 @@ Hooks are automatically discovered from three directories (in order of precedenc
2. **Managed hooks**: `~/.clawdbot/hooks/` (user-installed, shared across workspaces)
3. **Bundled hooks**: `<clawdbot>/dist/hooks/bundled/` (shipped with Clawdbot)
Managed hook directories can be either a **single hook** or a **hook pack** (package directory).
Each hook is a directory containing:
```
@@ -84,6 +86,30 @@ my-hook/
└── handler.ts # Handler implementation
```
## Hook Packs (npm/archives)
Hook packs are standard npm packages that export one or more hooks via `clawdbot.hooks` in
`package.json`. Install them with:
```bash
clawdbot hooks install <path-or-spec>
```
Example `package.json`:
```json
{
"name": "@acme/my-hooks",
"version": "0.1.0",
"clawdbot": {
"hooks": ["./hooks/my-hook", "./hooks/other-hook"]
}
}
```
Each entry points to a hook directory containing `HOOK.md` and `handler.ts` (or `index.ts`).
Hook packs can ship dependencies; they will be installed under `~/.clawdbot/hooks/<id>`.
## Hook Structure
### HOOK.md Format
@@ -252,10 +278,10 @@ export default handler;
```bash
# Verify hook is discovered
clawdbot hooks internal list
clawdbot hooks list
# Enable it
clawdbot hooks internal enable my-hook
clawdbot hooks enable my-hook
# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)
@@ -349,46 +375,46 @@ The old config format still works for backwards compatibility:
```bash
# List all hooks
clawdbot hooks internal list
clawdbot hooks list
# Show only eligible hooks
clawdbot hooks internal list --eligible
clawdbot hooks list --eligible
# Verbose output (show missing requirements)
clawdbot hooks internal list --verbose
clawdbot hooks list --verbose
# JSON output
clawdbot hooks internal list --json
clawdbot hooks list --json
```
### Hook Information
```bash
# Show detailed info about a hook
clawdbot hooks internal info session-memory
clawdbot hooks info session-memory
# JSON output
clawdbot hooks internal info session-memory --json
clawdbot hooks info session-memory --json
```
### Check Eligibility
```bash
# Show eligibility summary
clawdbot hooks internal check
clawdbot hooks check
# JSON output
clawdbot hooks internal check --json
clawdbot hooks check --json
```
### Enable/Disable
```bash
# Enable a hook
clawdbot hooks internal enable session-memory
clawdbot hooks enable session-memory
# Disable a hook
clawdbot hooks internal disable command-logger
clawdbot hooks disable command-logger
```
## Bundled Hooks
@@ -427,7 +453,7 @@ Saves session context to memory when you issue `/new`.
**Enable**:
```bash
clawdbot hooks internal enable session-memory
clawdbot hooks enable session-memory
```
### command-logger
@@ -468,7 +494,7 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
**Enable**:
```bash
clawdbot hooks internal enable command-logger
clawdbot hooks enable command-logger
```
## Best Practices
@@ -550,7 +576,7 @@ Registered hook: command-logger -> command
List all discovered hooks:
```bash
clawdbot hooks internal list --verbose
clawdbot hooks list --verbose
```
### Check Registration
@@ -569,7 +595,7 @@ const handler: InternalHookHandler = async (event) => {
Check why a hook isn't eligible:
```bash
clawdbot hooks internal info my-hook
clawdbot hooks info my-hook
```
Look for missing requirements in the output.
@@ -618,7 +644,7 @@ test('my handler works', async () => {
- **`src/hooks/config.ts`**: Eligibility checking
- **`src/hooks/hooks-status.ts`**: Status reporting
- **`src/hooks/loader.ts`**: Dynamic module loader
- **`src/cli/hooks-internal-cli.ts`**: CLI commands
- **`src/cli/hooks-cli.ts`**: CLI commands
- **`src/gateway/server-startup.ts`**: Loads hooks at gateway start
- **`src/auto-reply/reply/commands-core.ts`**: Triggers command events
@@ -672,7 +698,7 @@ Session reset
3. List all discovered hooks:
```bash
clawdbot hooks internal list
clawdbot hooks list
```
### Hook Not Eligible
@@ -680,7 +706,7 @@ Session reset
Check requirements:
```bash
clawdbot hooks internal info my-hook
clawdbot hooks info my-hook
```
Look for missing:
@@ -693,7 +719,7 @@ Look for missing:
1. Verify hook is enabled:
```bash
clawdbot hooks internal list
clawdbot hooks list
# Should show ✓ next to enabled hooks
```
@@ -772,7 +798,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
4. Verify and restart your gateway process:
```bash
clawdbot hooks internal list
clawdbot hooks list
# Should show: 🎯 my-hook ✓
```
@@ -785,7 +811,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
## See Also
- [CLI Reference: hooks internal](/cli/hooks)
- [CLI Reference: hooks](/cli/hooks)
- [Bundled Hooks README](https://github.com/clawdbot/clawdbot/tree/main/src/hooks/bundled)
- [Webhook Hooks](/automation/webhook)
- [Configuration](/gateway/configuration#hooks)

View File

@@ -157,9 +157,11 @@ export default {
```bash
clawdbot plugins list
clawdbot plugins info <id>
clawdbot plugins install <path> # add a local file/dir to plugins.load.paths
clawdbot plugins install <path> # copy a local file/dir into ~/.clawdbot/extensions/<id>
clawdbot plugins install ./extensions/voice-call # relative path ok
clawdbot plugins install ./plugin.tgz # install from a local tarball
clawdbot plugins install ./plugin.tgz # install from a local tarball
clawdbot plugins install ./plugin.zip # install from a local zip
clawdbot plugins install -l ./extensions/voice-call # link (no copy) for dev
clawdbot plugins install @clawdbot/voice-call # install from npm
clawdbot plugins update <id>
clawdbot plugins update --all

View File

@@ -87,7 +87,7 @@ On the first agent run, Clawdbot bootstraps a workspace (default `~/clawd`):
Gmail Pub/Sub setup is currently a manual step. Use:
```bash
clawdbot hooks gmail setup --account you@gmail.com
clawdbot webhooks gmail setup --account you@gmail.com
```
See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.