훅 (Hooks)

개요

훅(Hooks)은 OpenClaw의 이벤트 기반 자동화 시스템이다. 게이트웨이 내부 이벤트 또는 외부 HTTP 웹훅에 반응하여 자동으로 작업을 실행한다.

훅 타입

Internal (내부 이벤트)

게이트웨이 내부에서 발생하는 이벤트에 반응한다.

• 세션 시작/종료
• 메시지 수신/발신
• 에이전트 부팅/종료
• 도구 실행 전/후

Webhooks (외부 HTTP)

외부 서비스에서 HTTP 요청을 통해 트리거한다.

• GitHub 웹훅 (PR, 이슈 등)
• CI/CD 파이프라인 알림
• 커스텀 서비스 연동

번들 훅 (Bundled Hooks)

OpenClaw에 기본 포함된 훅이다.

훅 로딩 우선순위

여러 소스에서 훅이 로드될 때 우선순위가 적용된다. 같은 이벤트에 여러 훅이 있으면 높은 우선순위의 훅이 먼저 실행된다.

bundled (최저) < plugin < managed < workspace (최고)

커스텀 훅 만들기

워크스페이스에 HOOK.md와 handler.ts 파일을 배치하여 커스텀 훅을 만든다.

디렉토리 구조

workspace/
└── hooks/
    └── my-custom-hook/
        ├── HOOK.md
        └── handler.ts

HOOK.md

---
name: my-custom-hook
event: message.received
description: 수신 메시지를 외부 CRM에 기록
---

# My Custom Hook

메시지 수신 시 외부 CRM API에 대화 내용을 기록합니다.

handler.ts

import { HookContext, HookResult } from "openclaw/hooks";

export default async function handler(ctx: HookContext): Promise<HookResult> {
  const { event, payload } = ctx;

  const message = payload.message.text;
  const sender = payload.message.sender;

  await fetch("https://crm.example.com/api/log", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message, sender, timestamp: new Date() }),
  });

  return { status: "ok" };
}

이벤트 타입

CLI 명령어

훅 목록

openclaw hooks list

Name                  | Source    | Event              | Status
----------------------|----------|--------------------|--------
session-memory        | bundled  | session.end        | enabled
bootstrap-extra-files | bundled  | agent.boot         | enabled
command-logger        | bundled  | command.after       | disabled
boot-md               | bundled  | agent.boot         | enabled
my-custom-hook        | workspace| message.received   | enabled

훅 활성화/비활성화

openclaw hooks enable command-logger
openclaw hooks disable session-memory

훅 상세 정보

openclaw hooks info session-memory

Name: session-memory
Source: bundled
Event: session.end
Status: enabled
Description: 세션 종료 시 대화 요약을 메모리에 저장
Last triggered: 2026-04-01 08:45:00
Trigger count: 127