메인 콘텐츠로 건너뛰기

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.

훅은 Gateway 내부에서 어떤 일이 발생할 때 실행되는 작은 스크립트입니다. 디렉터리에서 발견할 수 있으며 openclaw hooks로 검사할 수 있습니다. Gateway는 훅을 활성화하거나 하나 이상의 훅 항목, 훅 팩, 레거시 핸들러 또는 추가 훅 디렉터리를 구성한 뒤에만 내부 훅을 로드합니다. OpenClaw에는 두 종류의 훅이 있습니다.
  • 내부 훅(이 페이지): /new, /reset, /stop 같은 에이전트 이벤트나 수명 주기 이벤트가 발생할 때 Gateway 내부에서 실행됩니다.
  • Webhook: 다른 시스템이 OpenClaw에서 작업을 트리거할 수 있게 하는 외부 HTTP 엔드포인트입니다. Webhook을 참조하세요.
훅은 Plugin 안에 함께 포함될 수도 있습니다. openclaw hooks list는 독립 실행형 훅과 Plugin이 관리하는 훅을 모두 표시합니다.

빠른 시작

# 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

이벤트 유형

이벤트발생 시점
command:new/new 명령이 실행됨
command:reset/reset 명령이 실행됨
command:stop/stop 명령이 실행됨
command모든 명령 이벤트(일반 리스너)
session:compact:beforeCompaction이 기록을 요약하기 전
session:compact:afterCompaction이 완료된 후
session:patch세션 속성이 수정될 때
agent:bootstrap작업공간 부트스트랩 파일이 주입되기 전
gateway:startup채널이 시작되고 훅이 로드된 후
gateway:shutdownGateway 종료가 시작될 때
gateway:pre-restart예정된 Gateway 재시작 전
message:received모든 채널에서 들어오는 메시지
message:transcribed오디오 전사가 완료된 후
message:preprocessed미디어 및 링크 전처리가 완료되거나 건너뛴 후
message:sent발신 메시지가 전달됨

훅 작성

훅 구조

각 훅은 두 파일이 포함된 디렉터리입니다.
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.openclaw):
필드설명
emojiCLI에 표시할 이모지
events수신할 이벤트 배열
export사용할 명명된 export(기본값은 "default")
os필요한 플랫폼(예: ["darwin", "linux"])
requires필요한 bins, anyBins, env 또는 config 경로
always적격성 검사를 우회함(불리언)
install설치 방법

핸들러 구현

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;
각 이벤트에는 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:aftercompactedCount, summaryLength, tokensBefore, tokensAfter를 추가합니다. command:stop은 사용자가 /stop을 실행하는 것을 관찰합니다. 이는 취소/명령 수명 주기에 해당하며, 에이전트 최종화 게이트가 아닙니다. 자연스러운 최종 답변을 검사하고 에이전트에 한 번 더 처리하도록 요청해야 하는 Plugin은 대신 타입이 지정된 Plugin 훅 before_agent_finalize를 사용해야 합니다. Plugin 훅을 참조하세요. Gateway 수명 주기 이벤트: gateway:shutdown에는 reasonrestartExpectedMs가 포함되며 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을 통해 이미 최종화된 세션은 중복 발생을 피하기 위해 건너뜁니다.

훅 발견

훅은 다음 디렉터리에서 발견되며, 뒤로 갈수록 재정의 우선순위가 높아집니다.
  1. 번들 훅: OpenClaw와 함께 제공됨
  2. Plugin 훅: 설치된 Plugin 안에 함께 포함된 훅
  3. 관리형 훅: ~/.openclaw/hooks/(사용자가 설치하며 작업공간 간 공유됨). hooks.internal.load.extraDirs의 추가 디렉터리도 이 우선순위를 공유합니다.
  4. 작업공간 훅: <workspace>/hooks/(에이전트별, 명시적으로 활성화하기 전까지 기본적으로 비활성화됨)
작업공간 훅은 새 훅 이름을 추가할 수 있지만, 같은 이름의 번들, 관리형 또는 Plugin 제공 훅을 재정의할 수는 없습니다. Gateway는 내부 훅이 구성될 때까지 시작 시 내부 훅 발견을 건너뜁니다. openclaw hooks enable <name>으로 번들 또는 관리형 훅을 활성화하거나, 훅 팩을 설치하거나, hooks.internal.enabled=true를 설정해 옵트인하세요. 이름이 지정된 훅 하나를 활성화하면 Gateway는 해당 훅의 핸들러만 로드합니다. hooks.internal.enabled=true, 추가 훅 디렉터리, 레거시 핸들러는 광범위한 발견에 옵트인합니다.

훅 팩

훅 팩은 package.jsonopenclaw.hooks를 통해 훅을 내보내는 npm 패키지입니다. 다음으로 설치합니다.
openclaw plugins install <path-or-spec>
Npm spec은 레지스트리 전용입니다(패키지 이름 + 선택적 정확한 버전 또는 dist-tag). Git/URL/file spec과 semver 범위는 거부됩니다.

번들 훅

이벤트수행 작업
session-memorycommand:new, command:reset세션 컨텍스트를 <workspace>/memory/에 저장
bootstrap-extra-filesagent:bootstrapglob 패턴에서 추가 부트스트랩 파일을 주입
command-loggercommand모든 명령을 ~/.openclaw/logs/commands.log에 기록
compaction-notifiersession:compact:before, session:compact:after세션 Compaction 시작/종료 시 보이는 채팅 알림을 전송
boot-mdgateway:startupGateway가 시작될 때 BOOT.md를 실행
번들 훅을 활성화합니다.
openclaw hooks enable <hook-name>

session-memory 세부 정보

마지막 15개의 사용자/어시스턴트 메시지를 추출하고 호스트 로컬 날짜를 사용해 <workspace>/memory/YYYY-MM-DD-HHMM.md에 저장합니다. 메모리 캡처는 백그라운드에서 실행되므로 /new/reset 확인 응답이 트랜스크립트 읽기나 선택적 슬러그 생성으로 지연되지 않습니다. 구성된 모델로 설명적인 파일 이름 슬러그를 생성하려면 hooks.internal.entries.session-memory.llmSlug: true를 설정하세요. workspace.dir가 구성되어 있어야 합니다.

bootstrap-extra-files 구성

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}
경로는 작업공간을 기준으로 해석됩니다. 인식되는 부트스트랩 기본 파일 이름만 로드됩니다(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": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}
훅별 환경 변수:
{
  "hooks": {
    "internal": {
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": { "MY_CUSTOM_VAR": "value" }
        }
      }
    }
  }
}
추가 훅 디렉터리:
{
  "hooks": {
    "internal": {
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}
레거시 hooks.internal.handlers 배열 구성 형식은 이전 버전과의 호환성을 위해 계속 지원되지만, 새 Hook은 검색 기반 시스템을 사용해야 합니다.

CLI 참조

# 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은 명령 처리 중에 실행됩니다. 무거운 작업은 void processInBackground(event)로 실행만 시작하고 기다리지 마세요.
  • 오류를 우아하게 처리하세요. 위험한 작업은 try/catch로 감싸세요. 다른 핸들러가 실행될 수 있도록 throw하지 마세요.
  • 이벤트를 일찍 필터링하세요. 이벤트 유형/작업이 관련 없으면 즉시 반환하세요.
  • 구체적인 이벤트 키를 사용하세요. 오버헤드를 줄이려면 "events": ["command"]보다 "events": ["command:new"]를 선호하세요.

문제 해결

Hook이 검색되지 않음

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

# List all discovered hooks
openclaw hooks list

Hook이 적합하지 않음

openclaw hooks info my-hook
누락된 바이너리(PATH), 환경 변수, 구성 값 또는 OS 호환성을 확인하세요.

Hook이 실행되지 않음

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

관련 항목