OpenClaw Hooks 관리 가이드: 자동화 설정 및 상태 확인하기

자동화된 워크플로우를 구축하다 보면 반복되는 이벤트 처리나 명령 실행을 관리하는 것이 생각보다 번거로울 때가 많습니다. 특히 에이전트의 상태를 유지하거나 로그를 남기는 작업을 매번 수동으로 설정하는 것은 개발자에게 큰 피로감을 주곤 하죠.

OpenClaw는 이러한 이벤트 기반 자동화를 OpenClaw hooks를 통해 간편하게 관리할 수 있도록 도와줍니다. 이 가이드를 통해 OpenClaw의 다양한 hook 기능을 활용하여 개발 환경을 더욱 효율적으로 만들어 보세요.

모든 Hook 목록 확인하기

현재 워크스페이스, 관리형, 추가 및 번들 디렉토리에서 발견된 모든 hook을 확인하려면 다음 명령어를 사용하세요. Gateway가 시작될 때 내부 hook 핸들러는 최소 하나의 내부 hook이 설정되기 전까지는 로드되지 않습니다.

openclaw hooks list

옵션:

• --eligible: 조건이 충족된 hook만 표시합니다.
• --json: JSON 형식으로 출력합니다.
• -v, --verbose: 누락된 요구 사항을 포함한 상세 정보를 표시합니다.

출력 예시:

Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued

상세 정보 예시:

openclaw hooks list --verbose

JSON 출력 예시:

openclaw hooks list --json

Hook 정보 가져오기

특정 hook에 대한 자세한 정보를 확인하고 싶을 때 이 명령어를 사용합니다.

openclaw hooks info <name>

인자:

• <name>: Hook 이름 또는 hook 키 (예: session-memory)

옵션:

• --json: JSON 형식으로 출력합니다.

예시:

openclaw hooks info session-memory

출력:

💾 session-memory ✓ Ready

Save session context to memory when /new or /reset command is issued

Details:
  Source: openclaw-bundled
  Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

Hook 적격성 확인하기

전체 hook의 상태를 요약하여 준비된 hook과 그렇지 않은 hook의 개수를 한눈에 파악할 수 있습니다.

openclaw hooks check

옵션:

• --json: JSON 형식으로 출력합니다.

출력 예시:

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

Hook 활성화하기

특정 hook을 설정 파일(~/.openclaw/openclaw.json)에 추가하여 활성화합니다.

openclaw hooks enable <name>

참고: 워크스페이스 hook은 여기서 활성화하기 전까지 기본적으로 비활성화 상태입니다. 플러그인으로 관리되는 hook은 openclaw hooks list에서 plugin:<id>로 표시되며, 여기서 직접 활성화/비활성화할 수 없습니다. 대신 플러그인 자체를 관리하세요.

예시:

openclaw hooks enable session-memory

출력:

✓ Enabled hook: 💾 session-memory

작동 방식:

1. Hook의 존재 여부와 적격성을 확인합니다.
2. 설정 파일의 hooks.internal.entries.<name>.enabled = true를 업데이트합니다.
3. 설정을 디스크에 저장합니다.

활성화 후: Gateway를 재시작하여 hook을 다시 로드하세요.

Hook 비활성화하기

설정 파일을 업데이트하여 특정 hook을 비활성화합니다.

openclaw hooks disable <name>

인자:

• <name>: Hook 이름 (예: command-logger)

예시:

openclaw hooks disable command-logger

출력:

⏸ Disabled hook: 📝 command-logger

비활성화 후: Gateway를 재시작하여 hook을 다시 로드하세요.

참고 사항

• openclaw hooks list --json, info --json, check --json 명령어는 구조화된 JSON을 표준 출력으로 직접 보냅니다.
• 플러그인 관리형 hook은 이곳에서 활성화/비활성화할 수 없으며, 해당 플러그인을 관리해야 합니다.

Hook 팩 설치하기

통합 플러그인 설치 프로그램을 통해 hook 팩을 설치할 수 있습니다.

openclaw plugins install <package>        # ClawHub first, then npm
openclaw plugins install <package> --pin  # pin version
openclaw plugins install <path>           # local path

openclaw hooks install은 호환성을 위해 유지되지만, 사용 시 경고 메시지가 출력되며 openclaw plugins install로 전달됩니다. npm 사양은 레지스트리 전용이며, 의존성 설치는 안전을 위해 --ignore-scripts와 함께 실행됩니다.

작동 방식:

• Hook 팩을 ~/.openclaw/hooks/<id>로 복사합니다.
• hooks.internal.entries.*에서 설치된 hook을 활성화합니다.
• hooks.internal.installs에 설치 기록을 남깁니다.

옵션:

• -l, --link: 복사하는 대신 로컬 디렉토리를 연결합니다.
• --pin: npm 설치를 정확한 버전으로 기록합니다.

예시:

# Local directory
openclaw plugins install ./my-hook-pack

# Local archive
openclaw plugins install ./my-hook-pack.zip

# NPM package
openclaw plugins install @openclaw/my-hook-pack

# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack

Hook 팩 업데이트하기

통합 플러그인 업데이트 프로그램을 통해 npm 기반의 hook 팩을 업데이트합니다.

openclaw plugins update <id>
openclaw plugins update --all

openclaw hooks update는 호환성을 위해 유지되지만, 사용 시 경고 메시지가 출력됩니다.

옵션:

• --all: 추적 중인 모든 hook 팩을 업데이트합니다.
• --dry-run: 실제 변경 없이 변경 사항을 미리 확인합니다.

번들 Hook

session-memory

/new 또는 /reset 명령 실행 시 세션 컨텍스트를 메모리에 저장합니다.

활성화:

openclaw hooks enable session-memory

bootstrap-extra-files

agent:bootstrap 과정 중에 추가적인 부트스트랩 파일을 주입합니다.

활성화:

openclaw hooks enable bootstrap-extra-files

command-logger

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

활성화:

openclaw hooks enable command-logger

로그 확인:

# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

boot-md

Gateway가 시작될 때 BOOT.md를 실행합니다.

활성화:

openclaw hooks enable boot-md

---

더 자세한 도움이 필요하시면 AI Setup Assistant를 확인해 보세요.

관련 문서:

• Hooks
• Plugin hooks