훅은 Gateway 내부에서 어떤 일이 발생할 때 실행되는 작은 스크립트입니다. 디렉터리에서 발견할 수 있으며Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw hooks로 검사할 수 있습니다. Gateway는 훅을 활성화하거나 하나 이상의 훅 항목, 훅 팩, 레거시 핸들러 또는 추가 훅 디렉터리를 구성한 뒤에만 내부 훅을 로드합니다.
OpenClaw에는 두 종류의 훅이 있습니다.
- 내부 훅(이 페이지):
/new,/reset,/stop같은 에이전트 이벤트나 수명 주기 이벤트가 발생할 때 Gateway 내부에서 실행됩니다. - Webhook: 다른 시스템이 OpenClaw에서 작업을 트리거할 수 있게 하는 외부 HTTP 엔드포인트입니다. Webhook을 참조하세요.
openclaw hooks list는 독립 실행형 훅과 Plugin이 관리하는 훅을 모두 표시합니다.
빠른 시작
이벤트 유형
| 이벤트 | 발생 시점 |
|---|---|
command:new | /new 명령이 실행됨 |
command:reset | /reset 명령이 실행됨 |
command:stop | /stop 명령이 실행됨 |
command | 모든 명령 이벤트(일반 리스너) |
session:compact:before | Compaction이 기록을 요약하기 전 |
session:compact:after | Compaction이 완료된 후 |
session:patch | 세션 속성이 수정될 때 |
agent:bootstrap | 작업공간 부트스트랩 파일이 주입되기 전 |
gateway:startup | 채널이 시작되고 훅이 로드된 후 |
gateway:shutdown | Gateway 종료가 시작될 때 |
gateway:pre-restart | 예정된 Gateway 재시작 전 |
message:received | 모든 채널에서 들어오는 메시지 |
message:transcribed | 오디오 전사가 완료된 후 |
message:preprocessed | 미디어 및 링크 전처리가 완료되거나 건너뛴 후 |
message:sent | 발신 메시지가 전달됨 |
훅 작성
훅 구조
각 훅은 두 파일이 포함된 디렉터리입니다.HOOK.md 형식
metadata.openclaw):
| 필드 | 설명 |
|---|---|
emoji | CLI에 표시할 이모지 |
events | 수신할 이벤트 배열 |
export | 사용할 명명된 export(기본값은 "default") |
os | 필요한 플랫폼(예: ["darwin", "linux"]) |
requires | 필요한 bins, anyBins, env 또는 config 경로 |
always | 적격성 검사를 우회함(불리언) |
install | 설치 방법 |
핸들러 구현
type, action, sessionKey, timestamp, messages(사용자에게 보내려면 push), context(이벤트별 데이터)가 포함됩니다. 에이전트 및 도구 Plugin 훅 컨텍스트에는 Plugin이 OTEL 상관관계를 위해 구조화된 로그에 전달할 수 있는 읽기 전용 W3C 호환 진단 추적 컨텍스트인 trace도 포함될 수 있습니다.
이벤트 컨텍스트 주요 사항
명령 이벤트(command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg.
메시지 이벤트(message:received): context.from, context.content, context.channelId, context.metadata(senderId, senderName, guildId를 포함한 제공자별 데이터). context.content는 명령과 유사한 메시지에 대해 비어 있지 않은 명령 본문을 우선 사용한 다음 원시 인바운드 본문과 일반 본문으로 대체합니다. 스레드 기록이나 링크 요약 같은 에이전트 전용 보강 정보는 포함하지 않습니다.
메시지 이벤트(message:sent): context.to, context.content, context.success, context.channelId.
메시지 이벤트(message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.
메시지 이벤트(message:preprocessed): context.bodyForAgent(최종 보강 본문), context.from, context.channelId.
부트스트랩 이벤트(agent:bootstrap): context.bootstrapFiles(변경 가능한 배열), context.agentId.
세션 패치 이벤트(session:patch): context.sessionEntry, context.patch(변경된 필드만), context.cfg. 권한 있는 클라이언트만 패치 이벤트를 트리거할 수 있습니다.
Compaction 이벤트: session:compact:before에는 messageCount, tokenCount가 포함됩니다. session:compact:after는 compactedCount, summaryLength, tokensBefore, tokensAfter를 추가합니다.
command:stop은 사용자가 /stop을 실행하는 것을 관찰합니다. 이는 취소/명령
수명 주기에 해당하며, 에이전트 최종화 게이트가 아닙니다. 자연스러운 최종 답변을 검사하고
에이전트에 한 번 더 처리하도록 요청해야 하는 Plugin은 대신 타입이 지정된
Plugin 훅 before_agent_finalize를 사용해야 합니다. Plugin 훅을 참조하세요.
Gateway 수명 주기 이벤트: gateway:shutdown에는 reason과 restartExpectedMs가 포함되며 Gateway 종료가 시작될 때 발생합니다. gateway:pre-restart에는 동일한 컨텍스트가 포함되지만, 종료가 예정된 재시작의 일부이고 유한한 restartExpectedMs 값이 제공될 때만 발생합니다. 종료 중에는 각 수명 주기 훅 대기가 최선형으로 제한되므로 핸들러가 멈춰도 종료는 계속됩니다.
gateway:shutdown(또는 gateway:pre-restart) 이벤트와 나머지 종료 시퀀스 사이에, Gateway는 프로세스가 중지될 때 아직 활성 상태였던 모든 세션에 대해 타입이 지정된 session_end Plugin 훅도 발생시킵니다. 이벤트의 reason은 일반 SIGTERM/SIGINT 중지의 경우 shutdown이고, 예정된 재시작의 일부로 닫기가 예약된 경우 restart입니다. 이 드레인은 제한되어 느린 session_end 핸들러가 프로세스 종료를 막을 수 없으며, replace / reset / delete / compaction을 통해 이미 최종화된 세션은 중복 발생을 피하기 위해 건너뜁니다.
훅 발견
훅은 다음 디렉터리에서 발견되며, 뒤로 갈수록 재정의 우선순위가 높아집니다.- 번들 훅: OpenClaw와 함께 제공됨
- Plugin 훅: 설치된 Plugin 안에 함께 포함된 훅
- 관리형 훅:
~/.openclaw/hooks/(사용자가 설치하며 작업공간 간 공유됨).hooks.internal.load.extraDirs의 추가 디렉터리도 이 우선순위를 공유합니다. - 작업공간 훅:
<workspace>/hooks/(에이전트별, 명시적으로 활성화하기 전까지 기본적으로 비활성화됨)
openclaw hooks enable <name>으로 번들 또는 관리형 훅을 활성화하거나, 훅 팩을 설치하거나, hooks.internal.enabled=true를 설정해 옵트인하세요. 이름이 지정된 훅 하나를 활성화하면 Gateway는 해당 훅의 핸들러만 로드합니다. hooks.internal.enabled=true, 추가 훅 디렉터리, 레거시 핸들러는 광범위한 발견에 옵트인합니다.
훅 팩
훅 팩은package.json의 openclaw.hooks를 통해 훅을 내보내는 npm 패키지입니다. 다음으로 설치합니다.
번들 훅
| 훅 | 이벤트 | 수행 작업 |
|---|---|---|
| session-memory | command:new, command:reset | 세션 컨텍스트를 <workspace>/memory/에 저장 |
| bootstrap-extra-files | agent:bootstrap | glob 패턴에서 추가 부트스트랩 파일을 주입 |
| command-logger | command | 모든 명령을 ~/.openclaw/logs/commands.log에 기록 |
| compaction-notifier | session:compact:before, session:compact:after | 세션 Compaction 시작/종료 시 보이는 채팅 알림을 전송 |
| boot-md | gateway:startup | Gateway가 시작될 때 BOOT.md를 실행 |
session-memory 세부 정보
마지막 15개의 사용자/어시스턴트 메시지를 추출하고 호스트 로컬 날짜를 사용해<workspace>/memory/YYYY-MM-DD-HHMM.md에 저장합니다. 메모리 캡처는 백그라운드에서 실행되므로 /new 및 /reset 확인 응답이 트랜스크립트 읽기나 선택적 슬러그 생성으로 지연되지 않습니다. 구성된 모델로 설명적인 파일 이름 슬러그를 생성하려면 hooks.internal.entries.session-memory.llmSlug: true를 설정하세요. workspace.dir가 구성되어 있어야 합니다.
bootstrap-extra-files 구성
AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
command-logger 세부 정보
모든 슬래시 명령을~/.openclaw/logs/commands.log에 기록합니다.
compaction-notifier 세부 정보
OpenClaw가 세션 트랜스크립트 압축을 시작하고 완료할 때 현재 대화에 짧은 상태 메시지를 보냅니다. 사용자가 어시스턴트가 컨텍스트를 요약 중이며 Compaction 후 계속 진행할 것임을 볼 수 있으므로, 채팅 표면에서 긴 턴이 덜 혼란스럽게 느껴집니다.boot-md 세부 정보
Gateway가 시작될 때 활성 작업공간의BOOT.md를 실행합니다.
Plugin 훅
Plugin은 더 깊은 통합을 위해 Plugin SDK를 통해 타입이 지정된 훅을 등록할 수 있습니다. 도구 호출 가로채기, 프롬프트 수정, 메시지 흐름 제어 등을 할 수 있습니다.before_tool_call, before_agent_reply,
before_install 또는 기타 프로세스 내부 수명 주기 훅이 필요할 때 Plugin 훅을 사용하세요.
전체 Plugin 훅 참조는 Plugin 훅을 참조하세요.
구성
레거시
hooks.internal.handlers 배열 구성 형식은 이전 버전과의 호환성을 위해 계속 지원되지만, 새 Hook은 검색 기반 시스템을 사용해야 합니다.CLI 참조
모범 사례
- 핸들러는 빠르게 유지하세요. Hook은 명령 처리 중에 실행됩니다. 무거운 작업은
void processInBackground(event)로 실행만 시작하고 기다리지 마세요. - 오류를 우아하게 처리하세요. 위험한 작업은 try/catch로 감싸세요. 다른 핸들러가 실행될 수 있도록 throw하지 마세요.
- 이벤트를 일찍 필터링하세요. 이벤트 유형/작업이 관련 없으면 즉시 반환하세요.
- 구체적인 이벤트 키를 사용하세요. 오버헤드를 줄이려면
"events": ["command"]보다"events": ["command:new"]를 선호하세요.
문제 해결
Hook이 검색되지 않음
Hook이 적합하지 않음
Hook이 실행되지 않음
- Hook이 활성화되어 있는지 확인하세요:
openclaw hooks list - Hook이 다시 로드되도록 Gateway 프로세스를 재시작하세요.
- Gateway 로그를 확인하세요:
./scripts/clawlog.sh | grep hook
관련 항목
- CLI 참조: hooks
- Webhook
- Plugin Hook — 인프로세스 Plugin 수명 주기 Hook
- 구성