Plugin دفتر وقایع

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

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

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 قرارداد ساختاریافته استخراج تصویر موردنیاز Logbook را فراهم می‌کند. با openclaw models auth login --provider openai وارد شوید؛ برای سایر مسیرهای احراز هویت، چارچوب Codex را ببینید.
• یک مدل پیش‌فرض عامل که به‌درستی کار کند. Logbook پس از مرحله بینایی، از آن برای ساخت کارت‌ها، یادداشت‌های جلسه هماهنگی و پرسش‌وپاسخ روز استفاده می‌کند.

شروع سریع

Pluginهای Codex و Logbook را فعال کنید:

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 را ببینید.

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

نحوه کار

1. تصویربرداری: هر captureIntervalSeconds (پیش‌فرض 30s)، Logbook فرمان تصویربرداری Node انتخاب‌شده را فراخوانی و یک قاب JPEG مقیاس‌شده ذخیره می‌کند. قاب‌های متوالی یکسان به‌عنوان بی‌فعالیت علامت‌گذاری و از تحلیل کنار گذاشته می‌شوند.
2. مشاهده: پس از سپری‌شدن یک پنجره تحلیل (پیش‌فرض 15 دقیقه)، Plugin از حداکثر 16 قاب فعال نمونه‌برداری می‌کند و آن‌ها را به مدل بینایی می‌فرستد؛ مدل مشاهدات فعالیت دارای مهر زمانی را برمی‌گرداند («VS Code: ویرایش store.ts، رفع یک خطای نوع»). وقفه تصویربرداری طولانی‌تر از دو دقیقه یا نیمه‌شب محلی نیز پنجره جاری را می‌بندد.
3. ترکیب: مشاهدات به‌همراه 45 دقیقه پایانی کارت‌های موجود، به کارت‌های خط زمانی (هرکدام 10-60 دقیقه) با عنوان، خلاصه، دسته‌بندی، برنامه اصلی و هر حواس‌پرتی کوتاه تبدیل و بازبینی می‌شوند.
4. پاک‌سازی: قاب‌های قدیمی‌تر از retentionDays (پیش‌فرض 14) حذف می‌شوند. کارت‌ها، مشاهدات و یادداشت‌های جلسه هماهنگی ذخیره‌شده در حافظه نهان نگه داشته می‌شوند.

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

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

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,        },      },    },  },}

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

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

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

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

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

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

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

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

روش‌های Gateway

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

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

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

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

عیب‌یابی

زبانه Logbook وجود ندارد

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

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

• تأیید کنید که نود screen.snapshot یا logbook.snapshot را ارائه می‌کند.
• مجوز Screen Recording را در Mac ضبط‌کننده اعطا کنید.
• اگر nodeId پیکربندی شده است، تأیید کنید که با شناسه نود یا نام نمایش مطابقت دارد.
• بررسی کنید که gateway.nodes.commands.deny شامل screen.snapshot نباشد.

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

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

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

مرتبط

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