Plugin دفتر ثبت وقایع

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

وضعیت متعلق به OpenClaw در Gateway و در مسیر <state-dir>/logbook/ باقی می‌ماند، اما پردازش مدل لزوماً محلی نیست. تصاویر نمونه‌برداری‌شدهٔ صفحه‌نمایش به مسیر بینایی پیکربندی‌شده ارسال می‌شوند؛ مشاهدات و متن خط زمانی نیز به مدل پیش‌فرض عامل می‌روند. اگر محتوای صفحه‌نمایش و متن فعالیت استخراج‌شده باید روی دستگاه باقی بمانند، برای هر دو مرحله از مسیرهای مدل محلی استفاده کنید.

گزارش‌کار به‌صورت همراه ارائه می‌شود و به‌طور پیش‌فرض غیرفعال است. فعال‌کردن Plugin باعث می‌شود Gateway از ضبط صفحه‌نمایش استفاده کند، زیرا مقدار پیش‌فرض captureEnabled برابر true است.

پیش از شروع

به موارد زیر نیاز دارید:

• یک Node متصل که screen.snapshot یا logbook.snapshot را ارائه کند. Node برنامهٔ macOS به مجوز Screen Recording نیاز دارد. یک میزبان Node بدون رابط گرافیکی در macOS (openclaw node host run) فرمان logbook.snapshot ارائه‌شده توسط Plugin را دریافت می‌کند که از ابزار سیستمی screencapture استفاده می‌کند.
• Plugin همراه Codex باید فعال و احراز هویت شده باشد. Codex در حال حاضر قرارداد استخراج ساخت‌یافتهٔ تصویر موردنیاز گزارش‌کار را فراهم می‌کند. با openclaw models auth login --provider openai وارد شوید؛ برای مسیرهای دیگر احراز هویت، محیط اجرایی Codex را ببینید.
• یک مدل پیش‌فرض عامل که به‌درستی کار کند. گزارش‌کار پس از مرحلهٔ بینایی، از آن برای ساخت کارت‌ها، یادداشت‌های جلسهٔ هماهنگی و پرسش‌وپاسخ روزانه استفاده می‌کند.

شروع سریع

Pluginهای Codex و گزارش‌کار را فعال کنید:

openclaw plugins enable codexopenclaw plugins enable logbook

برای راه‌اندازی قطعی، یک مدل بینایی صریح پیکربندی کنید:

{  plugins: {    entries: {      codex: {        enabled: true,      },      logbook: {        enabled: true,        config: {          visionModel: "codex/gpt-5.6-sol",        },      },    },  },}

اگر از plugins.allow استفاده می‌کنید، هر دو مورد codex و logbook را در آن قرار دهید. پس از تغییر پیکربندی Plugin، Gateway را راه‌اندازی مجدد کنید، سپس ثبت‌ها را بررسی کرده و داشبورد را باز کنید:

openclaw gateway restartopenclaw plugins inspect logbook --runtime --jsonopenclaw nodes status --connectedopenclaw nodes describe --node <idOrNameOrIp>openclaw dashboard

شرح Node باید شامل screen.snapshot یا logbook.snapshot باشد. Nodeهای بدون رابط گرافیکی فقط پس از فعال‌شدن Plugin، logbook.snapshot را اعلام می‌کنند. اگر فرمان وجود ندارد، عیب‌یابی Node را ببینید.

زبانهٔ گزارش‌کار فقط برای یک Plugin فعال و نشست رابط کنترل با مجوز operator.write نمایان می‌شود. ردیف وضعیت باید در حال ضبط را بدون خطا نشان دهد. پس از بسته‌شدن پنجرهٔ تحلیل، یک کارت خط زمانی ظاهر می‌شود؛ همچنین پس از ثبت فعالیت می‌توانید اکنون تحلیل شود را انتخاب کنید.

نحوهٔ کار

1. ضبط: در هر بازهٔ captureIntervalSeconds (پیش‌فرض ۳۰ ثانیه)، گزارش‌کار فرمان ضبط Node انتخاب‌شده را فراخوانی کرده و یک قاب JPEG با اندازهٔ مقیاس‌شده ذخیره می‌کند. قاب‌های یکسان متوالی به‌عنوان بیکار علامت‌گذاری شده و از تحلیل کنار گذاشته می‌شوند.
2. مشاهده: پس از سپری‌شدن یک پنجرهٔ تحلیل (پیش‌فرض ۱۵ دقیقه)، Plugin حداکثر ۱۶ قاب فعال را نمونه‌برداری کرده و به مدل بینایی می‌فرستد؛ مدل نیز مشاهدات فعالیت دارای مُهر زمانی را برمی‌گرداند («VS Code: ویرایش store.ts، رفع یک خطای نوع»). وقفهٔ ضبط طولانی‌تر از دو دقیقه یا نیمه‌شب محلی نیز پنجرهٔ جاری را می‌بندد.
3. ترکیب: مشاهدات به‌همراه کارت‌های موجودِ ۴۵ دقیقهٔ اخیر به کارت‌های خط زمانی بازنویسی می‌شوند (هرکدام ۱۰ تا ۶۰ دقیقه) که شامل عنوان، خلاصه، دسته، برنامهٔ اصلی و هرگونه حواس‌پرتی کوتاه هستند.
4. پاک‌سازی: قاب‌های قدیمی‌تر از retentionDays (پیش‌فرض ۱۴) حذف می‌شوند. کارت‌ها، مشاهدات و یادداشت‌های جلسهٔ هماهنگی ذخیره‌شده در حافظهٔ نهان نگه داشته می‌شوند.

مرز روزها و ساعت‌های خط زمانی از منطقهٔ زمانی محلی Gateway استفاده می‌کنند، نه منطقهٔ زمانی مرورگر. قاب‌ها و پایگاه‌دادهٔ SQLite خط زمانی در <state-dir>/logbook/ قرار دارند.

جریان مدل و داده

گزارش‌کار از دو مسیر مدل جداگانه استفاده می‌کند:

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

پیکربندی

{  plugins: {    entries: {      codex: {        enabled: true,      },      logbook: {        enabled: true,        config: {          captureEnabled: true,          captureIntervalSeconds: 30,          analysisIntervalMinutes: 15,          nodeId: "my-mac",          screenIndex: 0,          maxWidth: 1440,          visionModel: "codex/gpt-5.6-sol",          retentionDays: 14,        },      },    },  },}

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

بدون nodeId، گزارش‌کار ابتدا یک Node برنامهٔ متصل را که screen.snapshot ارائه می‌کند ترجیح می‌دهد، سپس به یک Node بدون رابط گرافیکی که logbook.snapshot ارائه می‌کند رجوع می‌کند. در تنظیمات بدون تثبیت Node، Node ناموفق به پشت سایر Nodeهای واجد شرایط منتقل می‌شود. کلید توقف موقت داشبورد فقط برای همان نشست است و با راه‌اندازی مجدد Gateway بازنشانی می‌شود؛ برای توقف پایدار از captureEnabled: false استفاده کنید.

انتخاب مدل بینایی

گزارش‌کار مدل مشاهده را به ترتیب زیر تعیین می‌کند:

1. plugins.entries.logbook.config.visionModel
2. نخستین ورودی Codex با قابلیت تصویر در tools.media.image.models
3. نخستین ورودی Codex با قابلیت تصویر در tools.media.models

سایر ارائه‌دهندگان رسانه نادیده گرفته می‌شوند، زیرا در حال حاضر قرارداد استخراج ساخت‌یافتهٔ موردنیاز گزارش‌کار را ارائه نمی‌کنند. تنظیم tools.media.image.enabled: false پیش‌فرض‌های رسانه‌ای به‌امانت‌گرفته‌شده را غیرفعال می‌کند، اما یک visionModel صریح گزارش‌کار همچنان اعمال می‌شود.

زبانهٔ داشبورد

• خط زمانی: کارت‌های بازشدنی برای هر فعالیت با رنگ‌های دسته، برنامهٔ اصلی، برچسب‌های حواس‌پرتی و یک قاب کلیدی از تصویر صفحه.
• نمای کلی روز: نسبت تمرکز، تفکیک دسته‌ها و برنامه‌های پرکاربرد.
• جلسهٔ هماهنگی روزانه: فعالیت‌های دیروز و امروز را به یک گزارش آمادهٔ جای‌گذاری تبدیل می‌کند.
• پرسش دربارهٔ روز: پاسخ به پرسش‌های زبان طبیعی بر پایهٔ خط زمانی ثبت‌شده («چه زمانی PR مربوط به Gateway را بررسی کردم؟»).
• اکنون تحلیل شود: به‌جای انتظار برای بازهٔ تحلیل، پنجرهٔ ضبط جاری را فوراً می‌بندد.

روش‌های Gateway

گزارش‌کار روش‌های RPC زیر را در Gateway ثبت می‌کند:

روش‌های خواندن، وضعیت عملیاتی یا متن استخراج‌شده را برمی‌گردانند. پیکسل‌های خام تصاویر صفحه‌نمایش، عملیات دارای هزینهٔ مدل و تغییرات زمان اجرا به operator.write نیاز دارند. زبانهٔ رابط کنترل نیز به operator.write نیاز دارد، زیرا این عملیات و پیش‌نمایش قاب‌های خام را ارائه می‌کند؛ یک کارخواه فقط‌خواندنی همچنان می‌تواند روش‌های متن استخراج‌شده را مستقیماً فراخوانی کند.

نکات حریم خصوصی

• تصاویر می‌توانند هر چیزی را که روی صفحه است، از جمله اطلاعات محرمانه، در خود داشته باشند. قاب‌ها هرگز دستگاه را ترک نمی‌کنند، مگر به‌عنوان ورودی نمونه‌برداری‌شده برای مدل مشاهدهٔ پیکربندی‌شده.
• مشاهدات، کارت‌های اخیر و پرسش‌ها ممکن است هنگام ترکیب کارت، تولید یادداشت جلسهٔ هماهنگی یا پرسش‌وپاسخ، از طریق مدل پیش‌فرض عامل دستگاه را ترک کنند. سیاست مدیریت دادهٔ ارائه‌دهنده را برای هر دو مسیر مدل اعمال کنید.
• هنگامی که به یک خط لولهٔ کاملاً محلی نیاز دارید، برای هر دو مدل مشاهدهٔ ساخت‌یافته و مدل پیش‌فرض عامل از مسیرهای محلی استفاده کنید.
• قاب‌ها، پایگاه‌دادهٔ خط زمانی و ضبط‌های موقت با مجوز فایل فقط برای مالک نوشته می‌شوند.
• افزودن screen.snapshot به gateway.nodes.denyCommands کلید قطع ضبط صفحه‌نمایش است: این کار هم ضبط Node برنامه و هم فرمان logbook.snapshot خود گزارش‌کار را مسدود می‌کند.
• تنظیم tools.media.image.enabled: false همچنین مانع می‌شود گزارش‌کار مدل‌های تصویر رسانه را برای تحلیل به امانت بگیرد؛ در این حالت فقط یک visionModel صریح در پیکربندی Plugin استفاده می‌شود.

عیب‌یابی

زبانهٔ گزارش‌کار وجود ندارد

هر سه شرط را بررسی کنید:

1. خروجی openclaw plugins list --enabled شامل logbook باشد.
2. Gateway پس از تغییر Plugin یا فهرست مجاز راه‌اندازی مجدد شده باشد.
3. اتصال رابط کنترل دارای operator.write باشد؛ نشست‌های فقط‌خواندنی توصیفگر زبانهٔ تعاملی را دریافت نمی‌کنند.

اگر plugins.allow تنظیم شده باشد، برای پیکربندی پیشنهادی باید هر دو مورد logbook و codex را شامل شود.

ثبت با خطا مواجه می‌شود

openclaw nodes status --connectedopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

• تأیید کنید که Node قابلیت screen.snapshot یا logbook.snapshot را ارائه می‌دهد.
• مجوز ضبط صفحه را در Mac ثبت‌کننده اعطا کنید.
• اگر nodeId پیکربندی شده است، تأیید کنید که با شناسه یا نام نمایشی Node مطابقت دارد.
• بررسی کنید که gateway.nodes.denyCommands شامل screen.snapshot نباشد.

پس از سه شکست متوالی، Logbook به‌مدت ده نوبت ثبت عقب‌نشینی می‌کند و سپس دوباره تلاش می‌کند. راه‌اندازیِ بدون تثبیت روی یک Node می‌تواند به Node واجد شرایط دیگری منتقل شود.

ثبت‌ها موفق‌اند، اما هیچ کارتی ظاهر نمی‌شود

• وضعیت مدل موجود نیست به این معناست که هیچ مسیر سازگارِ بینایی ساخت‌یافته‌ای یافت نشده است. Plugin مربوط به Codex را فعال و احراز هویت کنید، یا یک visionModel صریح و معتبر تنظیم کنید. تا زمانی که مدل موجود نباشد، فریم‌های ثبت‌شده در حالت انتظار باقی می‌مانند و پس از اصلاح پیکربندی قابل تحلیل خواهند بود.
• تا زمان analysisIntervalMinutes منتظر بمانید، یا پس از ثبت فعالیت، اکنون تحلیل کن را انتخاب کنید.
• فریم‌های یکسانِ متوالی شواهد بی‌کاری هستند و وارد دسته‌های تحلیل نمی‌شوند. پیش از آزمایش، محتوای قابل‌مشاهدهٔ صفحه را تغییر دهید.
• اگر جدیدترین دسته خطایی نشان می‌دهد، مشکل مدل یا احراز هویت را برطرف کنید و اکنون تحلیل کن را انتخاب کنید. برای جلوگیری از هزینهٔ تکراری مدل، تلاش مجدد برای دسته‌های ناموفق فقط با این اقدام صریح انجام می‌شود.

مرتبط

• مدیریت Pluginها
• محیط اجرایی Codex
• درک رسانه
• Nodeها
• عیب‌یابی Node
• رابط کاربری کنترل