OpenClaw Hooks 활용 가이드: 이벤트 자동화 설정하기

개발을 하다 보면 특정 이벤트가 발생할 때마다 반복적인 작업을 자동화하고 싶을 때가 많죠. 매번 수동으로 처리하기 번거로운 작업들을 OpenClaw의 Hook 기능을 활용해 효율적으로 관리하는 방법을 소개합니다.

OpenClaw의 Hook은 Gateway 내부에서 발생하는 다양한 이벤트에 반응하여 스크립트를 실행하는 강력한 자동화 도구입니다. 이 가이드를 통해 OpenClaw Hook을 설정하고, 커스텀 로직을 작성하여 워크플로우를 최적화하는 방법을 알아보세요.

빠른 시작

OpenClaw에서 제공하는 Hook을 확인하고 활성화하는 가장 간단한 방법입니다. 다음 명령어를 통해 바로 시작해 보세요.

1. 사용 가능한 Hook 목록을 확인합니다.

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

2. 필요한 Hook을 활성화합니다.

   # Enable a hook
   openclaw hooks enable session-memory

3. Hook 상태를 점검합니다.

   # Check hook status
   openclaw hooks check

4. 특정 Hook에 대한 상세 정보를 확인합니다.

   # Get detailed information
   openclaw hooks info session-memory

이벤트 유형

Gateway 내부에서 발생하는 다양한 이벤트에 맞춰 Hook을 트리거할 수 있습니다. 각 이벤트가 언제 발생하는지 아래 표를 참고하세요.

Event	When it fires
command:new	/new command issued
command:reset	/reset command issued
command:stop	/stop command issued
command	Any command event (general listener)
session:compact:before	Before compaction summarizes history
session:compact:after	After compaction completes
session:patch	When session properties are modified
agent:bootstrap	Before workspace bootstrap files are injected
gateway:startup	After channels start and hooks are loaded
message:received	Inbound message from any channel
message:transcribed	After audio transcription completes
message:preprocessed	After all media and link understanding completes
message:sent	Outbound message delivered

Hook 작성하기

Hook은 특정 디렉토리 구조를 따르며, 메타데이터와 핸들러 구현을 포함해야 합니다.

Hook 구조

각 Hook은 두 개의 파일로 구성된 디렉토리 형태입니다.

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

HOOK.md 형식

---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.

Metadata 필드(metadata.openclaw) 설명은 다음과 같습니다.

Field	Description
emoji	Display emoji for CLI
events	Array of events to listen for
export	Named export to use (defaults to "default")
os	Required platforms (e.g., ["darwin", "linux"])
requires	Required bins, anyBins, env, or config paths
always	Bypass eligibility checks (boolean)
install	Installation methods

핸들러 구현

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

  console.log(`[my-hook] New command triggered`);
  // Your logic here

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

export default handler;

Hook 탐색

OpenClaw는 다음 디렉토리 순서대로 Hook을 탐색하며, 뒤에 올수록 우선순위가 높습니다.

1. 번들 Hook: OpenClaw와 함께 제공되는 기본 Hook입니다.
2. 플러그인 Hook: 설치된 플러그인 내부에 포함된 Hook입니다.
3. 관리형 Hook: ~/.openclaw/hooks/ 경로에 위치하며 사용자 설치 Hook입니다.
4. 워크스페이스 Hook: <workspace>/hooks/ 경로에 위치하며 에이전트별로 설정됩니다.

번들 Hook

OpenClaw에서 기본 제공하는 유용한 Hook들입니다.

Hook	Events	What it does
session-memory	command:new, command:reset	Saves session context to <workspace>/memory/
bootstrap-extra-files	agent:bootstrap	Injects additional bootstrap files from glob patterns
command-logger	command	Logs all commands to ~/.openclaw/logs/commands.log
boot-md	gateway:startup	Runs BOOT.md when the gateway starts

번들 Hook을 활성화하려면 다음 명령어를 사용하세요.

openclaw hooks enable <hook-name>

session-memory 상세

마지막 15개의 메시지를 추출하여 JSON 형태가 아닌 읽기 쉬운 마크다운 파일로 저장합니다.

bootstrap-extra-files 설정

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

command-logger 상세

모든 슬래시 명령어를 ~/.openclaw/logs/commands.log에 기록합니다.

boot-md 상세

Gateway가 시작될 때 활성 워크스페이스의 BOOT.md를 실행합니다.

플러그인 Hook

플러그인은 Plugin SDK를 통해 더 깊은 통합이 가능합니다. 도구 호출 가로채기, 프롬프트 수정, 메시지 흐름 제어 등 28개의 다양한 Hook을 지원합니다.

설정

config.json 파일을 통해 Hook을 세밀하게 제어할 수 있습니다.

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

Hook별 환경 변수 설정 예시입니다.

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

추가 Hook 디렉토리 지정 방법입니다.

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

CLI 참조

CLI를 통해 Hook을 관리하는 명령어들입니다.

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

모범 사례

Hook을 효율적으로 작성하기 위한 몇 가지 팁을 공유합니다.

1. 핸들러를 빠르게 유지하세요. 무거운 작업은 void processInBackground(event)를 사용하세요.
2. 에러를 우아하게 처리하세요. try/catch를 사용하여 다른 핸들러가 영향을 받지 않도록 합니다.
3. 이벤트를 조기에 필터링하세요. 불필요한 이벤트는 즉시 반환하여 오버헤드를 줄입니다.
4. 구체적인 이벤트 키를 사용하세요. "events": ["command"]보다는 "events": ["command:new"]를 권장합니다.

문제 해결

Hook이 제대로 동작하지 않을 때 확인해야 할 사항들입니다.

Hook이 발견되지 않을 때

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

# List all discovered hooks
openclaw hooks list

Hook이 적합하지 않음(Not eligible)으로 나올 때

openclaw hooks info my-hook

PATH에 필요한 바이너리가 있는지, 환경 변수나 설정 값이 올바른지 확인하세요.

Hook이 실행되지 않을 때

1. Hook이 활성화되었는지 확인하세요: openclaw hooks list
2. Gateway 프로세스를 재시작하여 Hook을 다시 로드하세요.
3. Gateway 로그를 확인하세요: ./scripts/clawlog.sh | grep hook

관련 문서

• CLI Reference: hooks
• Webhooks
• Plugin Architecture
• Configuration

더 궁금한 점이 있다면 AI Setup Assistant를 통해 도움을 받아보세요!

openclaw plugins install <path-or-spec>