---
read_when:
    - شما یک خط زمانی به سبک Dayflow از روزتان در رابط کاربری کنترل می‌خواهید
    - شما در حال فعال‌سازی یا پیکربندی Plugin همراه Logbook هستید
    - می‌خواهید خلاصه‌های جلسهٔ روزانه یا مرور رویدادهای روز بر اساس فعالیت‌های صفحه‌نمایش تهیه شوند
summary: دفترچهٔ کار خودکار اختیاری که از تصاویر دوره‌ای صفحه‌نمایش ساخته می‌شود
title: Plugin دفتر ثبت وقایع
x-i18n:
    generated_at: "2026-07-12T10:24:59Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: a3ea1d40d62041417d047fbaf6b02aeb86e76314b8f620f7b9939e2e0c3b9f7e
    source_path: plugins/logbook.md
    workflow: 16
---

Plugin گزارش‌کار، فعالیت صفحه‌نمایش را به یک دفترچهٔ خودکار فعالیت‌های کاری تبدیل می‌کند. این Plugin
به‌صورت دوره‌ای از صفحه‌نمایش یک Node جفت‌شده عکس می‌گیرد، آن‌ها را به
مشاهدات دارای مُهر زمانی خلاصه می‌کند و کارت‌های خط زمانی را در
[رابط کنترل](/fa/web/control-ui) می‌سازد. همچنین می‌تواند یادداشت‌های روزانهٔ جلسهٔ هماهنگی تولید کند و
به پرسش‌های مربوط به یک روز ثبت‌شده پاسخ دهد.

وضعیت متعلق به 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](/fa/plugins/codex-harness) را ببینید.
- یک مدل پیش‌فرض عامل که به‌درستی کار کند. گزارش‌کار پس از مرحلهٔ بینایی، از آن برای ساخت کارت‌ها، یادداشت‌های
  جلسهٔ هماهنگی و پرسش‌وپاسخ روزانه استفاده می‌کند.

## شروع سریع

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

```bash
openclaw plugins enable codex
openclaw plugins enable logbook
```

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

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

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

```bash
openclaw gateway restart
openclaw plugins inspect logbook --runtime --json
openclaw nodes status --connected
openclaw nodes describe --node <idOrNameOrIp>
openclaw dashboard
```

شرح Node باید شامل `screen.snapshot` یا `logbook.snapshot` باشد.
Nodeهای بدون رابط گرافیکی فقط پس از فعال‌شدن Plugin، `logbook.snapshot` را اعلام می‌کنند.
اگر فرمان وجود ندارد، [عیب‌یابی Node](/fa/nodes/troubleshooting) را ببینید.

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

## نحوهٔ کار

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

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

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

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

| مرحله | دادهٔ ارسالی | مسیر مدل |
| ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------- |
| مشاهده | حداکثر ۱۶ قاب JPEG نمونه‌برداری‌شده به‌همراه زمان ضبط آن‌ها | `visionModel`، یا یک ورودی سازگار Codex که از `tools.media` به امانت گرفته شده است |
| ترکیب کارت‌ها | مشاهدات دارای مُهر زمانی و کارت‌های اخیر خط زمانی | مدل پیش‌فرض عامل از طریق زمان اجرای LLM مربوط به Plugin |
| تولید یادداشت جلسهٔ هماهنگی | کارت‌های روز انتخاب‌شده و روز قبل | مدل پیش‌فرض عامل از طریق زمان اجرای LLM مربوط به Plugin |
| پرسش دربارهٔ روز | پرسش، کارت‌های روز انتخاب‌شده و مشاهدات اخیر | مدل پیش‌فرض عامل از طریق زمان اجرای LLM مربوط به Plugin |

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

## پیکربندی

```json5
{
  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,
        },
      },
    },
  },
}
```

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

| کلید | پیش‌فرض | بازه یا مقادیر | رفتار |
| ------------------------- | ------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| `captureEnabled` | `true` | بولی | کلید اصلی پایدار برای تصاویر جدید؛ هنگامی که `false` باشد، خط زمانی همچنان در دسترس است |
| `captureIntervalSeconds` | `30` | `5`-`600` | تأخیر میان تلاش‌های ضبط |
| `analysisIntervalMinutes` | `15` | `3`-`120` | پنجرهٔ هدف مشاهده؛ وقفه‌ها و نیمه‌شب می‌توانند آن را زودتر ببندند |
| `nodeId` | تنظیم‌نشده | شناسهٔ Node یا نام نمایشی | ضبط را به یک Node متصل محدود می‌کند؛ تطبیق به بزرگی و کوچکی حروف حساس نیست |
| `screenIndex` | `0` | `0`-`16` | نمایهٔ نمایشگر با مبدأ صفر |
| `maxWidth` | `1440` | `480`-`3840` | سقف درخواستی اندازهٔ ضبط؛ macOS بدون رابط گرافیکی آن را روی بزرگ‌ترین بُعد اعمال می‌کند |
| `visionModel` | تنظیم‌نشده | `provider/model` | مسیر ساخت‌یافتهٔ صریح؛ ارجاع‌های نادرست تحلیل را متوقف می‌کنند و ارائه‌دهندگان پشتیبانی‌نشده باعث شکست دسته‌ها می‌شوند |
| `retentionDays` | `14` | `1`-`365` | قاب‌های قدیمی را حذف می‌کند؛ کارت‌ها، مشاهدات و یادداشت‌های جلسهٔ هماهنگی باقی می‌مانند |

بدون `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 ثبت می‌کند:

| روش | پارامترها | دامنه | نتیجه |
| --------------------- | ------------------------ | ---------------- | ------------------------------------------------------------------------ |
| `logbook.status` | هیچ‌کدام | `operator.read` | وضعیت ضبط، تحلیل، مدل، Node، روز Gateway و منطقهٔ زمانی Gateway |
| `logbook.days` | هیچ‌کدام | `operator.read` | روزهای دارای تعداد کارت‌های خط زمانی و محدوده‌های زمانی کارت |
| `logbook.timeline` | `{ day?: "YYYY-MM-DD" }` | `operator.read` | کارت‌های استخراج‌شده و آمار روز؛ پیش‌فرض، روز جاری Gateway است |
| `logbook.frames` | `{ startMs, endMs }` | `operator.write` | فرادادهٔ قاب‌ها در بازهٔ درخواستی بر حسب میلی‌ثانیه از مبدأ |
| `logbook.frame` | `{ frameId }` | `operator.write` | یک قاب خام JPEG به‌صورت base64 |
| `logbook.standup` | `{ day?, refresh? }` | `operator.write` | متن جلسهٔ هماهنگی ذخیره‌شده در حافظهٔ نهان یا بازتولیدشده برای یک روز |
| `logbook.ask` | `{ day?, question }` | `operator.write` | پاسخ مبتنی بر خط زمانی برای یک روز |
| `logbook.capture.set` | `{ paused }` | `operator.write` | وضعیت توقف موقت مخصوص نشست و وضعیت به‌روزشده |
| `logbook.analyze.now` | هیچ‌کدام | `operator.write` | تحلیل در انتظار را آغاز می‌کند یا دلیل آغازنشدن آن را برمی‌گرداند |

روش‌های خواندن، وضعیت عملیاتی یا متن استخراج‌شده را برمی‌گردانند. پیکسل‌های خام
تصاویر صفحه‌نمایش، عملیات دارای هزینهٔ مدل و تغییرات زمان اجرا به
`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` را شامل شود.

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

```bash
openclaw nodes status --connected
openclaw 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ها](/fa/plugins/manage-plugins)
- [محیط اجرایی Codex](/fa/plugins/codex-harness)
- [درک رسانه](/fa/nodes/media-understanding)
- [Nodeها](/fa/nodes)
- [عیب‌یابی Node](/fa/nodes/troubleshooting)
- [رابط کاربری کنترل](/fa/web/control-ui)