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

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

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

## شروع سریع

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

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

زبانه 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 از دو مسیر مدل جداگانه استفاده می‌کند:

| مرحله            | داده ارسالی                                                 | مسیر مدل                                                       |
| ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------- |
| مشاهده          | حداکثر 16 قاب 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,
        },
      },
    },
  },
}
```

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

| کلید                       | پیش‌فرض | بازه یا مقادیر         | رفتار                                                                                     |
| ------------------------- | ------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| `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`، 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 را ثبت می‌کند:

| روش                | پارامترها               | دامنه            | نتیجه                                                                   |
| --------------------- | ------------------------ | ---------------- | ------------------------------------------------------------------------ |
| `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.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` را شامل شود.

### ضبط خطا گزارش می‌کند

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