هوک‌ها

Hookها اسکریپت‌های کوچکی هستند که هنگام رخ‌دادن رویدادهای عامل، داخل Gateway اجرا می‌شوند: فرمان‌هایی مانند /new، /reset، /stop، Compaction نشست، چرخهٔ حیات Gateway و جریان پیام. آن‌ها از دایرکتوری‌ها شناسایی و با openclaw hooks مدیریت می‌شوند. Gateway تنها پس از فعال‌کردن Hookها یا پیکربندی حداقل یک ورودی Hook، بستهٔ Hook، کنترل‌گر قدیمی یا دایرکتوری اضافی Hook، Hookهای داخلی را بارگذاری می‌کند.

در OpenClaw دو نوع Hook وجود دارد:

• Hookهای داخلی (این صفحه): هنگام رخ‌دادن رویدادهای عامل، داخل Gateway اجرا می‌شوند.
• Webhookها: نقاط پایانی HTTP خارجی که به سامانه‌های دیگر امکان می‌دهند کاری را در OpenClaw آغاز کنند. به Webhookها مراجعه کنید.

Hookها همچنین می‌توانند داخل Pluginها بسته‌بندی شوند. openclaw hooks list هم Hookهای مستقل و هم Hookهای مدیریت‌شده توسط Plugin را نشان می‌دهد (که به‌شکل plugin:<id> نمایش داده می‌شوند).

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

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

هنگامی از Hookهای داخلی استفاده کنید که خودکارسازی‌ای می‌خواهید که مانند یک یکپارچه‌سازی کوچک نصب‌شده عمل کند. هنگامی از Hookهای نوع‌دار Plugin استفاده کنید که به کنترل چرخهٔ حیات زمان اجرا نیاز دارید.

شروع سریع

# فهرست Hookهای موجودopenclaw hooks list # فعال‌کردن یک Hookopenclaw hooks enable session-memory # بررسی وضعیت Hookopenclaw hooks check # دریافت اطلاعات تفصیلیopenclaw hooks info session-memory

انواع رویداد

Hookها برای دریافت هر کنش در یک خانواده، در یک کلید مشخص از این جدول یا در نام خام خانواده (command، session، agent، gateway، message) مشترک می‌شوند. هستهٔ OpenClaw هیچ رویداد دیگری منتشر نمی‌کند؛ بنابراین هر نام دیگری تقریباً همیشه یک غلط تایپی است که Hook را بی‌سروصدا غیرفعال باقی می‌گذارد (تنها Pluginی که یک رویداد سفارشی منتشر کند می‌تواند آن را فعال کند). بارگذار Hook برای چنین نام‌هایی هشدار ثبت می‌کند (برای مثال command:nwe) و openclaw hooks info <name> آن‌ها را علامت‌گذاری می‌کند؛ بنابراین Hookی که هرگز اجرا نمی‌شود، قابل عیب‌یابی است.

نوشتن Hookها

ساختار Hook

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

my-hook/├── HOOK.md          # فراداده + مستندات└── handler.ts       # پیاده‌سازی کنترل‌گر

فایل کنترل‌گر می‌تواند handler.ts، handler.js، index.ts یا index.js باشد.

قالب HOOK.md

---name: my-hookdescription: "توضیحی کوتاه دربارهٔ کاری که این Hook انجام می‌دهد"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Hook من مستندات تفصیلی در اینجا قرار می‌گیرد.

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

پیاده‌سازی کنترل‌گر

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] فرمان جدید فعال شد`);  // منطق شما در اینجا   // در صورت تمایل، در سطوح پاسخ‌پذیر پاسخی ارسال کنید  event.messages.push("Hook اجرا شد!");}; export default handler;

هر رویداد شامل این موارد است: type، action، sessionKey، timestamp، messages و context (داده‌های مختص رویداد). زمینه‌های Hook نوع‌دار Plugin برای Hookهای عامل و ابزار می‌توانند trace را نیز شامل شوند؛ یک زمینهٔ ردیابی تشخیصی فقط‌خواندنی و سازگار با W3C که Pluginها می‌توانند برای هم‌بستگی OTEL به گزارش‌های ساخت‌یافته منتقل کنند.

رشته‌هایی که به event.messages افزوده می‌شوند، تنها برای command:new و command:reset به چت بازگردانده می‌شوند (به‌عنوان پاسخ به گفت‌وگوی مبدأ مسیریابی می‌شوند) و برای session:compact:before / session:compact:after (به‌عنوان اعلان‌های وضعیت Compaction ارسال می‌شوند). همهٔ رویدادهای دیگر، از جمله command:stop، message:*، agent:bootstrap، session:patch و gateway:*، پیام‌های افزوده‌شده را نادیده می‌گیرند.

نکات برجستهٔ زمینهٔ رویداد

رویدادهای فرمان (command:new، command:reset): context.sessionEntry، context.previousSessionEntry، context.commandSource، context.senderId، context.workspaceDir، context.cfg.

رویدادهای فرمان (command:stop): context.sessionEntry، context.sessionId، context.commandSource، context.senderId.

رویدادهای پیام (message:received): context.from، context.content، context.channelId، context.media (اطلاعات مرتب‌شدهٔ پیوست‌های مرحله‌بندی‌شده)، context.originalMedia به‌همراه context.mediaStagingPending هنگامی که رسانهٔ راه‌دور هنوز به‌صورت محلی مرحله‌بندی نشده است، و context.metadata (داده‌های مختص ارائه‌دهنده شامل senderId، senderName، guildId). context.content برای پیام‌های فرمان‌مانند، بدنهٔ فرمان غیرخالی را ترجیح می‌دهد، سپس به بدنهٔ خام ورودی و بدنهٔ عمومی بازمی‌گردد؛ این مورد شامل غنی‌سازی‌های مختص عامل مانند تاریخچهٔ رشته یا خلاصه‌های پیوند نمی‌شود. نام‌های مستعار قدیمی رسانه در metadata منسوخ شده‌اند.

رویدادهای پیام (message:sent): context.to، context.content، context.success، context.channelId، به‌همراه context.error هنگام ناموفق‌بودن ارسال.

رویدادهای پیام (message:transcribed): context.transcript، context.from، context.channelId و context.media. context.mediaPath و context.mediaType همچنان نام‌های مستعار منسوخ‌شده برای نخستین مورد هستند.

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

رویدادهای راه‌اندازی (agent:bootstrap): context.bootstrapFiles (آرایهٔ تغییرپذیر)، context.agentId.

رویدادهای وصلهٔ نشست (session:patch): context.sessionEntry، context.patch (فقط فیلدهای تغییرکرده)، context.cfg. فقط کلاینت‌های دارای امتیاز می‌توانند رویدادهای وصله را فعال کنند؛ زمینه یک کپی است، بنابراین کنترل‌گرها نمی‌توانند ورودی زندهٔ نشست را تغییر دهند.

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

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

رویدادهای چرخهٔ حیات Gateway: gateway:shutdown شامل reason و restartExpectedMs است و هنگام آغاز خاموش‌شدن Gateway فعال می‌شود. gateway:pre-restart همان زمینه را شامل می‌شود، اما تنها زمانی فعال می‌شود که خاموش‌شدن بخشی از یک راه‌اندازی مجدد مورد انتظار باشد و مقدار متناهی restartExpectedMs ارائه شود. هنگام خاموش‌شدن، انتظار برای هر Hook چرخهٔ حیات به‌صورت بهترین تلاش و محدود انجام می‌شود تا اگر کنترل‌گری متوقف شد، خاموش‌شدن ادامه یابد. بودجهٔ انتظار پیش‌فرض برای gateway:shutdown برابر 5 ثانیه و برای gateway:pre-restart برابر 10 ثانیه است.

برای اعلان‌های کوتاه راه‌اندازی مجدد، درحالی‌که کانال‌ها همچنان در دسترس‌اند، از 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 تقریباً تا ${restartInSeconds} ثانیهٔ دیگر راه‌اندازی مجدد می‌شود (${event.context.reason}). اکنون نقطهٔ بازرسی ایجاد کنید.`,  ]);}

بین رویداد gateway:shutdown (یا gateway:pre-restart) و ادامهٔ توالی خاموش‌شدن، Gateway همچنین برای هر نشستی که هنگام توقف فرایند همچنان فعال بوده است، یک Hook نوع‌دار Plugin به نام session_end فعال می‌کند. مقدار reason این رویداد برای توقف ساده با SIGTERM/SIGINT برابر shutdown و هنگامی که بسته‌شدن به‌عنوان بخشی از یک راه‌اندازی مجدد مورد انتظار زمان‌بندی شده باشد برابر restart است. این تخلیه محدود است تا یک کنترل‌گر کند session_end نتواند خروج فرایند را مسدود کند، و نشست‌هایی که پیش‌تر از طریق جایگزینی / بازنشانی / حذف / Compaction نهایی شده‌اند، برای جلوگیری از فعال‌شدن دوباره نادیده گرفته می‌شوند.

شناسایی Hook

Hookها از چهار منبع شناسایی می‌شوند:

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

هوک‌های فضای‌کار می‌توانند نام‌های هوک جدیدی اضافه کنند، اما نمی‌توانند هوک‌های هم‌نامِ همراه، مدیریت‌شده یا ارائه‌شده توسط Plugin را بازنویسی کنند.

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

بسته‌های هوک

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

openclaw plugins install <path-or-spec>

مشخصات Npm فقط به رجیستری محدود می‌شوند (نام بسته + نسخه دقیق اختیاری یا dist-tag). مشخصات Git/URL/file و بازه‌های semver رد می‌شوند. فرمان‌های قدیمی‌تر openclaw hooks install و openclaw hooks update نام‌های مستعار منسوخ‌شده برای openclaw plugins install / openclaw plugins update هستند.

هوک‌های همراه

برای فعال‌کردن هر هوک همراه:

openclaw hooks enable <hook-name>

جزئیات session-memory

آخرین پیام‌های کاربر/دستیار را استخراج می‌کند (پیش‌فرض 15، قابل‌پیکربندی با hooks.internal.entries.session-memory.messages) و با استفاده از تاریخ محلی میزبان در <workspace>/memory/YYYY-MM-DD-HHMM.md ذخیره می‌کند. ثبت حافظه در پس‌زمینه اجرا می‌شود تا تأییدهای /new و /reset به‌دلیل خواندن رونوشت یا تولید اختیاری نامک به تأخیر نیفتند. برای تولید نامک‌های توصیفی نام فایل، hooks.internal.entries.session-memory.llmSlug: true را تنظیم کنید و در صورت تمایل، hooks.internal.entries.session-memory.model را روی یک نام مستعار پیکربندی‌شده مانند sonnet، یک شناسه مدل ساده در ارائه‌دهنده پیش‌فرض عامل، یا یک ارجاع provider/model تنظیم کنید. وقتی model حذف شده باشد، تولید نامک از مدل پیش‌فرض عامل استفاده می‌کند و در صورت دردسترس‌نبودن، به نامک‌های برچسب زمانی برمی‌گردد. مستلزم پیکربندی workspace.dir است.

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

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

patterns و files به‌عنوان نام‌های مستعار paths پذیرفته می‌شوند. مسیرها نسبت به فضای‌کار تفکیک می‌شوند و باید درون آن باقی بمانند. فقط نام‌های پایه راه‌اندازی اولیه شناخته‌شده بارگذاری می‌شوند (AGENTS.md، SOUL.md، TOOLS.md، IDENTITY.md، USER.md، HEARTBEAT.md، BOOTSTRAP.md، MEMORY.md).

جزئیات command-logger

هر فرمان اسلش را به‌صورت یک خط JSON (برچسب زمانی، کنش، کلید نشست، شناسه فرستنده، منبع) در ~/.openclaw/logs/commands.log ثبت می‌کند.

جزئیات compaction-notifier

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

جزئیات boot-md

در زمان راه‌اندازی Gateway، برای هر محدوده عامل پیکربندی‌شده، اگر فایل در فضای‌کار تفکیک‌شده آن عامل وجود داشته باشد، BOOT.md را اجرا می‌کند.

هوک‌های Plugin

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

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

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

پیکربندی

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

مقادیر محیطی مختص هر هوک، بررسی‌های صلاحیت requires.env هوک را برآورده می‌کنند (در کنار محیط فرایند) و کنترل‌گرها می‌توانند آن‌ها را از ورودی پیکربندی هوک خود بخوانند:

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

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

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

مرجع CLI

# فهرست‌کردن همه هوک‌ها (--eligible، --verbose یا --json را اضافه کنید)openclaw hooks list # نمایش اطلاعات تفصیلی درباره یک هوکopenclaw hooks info <hook-name> # نمایش خلاصه صلاحیتopenclaw hooks check # فعال/غیرفعال‌کردنopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

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

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

عیب‌یابی

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

# بررسی ساختار دایرکتوریls -la ~/.openclaw/hooks/my-hook/# باید نمایش دهد: HOOK.md، handler.ts # فهرست‌کردن همه هوک‌های کشف‌شدهopenclaw hooks list

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

openclaw hooks info my-hook

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

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

1. بررسی کنید هوک فعال است: openclaw hooks list
2. فرایند Gateway را مجدداً راه‌اندازی کنید تا هوک‌ها دوباره بارگذاری شوند.
3. لاگ‌های Gateway را بررسی کنید: openclaw logs --follow | grep -i hook

مرتبط

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