Hooks

Hooks ger ett utbyggbart händelsestyrt system för att automatisera åtgärder som svar på agentkommandon och händelser. Hooks upptäcks automatiskt från kataloger och kan hanteras via kommandon CLI, liknande hur färdigheter fungerar i OpenClaw.

Kom igång

Krokar är små skript som körs när något händer. Det finns två typer:

Hooks (denna sida): körs inuti Gateway när agenthändelser inträffar, som /new, /reset, /stop eller livscykelhändelser.
Webhooks: externa HTTP-webhooks som låter andra system utlösa fungera i OpenClaw. Se Webhook krokar eller använd openclaw webhooks för Gmail hjälparkommandon.

Hooks kan också paketeras inuti plugins; se Plugins. Vanliga användningsområden:

Spara en minnesögonblicksbild när du återställer en session
Hålla ett revisionsspår av kommandon för felsökning eller regelefterlevnad
Trigga uppföljande automatisering när en session startar eller slutar
Skriva filer till agentens arbetsyta eller anropa externa API:er när händelser inträffar

Om du kan skriva en liten TypeScript funktion kan du skriva en krok. Krokar upptäcks automatiskt, och du aktiverar eller inaktiverar dem via CLI.

Översikt

Hooks-systemet låter dig:

Spara sessionskontext till minne när /new utfärdas
Logga alla kommandon för revision
Trigga anpassade automatiseringar vid agentens livscykelhändelser
Utöka OpenClaws beteende utan att ändra kärnkod

Kom igång

Medföljande hooks

OpenClaw levereras med fyra medföljande hooks som upptäcks automatiskt:

💾 session-memory: Sparar sessionskontext till agentens arbetsyta (standard ~/.openclaw/workspace/memory/) när du utfärdar /new
📝 command-logger: Loggar alla kommandon till ~/.openclaw/logs/commands.log
🚀 boot-md: Kör BOOT.md när gatewayen startar (kräver att interna hooks är aktiverade)
😈 soul-evil: Byter injicerat SOUL.md-innehåll mot SOUL_EVIL.md under ett rensningsfönster eller av slumpmässig chans

Lista tillgängliga hooks:

openclaw hooks list

Aktivera en hook:

openclaw hooks enable session-memory

Kontrollera hook-status:

openclaw hooks check

Hämta detaljerad information:

openclaw hooks info session-memory

Introduktion

Under onboarding (openclaw onboard), kommer du bli ombedd att aktivera rekommenderade hooks. Guiden upptäcker automatiskt kvalificerade krokar och presenterar dem för urval.

Hook-upptäckt

Hooks upptäcks automatiskt från tre kataloger (i prioritetsordning):

Arbetsyte-hooks: <workspace>/hooks/ (per agent, högsta prioritet)
Hanterade hooks: ~/.openclaw/hooks/ (användarinstallerade, delas mellan arbetsytor)
Medföljande hooks: <openclaw>/dist/hooks/bundled/ (levereras med OpenClaw)

Hanterade hook-kataloger kan vara antingen en enskild hook eller ett hook-paket (paketkatalog). Varje hook är en katalog som innehåller:

my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

Hook-paket (npm/arkiv)

Krokpaket är standard npm paket som exporterar en eller flera krokar via openclaw.hooks i package.json. Installera dem med:

openclaw hooks install <path-or-spec>

Npm-specifikationer är endast registry-baserade (paketnamn + valfri version/tagg). Git/URL-/fil-specifikationer avvisas. Exempel på package.json:

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

Varje post pekar på en krokkatalog som innehåller HOOK.md och handler.ts (eller index.ts). Krokpaket kan skicka beroenden, de kommer att installeras under ~/.openclaw/hooks/<id>. Säkerhetsnotering: openclaw hooks install installerar beroenden med npm install --ignore-scripts (inga livscykelskript). Håll hook‑paketens beroendeträd “ren JS/TS” och undvik paket som förlitar sig på postinstall-byggen.

Hook-struktur

HOOK.md-format

Filen HOOK.md innehåller metadata i YAML-frontmatter plus Markdown-dokumentation:

---
name: my-hook
description: "Kort beskrivning av vad denna hook gör"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detaljerad dokumentation finns här...

## Vad den gör

- Lyssnar efter `/new`-kommandon
- Utför en åtgärd
- Loggar resultatet

## Krav

- Node.js måste vara installerat

## Konfiguration

Ingen konfiguration behövs.

Metadatafält

Objektet metadata.openclaw stöder:

emoji: Visa emoji för CLI (t.ex., "💾")
händelser: En rad händelser att lyssna på (t.ex., ["kommand:new", "kommando: reset"])
export: Namngiven export att använda (standard "default")
homepage: Dokumentations-URL
requires: Valfria krav
- bins: Obligatoriska binärer på PATH (t.ex., ["git", "node"])
- anyBins: Minst en av dessa binärer måste finnas
- env: Krävs miljövariabler
- config: Obligatoriska konfigurationsvägar (t.ex., ["workspace.dir"])
- os: Obligatoriska plattformar (t.ex., ["darwin", "linux"])
always: Förbigå behörighetskontroller (boolean)
install: Installationsmetoder (för medföljande hooks: [{"id":"bundled","kind":"bundled"}])

Handler-implementation

Filen handler.ts exporterar en HookHandler-funktion:

import type { HookHandler } from "../../src/hooks/hooks.js";

const myHandler: HookHandler = async (event) => {
  // Only trigger on 'new' command
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // Your custom logic here

  // Optionally send message to user
  event.messages.push("✨ My hook executed!");
};

export default myHandler;

Händelsekontext

Varje händelse innehåller:

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // e.g., 'new', 'reset', 'stop'
  sessionKey: string,          // Session identifier
  timestamp: Date,             // When the event occurred
  messages: string[],          // Push messages here to send to user
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

Händelsetyper

Kommandohändelser

Triggas när agentkommandon utfärdas:

agent:bootstrap: Innan arbetsytans bootstrap-filer injiceras (hooks kan mutera context.bootstrapFiles)
command:new: När kommandot /new utfärdas
command:reset: När kommandot /reset utfärdas
command:stop: När kommandot /stop utfärdas

Gateway-händelser

agent:bootstrap: Innan arbetsytans bootstrap-filer injiceras (hooks kan mutera context.bootstrapFiles)

Gateway-händelser

Triggas när gatewayen startar:

gateway:startup: Efter att kanaler startar och hooks har laddats

Verktygsresultat-hooks (Plugin API)

Dessa hooks är inte händelseströmslyssnare; de låter plugins synkront justera verktygsresultat innan OpenClaw sparar dem.

tool_result_persist: transformera verktygsresultat innan de skrivs till sessionsutskriften. Måste vara synkroniserad; returnera det uppdaterade verktygsresultatet nyttolast eller odefinierad för att behålla det som -is. Se Agent Loop.

Framtida händelser

Planerade händelsetyper:

session:start: När en ny session börjar
session:end: När en session avslutas
agent:error: När en agent stöter på ett fel
message:sent: När ett meddelande skickas
message:received: När ett meddelande tas emot

Skapa anpassade hooks

1. Välj plats

Arbetsyte-hooks (<workspace>/hooks/): Per agent, högsta prioritet
Hanterade hooks (~/.openclaw/hooks/): Delas mellan arbetsytor

2. Skapa katalogstruktur

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

3. Skapa HOOK.md

---
name: my-hook
description: "Does something useful"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

This hook does something useful when you issue `/new`.

4. Skapa handler.ts

import type { HookHandler } from "../../src/hooks/hooks.js";

const handler: HookHandler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log("[my-hook] Running!");
  // Your logic here
};

export default handler;

5. Aktivera och testa

# Verify hook is discovered
openclaw hooks list

# Enable it
openclaw hooks enable my-hook

# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)

# Trigger the event
# Send /new via your messaging channel

Konfiguration

Per-hook-konfiguration

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

Per-hook-konfiguration

Hooks kan ha anpassad konfiguration:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": {
            "MY_CUSTOM_VAR": "value"
          }
        }
      }
    }
  }
}

Extra kataloger

Ladda hooks från ytterligare kataloger:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

Äldre konfigformat (stöds fortfarande)

Det gamla konfigformatet fungerar fortfarande för bakåtkompatibilitet:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts",
          "export": "default"
        }
      ]
    }
  }
}

Obs: module måste vara en arbetsyterelativ sökväg. Absoluta sökvägar och traversal utanför arbetsytan avvisas. Migration: Använd det nya upptäcktsbaserade systemet för nya krokar. Äldre hanterare laddas efter katalogbaserade krokar.

Hook-information

Lista hooks

# List all hooks
openclaw hooks list

# Show only eligible hooks
openclaw hooks list --eligible

# Verbose output (show missing requirements)
openclaw hooks list --verbose

# JSON output
openclaw hooks list --json

Hook-information

# Show detailed info about a hook
openclaw hooks info session-memory

# JSON output
openclaw hooks info session-memory --json

Kontrollera behörighet

# Show eligibility summary
openclaw hooks check

# JSON output
openclaw hooks check --json

Aktivera/inaktivera

# Enable a hook
openclaw hooks enable session-memory

# Disable a hook
openclaw hooks disable command-logger

Referens för medföljande hooks

session-memory

Utdata: <workspace>/memory/YYYY-MM-DD-slug.md (standard ~/.openclaw/workspace) Vad den gör: Krav: workspace.dir måste vara konfigurerad Exempelutdata: Vad den gör:

Använder sessionsposten före återställning för att hitta rätt transkript
Extraherar de senaste 15 raderna av konversationen
Använder LLM för att generera en beskrivande filnamnsslug
Sparar sessionsmetadata till en daterad minnesfil

Exempelutdata:

# Session: 2026-01-16 14:30:00 UTC

- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

Exempel på filnamn:

2026-01-16-vendor-pitch.md
2026-01-16-api-design.md
2026-01-16-1430.md (reservtidsstämpel om slug-generering misslyckas)

Loggar alla kommandohändelser till en centraliserad revisionsfil.

openclaw hooks enable session-memory

bootstrap-extra-files

Utdata: ~/.openclaw/logs/commands.log Vad den gör: Krav: workspace.dir måste vara konfigurerad Exempel på loggposter: Konfig:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

Obs:

Sökvägar löses relativt till arbetsytan.
Filer måste stanna inom arbetsytan (realpath-kontrolleras).
Endast igenkända bootstrap-basnamn läses in.
Subagentens allowlist bevaras (endast AGENTS.md och TOOLS.md).

Aktivera:

openclaw hooks enable bootstrap-extra-files

command-logger

Händelser: agent:bootstrap Dokumentation: SOUL Evil Hook Utdata: Inga filer skrivs; byten sker endast i minnet. Aktivera: Vad den gör:

Fångar händelsedetaljer (kommandoåtgärd, tidsstämpel, sessionsnyckel, avsändar-ID, källa)
Lägger till i loggfil i JSONL-format
Kör tyst i bakgrunden

Exempel på loggposter:

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"[email protected]","source":"whatsapp"}

Visa loggar:

# View recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print with jq
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

Krav: workspace.dir måste vara konfigurerad

openclaw hooks enable command-logger

boot-md

Kör BOOT.md när gateway (nätverksgateway) startar (efter att kanalerna startat). Interna krokar måste vara aktiverade för att detta ska kunna köras. Händelser: gateway:startup Krav: workspace.dir måste vara konfigurerad Vad den gör:

Läser BOOT.md från din arbetsyta
Kör instruktionerna via agent-runnern
Skickar eventuella begärda utgående meddelanden via meddelandeverktyget

Aktivera:

openclaw hooks enable boot-md

Bästa praxis

Håll handlers snabba

Krokar körs under kommandobearbetning. Håll dem lätta:

// ✓ Good - async work, returns immediately
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ Bad - blocks command processing
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

Hantera fel på ett robust sätt

Omslut alltid riskfyllda operationer:

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // Don't throw - let other handlers run
  }
};

Filtrera händelser tidigt

I stället för:

const handler: HookHandler = async (event) => {
  // Only handle 'new' commands
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // Your logic here
};

Felsökning

Specificera exakta händelser i metadata när det är möjligt:

metadata: { "openclaw": { "events": ["command:new"] } } # Specific

I stället för:

metadata: { "openclaw": { "events": ["command"] } } # General - more overhead

Felsökning

Aktivera hook-loggning

Gatewayen loggar laddning av hooks vid uppstart:

Registered hook: session-memory -> command:new
Registered hook: bootstrap-extra-files -> agent:bootstrap
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

Kontrollera upptäckt

Lista alla upptäckta hooks:

openclaw hooks list --verbose

Kontrollera registrering

Leta efter saknade krav i utdata.

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // Your logic
};

Gateway-loggar

Övervaka gateway-loggar för att se hook-exekvering:

openclaw hooks info my-hook

Leta efter saknade krav i utdata.

Testning

Gateway-loggar

Övervaka gateway-loggar för att se hook-exekvering:

# macOS
./scripts/clawlog.sh -f

# Other platforms
tail -f ~/.openclaw/gateway.log

Testa hooks direkt

Testa dina handlers isolerat:

import { test } from "vitest";
import { createHookEvent } from "./src/hooks/hooks.js";
import myHandler from "./hooks/my-hook/handler.js";

test("my handler works", async () => {
  const event = createHookEvent("command", "new", "test-session", {
    foo: "bar",
  });

  await myHandler(event);

  // Assert side effects
});

Händelseflöde

Kärnkomponenter

src/hooks/types.ts: Typdefinitioner
src/hooks/workspace.ts: Katalogskanning och laddning
src/hooks/frontmatter.ts: Parsning av HOOK.md-metadata
src/hooks/config.ts: Behörighetskontroll
src/hooks/hooks-status.ts: Statusrapportering
src/hooks/loader.ts: Dynamisk modulladdare
src/cli/hooks-cli.ts: CLI-kommandon
src/gateway/server-startup.ts: Laddar hooks vid gateway-start
src/auto-reply/reply/commands-core.ts: Triggar kommandohändelser

Hook upptäcks inte

Gateway startup
    ↓
Scan directories (workspace → managed → bundled)
    ↓
Parse HOOK.md files
    ↓
Check eligibility (bins, env, config, os)
    ↓
Load handlers from eligible hooks
    ↓
Register handlers for events

Hook inte behörig

User sends /new
    ↓
Command validation
    ↓
Create hook event
    ↓
Trigger hook (all registered handlers)
    ↓
Command processing continues
    ↓
Session reset

Felsökning

Hook upptäcks inte

Binärer (kontrollera PATH)

ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

Miljövariabler

cat ~/.openclaw/hooks/my-hook/HOOK.md
# Should have YAML frontmatter with name and metadata

Konfigvärden
openclaw hooks list

Hook körs inte

Kontrollera kraven:

openclaw hooks info my-hook

Kontrollera TypeScript-/importfel:

Binärer (kontrollera PATH)
Miljövariabler
Konfigvärden
OS-kompatibilitet

Migreringsguide

Verifiera att hooken är aktiverad:

openclaw hooks list
# Should show ✓ next to enabled hooks

Starta om din gateway-process så att hooks laddas om.
Kontrollera gateway-loggar efter fel:
./scripts/clawlog.sh | grep hook

Handler-fel

Kontrollera TypeScript-/importfel:

# Test import directly
node -e "import('./path/to/handler.ts').then(console.log)"

Migreringsguide

Från äldre konfig till upptäckt

Före:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts"
        }
      ]
    }
  }
}

Efter:

Skapa hook-katalog:

mkdir -p ~/.openclaw/hooks/my-hook
mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts

Skapa HOOK.md:

---
name: my-hook
description: "My custom hook"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Hook

Does something useful.

Uppdatera konfig:

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": { "enabled": true }
      }
    }
  }
}

Verifiera och starta om din gateway-process:

openclaw hooks list
# Should show: 🎯 my-hook ✓

Fördelar med migrering:

Automatisk upptäckt
CLI-hantering
Behörighetskontroll
Bättre dokumentation
Konsekvent struktur

​Hooks

​Kom igång

​Översikt

​Kom igång

​Medföljande hooks

​Introduktion

​Hook-upptäckt

​Hook-paket (npm/arkiv)

​Hook-struktur

​HOOK.md-format

​Metadatafält

​Handler-implementation

​Händelsekontext

​Händelsetyper

​Kommandohändelser

​Gateway-händelser

​Gateway-händelser

​Verktygsresultat-hooks (Plugin API)

​Framtida händelser

​Skapa anpassade hooks

​1. Välj plats

​2. Skapa katalogstruktur

​3. Skapa HOOK.md

​4. Skapa handler.ts

​5. Aktivera och testa

​Konfiguration

​Per-hook-konfiguration

​Per-hook-konfiguration

​Extra kataloger

​Äldre konfigformat (stöds fortfarande)

​Hook-information

​Lista hooks

​Hook-information

​Kontrollera behörighet

​Aktivera/inaktivera

​Referens för medföljande hooks

​session-memory

​bootstrap-extra-files

​command-logger

​boot-md

​Bästa praxis

​Håll handlers snabba

​Hantera fel på ett robust sätt

​Filtrera händelser tidigt

​Felsökning

​Felsökning

​Aktivera hook-loggning

​Kontrollera upptäckt

​Kontrollera registrering

​Gateway-loggar

​Testning

​Gateway-loggar

​Testa hooks direkt

​Händelseflöde

​Kärnkomponenter

​Hook upptäcks inte

​Hook inte behörig

​Felsökning

​Hook upptäcks inte

​Hook körs inte

​Migreringsguide

​Handler-fel

​Migreringsguide

​Från äldre konfig till upptäckt

​Se även

Hooks

Kom igång

Översikt

Kom igång

Medföljande hooks

Introduktion

Hook-upptäckt

Hook-paket (npm/arkiv)

Hook-struktur

HOOK.md-format

Metadatafält

Handler-implementation

Händelsekontext

Händelsetyper

Kommandohändelser

Gateway-händelser

Gateway-händelser

Verktygsresultat-hooks (Plugin API)

Framtida händelser

Skapa anpassade hooks

1. Välj plats

2. Skapa katalogstruktur

3. Skapa HOOK.md

4. Skapa handler.ts

5. Aktivera och testa

Konfiguration

Per-hook-konfiguration

Per-hook-konfiguration

Extra kataloger

Äldre konfigformat (stöds fortfarande)

Hook-information

Lista hooks

Hook-information

Kontrollera behörighet

Aktivera/inaktivera

Referens för medföljande hooks

session-memory

bootstrap-extra-files

command-logger

boot-md

Bästa praxis

Håll handlers snabba

Hantera fel på ett robust sätt

Filtrera händelser tidigt

Felsökning

Felsökning

Aktivera hook-loggning

Kontrollera upptäckt

Kontrollera registrering

Gateway-loggar

Testning

Gateway-loggar

Testa hooks direkt

Händelseflöde

Kärnkomponenter

Hook upptäcks inte

Hook inte behörig

Felsökning

Hook upptäcks inte

Hook körs inte

Migreringsguide

Handler-fel

Migreringsguide

Från äldre konfig till upptäckt

Se även