هوک‌ها

هوک‌ها اسکریپت‌های کوچکی هستند که وقتی چیزی داخل Gateway رخ می‌دهد اجرا می‌شوند. آن‌ها می‌توانند از دایرکتوری‌ها کشف شوند و با openclaw hooks بررسی شوند. Gateway فقط بعد از اینکه هوک‌ها را فعال کنید یا دست‌کم یک ورودی هوک، بسته هوک، handler قدیمی، یا دایرکتوری هوک اضافی پیکربندی کنید، هوک‌های داخلی را بارگذاری می‌کند.

در OpenClaw دو نوع هوک وجود دارد:

• هوک‌های داخلی (این صفحه): داخل Gateway هنگام رخ دادن رویدادهای عامل اجرا می‌شوند، مانند /new، /reset، /stop، یا رویدادهای چرخه حیات.
• Webhookها: endpointهای HTTP خارجی که به سیستم‌های دیگر اجازه می‌دهند کاری را در OpenClaw راه‌اندازی کنند. Webhookها را ببینید.

هوک‌ها همچنین می‌توانند داخل pluginها بسته‌بندی شوند. openclaw hooks list هم هوک‌های مستقل و هم هوک‌های مدیریت‌شده توسط plugin را نشان می‌دهد.

سطح مناسب را انتخاب کنید

OpenClaw چندین سطح افزونه دارد که مشابه به نظر می‌رسند اما مسائل متفاوتی را حل می‌کنند:

وقتی اتوماسیونی می‌خواهید که مانند یک integration کوچک نصب‌شده رفتار کند، از هوک‌های داخلی استفاده کنید. وقتی به کنترل چرخه حیات runtime نیاز دارید، از هوک‌های plugin تایپ‌شده استفاده کنید.

شروع سریع

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

انواع رویداد

نوشتن هوک‌ها

ساختار هوک

هر هوک یک دایرکتوری است که دو فایل دارد:

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

قالب HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

فیلدهای metadata (metadata.openclaw):

پیاده‌سازی handler

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

هر رویداد شامل این موارد است: type، action، sessionKey، timestamp، messages (پاسخ‌ها را فقط روی سطح‌های قابل پاسخ‌گویی اینجا push کنید)، و context (داده‌های مخصوص رویداد). contextهای هوک plugin عامل و ابزار همچنین می‌توانند trace را شامل شوند، یک context trace تشخیصی فقط‌خواندنی سازگار با W3C که pluginها ممکن است برای هم‌بستگی OTEL به structured logها پاس بدهند.

event.messages فقط روی سطح‌های قابل پاسخ‌گویی مانند command:* و message:received به‌صورت خودکار تحویل داده می‌شود. رویدادهای صرفاً چرخه حیات مانند agent:bootstrap، session:*، gateway:*، یا message:sent کانال پاسخ ندارند و پیام‌های pushشده را نادیده می‌گیرند.

نکات مهم context رویداد

رویدادهای دستور (command:new، command:reset): context.sessionEntry، context.previousSessionEntry، context.commandSource، context.workspaceDir، context.cfg.

رویدادهای پیام (message:received): context.from، context.content، context.channelId، context.metadata (داده‌های مخصوص provider شامل senderId، senderName، guildId). context.content برای پیام‌های شبیه دستور، بدنه دستور غیرخالی را ترجیح می‌دهد، سپس به بدنه ورودی خام و بدنه عمومی fallback می‌کند؛ شامل enrichmentهای فقط عامل مانند تاریخچه thread یا خلاصه‌های لینک نیست.

رویدادهای پیام (message:sent): context.to، context.content، context.success، context.channelId.

رویدادهای پیام (message:transcribed): context.transcript، context.from، context.channelId، context.mediaPath.

رویدادهای پیام (message:preprocessed): context.bodyForAgent (بدنه enriched نهایی)، context.from، context.channelId.

رویدادهای Bootstrap (agent:bootstrap): context.bootstrapFiles (آرایه قابل تغییر)، context.agentId.

رویدادهای patch session (session:patch): context.sessionEntry، context.patch (فقط فیلدهای تغییرکرده)، context.cfg. فقط clientهای privileged می‌توانند رویدادهای patch را راه‌اندازی کنند.

رویدادهای Compaction: session:compact:before شامل messageCount، tokenCount است. session:compact:after مقادیر compactedCount، summaryLength، tokensBefore، tokensAfter را اضافه می‌کند.

command:stop صدور /stop توسط کاربر را مشاهده می‌کند؛ این چرخه حیات لغو/دستور است، نه یک gate نهایی‌سازی عامل. Pluginهایی که نیاز دارند یک پاسخ نهایی طبیعی را بررسی کنند و از عامل یک گذر دیگر بخواهند باید به‌جای آن از هوک plugin تایپ‌شده before_agent_finalize استفاده کنند. هوک‌های Plugin را ببینید.

رویدادهای چرخه حیات Gateway: gateway:shutdown شامل reason و restartExpectedMs است و وقتی shutdown کردن gateway آغاز می‌شود رخ می‌دهد. gateway:pre-restart همان context را شامل می‌شود اما فقط وقتی رخ می‌دهد که shutdown بخشی از یک restart مورد انتظار باشد و مقدار finite restartExpectedMs ارائه شود. در طول shutdown، انتظار برای هر هوک چرخه حیات best-effort و bounded است تا اگر handler متوقف شد، shutdown ادامه پیدا کند. بودجه انتظار پیش‌فرض برای gateway:shutdown برابر ۵ ثانیه و برای gateway:pre-restart برابر ۱۰ ثانیه است.

برای noticeهای کوتاه restart در حالی که channelها هنوز در دسترس هستند، از gateway:pre-restart استفاده کنید:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

بین رویداد gateway:shutdown (یا gateway:pre-restart) و ادامه sequence shutdown، gateway همچنین برای هر session که هنگام توقف process هنوز active بوده است، یک هوک plugin تایپ‌شده session_end را fire می‌کند. reason رویداد برای توقف ساده SIGTERM/SIGINT برابر shutdown و وقتی close به‌عنوان بخشی از restart مورد انتظار schedule شده باشد برابر restart است. این drain محدود است تا handler کند session_end نتواند خروج process را مسدود کند، و sessionهایی که از قبل از طریق replace / reset / delete / compaction نهایی شده‌اند skip می‌شوند تا از double-firing جلوگیری شود.

کشف هوک

هوک‌ها از این دایرکتوری‌ها کشف می‌شوند، به ترتیب افزایش اولویت override:

1. هوک‌های bundled: همراه OpenClaw ارائه می‌شوند
2. هوک‌های Plugin: هوک‌هایی که داخل pluginهای نصب‌شده بسته‌بندی شده‌اند
3. هوک‌های managed: ~/.openclaw/hooks/ (نصب‌شده توسط کاربر، مشترک میان workspaceها). دایرکتوری‌های اضافی از hooks.internal.load.extraDirs این اولویت را به اشتراک می‌گذارند.
4. هوک‌های Workspace: <workspace>/hooks/ (برای هر عامل، به‌صورت پیش‌فرض غیرفعال تا وقتی صریحاً فعال شود)

هوک‌های Workspace می‌توانند نام‌های هوک جدید اضافه کنند اما نمی‌توانند هوک‌های bundled، managed، یا ارائه‌شده توسط plugin با همان نام را override کنند.

Gateway هنگام startup تا وقتی هوک‌های داخلی پیکربندی نشده باشند، کشف هوک داخلی را skip می‌کند. یک هوک bundled یا managed را با openclaw hooks enable <name> فعال کنید، یک بسته هوک نصب کنید، یا hooks.internal.enabled=true را تنظیم کنید تا opt in کنید. وقتی یک هوک نام‌دار را فعال می‌کنید، Gateway فقط handler همان هوک را بارگذاری می‌کند؛ hooks.internal.enabled=true، دایرکتوری‌های هوک اضافی، و handlerهای قدیمی به کشف گسترده opt in می‌کنند.

بسته‌های هوک

بسته‌های هوک packageهای npm هستند که هوک‌ها را از طریق openclaw.hooks در package.json export می‌کنند. با این دستور نصب کنید:

openclaw plugins install <path-or-spec>

specهای npm فقط registry هستند (نام package + نسخه exact اختیاری یا dist-tag). specهای Git/URL/file و semver rangeها رد می‌شوند.

هوک‌های bundled

هر هوک بسته‌بندی‌شده‌ای را فعال کنید:

openclaw hooks enable <hook-name>

جزئیات session-memory

آخرین ۱۵ پیام کاربر/دستیار را استخراج می‌کند و با استفاده از تاریخ محلی میزبان در <workspace>/memory/YYYY-MM-DD-HHMM.md ذخیره می‌کند. ثبت حافظه در پس‌زمینه اجرا می‌شود تا تأییدهای /new و /reset به‌خاطر خواندن رونوشت یا تولید اختیاری slug به تأخیر نیفتند. برای تولید slugهای توصیفی نام فایل با مدل پیکربندی‌شده، hooks.internal.entries.session-memory.llmSlug: true را تنظیم کنید. لازم است workspace.dir پیکربندی شده باشد.

پیکربندی bootstrap-extra-files

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

مسیرها نسبت به فضای کاری resolve می‌شوند. فقط basenameهای شناخته‌شدهٔ راه‌اندازی بارگذاری می‌شوند (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

جزئیات command-logger

هر فرمان اسلش را در ~/.openclaw/logs/commands.log ثبت می‌کند.

جزئیات compaction-notifier

وقتی OpenClaw فشرده‌سازی رونوشت نشست را شروع و تمام می‌کند، پیام‌های کوتاه وضعیت را به گفت‌وگوی فعلی می‌فرستد. این کار نوبت‌های طولانی را در سطح‌های چت کمتر گیج‌کننده می‌کند، چون کاربر می‌تواند ببیند که دستیار در حال خلاصه‌سازی زمینه است و پس از Compaction ادامه خواهد داد.

جزئیات boot-md

وقتی Gateway شروع می‌شود، BOOT.md را از فضای کاری فعال اجرا می‌کند.

هوک‌های Plugin

Pluginها می‌توانند برای یکپارچه‌سازی عمیق‌تر، هوک‌های typed را از طریق Plugin SDK ثبت کنند: رهگیری فراخوانی‌های ابزار، تغییر promptها، کنترل جریان پیام، و موارد دیگر. وقتی به before_tool_call، before_agent_reply، before_install، یا سایر هوک‌های چرخه‌حیات درون‌فرایندی نیاز دارید، از هوک‌های Plugin استفاده کنید.

هوک‌های داخلی مدیریت‌شده توسط Plugin متفاوت‌اند: آن‌ها در سامانهٔ رویداد command/lifecycle درشت‌دانهٔ این صفحه شرکت می‌کنند و در openclaw hooks list به‌صورت plugin:<id> نمایش داده می‌شوند. از آن‌ها برای اثرات جانبی و سازگاری با بسته‌های هوک استفاده کنید، نه برای middleware ترتیبی یا دروازه‌های policy.

برای مرجع کامل هوک Plugin، هوک‌های Plugin را ببینید.

پیکربندی

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

متغیرهای محیطی برای هر هوک:

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

دایرکتوری‌های هوک اضافی:

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

مرجع CLI

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

بهترین روش‌ها

• handlerها را سریع نگه دارید. هوک‌ها هنگام پردازش فرمان اجرا می‌شوند. کارهای سنگین را با void processInBackground(event) به‌صورت fire-and-forget اجرا کنید.
• خطاها را با ظرافت مدیریت کنید. عملیات پرخطر را در try/catch بپیچید؛ throw نکنید تا handlerهای دیگر بتوانند اجرا شوند.
• رویدادها را زود فیلتر کنید. اگر نوع/کنش رویداد مرتبط نیست، بلافاصله برگردید.
• از کلیدهای رویداد مشخص استفاده کنید. برای کاهش سربار، "events": ["command:new"] را به "events": ["command"] ترجیح دهید.

عیب‌یابی

هوک کشف نمی‌شود

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

هوک واجد شرایط نیست

openclaw hooks info my-hook

نبود binaryها (PATH)، متغیرهای محیطی، مقدارهای پیکربندی، یا سازگاری سیستم‌عامل را بررسی کنید.

هوک اجرا نمی‌شود

1. بررسی کنید هوک فعال است: openclaw hooks list
2. فرایند Gateway خود را بازراه‌اندازی کنید تا هوک‌ها دوباره بارگذاری شوند.
3. لاگ‌های Gateway را بررسی کنید: ./scripts/clawlog.sh | grep hook

مرتبط

• مرجع CLI: هوک‌ها
• Webhookها
• هوک‌های Plugin — هوک‌های چرخه‌حیات Plugin درون‌فرایندی
• پیکربندی