OpenClaw Hooks란? cron과 다른 자동화 이벤트 처리의 기준

OpenClaw에서 어떤 일은 “매일 오전에 실행”처럼 시간을 정해 두는 편이 맞고, 어떤 일은 대화가 초기화되었을 때처럼 사건이 생긴 직후 짧게 처리하는 편이 맞습니다. 후자에 쓰는 장치가 내부 Hooks입니다.

이 글은 특정 설정을 직접 운영한 경험담이 아니라 OpenClaw 공식 Hooks 문서를 바탕으로, cron·웹훅·플러그인 훅을 처음 구분할 때 필요한 범위만 한국어로 풀어 쓴 해설입니다. 각 기능의 실제 사용 가능 여부는 Gateway 설정과 실행 환경에서 다시 확인해야 합니다.

Hooks는 ‘시간표’가 아니라 이벤트에 반응하는 작은 처리기입니다

내부 Hooks는 Gateway 프로세스가 이벤트를 내보낼 때 실행되는 작은 JavaScript 또는 TypeScript 처리기입니다. 예를 들어 /new나 /reset 같은 명령을 기록하거나, 세션·메시지 수명주기에서 짧은 부수 작업을 할 때 쓸 수 있습니다.

그래서 “매일 정해진 시각에 보고서를 만들기”에는 cron 작업이, 외부 서비스의 HTTP 요청으로 시작해야 하는 일에는 웹훅이 더 자연스럽습니다. 프롬프트나 도구 호출을 가로채고 반환값·우선순위까지 제어해야 한다면 내부 Hooks가 아니라 플러그인 Hooks가 맞는지 먼저 확인해야 합니다.

세 가지 상태를 따로 확인해야 합니다

공식 문서는 Hook이 요건을 충족하는지, 설정에서 활성화됐는지, 실행 중인 Gateway에 실제로 로드됐는지를 서로 다른 상태로 설명합니다. 목록에서 준비됨으로 보인다고 이벤트가 이미 실행됐다는 뜻은 아닙니다.

1. 운영체제·실행 파일·환경 설정 같은 요구 조건을 확인합니다.
2. 해당 Hook이 설정에서 선택·활성화됐는지 봅니다.
3. 변경 뒤에는 실제 로그나 Hook 고유의 결과를 확인해 이벤트가 한 번 실행됐는지 검증합니다.

특히 설정을 바꾼 뒤에는 ‘check’ 결과만으로 충분하다고 단정하지 않는 편이 좋습니다. 공식 문서도 실제 부수 효과나 Hook별 로그 확인을 권합니다.

처음에는 번들 Hook부터 범위를 작게 잡습니다

OpenClaw에는 command-logger, session-memory, compaction-notifier처럼 자주 쓰는 번들 Hook이 포함돼 있습니다. 예를 들어 command logger는 일부 명령 이벤트를 JSONL 로그에 남기고, session memory는 새 세션·초기화·자동 리셋 시점의 최근 대화를 작업공간 메모리에 저장합니다.

다만 로그와 메모리에는 세션·발신자 정보나 대화 일부가 들어갈 수 있습니다. 필요 이상의 본문·전체 설정·비밀값을 기록하지 말고, 보관 기간과 파일 접근 권한을 함께 검토해야 합니다.

이벤트 안의 작업은 짧고, 다시 실행돼도 안전하게

내부 Hooks는 신뢰된 코드로 Gateway 프로세스의 파일·네트워크·환경 접근 권한 안에서 실행됩니다. 샌드박스 스크립트처럼 취급하면 안 되며, 작업공간이나 내려받은 Hook 코드는 활성화 전에 읽어 보는 것이 안전합니다.

같은 이벤트의 처리기는 순서대로 실행되지만 서로 다른 이벤트는 겹칠 수 있습니다. 일반적인 자동 재시도·정확히 한 번 실행 보장·영구 작업 대기열도 제공되지 않습니다. 따라서 네트워크 호출에는 제한 시간을 두고, 결과가 중복돼도 문제가 없도록 설계하며, 오래 걸리거나 지속적인 작업은 cron 또는 별도의 서비스로 옮기는 편이 낫습니다.

정리: 무엇으로 시작할지 고르는 질문

• 시간이 기준인가? → cron 작업을 먼저 검토합니다.
• 외부 시스템의 HTTP 요청이 시작점인가? → 웹훅을 검토합니다.
• 세션·명령·Gateway 이벤트 직후 짧은 처리가 필요한가? → 내부 Hooks를 검토합니다.
• 도구 호출·응답 수명주기의 제어가 필요한가? → 플러그인 Hooks 문서를 확인합니다.

작은 기록 작업부터 시작하고 실제 결과를 확인한 다음 범위를 넓히면, 자동화를 늘리면서도 원인을 추적하기 쉬워집니다. OpenClaw의 기본 구조는 OpenClaw란 무엇인가 글에서 먼저 볼 수 있습니다.

---

출처: OpenClaw 공식 문서 Hooks, Bundled hooks, Hook configuration and discovery. 이 글은 공식 문서를 요약·해설한 것이며 개인 사용 경험이나 보안 효과를 보장하지 않습니다.