훅

훅은 에이전트 명령 및 이벤트에 대한 응답으로 동작을 자동화하는 확장 가능한 이벤트 기반 시스템을 제공합니다. 훅은 디렉토리에서 자동으로 검색되며, OpenClaw의 스킬과 유사한 방식으로 CLI 명령을 통해 관리할 수 있습니다.

시작하기

훅은 무언가가 발생하면 실행되는 작은 스크립트입니다. 두 종류가 있습니다:

• 훅 (이 페이지): /new, /reset, /stop 또는 라이프사이클 이벤트와 같은 에이전트 이벤트가 발생하면 Gateway 내에서 실행됩니다.
• 웹훅: 다른 시스템이 OpenClaw에서 작업을 트리거할 수 있게 해주는 외부 HTTP 웹훅입니다. 웹훅을 참고하거나, Gmail 헬퍼 명령에는 openclaw webhooks를 사용하세요.

훅은 플러그인 안에 번들로 포함할 수도 있습니다. 플러그인을 참고하세요.

일반적인 용도:

• 세션을 초기화할 때 메모리 스냅샷 저장
• 트러블슈팅이나 규정 준수를 위한 명령 감사 추적 유지
• 세션이 시작되거나 종료될 때 후속 자동화 트리거
• 이벤트 발생 시 에이전트 워크스페이스에 파일 쓰기 또는 외부 API 호출

간단한 TypeScript 함수를 작성할 수 있다면, 훅을 작성할 수 있습니다. 훅은 자동으로 검색되며, CLI를 통해 활성화하거나 비활성화합니다.

개요

훅 시스템을 통해 다음을 할 수 있습니다:

• /new 명령 발행 시 세션 컨텍스트를 메모리에 저장
• 감사를 위해 모든 명령 로깅
• 에이전트 라이프사이클 이벤트에 커스텀 자동화 트리거
• 코어 코드를 수정하지 않고 OpenClaw의 동작 확장

시작하기

번들 훅

OpenClaw에는 자동으로 검색되는 네 가지 번들 훅이 포함되어 있습니다:

• session-memory: /new 명령을 실행하면 에이전트 워크스페이스(기본값 ~/.openclaw/workspace/memory/)에 세션 컨텍스트를 저장합니다
• bootstrap-extra-files: agent:bootstrap 중에 설정된 glob/경로 패턴에서 추가 워크스페이스 부트스트랩 파일을 주입합니다
• command-logger: 모든 명령 이벤트를 ~/.openclaw/logs/commands.log에 기록합니다
• boot-md: 게이트웨이 시작 시 BOOT.md를 실행합니다 (내부 훅 활성화 필요)

사용 가능한 훅 목록 확인:

openclaw hooks list

훅 활성화:

openclaw hooks enable session-memory

훅 상태 확인:

openclaw hooks check

상세 정보 확인:

openclaw hooks info session-memory

온보딩

온보딩(openclaw onboard) 중에 권장 훅을 활성화할지 묻는 메시지가 표시됩니다. 위자드가 적격한 훅을 자동으로 검색하여 선택할 수 있게 제시합니다.

훅 검색

훅은 세 개의 디렉토리에서 자동으로 검색됩니다 (우선순위 순서):

1. 워크스페이스 훅: <workspace>/hooks/ (에이전트별, 최우선)
2. 관리 훅: ~/.openclaw/hooks/ (사용자 설치, 워크스페이스 간 공유)
3. 번들 훅: <openclaw>/dist/hooks/bundled/ (OpenClaw에 포함)

관리 훅 디렉토리는 단일 훅 또는 훅 팩 (패키지 디렉토리)일 수 있습니다.

각 훅은 다음을 포함하는 디렉토리입니다:

my-hook/
├── HOOK.md          # 메타데이터 + 문서
└── handler.ts       # 핸들러 구현

훅 팩 (npm/아카이브)

훅 팩은 package.json의 openclaw.hooks를 통해 하나 이상의 훅을 내보내는 표준 npm 패키지입니다. 다음으로 설치합니다:

openclaw hooks install <path-or-spec>

npm 스펙은 레지스트리 전용입니다 (패키지 이름 + 선택적 정확한 버전 또는 dist-tag). Git/URL/파일 스펙과 semver 범위는 거부됩니다.

베어 스펙과 @latest는 안정 트랙을 유지합니다. npm이 이들 중 하나를 프리릴리스로 해석하면, OpenClaw가 중단되고 @beta/@rc와 같은 프리릴리스 태그 또는 정확한 프리릴리스 버전으로 명시적으로 옵트인할 것을 요청합니다.

package.json 예시:

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

각 항목은 HOOK.md와 handler.ts (또는 index.ts)를 포함하는 훅 디렉토리를 가리킵니다. 훅 팩은 의존성을 포함할 수 있으며, ~/.openclaw/hooks/<id> 아래에 설치됩니다. 각 openclaw.hooks 항목은 심볼릭 링크 해석 후에도 패키지 디렉토리 내에 있어야 합니다. 벗어나는 항목은 거부됩니다.

보안 참고: openclaw hooks install은 npm install --ignore-scripts (라이프사이클 스크립트 없음)로 의존성을 설치합니다. 훅 팩의 의존성 트리를 “순수 JS/TS”로 유지하고, postinstall 빌드에 의존하는 패키지를 피하세요.

훅 구조

HOOK.md 형식

HOOK.md 파일은 YAML 프런트매터와 마크다운 문서를 포함합니다:

---
name: my-hook
description: "이 훅이 하는 일에 대한 간단한 설명"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

상세 문서는 여기에...

## 기능

- `/new` 명령을 감지합니다
- 어떤 동작을 수행합니다
- 결과를 기록합니다

## 요구 사항

- Node.js가 설치되어 있어야 합니다

## 설정

설정이 필요 없습니다.

메타데이터 필드

metadata.openclaw 객체는 다음을 지원합니다:

• emoji: CLI 표시용 이모지 (예: "💾")
• events: 감지할 이벤트 배열 (예: ["command:new", "command:reset"])
• export: 사용할 이름 내보내기 (기본값 "default")
• homepage: 문서 URL
• requires: 선택적 요구 사항
  • bins: PATH에 필요한 바이너리 (예: ["git", "node"])
  • anyBins: 이 바이너리 중 최소 하나가 있어야 함
  • env: 필수 환경 변수
  • config: 필수 설정 경로 (예: ["workspace.dir"])
  • os: 필수 플랫폼 (예: ["darwin", "linux"])
• always: 적격성 검사 우회 (불리언)
• install: 설치 방법 (번들 훅의 경우: [{"id":"bundled","kind":"bundled"}])

핸들러 구현

handler.ts 파일은 HookHandler 함수를 내보냅니다:

const myHandler = async (event) => {
  // 'new' 명령에서만 트리거
  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()}`);

  // 커스텀 로직 작성

  // 선택적으로 사용자에게 메시지 전송
  event.messages.push("✨ My hook executed!");
};

export default myHandler;

이벤트 컨텍스트

각 이벤트는 다음을 포함합니다:

{
  type: 'command' | 'session' | 'agent' | 'gateway' | 'message',
  action: string,              // 예: 'new', 'reset', 'stop', 'received', 'sent'
  sessionKey: string,          // 세션 식별자
  timestamp: Date,             // 이벤트 발생 시각
  messages: string[],          // 사용자에게 보낼 메시지를 여기에 추가
  context: {
    // Command 이벤트:
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // 예: 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig,
    // Message 이벤트 (전체 세부사항은 메시지 이벤트 섹션 참고):
    from?: string,             // message:received
    to?: string,               // message:sent
    content?: string,
    channelId?: string,
    success?: boolean,         // message:sent
  }
}

이벤트 유형

Command 이벤트

에이전트 명령이 발행될 때 트리거됩니다:

• command: 모든 명령 이벤트 (일반 리스너)
• command:new: /new 명령이 발행될 때
• command:reset: /reset 명령이 발행될 때
• command:stop: /stop 명령이 발행될 때

Session 이벤트

• session:compact:before: 압축이 기록을 요약하기 직전
• session:compact:after: 요약 메타데이터와 함께 압축이 완료된 후

내부 훅 페이로드는 이를 type: "session", action: "compact:before" / action: "compact:after"로 방출합니다. 리스너는 위의 결합 키로 구독합니다. 특정 핸들러 등록은 ${type}:${action} 형식의 리터럴 키를 사용합니다. 이 이벤트들에 대해서는 session:compact:before와 session:compact:after로 등록하세요.

Agent 이벤트

• agent:bootstrap: 워크스페이스 부트스트랩 파일이 주입되기 전 (훅이 context.bootstrapFiles를 변경 가능)

Gateway 이벤트

게이트웨이가 시작될 때 트리거됩니다:

• gateway:startup: 채널이 시작되고 훅이 로드된 후

Message 이벤트

메시지가 수신되거나 발송될 때 트리거됩니다:

• message: 모든 메시지 이벤트 (일반 리스너)
• message:received: 어떤 채널에서든 인바운드 메시지가 수신될 때. 미디어 이해 전 처리 초기에 발생합니다. 콘텐츠에는 아직 처리되지 않은 미디어 첨부파일의 원시 플레이스홀더(예: <media:audio>)가 포함될 수 있습니다.
• message:transcribed: 오디오 전사 및 링크 이해를 포함하여 메시지가 완전히 처리된 후. 이 시점에서 transcript에는 오디오 메시지의 전체 전사 텍스트가 포함됩니다. 전사된 오디오 콘텐츠에 접근해야 할 때 이 훅을 사용하세요.
• message:preprocessed: 모든 미디어 + 링크 이해가 완료된 후 모든 메시지에 대해 발생하며, 에이전트가 보기 전에 훅이 완전히 강화된 본문(전사, 이미지 설명, 링크 요약)에 접근할 수 있게 합니다.
• message:sent: 아웃바운드 메시지가 성공적으로 발송된 후

메시지 이벤트 컨텍스트

메시지 이벤트는 메시지에 대한 풍부한 컨텍스트를 포함합니다:

// message:received 컨텍스트
{
  from: string,           // 발신자 식별자 (전화번호, 사용자 ID 등)
  content: string,        // 메시지 내용
  timestamp?: number,     // 수신 시 Unix 타임스탬프
  channelId: string,      // 채널 (예: "whatsapp", "telegram", "discord")
  accountId?: string,     // 멀티 계정 설정용 제공자 계정 ID
  conversationId?: string, // 채팅/대화 ID
  messageId?: string,     // 제공자의 메시지 ID
  metadata?: {            // 추가 제공자별 데이터
    to?: string,
    provider?: string,
    surface?: string,
    threadId?: string,
    senderId?: string,
    senderName?: string,
    senderUsername?: string,
    senderE164?: string,
  }
}

// message:sent 컨텍스트
{
  to: string,             // 수신자 식별자
  content: string,        // 발송된 메시지 내용
  success: boolean,       // 발송 성공 여부
  error?: string,         // 발송 실패 시 오류 메시지
  channelId: string,      // 채널 (예: "whatsapp", "telegram", "discord")
  accountId?: string,     // 제공자 계정 ID
  conversationId?: string, // 채팅/대화 ID
  messageId?: string,     // 제공자가 반환한 메시지 ID
  isGroup?: boolean,      // 이 아웃바운드 메시지가 그룹/채널 컨텍스트에 속하는지 여부
  groupId?: string,       // message:received와의 상관관계를 위한 그룹/채널 식별자
}

// message:transcribed 컨텍스트
{
  body?: string,          // 강화 전 원시 인바운드 본문
  bodyForAgent?: string,  // 에이전트에게 보이는 강화된 본문
  transcript: string,     // 오디오 전사 텍스트
  channelId: string,      // 채널 (예: "telegram", "whatsapp")
  conversationId?: string,
  messageId?: string,
}

// message:preprocessed 컨텍스트
{
  body?: string,          // 원시 인바운드 본문
  bodyForAgent?: string,  // 미디어/링크 이해 후 최종 강화된 본문
  transcript?: string,    // 오디오가 있을 때의 전사
  channelId: string,      // 채널 (예: "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] Received from ${event.context.from}: ${event.context.content}`);
  } else if (isMessageSentEvent(event as { type: string; action: string })) {
    console.log(`[message-logger] Sent to ${event.context.to}: ${event.context.content}`);
  }
};

export default handler;

도구 결과 훅 (플러그인 API)

이 훅은 이벤트 스트림 리스너가 아닙니다. 플러그인이 OpenClaw가 결과를 저장하기 전에 도구 결과를 동기적으로 조정할 수 있게 합니다.

• tool_result_persist: 도구 결과가 세션 트랜스크립트에 기록되기 전에 변환합니다. 동기적이어야 합니다. 업데이트된 도구 결과 페이로드를 반환하거나, 그대로 유지하려면 undefined를 반환합니다. 에이전트 루프를 참고하세요.

플러그인 훅 이벤트

플러그인 훅 러너를 통해 노출되는 압축 라이프사이클 훅:

• before_compaction: 카운트/토큰 메타데이터와 함께 압축 전에 실행
• after_compaction: 압축 요약 메타데이터와 함께 압축 후에 실행

향후 이벤트

계획된 이벤트 유형:

• session:start: 새 세션이 시작될 때
• session:end: 세션이 종료될 때
• agent:error: 에이전트가 오류를 만났을 때

커스텀 훅 만들기

1. 위치 선택

• 워크스페이스 훅 (<workspace>/hooks/): 에이전트별, 최우선
• 관리 훅 (~/.openclaw/hooks/): 워크스페이스 간 공유

2. 디렉토리 구조 생성

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

3. HOOK.md 생성

---
name: my-hook
description: "유용한 작업을 수행합니다"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

이 훅은 `/new`를 실행할 때 유용한 작업을 수행합니다.

4. handler.ts 생성

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

  console.log("[my-hook] Running!");
  // 여기에 로직 작성
};

export default handler;

5. 활성화 및 테스트

# 훅이 검색되었는지 확인
openclaw hooks list

# 활성화
openclaw hooks enable my-hook

# 게이트웨이 프로세스를 재시작합니다 (macOS의 메뉴 바 앱 재시작 또는 개발 프로세스 재시작)

# 이벤트 트리거
# 메시징 채널을 통해 /new를 전송

설정

새 설정 형식 (권장)

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

참고: module은 워크스페이스 상대 경로여야 합니다. 절대 경로와 워크스페이스 외부로의 탐색은 거부됩니다.

마이그레이션: 새 훅에는 새로운 검색 기반 시스템을 사용하세요. 레거시 핸들러는 디렉토리 기반 훅 이후에 로드됩니다.

CLI 명령

훅 목록

# 모든 훅 나열
openclaw hooks list

# 적격한 훅만 표시
openclaw hooks list --eligible

# 상세 출력 (누락된 요구 사항 표시)
openclaw hooks list --verbose

# JSON 출력
openclaw hooks list --json

훅 정보

# 훅에 대한 상세 정보 표시
openclaw hooks info session-memory

# JSON 출력
openclaw hooks info session-memory --json

적격성 확인

# 적격성 요약 표시
openclaw hooks check

# JSON 출력
openclaw hooks check --json

활성화/비활성화

# 훅 활성화
openclaw hooks enable session-memory

# 훅 비활성화
openclaw hooks disable command-logger

번들 훅 참조

session-memory

/new 명령을 실행하면 세션 컨텍스트를 메모리에 저장합니다.

이벤트: command:new

요구 사항: workspace.dir이 설정되어 있어야 합니다

출력: <workspace>/memory/YYYY-MM-DD-slug.md (기본값 ~/.openclaw/workspace)

동작 방식:

1. 리셋 전 세션 항목을 사용하여 올바른 트랜스크립트를 찾습니다
2. 마지막 15줄의 대화를 추출합니다
3. LLM을 사용하여 설명적인 파일명 슬러그를 생성합니다
4. 세션 메타데이터를 날짜가 포함된 메모리 파일에 저장합니다

출력 예시:

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

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

파일명 예시:

• 2026-01-16-vendor-pitch.md
• 2026-01-16-api-design.md
• 2026-01-16-1430.md (슬러그 생성 실패 시 대체 타임스탬프)

활성화:

openclaw hooks enable session-memory

bootstrap-extra-files

agent:bootstrap 중에 추가 부트스트랩 파일(예: 모노레포 로컬 AGENTS.md / TOOLS.md)을 주입합니다.

이벤트: agent:bootstrap

요구 사항: workspace.dir이 설정되어 있어야 합니다

출력: 파일이 기록되지 않습니다. 부트스트랩 컨텍스트는 메모리에서만 수정됩니다.

설정:

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

참고:

• 경로는 워크스페이스 기준으로 해석됩니다.
• 파일은 워크스페이스 내에 있어야 합니다 (realpath 확인).
• 인식된 부트스트랩 기본 이름만 로드됩니다.
• 서브에이전트 허용 목록이 보존됩니다 (AGENTS.md와 TOOLS.md만 해당).

활성화:

openclaw hooks enable bootstrap-extra-files

command-logger

모든 명령 이벤트를 중앙 감사 파일에 기록합니다.

이벤트: command

요구 사항: 없음

출력: ~/.openclaw/logs/commands.log

동작 방식:

1. 이벤트 세부사항(명령 동작, 타임스탬프, 세션 키, 발신자 ID, 소스)을 캡처합니다
2. JSONL 형식으로 로그 파일에 추가합니다
3. 백그라운드에서 조용히 실행됩니다

로그 항목 예시:

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

로그 확인:

# 최근 명령 확인
tail -n 20 ~/.openclaw/logs/commands.log

# jq로 보기 좋게 출력
cat ~/.openclaw/logs/commands.log | jq .

# 동작별 필터링
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

활성화:

openclaw hooks enable command-logger

boot-md

게이트웨이 시작 시 (채널 시작 후) BOOT.md를 실행합니다. 이것이 실행되려면 내부 훅이 활성화되어 있어야 합니다.

이벤트: gateway:startup

요구 사항: workspace.dir이 설정되어 있어야 합니다

동작 방식:

1. 워크스페이스에서 BOOT.md를 읽습니다
2. 에이전트 러너를 통해 지시사항을 실행합니다
3. 메시지 도구를 통해 요청된 아웃바운드 메시지를 발송합니다

활성화:

openclaw hooks enable boot-md

모범 사례

핸들러를 빠르게 유지하세요

훅은 명령 처리 중에 실행됩니다. 가볍게 유지하세요:

// ✓ 좋음 - 비동기 작업, 즉시 반환
const handler: HookHandler = async (event) => {
  void processInBackground(event); // 발사 후 잊기
};

// ✗ 나쁨 - 명령 처리를 차단
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));
    // throw하지 마세요 - 다른 핸들러가 실행될 수 있게
  }
};

이벤트를 일찍 필터링하세요

관련 없는 이벤트는 일찍 반환하세요:

const handler: HookHandler = async (event) => {
  // 'new' 명령만 처리
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // 여기에 로직 작성
};

구체적인 이벤트 키를 사용하세요

가능한 경우 메타데이터에서 정확한 이벤트를 지정하세요:

metadata: { "openclaw": { "events": ["command:new"] } } # 구체적

이것보다 낫습니다:

metadata: { "openclaw": { "events": ["command"] } } # 일반적 - 더 많은 오버헤드

디버깅

훅 로깅 활성화

게이트웨이는 시작 시 훅 로딩을 기록합니다:

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] Triggered:", event.type, event.action);
  // 로직
};

적격성 확인

훅이 적격하지 않은 이유 확인:

openclaw hooks info my-hook

출력에서 누락된 요구 사항을 찾으세요.

테스트

게이트웨이 로그

게이트웨이 로그를 모니터링하여 훅 실행을 확인:

# macOS
./scripts/clawlog.sh -f

# 기타 플랫폼
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);

  // 부작용 확인
});

아키텍처

핵심 컴포넌트

• src/hooks/types.ts: 타입 정의
• src/hooks/workspace.ts: 디렉토리 스캔 및 로딩
• src/hooks/frontmatter.ts: HOOK.md 메타데이터 파싱
• src/hooks/config.ts: 적격성 확인
• src/hooks/hooks-status.ts: 상태 보고
• src/hooks/loader.ts: 동적 모듈 로더
• src/cli/hooks-cli.ts: CLI 명령
• src/gateway/server-startup.ts: 게이트웨이 시작 시 훅 로드
• src/auto-reply/reply/commands-core.ts: 명령 이벤트 트리거

검색 흐름

게이트웨이 시작
    ↓
디렉토리 스캔 (워크스페이스 → 관리 → 번들)
    ↓
HOOK.md 파일 파싱
    ↓
적격성 확인 (바이너리, 환경 변수, 설정, OS)
    ↓
적격한 훅에서 핸들러 로드
    ↓
이벤트별 핸들러 등록

이벤트 흐름

사용자가 /new 전송
    ↓
명령 유효성 검사
    ↓
훅 이벤트 생성
    ↓
훅 트리거 (등록된 모든 핸들러)
    ↓
명령 처리 계속
    ↓
세션 리셋

트러블슈팅

훅이 검색되지 않음

1. 디렉토리 구조 확인:

   ls -la ~/.openclaw/hooks/my-hook/
   # 표시되어야 함: HOOK.md, handler.ts

2. HOOK.md 형식 확인:

   cat ~/.openclaw/hooks/my-hook/HOOK.md
   # YAML 프런트매터에 name과 metadata가 있어야 합니다

3. 검색된 모든 훅 나열:

   openclaw hooks list

훅이 적격하지 않음

요구 사항 확인:

openclaw hooks info my-hook

누락된 항목 확인:

• 바이너리 (PATH 확인)
• 환경 변수
• 설정 값
• OS 호환성

훅이 실행되지 않음

1. 훅이 활성화되어 있는지 확인:

   openclaw hooks list
   # 활성화된 훅 옆에 ✓가 표시되어야 합니다

2. 게이트웨이 프로세스를 재시작하여 훅이 다시 로드되게 하세요.

3. 게이트웨이 로그에서 오류 확인:

   ./scripts/clawlog.sh | grep hook

핸들러 오류

TypeScript/import 오류 확인:

# import를 직접 테스트
node -e "import('./path/to/handler.ts').then(console.log)"

마이그레이션 가이드

레거시 설정에서 검색 기반으로

이전:

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

이후:

1. 훅 디렉토리 생성:

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

2. HOOK.md 생성:

   ---
   name: my-hook
   description: "내 커스텀 훅"
   metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
   ---
   
   # My Hook
   
   유용한 작업을 수행합니다.

3. 설정 업데이트:

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

4. 확인 및 게이트웨이 프로세스 재시작:

   openclaw hooks list
   # 표시되어야 함: 🎯 my-hook ✓

마이그레이션의 장점:

• 자동 검색
• CLI 관리
• 적격성 확인
• 더 나은 문서화
• 일관된 구조

참고 자료

• CLI 참조: hooks
• 번들 훅 README
• 웹훅
• 설정