هوک‌ها

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

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

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

Hooks همچنین می‌توانند داخل Pluginها بسته‌بندی شوند. openclaw hooks list هم hooks مستقل و هم hooks مدیریت‌شده توسط 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

نوع‌های رویداد

نوشتن hooks

ساختار hook

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

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 message to user  event.messages.push("Hook executed!");}; export default handler;

هر رویداد شامل این موارد است: type، action، sessionKey، timestamp، messages (برای ارسال به کاربر به آن push کنید)، و context (داده‌های مخصوص رویداد). contextهای hook مربوط به agent و tool plugin همچنین می‌توانند trace را شامل شوند؛ یک context رهگیری تشخیصی فقط‌خواندنی سازگار با W3C که Pluginها ممکن است برای هم‌بستگی OTEL آن را به لاگ‌های ساختاریافته بدهند.

نکات برجسته 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 برای پیام‌های شبیه دستور، بدنه دستور غیرخالی را ترجیح می‌دهد، سپس به بدنه خام ورودی و بدنه عمومی برمی‌گردد؛ شامل غنی‌سازی‌های فقط مخصوص agent مانند تاریخچه 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 (بدنه نهایی غنی‌شده)، context.from، context.channelId.

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

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

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

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

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

بین رویداد gateway:shutdown (یا gateway:pre-restart) و باقی دنباله خاموشی، gateway همچنین برای هر session که هنگام توقف فرایند هنوز فعال بوده، یک hook نوع‌دار Plugin به نام session_end اجرا می‌کند. مقدار reason رویداد برای توقف ساده SIGTERM/SIGINT برابر shutdown و وقتی بستن به‌عنوان بخشی از یک restart موردانتظار زمان‌بندی شده باشد برابر restart است. این drain محدود است تا یک handler کند session_end نتواند خروج فرایند را مسدود کند، و sessionهایی که قبلا از طریق replace / reset / delete / compaction نهایی شده‌اند برای جلوگیری از اجرای دوباره رد می‌شوند.

کشف hook

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

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

Hooks فضای کاری می‌توانند نام‌های hook جدید اضافه کنند، اما نمی‌توانند hooks بسته‌بندی‌شده، مدیریت‌شده، یا ارائه‌شده توسط Plugin را که همان نام را دارند override کنند.

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

بسته‌های hook

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

openclaw plugins install <path-or-spec>

مشخصه‌های Npm فقط registry هستند (نام پکیج + نسخه دقیق اختیاری یا dist-tag). مشخصه‌های Git/URL/file و بازه‌های semver رد می‌شوند.

hooks بسته‌بندی‌شده

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

openclaw hooks enable <hook-name>

جزئیات session-memory

آخرین 15 پیام کاربر/assistant را استخراج می‌کند و با استفاده از تاریخ محلی host در <workspace>/memory/YYYY-MM-DD-HHMM.md ذخیره می‌کند. ثبت memory در پس‌زمینه اجرا می‌شود تا acknowledgementهای /new و /reset به‌خاطر خواندن transcript یا تولید اختیاری 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"]        }      }    }  }}

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

جزئیات command-logger

هر دستور slash را در ~/.openclaw/logs/commands.log لاگ می‌کند.

جزئیات compaction-notifier

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

جزئیات boot-md

هنگام شروع gateway، BOOT.md را از workspace فعال اجرا می‌کند.

hooks Plugin

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

برای مرجع کامل hookهای Plugin، hooks Plugin را ببینید.

پیکربندی

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

متغیرهای محیطی برای هر hook:

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

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

{  "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ها را سریع نگه دارید. هوک‌ها هنگام پردازش فرمان اجرا می‌شوند. کارهای سنگین را به‌صورت fire-and-forget با void processInBackground(event) اجرا کنید.
• خطاها را با وقار مدیریت کنید. عملیات پرریسک را در try/catch بپیچید؛ خطا پرتاب نکنید تا 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 درون‌فرایندی
• پیکربندی