openclaw hooks list

openclaw hooks enable session-memory

openclaw hooks check

openclaw hooks info session-memory

my-hook/
├── HOOK.md          # 메타데이터 + 문서
└── handler.ts       # 핸들러 구현

openclaw hooks install <path-or-spec>

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

---
name: my-hook
description: "이 후크가 하는 일에 대한 간단한 설명"
homepage: https://docs.openclaw.ai/automation/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

자세한 문서는 여기에 작성됩니다...

## 수행 기능

- `/new` 명령어를 대기
- 특정 작업 수행
- 결과를 기록

## 요구 사항

- Node.js가 설치되어 있어야 합니다

## 구성

구성이 필요하지 않습니다.

import type { HookHandler } from "../../src/hooks/hooks.js";

const myHandler: HookHandler = async (event) => {
  // 'new' 명령어에서만 트리거
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  console.log(`  Session: ${event.sessionKey}`);
  console.log(`  Timestamp: ${event.timestamp.toISOString()}`);

  // 여기에 사용자 정의 로직 추가

  // 사용자에게 메시지 전송 선택 사항
  event.messages.push("✨ My hook executed!");
};

export default myHandler;

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // 예: 'new', 'reset', 'stop'
  sessionKey: string,          // 세션 식별자
  timestamp: Date,             // 이벤트 발생 시각
  messages: string[],          // 사용자에게 전송할 메시지 푸시
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // 예: 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

// message:received context
{
  from: string,           // 발신자 식별자 (전화번호, 사용자 ID 등)
  content: string,        // 메시지 콘텐츠
  timestamp?: number,     // 수신 시 Unix 타임스탬프
  channelId: string,      // 채널 (예: "whatsapp", "telegram", "discord")
  accountId?: string,     // 다중 계정 설정용 프로바이더 계정 ID
  conversationId?: string, // 채팅/대화 ID
  messageId?: string,     // 프로바이더로부터의 메시지 ID
  metadata?: {            // 프로바이더별 추가 데이터
    to?: string,
    provider?: string,
    surface?: string,
    threadId?: string,
    senderId?: string,
    senderName?: string,
    senderUsername?: string,
    senderE164?: string,
  }
}

// message:sent context
{
  to: string,             // 수신자 식별자
  content: string,        // 전송된 메시지 콘텐츠
  success: boolean,       // 전송 성공 여부
  error?: string,         // 전송 실패 시 오류 메시지
  channelId: string,      // 채널 (예: "whatsapp", "telegram", "discord")
  accountId?: string,     // 프로바이더 계정 ID
  conversationId?: string, // 채팅/대화 ID
  messageId?: string,     // 프로바이더가 반환한 메시지 ID
}

import type { HookHandler } from "../../src/hooks/hooks.js";
import { isMessageReceivedEvent, isMessageSentEvent } from "../../src/hooks/internal-hooks.js";

const handler: HookHandler = async (event) => {
  if (isMessageReceivedEvent(event)) {
    console.log(`[message-logger] Received from ${event.context.from}: ${event.context.content}`);
  } else if (isMessageSentEvent(event)) {
    console.log(`[message-logger] Sent to ${event.context.to}: ${event.context.content}`);
  }
};

export default handler;

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

---
name: my-hook
description: "유용한 일을 합니다"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

이 후크는 `/new` 명령어를 발행할 때 유용한 일을 합니다.

import type { HookHandler } from "../../src/hooks/hooks.js";

const handler: HookHandler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log("[my-hook] Running!");
  // 여기에 로직 추가
};

export default handler;

# 후크가 검색되는지 확인
openclaw hooks list

# 활성화
openclaw hooks enable my-hook

# 게이트웨이 프로세스 재시작 (macOS에서 메뉴 바 앱 재시작하거나 개발 프로세스 재시작)

# 이벤트 트리거
# 메시지 채널을 통해 /new 전송

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": {
            "MY_CUSTOM_VAR": "value"
          }
        }
      }
    }
  }
}

{
  "hooks": {
    "internal": {
      "enabled": true,
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts",
          "export": "default"
        }
      ]
    }
  }
}

# 모든 후크 나열
openclaw hooks list

# 적격 후크만 표시
openclaw hooks list --eligible

# 자세한 출력 (누락된 요구 사항 표시)
openclaw hooks list --verbose

# JSON 출력
openclaw hooks list --json

# 후크에 대한 자세한 정보 표시
openclaw hooks info session-memory

# JSON 출력
openclaw hooks info session-memory --json

# 적격성 요약 표시
openclaw hooks check

# JSON 출력
openclaw hooks check --json

# 후크 활성화
openclaw hooks enable session-memory

# 후크 비활성화
openclaw hooks disable command-logger

# 세션: 2026-01-16 14:30:00 UTC

- **세션 키**: agent:main:main
- **세션 ID**: abc123def456
- **출처**: telegram

openclaw hooks enable session-memory

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

openclaw hooks enable bootstrap-extra-files

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}

# 최근 명령어 보기
tail -n 20 ~/.openclaw/logs/commands.log

# jq로 예쁘게 인쇄하기
cat ~/.openclaw/logs/commands.log | jq .

# 동작별 필터
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

openclaw hooks enable command-logger

openclaw hooks enable boot-md

// ✓ 양호 - 비동기 작업, 즉시 반환
const handler: HookHandler = async (event) => {
  void processInBackground(event); // 실행하고 잊어버리기
};

// ✗ 좋지 않음 - 명령 처리 지연
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // 던지지 마세요 - 다른 핸들러가 실행되도록 하세요
  }
};

const handler: HookHandler = async (event) => {
  // 'new' 명령어에서만 처리
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  // 여기에 로직 추가
};

metadata: { "openclaw": { "events": ["command:new"] } } # 특정

metadata: { "openclaw": { "events": ["command"] } } # 일반적 - 더 많은 오버헤드

Registered hook: session-memory -> command:new
Registered hook: bootstrap-extra-files -> agent:bootstrap
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

openclaw hooks list --verbose

const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // 여기에 로직
};

openclaw hooks info my-hook

# macOS
./scripts/clawlog.sh -f

# 다른 플랫폼
tail -f ~/.openclaw/gateway.log

import { test } from "vitest";
import { createHookEvent } from "./src/hooks/hooks.js";
import myHandler from "./hooks/my-hook/handler.js";

test("my handler works", async () => {
  const event = createHookEvent("command", "new", "test-session", {
    foo: "bar",
  });

  await myHandler(event);

  // 부작용 확인
});

게이트웨이 시작
    ↓
디렉토리 스캔 (워크스페이스 → 관리 → 번들)
    ↓
HOOK.md 파일 파싱
    ↓
적격성 확인 (바이너리, 환경 변수, 구성, 운영체제)
    ↓
적격 후크에서 핸들러 로드
    ↓
이벤트용 핸들러 등록

사용자가 /new 보냄
    ↓
명령어 유효성 검사
    ↓
후크 이벤트 생성
    ↓
후크 트리거 (모든 등록된 핸들러)
    ↓
명령어 처리 계속
    ↓
세션 리셋

openclaw hooks info my-hook

# 직접 임포트 테스트
node -e "import('./path/to/handler.ts').then(console.log)"

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts"
        }
      ]
    }
  }
}