openclaw hooks list

openclaw hooks enable session-memory

openclaw hooks check

openclaw hooks info session-memory

my-hook/
├── HOOK.md          # Metadata + tài liệu
└── handler.ts       # Triển khai handler

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: "Mô tả ngắn gọn về những gì hook này làm"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Tài liệu chi tiết ở đây...

## Những gì nó làm

- Lắng nghe các lệnh `/new`
- Thực hiện một số hành động
- Ghi lại kết quả

## Yêu cầu

- Node.js phải được cài đặt

## Cấu hình

Không cần cấu hình.

const myHandler = async (event) => {
  // Chỉ kích hoạt trên lệnh 'new'
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] Lệnh mới được kích hoạt`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // Logic tùy chỉnh của bạn ở đây

  // Tùy chọn gửi tin nhắn đến người dùng
  event.messages.push("✨ Hook của tôi đã thực thi!");
};

export default myHandler;

{
  type: 'command' | 'session' | 'agent' | 'gateway' | 'message',
  action: string,              // ví dụ: 'new', 'reset', 'stop', 'received', 'sent'
  sessionKey: string,          // Định danh session
  timestamp: Date,             // Khi sự kiện xảy ra
  messages: string[],          // Đẩy tin nhắn vào đây để gửi đến người dùng
  context: {
    // Sự kiện lệnh:
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // ví dụ: 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig,
    // Sự kiện tin nhắn (xem phần Sự kiện Tin nhắn để biết chi tiết đầy đủ):
    from?: string,             // message:received
    to?: string,               // message:sent
    content?: string,
    channelId?: string,
    success?: boolean,         // message:sent
  }
}

// ngữ cảnh message:received
{
  from: string,           // Định danh người gửi (số điện thoại, ID người dùng, v.v.)
  content: string,        // Nội dung tin nhắn
  timestamp?: number,     // Dấu thời gian Unix khi nhận
  channelId: string,      // Kênh (ví dụ: "whatsapp", "telegram", "discord")
  accountId?: string,     // ID tài khoản nhà cung cấp cho các thiết lập nhiều tài khoản
  conversationId?: string, // ID cuộc trò chuyện
  messageId?: string,     // ID tin nhắn từ nhà cung cấp
  metadata?: {            // Dữ liệu bổ sung cụ thể của nhà cung cấp
    to?: string,
    provider?: string,
    surface?: string,
    threadId?: string,
    senderId?: string,
    senderName?: string,
    senderUsername?: string,
    senderE164?: string,
  }
}

// ngữ cảnh message:sent
{
  to: string,             // Định danh người nhận
  content: string,        // Nội dung tin nhắn đã gửi
  success: boolean,       // Việc gửi có thành công không
  error?: string,         // Thông báo lỗi nếu gửi thất bại
  channelId: string,      // Kênh (ví dụ: "whatsapp", "telegram", "discord")
  accountId?: string,     // ID tài khoản nhà cung cấp
  conversationId?: string, // ID cuộc trò chuyện
  messageId?: string,     // ID tin nhắn trả về bởi nhà cung cấp
  isGroup?: boolean,      // Tin nhắn gửi đi này có thuộc về ngữ cảnh nhóm/kênh không
  groupId?: string,       // Định danh nhóm/kênh để tương quan với message:received
}

// ngữ cảnh message:transcribed
{
  body?: string,          // Nội dung thô trước khi làm giàu
  bodyForAgent?: string,  // Nội dung đã làm giàu hiển thị cho agent
  transcript: string,     // Văn bản phiên âm âm thanh
  channelId: string,      // Kênh (ví dụ: "telegram", "whatsapp")
  conversationId?: string,
  messageId?: string,
}

// ngữ cảnh message:preprocessed
{
  body?: string,          // Nội dung thô
  bodyForAgent?: string,  // Nội dung đã làm giàu cuối cùng sau khi hiểu phương tiện/liên kết
  transcript?: string,    // Phiên âm khi có âm thanh
  channelId: string,      // Kênh (ví dụ: "telegram", "whatsapp")
  conversationId?: string,
  messageId?: string,
  isGroup?: boolean,
  groupId?: string,
}

const isMessageReceivedEvent = (event: { type: string; action: string }) =>
  event.type === "message" && event.action === "received";
const isMessageSentEvent = (event: { type: string; action: string }) =>
  event.type === "message" && event.action === "sent";

const handler = async (event) => {
  if (isMessageReceivedEvent(event as { type: string; action: string })) {
    console.log(`[message-logger] Nhận từ ${event.context.from}: ${event.context.content}`);
  } else if (isMessageSentEvent(event as { type: string; action: string })) {
    console.log(`[message-logger] Gửi đến ${event.context.to}: ${event.context.content}`);
  }
};

export default handler;

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

---
name: my-hook
description: "Làm điều gì đó hữu ích"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

Hook này làm điều gì đó hữu ích khi bạn phát hành `/new`.

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

  console.log("[my-hook] Đang chạy!");
  // Logic của bạn ở đây
};

export default handler;

# Xác minh hook được phát hiện
openclaw hooks list

# Bật nó
openclaw hooks enable my-hook

# Khởi động lại quá trình gateway của bạn (khởi động lại ứng dụng menu bar trên macOS, hoặc khởi động lại quá trình dev của bạn)

# Kích hoạt sự kiện
# Gửi /new qua kênh nhắn tin của bạn

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

# Liệt kê tất cả các hooks
openclaw hooks list

# Chỉ hiển thị các hooks đủ điều kiện
openclaw hooks list --eligible

# Đầu ra chi tiết (hiển thị các yêu cầu thiếu)
openclaw hooks list --verbose

# Đầu ra JSON
openclaw hooks list --json

# Hiển thị thông tin chi tiết về một hook
openclaw hooks info session-memory

# Đầu ra JSON
openclaw hooks info session-memory --json

# Hiển thị tóm tắt đủ điều kiện
openclaw hooks check

# Đầu ra JSON
openclaw hooks check --json

# Bật một hook
openclaw hooks enable session-memory

# Tắt một 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

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

openclaw hooks enable bootstrap-extra-files

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

# Xem các lệnh gần đây
tail -n 20 ~/.openclaw/logs/commands.log

# In đẹp với jq
cat ~/.openclaw/logs/commands.log | jq .

# Lọc theo hành động
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

openclaw hooks enable command-logger

openclaw hooks enable boot-md

// ✓ Tốt - công việc async, trả về ngay lập tức
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Kích hoạt và quên
};

// ✗ Xấu - chặn xử lý lệnh
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] Thất bại:", err instanceof Error ? err.message : String(err));
    // Không ném lỗi - để các handler khác chạy
  }
};

const handler: HookHandler = async (event) => {
  // Chỉ xử lý các lệnh 'new'
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // Logic của bạn ở đây
};

metadata: { "openclaw": { "events": ["command:new"] } } # Cụ thể

metadata: { "openclaw": { "events": ["command"] } } # Chung - nhiều overhead hơn

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

openclaw hooks list --verbose

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Đã kích hoạt:", event.type, event.action);
  // Logic của bạn
};

openclaw hooks info my-hook

# macOS
./scripts/clawlog.sh -f

# Các nền tảng khác
tail -f ~/.openclaw/gateway.log

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

test("my handler works", async () => {
  const event = {
    type: "command",
    action: "new",
    sessionKey: "test-session",
    timestamp: new Date(),
    messages: [],
    context: { foo: "bar" },
  };

  await myHandler(event);

  // Khẳng định các tác động phụ
});

Khởi động Gateway
    ↓
Quét thư mục (workspace → managed → bundled)
    ↓
Phân tích tệp HOOK.md
    ↓
Kiểm tra đủ điều kiện (bins, env, config, os)
    ↓
Tải handlers từ các hooks đủ điều kiện
    ↓
Đăng ký handlers cho các sự kiện

Người dùng gửi /new
    ↓
Xác thực lệnh
    ↓
Tạo sự kiện hook
    ↓
Kích hoạt hook (tất cả các handlers đã đăng ký)
    ↓
Tiếp tục xử lý lệnh
    ↓
Reset session

openclaw hooks info my-hook

# Kiểm tra import trực tiếp
node -e "import('./path/to/handler.ts').then(console.log)"

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