openclaw hooks list

openclaw hooks enable session-memory

openclaw hooks check

openclaw hooks info session-memory

my-hook/
├── HOOK.md          # 元數(shù)據(jù) + 文檔
└── handler.ts       # 處理程序?qū)崿F(xiàn)

openclaw hooks install <path-or-spec>

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

---
name: my-hook
description: "Short description of what this hook does"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "??", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
Detailed documentation goes here...
## What It Does
- Listens for `/new` commands
- Performs some action
- Logs the result
## Requirements
- Node.js must be installed
## Configuration
No configuration needed.

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;

{
  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
  }
}

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

---
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`.

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;

# 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

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

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

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

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

# 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

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

# Show eligibility summary
openclaw hooks check
# JSON output
openclaw hooks check --json

# Enable a hook
openclaw hooks enable session-memory
# Disable a hook
openclaw hooks disable command-logger

# Session: 2026-01-16 14:30:00 UTC
- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

openclaw hooks enable session-memory

{"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":"user@example.com","source":"whatsapp"}

# 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 .

openclaw hooks enable command-logger

openclaw hooks enable boot-md

// ? 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);
};

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
  }
};

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

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

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

Registered hook: session-memory -> command:new
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

openclaw hooks list --verbose

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

openclaw hooks info my-hook

# macOS
./scripts/clawlog.sh -f
# Other platforms
tail -f ~/.openclaw/gateway.log

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
});

Gateway 網(wǎng)關(guān)啟動(dòng)
    ↓
掃描目錄（工作區(qū) → 托管 → 捆綁）
    ↓
解析 HOOK.md 文件
    ↓
檢查資格（bins、env、config、os）
    ↓
從符合條件的 hooks 加載處理程序
    ↓
為事件注冊(cè)處理程序

用戶發(fā)送 /new
    ↓
命令驗(yàn)證
    ↓
創(chuàng)建 hook 事件
    ↓
觸發(fā) hook（所有注冊(cè)的處理程序）
    ↓
命令處理繼續(xù)
    ↓
會(huì)話重置

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

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

openclaw hooks list

openclaw hooks info my-hook

openclaw hooks list
# Should show ? next to enabled hooks

./scripts/clawlog.sh | grep hook

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

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

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

---
name: my-hook
description: "My custom hook"
metadata: { "openclaw": { "emoji": "??", "events": ["command:new"] } }
---
# My Hook
Does something useful.

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

openclaw hooks list
# Should show: ?? my-hook ?