​

—to [email protected] \

​

18. Watch holati va tarixini tekshiring:

19. gog gmail watch status —account [email protected] gog gmail history —account [email protected] —since <historyId> 20. Nosozliklarni bartaraf etish

• 21. Invalid topicName: loyiha nomuvofiqligi (topic OAuth client loyihasida emas).
• 22. User not authorized: topic’da roles/pubsub.publisher yetishmaydi. 23. Bo‘sh xabarlar: Gmail push faqat historyId beradi; gog gmail history orqali olib keling.

24. Tozalash
25. gog gmail watch stop —account [email protected] gcloud pubsub subscriptions delete gog-gmail-watch-push gcloud pubsub topics delete gog-gmail-watch

• 26. Hooks: buyruqlar va hayotiy sikl hodisalari uchun hodisaga asoslangan avtomatlashtirish
• 27. Siz /new, /reset, /stop va agent hayotiy sikli hodisalari uchun hodisaga asoslangan avtomatlashtirishni xohlaysiz
• 28. Siz hook’larni yaratmoqchi, o‘rnatmoqchi yoki nosozliklarni tuzatmoqchisiz
• 29. Hooks

30. Hooks 31. Hooks agent buyruqlari va hodisalariga javoban harakatlarni avtomatlashtirish uchun kengaytiriladigan hodisaga asoslangan tizimni taqdim etadi.

​

32. Hooks kataloglardan avtomatik aniqlanadi va CLI buyruqlari orqali boshqariladi, xuddi OpenClaw’dagi skill’lar kabi.

33. Yo‘naltiruvchi ma’lumot

• 34. Hooks — biror narsa sodir bo‘lganda ishga tushadigan kichik skriptlar.
• 35. Ikki xil turi mavjud:
• Trigger custom automations on agent lifecycle events
• Extend OpenClaw’s behavior without modifying core code

​

12. Boshlash

​

Bundled Hooks

• 💾 session-memory: Saves session context to your agent workspace (default ~/.openclaw/workspace/memory/) when you issue /new
• 📝 command-logger: Logs all command events to ~/.openclaw/logs/commands.log
• 13. 🚀 boot-md: Shlyuz ishga tushganda BOOT.md ni ishga tushiradi (ichki hooklar yoqilgan bo‘lishi kerak)
• 😈 soul-evil: Swaps injected SOUL.md content with SOUL_EVIL.md during a purge window or by random chance

openclaw hooks list

14. Hookni yoqish:

15. openclaw hooks enable session-memory

openclaw hooks check

openclaw hooks info session-memory

​

16. Onboarding

17. Onboarding paytida (openclaw onboard), sizga tavsiya etilgan hooklarni yoqish taklif etiladi. The wizard automatically discovers eligible hooks and presents them for selection.

​

Hook Discovery

1. Workspace hooks: <workspace>/hooks/ (per-agent, highest precedence)
2. Managed hooks: ~/.openclaw/hooks/ (user-installed, shared across workspaces)
3. Bundled hooks: <openclaw>/dist/hooks/bundled/ (shipped with OpenClaw)

my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

​

18. Hook paketlari (npm/arxivlar)

openclaw hooks install <path-or-spec>

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

​

Hook tuzilmasi

​

HOOK.md formati

---
name: my-hook
description: "Short description of what this hook does"
homepage: https://docs.openclaw.ai/hooks#my-hook
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here...

## What It Does

- Listens for `/new` commands
- Performs some action
- Logs the result

## Requirements

- Node.js must be installed

## Configuration

No configuration needed.

​

Metama’lumot maydonlari

• emoji: CLI uchun ko‘rsatiladigan emoji (masalan, "💾")
• events: Kuzatish uchun hodisalar ro‘yxati (masalan, ["command:new", "command:reset"])
• export: Foydalaniladigan nomlangan eksport (standart qiymati "default")
• homepage: Hujjatlar URL manzili
• requires: Ixtiyoriy talablar
  • bins: Required binaries on PATH (e.g., ["git", "node"])
  • anyBins: At least one of these binaries must be present
  • env: Required environment variables
  • config: Required config paths (e.g., ["workspace.dir"])
  • os: Required platforms (e.g., ["darwin", "linux"])
• always: Bypass eligibility checks (boolean)
• install: Installation methods (for bundled hooks: [{"id":"bundled","kind":"bundled"}])

​

Handler Implementation

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

const myHandler: HookHandler = async (event) => {
  // Only trigger on 'new' command
  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()}`);

  // Your custom logic here

  // Optionally send message to user
  event.messages.push("✨ My hook executed!");
};

export default myHandler;

​

Event Context

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // e.g., 'new', 'reset', 'stop'
  sessionKey: string,          // Session identifier
  timestamp: Date,             // When the event occurred
  messages: string[],          // Push messages here to send to user
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

​

Event Types

​

Command Events

• command: All command events (general listener)
• command:new: When /new command is issued
• command:reset: When /reset command is issued
• command:stop: When /stop command is issued

​

Agent Events

• agent:bootstrap: Before workspace bootstrap files are injected (hooks may mutate context.bootstrapFiles)

​

Gateway Events

• gateway:startup: After channels start and hooks are loaded

​

Tool Result Hooks (Plugin API)

• tool_result_persist: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or undefined to keep it as-is. See Agent Loop.

​

Future Events

• session:start: When a new session begins
• session:end: When a session ends
• agent:error: When an agent encounters an error
• message:sent: When a message is sent
• message:received: When a message is received

​

Creating Custom Hooks

​

1. Choose Location

• Workspace hooks (<workspace>/hooks/): Per-agent, highest precedence
• Managed hooks (~/.openclaw/hooks/): Shared across workspaces

​

2. Create Directory Structure

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

​

3. Create HOOK.md

---
name: my-hook
description: "Does something useful"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---

# My Custom Hook

This hook does something useful when you issue `/new`.

​

4. Create handler.ts

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!");
  // Your logic here
};

export default handler;

​

5. Enable and Test

# Verify hook is discovered
openclaw hooks list

# Enable it
openclaw hooks enable my-hook

# Restart your gateway process (menu bar app restart on macOS, or restart your dev process)

# Trigger the event
# Send /new via your messaging channel

​

Configuration

​

New Config Format (Recommended)

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

​

Per-Hook Configuration

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

​

Extra Directories

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

​

Legacy Config Format (Still Supported)

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

​

CLI Commands

​

List Hooks

# List all hooks
openclaw hooks list

# Show only eligible hooks
openclaw hooks list --eligible

# Verbose output (show missing requirements)
openclaw hooks list --verbose

# JSON output
openclaw hooks list --json

​

Hook Information

20. # Hook haqida batafsil ma’lumotni ko‘rsatish
openclaw hooks info session-memory

# JSON chiqishi
openclaw hooks info session-memory --json

​

Check Eligibility

# Show eligibility summary
openclaw hooks check

# JSON output
openclaw hooks check --json

​

Enable/Disable

# Enable a hook
openclaw hooks enable session-memory

# Disable a hook
openclaw hooks disable command-logger

​

Bundled hook reference

​

21. session-memory

1. Uses the pre-reset session entry to locate the correct transcript
2. Extracts the last 15 lines of conversation
3. Uses LLM to generate a descriptive filename slug
4. Saves session metadata to a dated memory file

# Session: 2026-01-16 14:30:00 UTC

- **Session Key**: agent:main:main
- **Session ID**: abc123def456
- **Source**: telegram

• 2026-01-16-vendor-pitch.md
• 2026-01-16-api-design.md
• 2026-01-16-1430.md (fallback timestamp if slug generation fails)

openclaw hooks enable session-memory

​

command-logger

1. Captures event details (command action, timestamp, session key, sender ID, source)
2. JSONL formatida log fayliga qo‘shadi
3. Fon rejimida jim ishlaydi

{"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":"[email protected]","source":"whatsapp"}

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

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

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

openclaw hooks enable command-logger

​

soul-evil

openclaw hooks enable soul-evil

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": { "at": "21:00", "duration": "15m" }
        }
      }
    }
  }
}

​

boot-md

1. Workspace’ingizdan BOOT.md ni o‘qiydi
2. Ko‘rsatmalarni agent runner orqali bajaradi
3. So‘ralgan barcha tashqi xabarlarni message tool orqali yuboradi

openclaw hooks enable boot-md

​

Eng Yaxshi Amaliyotlar

​

Handlerlarni Tez Saqlang

// ✓ Good - async work, returns immediately
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ Bad - blocks command processing
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

​

Xatolarni Muloyimlik Bilan Qayta Ishlang

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err));
    // Don't throw - let other handlers run
  }
};

​

Hodisalarni Erta Filtrlash

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

  // Your logic here
};

​

Aniq Hodisa Kalitlaridan Foydalaning

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

metadata: { "openclaw": { "events": ["command"] } } # General - more overhead

​

Nosozliklarni Tuzatish

​

Hook Loglashni Yoqish

Registered hook: session-memory -> command:new
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

​

Kashfiyotni Tekshirish

1. openclaw hooks list --verbose

​

2. Roʻyxatdan oʻtishni tekshiring

3. Handler ichida, chaqirilgan paytini log qiling:

4. const handler: HookHandler = async (event) => {
  console.log("[my-handler] Triggered:", event.type, event.action);
  // Sizning mantiqingiz
};

​

5. Moslikni tekshiring

6. Hook nima uchun mos emasligini tekshiring:

7. openclaw hooks info my-hook

8. Chiqishda yetishmayotgan talablarni qidiring.

​

9. Test qilish

​

10. Gateway loglari

11. Hook bajarilishini ko‘rish uchun gateway loglarini kuzating:

12. # macOS
./scripts/clawlog.sh -f

# Boshqa platformalar
tail -f ~/.openclaw/gateway.log

​

13. Hook’larni bevosita test qilish

14. Handler’laringizni alohida holatda test qiling:

15. 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);

  // Yon ta’sirlarni tekshirish
});

​

16. Arxitektura

​

17. Asosiy komponentlar

• 18. src/hooks/types.ts: Tip ta’riflari
• 19. src/hooks/workspace.ts: Kataloglarni skanerlash va yuklash
• 20. src/hooks/frontmatter.ts: HOOK.md metadata’ni ajratib olish
• 21. src/hooks/config.ts: Moslikni tekshirish
• 22. src/hooks/hooks-status.ts: Holatni hisobot qilish
• 23. src/hooks/loader.ts: Dinamik modul yuklovchi
• 24. src/cli/hooks-cli.ts: CLI buyruqlari
• 25. src/gateway/server-startup.ts: Gateway ishga tushganda hook’larni yuklaydi
• 26. src/auto-reply/reply/commands-core.ts: Buyruq hodisalarini ishga tushiradi

​

27. Aniqlash oqimi

28. Gateway ishga tushishi
    ↓
Kataloglarni skanerlash (workspace → managed → bundled)
    ↓
HOOK.md fayllarini tahlil qilish
    ↓
Moslikni tekshirish (binlar, env, config, OS)
    ↓
Mos hook’lardan handler’larni yuklash
    ↓
Hodisalar uchun handler’larni ro‘yxatdan o‘tkazish

​

29. Hodisa oqimi

30. Foydalanuvchi /new yuboradi
    ↓
Buyruqni tekshirish
    ↓
Hook hodisasini yaratish
    ↓
Hook’ni ishga tushirish (barcha ro‘yxatdan o‘tgan handler’lar)
    ↓
Buyruqni qayta ishlash davom etadi
    ↓
Sessiyani qayta o‘rnatish

​

31. Nosozliklarni bartaraf etish

​

32. Hook topilmadi

1. 33. Katalog tuzilmasini tekshiring:
   34. ls -la ~/.openclaw/hooks/my-hook/
   # Quyidagilar bo‘lishi kerak: HOOK.md, handler.ts
   
2. 35. HOOK.md formatini tekshiring:
   36. cat ~/.openclaw/hooks/my-hook/HOOK.md
   # name va metadata’ga ega YAML frontmatter bo‘lishi kerak
   
3. 37. Barcha aniqlangan hook’larni ro‘yxatlang:
   38. openclaw hooks list
   

​

39) Hook mos emas

40. Talablarni tekshiring:

41. openclaw hooks info my-hook

42. Yetishmayotganlarni qidiring:

• 43. Binariylar (PATH’ni tekshiring)
• 44. Muhit o‘zgaruvchilari
• 45. Konfiguratsiya qiymatlari
• 46. OS mosligi

​

47. Hook bajarilmayapti

1. 48. Hook yoqilganligini tekshiring:
   49. openclaw hooks list
   # Yoqilgan hook’lar yonida ✓ bo‘lishi kerak
   
2. 50. Hook’lar qayta yuklanishi uchun gateway jarayonini qayta ishga tushiring.
3. Check gateway logs for errors:
   ./scripts/clawlog.sh | grep hook
   

​

Handler Errors

# Test import directly
node -e "import('./path/to/handler.ts').then(console.log)"

​

Migration Guide

​

From Legacy Config to Discovery

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

1. Create hook directory:
   mkdir -p ~/.openclaw/hooks/my-hook
   mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts
   
2. Create HOOK.md:
   ---
   name: my-hook
   description: "My custom hook"
   metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
   ---
   
   # My Hook
   
   Does something useful.
   
3. Update config:
   {
     "hooks": {
       "internal": {
         "enabled": true,
         "entries": {
           "my-hook": { "enabled": true }
         }
       }
     }
   }
   
4. Verify and restart your gateway process:
   openclaw hooks list
   # Should show: 🎯 my-hook ✓
   

• Automatic discovery
• CLI management
• Eligibility checking
• Better documentation
• Consistent structure

​

22. Shuningdek qarang

• CLI Reference: hooks
• Bundled Hooks README
• Webhook Hooks
• Configuration