LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/hooks.md
View on GitHub# OpenClaw Hooks Reference
## Table of Contents
- [Overview](#overview)
- [Two Systems: Internal Hooks vs HTTP Webhooks](#two-systems-internal-hooks-vs-http-webhooks)
- [Internal Hooks](#internal-hooks)
- [Architecture](#architecture)
- [Event Types](#event-types)
- [Hook Directory Structure](#hook-directory-structure)
- [HOOK.md Metadata](#hookmd-metadata)
- [handler.ts Implementation](#handlerts-implementation)
- [Bundled Hooks](#bundled-hooks)
- [Hook Packs](#hook-packs)
- [CLI Commands](#cli-commands)
- [Configuration](#configuration)
- [Custom Hook Authoring](#custom-hook-authoring)
- [HTTP Webhooks](#http-webhooks)
- [Enable](#enable)
- [Endpoints](#endpoints)
- [Auth](#auth)
- [Session Key Policy](#session-key-policy)
- [Security](#security)
- [Use Cases & Patterns](#use-cases--patterns)
- [Troubleshooting](#troubleshooting)
---
## Overview
OpenClaw's **Hooks** system provides an extensible, event-driven mechanism for automating actions in response to agent commands, lifecycle events, and external triggers — all **without modifying core code**.
There are **two distinct systems** both referred to as "hooks":
1. **Internal Hooks** — local event handlers running inside the Gateway process
2. **HTTP Webhooks** — inbound HTTP endpoints allowing external systems to trigger OpenClaw
---
## Two Systems: Internal Hooks vs HTTP Webhooks
| Aspect | Internal Hooks | HTTP Webhooks |
|---|---|---|
| **Direction** | Inside-out: respond to internal events | Outside-in: external HTTP calls trigger OpenClaw |
| **Runtime** | Execute within Gateway process | Gateway exposes HTTP endpoints |
| **Language** | TypeScript (`handler.ts`) | Any HTTP client (curl, GitHub, Stripe, n8n) |
| **Auth** | N/A (trusted local execution) | Requires `gateway.auth.token` or `gateway.auth.password` |
| **Config key** | Managed via `openclaw hooks` CLI | `gateway.webhooks.enabled` / `hooks.enabled` + `hooks.token` |
| **Use cases** | Audit logging, session memory, bootstrap injection | GitHub webhooks, Stripe events, external automation |
---
## Internal Hooks
### Architecture
Internal hooks are small TypeScript scripts that execute when specific events fire within the OpenClaw Gateway. They are:
- **Automatically discovered** from designated directories
- **Managed via CLI** (enable/disable/install)
- **Event-driven** — each hook subscribes to one or more event types
- **Scoped** — workspace hooks override managed hooks, which override bundled hooks
### Event Types
#### Command Events
| Event | Trigger |
|---|---|
| `command` | Any command event (wildcard listener) |
| `command:new` | User issues `/new` command |
| `command:reset` | User issues `/reset` command |
| `command:stop` | User issues `/stop` command |
#### Agent Events
| Event | Trigger |
|---|---|
| `agent:bootstrap` | Before workspace bootstrap files are injected; hooks can modify `context.bootstrapFiles` |
#### Gateway Events
| Event | Trigger |
|---|---|
| `gateway:startup` | After channels have started and hooks are loaded |
#### Message Events
| Event | Trigger |
|---|---|
| `message` | Any message event (wildcard listener) |
| `message:received` | Inbound message received from any channel (early pipeline) |
| `message:transcribed` | Message fully processed, including audio transcription |
| `message:preprocessed` | After all media and link understanding is complete |
#### Future Events (Planned)
| Event | Trigger |
|---|---|
| `session:start` | When a new session begins |
| `session:end` | When a session concludes |
| `agent:error` | When an agent encounters an error |
### Hook Directory Structure
Hooks are discovered from three directories, processed in **precedence order**:
| Priority | Location | Scope |
|---|---|---|
| 1 (highest) | `<workspace>/hooks/` | Per-agent workspace hooks |
| 2 | `~/.openclaw/hooks/` | User-managed hooks, shared across workspaces |
| 3 (lowest) | `<openclaw>/dist/hooks/bundled/` | Bundled hooks shipped with OpenClaw |
Each hook is a **directory** containing:
```
my-hook/
├── HOOK.md # Metadata + documentation (required)
└── handler.ts # Hook logic (required, can also be index.ts)
```
Additional directories can be specified via configuration (see [Configuration](#configuration)).
### HOOK.md Metadata
The `HOOK.md` file contains YAML frontmatter for metadata, followed by Markdown documentation.
```markdown
---
metadata:
openclaw:
name: session-memory
description: Save session context to memory on /new
emoji: 🧠
events:
- command:new
requires:
bins: []
env: []
---
# Session Memory Hook
This hook automatically saves the current session context to the agent's
workspace memory when the user issues the `/new` command, preserving
conversation continuity across sessions.
```
**Frontmatter fields** (under `metadata.openclaw`):
| Field | Type | Description |
|---|---|---|
| `name` | string | Hook identifier (used in CLI commands) |
| `description` | string | Short description |
| `emoji` | string | Display emoji |
| `events` | string[] | List of event types this hook subscribes to |
| `requires.bins` | string[] | Required binaries (hook won't activate if missing) |
| `requires.env` | string[] | Required environment variables |
### handler.ts Implementation
The `handler.ts` file exports a `HookHandler` function that receives an event object.
```typescript
import type { HookHandler } from "openclaw/hooks";
export const handler: HookHandler = async (event) => {
// event.type — the event type string (e.g. "command:new")
// event.context — contextual data (varies by event type)
// event.config — per-hook configuration
if (event.type === "command:new") {
// Save session context to memory file
const sessionData = event.context.sessionSummary;
// ... write to workspace memory ...
console.log("[session-memory] Saved session context");
}
};
```
**Event object properties** (vary by event type):
| Property | Description |
|---|---|
| `event.type` | The event type string |
| `event.context` | Rich context object (session data, bootstrap files, message content, etc.) |
| `event.config` | Per-hook custom configuration |
For `agent:bootstrap` events, hooks can modify `event.context.bootstrapFiles` to inject additional files into the workspace.
### Bundled Hooks
OpenClaw ships with several pre-built hooks:
| Hook | Events | Description |
|---|---|---|
| `session-memory` | `command:new` | Saves session context to agent workspace memory on `/new` |
| `command-logger` | `command` | Logs all command events to `~/.openclaw/logs/commands.log` for audit |
| `boot-md` | `gateway:startup` | Runs the `BOOT.md` file when Gateway starts |
| `bootstrap-extra-files` | `agent:bootstrap` | Injects additional workspace files based on configured glob patterns |
### Hook Packs
Hook packs are **distributable bundles** containing one or more hooks. They support:
- **Local installation**: from a folder or archive
- **npm distribution**: standard npm packages
```bash
# Install from local folder
openclaw hooks install ./my-hook-pack
# Install from npm
openclaw hooks install @myorg/openclaw-hooks-audit
# Update installed hook packs (npm only)
openclaw hooks update
```
When installed, hook packs are placed in `~/.openclaw/hooks/<id>/` and their hooks are automatically enabled.
**Creating a hook pack** for npm distribution:
```json
{
"name": "@myorg/openclaw-hooks-audit",
"version": "1.0.0",
"openclaw": {
"type": "hook-pack"
}
}
```
### CLI Commands
```bash
# List all discovered hooks (workspace, managed, bundled)
openclaw hooks list
openclaw hooks list --eligible # Only hooks meeting requirements
openclaw hooks list --verbose # Include missing requirements detail
openclaw hooks list --json # Machine-readable output
# Get detailed info about a hook
openclaw hooks info <name>
# Check eligibility status for all hooks
openclaw hooks check
# Enable / disable a hook
openclaw hooks enable <name>
openclaw hooks disable <name>
# Install hook packs
openclaw hooks install <path-or-spec>
# Update installed hook packs (npm)
openclaw hooks update
```
### Configuration
**In `~/.openclaw/openclaw.json`:**
```json5
{
hooks: {
// Enable webhook HTTP endpoints (separate from internal hooks)
enabled: true,
// Shared secret for webhook authentication
token: "your-webhook-token",
// Custom webhook path prefix (default: /hooks)
path: "/hooks",
// Load hooks from additional directories
dirs: [
"/path/to/custom/hooks",
"~/my-project/hooks",
],
},
}
```
**Per-hook configuration** can be specified in the hook's `HOOK.md` frontmatter or through the main config file, and is accessible via `event.config` in the handler.
**After enabling/disabling hooks**, restart the Gateway for changes to take effect:
```bash
openclaw gateway restart
```
### Custom Hook Authoring
**Step-by-step guide to create a custom hook:**
1. **Choose location**:
- `<workspace>/hooks/` — per-agent, highest precedence
- `~/.openclaw/hooks/` — shared across workspaces
2. **Create directory**:
```bash
mkdir -p ~/.openclaw/hooks/my-custom-hook
```
3. **Create `HOOK.md`**:
```markdown
---
metadata:
openclaw:
name: my-custom-hook
description: Notifies Slack when a session ends
emoji: 🔔
events:
- command:new
- command:reset
requires:
bins: []
env:
- SLACK_WEBHOOK_URL
---
# My Custom Hook
Posts a notification to Slack whenever a session is reset or a new one starts.
```
4. **Create `handler.ts`**:
```typescript
import type { HookHandler } from "openclaw/hooks";
export const handler: HookHandler = async (event) => {
const webhookUrl = process.env.SLACK_WEBHOOK_URL;
if (!webhookUrl) return;
const message = event.type === "command:new"
? "🆕 New session started"
: "🔄 Session reset";
await fetch(webhookUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: message }),
});
};
```
5. **Enable and test**:
```bash
openclaw hooks enable my-custom-hook
openclaw hooks info my-custom-hook
openclaw gateway restart
```
---
## HTTP Webhooks
HTTP webhooks are **inbound HTTP endpoints** exposed by the Gateway, allowing external systems to trigger agent work.
> Note: For detailed webhook configuration, also see [automation.md](automation.md).
### Enable
```json5
{
gateway: {
webhooks: { enabled: true },
},
}
```
### Endpoints
| Endpoint | Method | Description |
|---|---|---|
| `POST /hooks/wake` | POST | Trigger a wake/heartbeat cycle |
| `POST /hooks/agent` | POST | Send a prompt, run a dedicated agent turn |
| `POST /hooks/<name>` | POST | Custom-named endpoints via `gateway.webhooks.map` |
**`/hooks/agent` payload options:**
| Field | Description |
|---|---|
| `message` | The prompt to send |
| `name` | Optional display name |
| `agentId` | Route to a specific agent |
| `sessionKey` | Identify the agent's session |
| `wakeMode` | Wake behavior control |
| `model` | Override model |
| `thinking` | Override thinking level |
| `delivery` | Delivery options (channel, target) |
### Auth
Webhooks require `gateway.auth.token` or `gateway.auth.password`. Pass via:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "Check server status"}'
```
### Session Key Policy
- Default: each webhook call gets a fresh `hook:<uuid>` session key
- Override with `sessionKey` in the request body for persistent sessions
### Security
- Always use auth tokens
- Bind to loopback (`127.0.0.1`) or use Tailscale/VPN
- Webhooks inherit the agent's tool permissions
- Never expose webhook endpoints to the public internet without auth
---
## Use Cases & Patterns
### 1. Session Memory Preservation
**Hook**: `session-memory` (bundled)
**Event**: `command:new`
**Pattern**: Auto-save session summary before starting a new one, preventing context loss.
### 2. Audit Logging
**Hook**: `command-logger` (bundled)
**Event**: `command` (all)
**Pattern**: Log every command with timestamp and user identity to `~/.openclaw/logs/commands.log` for compliance/audit trails.
### 3. Custom Bootstrap Injection
**Hook**: `bootstrap-extra-files` (bundled)
**Event**: `agent:bootstrap`
**Pattern**: Inject project-specific files (`.cursorrules`, `CONVENTIONS.md`, etc.) into the workspace at agent startup.
### 4. External Notifications
**Event**: `command:new`, `command:reset`
**Pattern**: Send Slack/Discord/email notifications when sessions change, useful for team monitoring.
### 5. GitHub → Agent Pipeline
**Type**: HTTP Webhook
**Pattern**: GitHub sends push/PR webhooks to `/hooks/agent`, OpenClaw runs code review or deployment checks.
### 6. Stripe → Agent Processing
**Type**: HTTP Webhook
**Pattern**: Stripe payment events trigger agent runs for order confirmation, refund processing, or subscription management.
### 7. Scheduled Maintenance via Cron + Hooks
**Pattern**: Cron job triggers a heartbeat; internal hook on `gateway:startup` ensures environment is clean.
### 8. Message Filtering / Preprocessing
**Event**: `message:received`, `message:preprocessed`
**Pattern**: Custom hooks that filter spam, redact PII, or enrich messages before they reach the agent.
### 9. Multi-Agent Event Bus
**Pattern**: Hooks function as an event bus, allowing one agent's actions to trigger hooks that affect other agents in multi-agent setups.
### 10. Gateway Startup Initialization
**Hook**: `boot-md` (bundled)
**Event**: `gateway:startup`
**Pattern**: Execute a `BOOT.md` instruction file to set up the agent's identity, load configurations, or run startup tasks.
---
## Troubleshooting
| Problem | Diagnosis | Fix |
|---|---|---|
| Hook not firing | `openclaw hooks list --verbose` — check if eligible | Ensure required bins/env are present, then `openclaw hooks enable <name>` |
| Hook enabled but no effect | Check Gateway logs (`openclaw logs --follow`) | Restart Gateway after enabling: `openclaw gateway restart` |
| Webhook returns 401 | Auth token mismatch | Verify `gateway.auth.token` matches `Authorization` header |
| Webhook returns 404 | Webhooks not enabled or wrong path | Set `gateway.webhooks.enabled: true`, check `hooks.path` |
| Hook from plugin not appearing | Plugin may not be loaded | Check `openclaw plugins list`, ensure plugin is enabled |
| Custom hook directory not scanned | Extra dirs not configured | Add path to `hooks.dirs` in config |
| Hook pack install fails | Network or permissions issue | Check npm access, try local install path instead |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |