OpenClaw Hooks: 완전한 개발자 가이드(2026)

OpenClaw 후크 검색 작동 방식

게이트웨이는 다음을 사용합니다. 자동 디렉토리 스캐닝 후크를 발견합니다. 시작 시 구성된 후크 디렉터리를 검색하고 찾은 유효한 후크 패키지를 로드합니다.

후크가 활성화되기 전 두 가지 중요한 전제 조건은 다음과 같습니다.

1. Hooks은 다음과 같아야 합니다. 명시적으로 활성화됨 — 후크 디렉토리만으로는 충분하지 않습니다
2. 적어도 하나의 후크 항목을 구성해야 합니다. 게이트웨이 설정에서

각 후크 패키지에는 정확히 두 개의 파일이 필요합니다.

• HOOK.md — 후크의 이름, 버전, 설명, 수명 주기 이벤트 구독 및 필요한 권한을 선언하는 메타데이터 파일
• handler.ts (또는 handler.js) — 이벤트가 발생할 때 실행되는 실제 로직을 포함하는 구현 파일

모든 개발자가 알아야 할 4가지 수명주기 이벤트

PreToolUse 가장 강력한 이벤트입니다. 중단하다 실행 전 도구 호출. 후크가 PreToolUse 중에 거부 신호를 반환하면 에이전트는 도구를 호출하지 않습니다.

PostToolUse 자동화를 위한 일꾼입니다. 파일이 작성되었나요? 린터를 실행하세요. 테스트가 수정되었나요? 제품군을 실행합니다. 코드가 커밋되었나요? 빌드를 트리거합니다.

Step-by-Step: 처음부터 첫 번째 사용자 정의 후크 작성

대부분의 문서에는 명령이 나와 있습니다. 이는 아무것도 없는 상태에서 작동하는 후크까지의 전체 경로를 보여줍니다.

Step 1 — 후크 디렉터리 생성

mkdir -p .openclaw/hooks/auto-lint

Step 2 — HOOK.md 메타데이터 쓰기

# auto-lint **Version:** 1.0.0 **Event:** PostToolUse **Description:** Runs ESLint on any file written by the agent **Tools:** write_file, edit_file

Tools 필드는 후크 범위를 특정 도구 호출로 지정합니다. 그것이 없으면 후크가 작동합니다. 모든 PostToolUse 이벤트 — 일반적으로 원하는 것이 아닙니다.

Step 3 — handler.ts 구현

import { PostToolUseEvent } from "@openclaw/sdk"; import { execSync } from "child_process"; export default function handler(event: PostToolUseEvent) { const filePath = event.toolResult?.path; if (!filePath) return; try { execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" }); } catch (err) { console.error(`[auto-lint] ESLint failed on ${filePath}`); } }

Step 4 — CLI를 통해 활성화

openclaw hooks enable auto-lint

Step 5 — 로드되었는지 확인

openclaw hooks list

enabled 상태의 auto-lint이 표시되어야 합니다. 세션을 시작하고, 파일을 쓰고, linter가 실행되는 것을 지켜보세요.

후크 핸들러에 대한 JavaScript 및 TypeScript — 2026년에 선택할 항목

SDK는 전체 TypeScript 유형과 함께 제공되며 2026 SDK 릴리스부터 TypeScript은 권장 기본값입니다. 새로운 후크를 위해.

버전 제어를 약속하거나 팀과 공유할 후크를 작성하는 경우 TypeScript를 사용하세요. 일회용 로컬 가드레일의 경우 일반 JavaScript이 좋습니다. 이름을 handler.js로 지정하고 컴파일 단계를 건너뛰세요.

OpenClaw Hooks CLI Reference

Managing Hook Packs — 설치, 업데이트 및 --dry-run 워크플로

후크 팩은 여러 관련 후크를 단일 설치 가능 단위로 묶습니다. 설치 워크플로는 다음을 확인합니다. 무결성 해시 디스크에 무엇이든 쓰기 전에.

# Preview what would be installed without committing openclaw hooks install productivity-pack --dry-run # Install non-interactively (for CI environments) openclaw hooks install productivity-pack --yes # Update all installed packs openclaw hooks update --all

Bundled Hooks Reference: OpenClaw과 함께 제공되는 것

전체 구성 옵션을 보려면 openclaw hooks inspect session-memory을 실행하세요. 대부분의 번들 후크는 합리적인 기본값으로 제공되지만 사용자 정의를 위해 구성 필드를 노출합니다.

실제 후크 사용 사례(작업 예제 포함)

1. File Protection Guardrail (PreToolUse)

에이전트가 .env 파일을 건드리지 못하도록 방지합니다.

import { PreToolUseEvent } from "@openclaw/sdk"; export default function handler(event: PreToolUseEvent) { const target = event.toolInput?.path ?? ""; if (target.includes(".env")) { return { abort: true, reason: "Modification of .env files is blocked by policy." }; } }

write_file 및 edit_file 범위의 PreToolUse을 구독하는 일치하는 HOOK.md을 사용하여 이를 .openclaw/hooks/protect-env/에 삭제합니다. 에이전트는 해당 컨텍스트에서 거부 이유를 수신하고 재시도하지 않습니다.

2. Slack 세션 중단 알림

import { StopEvent } from "@openclaw/sdk"; export default async function handler(event: StopEvent) { await fetch(process.env.SLACK_WEBHOOK_URL!, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}` }) }); }

이 후크를 Stop 이벤트에 구독하세요. 모든 세션이 종료되면 요약과 함께 Slack 메시지가 표시됩니다. 외부 서버가 필요하지 않습니다. 게이트웨이 프로세스가 아웃바운드 요청을 직접 수행합니다.

3. Auto-Format + Test on PostToolUse

import { PostToolUseEvent } from "@openclaw/sdk"; import { execSync } from "child_process"; export default function handler(event: PostToolUseEvent) { const file = event.toolResult?.path; if (!file?.endsWith(".ts")) return; execSync(`prettier --write "${file}"`); execSync("npm test -- --passWithNoTests", { stdio: "inherit" }); }

이는 모든 TypeScript 파일 쓰기 후에 실행되어 형식을 지정한 다음 테스트 스위트를 실행합니다. 대규모 프로젝트에서는 속도가 느립니다. HOOK.md의 Tools 필드를 사용하여 범위를 엄격하게 지정하세요.

팀을 위한 Hooks — 공유 프로젝트 전체에 가드레일 적용

.openclaw/hooks/ 디렉터리를 버전 제어에 커밋합니다. 저장소를 복제하는 모든 개발자는 자동으로 동일한 후크 구성을 갖습니다.

• 프로젝트 구성에서 중요한 후크를 enabled에 잠급니다. — 팀원이 실수로 파일 가드를 비활성화하는 것을 방지합니다.
• HOOK.md 설명을 사용하여 의도를 문서화하세요. — 코드 주석처럼 취급하면 팀원이 읽을 것입니다.
• Scope hooks to tool-level granularity — 광범위한 후크는 모든 에이전트 상호 작용 속도를 늦추고 마찰을 일으켜 팀원이 이를 비활성화하게 만듭니다.
• 단일 저장소에서 상위 디렉터리의 후크는 하위 디렉터리 수준에서 재정의되지 않는 한 모든 중첩 프로젝트에 적용됩니다.

CI/CD Integration — OpenClaw Hooks을 비대화식으로 실행

GitHub 작업 또는 헤드리스 환경에서는 대화형 확인 프롬프트로 인해 파이프라인이 중단됩니다. 건너뛰려면 --yes을 사용하세요.

- name: Install hooks non-interactively run: openclaw hooks install qa-pack --yes - name: Run OpenClaw session env: OPENCLAW_HOOKS_ENABLED: "true" SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL run: openclaw run --task "audit dependencies" --yes

Hook Security: 실행되는 항목, 액세스할 수 있는 항목 및 안전을 유지하는 방법

이것은 대부분의 문서에서 완전히 건너뛰는 부분이며 커뮤니티 후크 팩을 설치하는 경우 가장 중요한 섹션입니다.

액세스할 수 있는 후크: 후크 스크립트는 게이트웨이 프로세스의 전체 권한. 게이트웨이가 사용자 계정으로 실행되는 경우 후크는 계정이 읽을 수 있는 모든 파일을 읽고, 네트워크를 요청하고, 하위 프로세스를 실행하고, 비밀을 포함한 환경 변수에 액세스할 수 있습니다.

Hook Pack Audit Checklist

타사 팩을 설치하기 전에 다음을 수행하십시오.

openclaw hooks inspect 명령은 설치된 후크의 전체 소스 경로를 보여줍니다. 이를 사용하여 업데이트 후 핸들러 코드를 다시 검토합니다.

Troubleshooting OpenClaw Hooks — 실행되지 않을 때

Frequently Asked Questions

최종 생각 — 작업 흐름에 맞는 올바른 후크 전략 선택

실제 문제를 해결하는 하나의 후크, 즉 파일 가드 또는 쓰기 후 린터로 시작하십시오. 더 많은 레이어를 추가하기 전에 처음부터 끝까지 작동하도록 하세요. 후크의 힘은 복합적입니다. 범위가 잘 지정된 후크 3개가 원활하게 실행되는 세션은 범위가 좋지 않은 10개의 후크가 있는 세션보다 훨씬 더 안정적입니다.