日誌簿外掛

Logbook 外掛會將螢幕活動轉換成自動工作日誌。它會定期從已配對的節點擷取螢幕快照，將其摘要為附有時間戳記的觀察紀錄，並在控制介面中建立時間軸卡片。它也能產生每日站立會議紀錄，並回答關於所追蹤日期的問題。

OpenClaw 所擁有的狀態會保留在閘道的 <state-dir>/logbook/ 下，但模型處理不一定在本機進行。取樣的螢幕截圖會傳送至已設定的視覺路由；觀察紀錄與時間軸文字則會傳送至預設代理模型。如果螢幕內容和衍生的活動文字都必須留在機器上，請在這兩個階段都使用本機模型路由。

Logbook 已隨附提供，但預設停用。啟用此外掛會讓閘道選擇加入螢幕擷取，因為 captureEnabled 預設為 true。

開始之前

你需要：

• 一個已連線且公開 screen.snapshot 或 logbook.snapshot 的節點。macOS 應用程式節點需要 Screen Recording 權限。無介面的 macOS 節點主機（openclaw node host run）會取得由外掛提供的 logbook.snapshot 命令，其底層使用系統的 screencapture 工具。
• 已啟用並完成驗證的隨附 Codex 外掛。Codex 目前提供 Logbook 所需的結構化影像擷取合約。使用 openclaw models auth login --provider openai 登入；其他驗證方式請參閱 Codex 執行框架。
• 可正常運作的預設代理模型。Logbook 會在視覺處理完成後，使用它合成卡片、站立會議紀錄及當日問答。

快速開始

啟用 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。變更外掛設定後，請重新啟動閘道，然後檢查註冊項目並開啟儀表板：

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

節點說明中必須包含 screen.snapshot 或 logbook.snapshot。無介面節點只會在外掛啟用後公布 logbook.snapshot。如果缺少該命令，請參閱節點疑難排解。

Logbook 分頁只會在外掛已啟用，且控制介面工作階段具備 operator.write 時顯示。狀態列應顯示 正在擷取，且沒有錯誤。分析視窗關閉時會出現時間軸卡片；或者，你也可以在擷取到活動後選取 立即分析。

運作方式

1. 擷取：每隔 captureIntervalSeconds（預設 30 秒），Logbook 會呼叫所選節點的擷取命令，並儲存一個縮放後的 JPEG 畫格。連續相同的畫格會標記為閒置，並從分析中排除。
2. 觀察：當分析視窗（預設 15 分鐘）經過後，外掛最多會取樣 16 個活動畫格並傳送至視覺模型，由模型傳回附有時間戳記的活動觀察紀錄（「VS Code：正在編輯 store.ts，修正型別錯誤」）。擷取中斷超過兩分鐘或到達本機午夜時，也會關閉目前的視窗。
3. 合成：觀察紀錄連同最近 45 分鐘的既有卡片，會重新整理為時間軸卡片（每張涵蓋 10 至 60 分鐘），其中包含標題、摘要、類別、主要應用程式，以及任何短暫的分心活動。
4. 清除：早於 retentionDays（預設 14）的畫格會被刪除。卡片、觀察紀錄和快取的站立會議紀錄則會保留。

日期邊界和時間軸時鐘使用閘道的本機時區，而非瀏覽器的時區。畫格和 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 會優先選擇公開 screen.snapshot 的已連線應用程式節點，然後才改用公開 logbook.snapshot 的無介面節點。在未固定節點的設定中，失敗的節點會輪替至其他符合資格的節點之後。儀表板的暫停切換僅適用於目前工作階段，並會在閘道重新啟動時重設；若要持久停止，請使用 captureEnabled: false。

視覺模型選擇

Logbook 會依照以下順序解析觀察模型：

1. plugins.entries.logbook.config.visionModel
2. tools.media.image.models 下第一個具備影像能力的 Codex 項目
3. tools.media.models 下第一個具備影像能力的 Codex 項目

其他媒體提供者會被略過，因為它們目前未公開 Logbook 所需的結構化擷取合約。設定 tools.media.image.enabled: false 會停用借用的媒體預設值，但明確設定的 Logbook visionModel 仍會套用。

儀表板分頁

• 時間軸：每項活動都有可展開的卡片，其中包含類別色彩、主要應用程式、分心活動標籤和快照關鍵畫格。
• 當日概覽：專注比例、類別細分、最常使用的應用程式。
• 每日站立會議紀錄：將昨天和今天的內容轉換為可直接貼上的更新。
• 詢問當日活動：根據追蹤的時間軸回答自然語言問題（「我何時審查了閘道 PR？」）。
• 立即分析：立即關閉目前的擷取視窗，而不等待分析間隔。

閘道方法

Logbook 會註冊以下閘道 RPC 方法：

讀取方法會傳回操作狀態或衍生文字。原始螢幕截圖像素、會產生模型費用的動作及執行階段變更都需要 operator.write。控制介面分頁也需要 operator.write，因為它會公開這些動作和原始畫格預覽；唯讀用戶端仍可直接呼叫衍生文字方法。

隱私權注意事項

• 快照可能包含螢幕上的任何內容，包括機密資料。除了作為取樣輸入傳送至已設定的觀察模型外，畫格絕不會離開機器。
• 在卡片合成、產生站立會議紀錄或問答期間，觀察紀錄、近期卡片和問題可能會透過預設代理模型離開機器。請將提供者的資料處理政策套用至兩條模型路由。
• 需要完全在本機執行的管線時，請同時為結構化觀察模型和預設代理模型使用本機路由。
• 畫格、時間軸資料庫和暫存擷取內容會以僅擁有者可存取的檔案權限寫入。
• 將 screen.snapshot 加入 gateway.nodes.denyCommands 是螢幕擷取的終止開關：它會同時封鎖應用程式節點擷取和 Logbook 自己的 logbook.snapshot 命令。
• 設定 tools.media.image.enabled: false 也會阻止 Logbook 借用媒體影像模型進行分析；此時只會使用外掛設定中明確指定的 visionModel。

疑難排解

缺少 Logbook 分頁

請檢查以下三個條件：

1. openclaw plugins list --enabled 包含 logbook。
2. 變更外掛或允許清單後，閘道已重新啟動。
3. 控制介面連線具備 operator.write；唯讀工作階段不會收到互動式分頁描述項。

如果已設定 plugins.allow，建議的設定必須同時包含 logbook 和 codex。

擷取回報錯誤

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

• 確認節點有提供 screen.snapshot 或 logbook.snapshot。
• 在執行擷取的 Mac 上授予螢幕錄製權限。
• 如果已設定 nodeId，請確認其與節點 ID 或顯示名稱相符。
• 檢查 gateway.nodes.denyCommands 不包含 screen.snapshot。

連續失敗三次後，Logbook 會暫停十個擷取週期，然後重試。未固定節點的設定可以切換至另一個符合條件的節點。

擷取成功但未出現卡片

• 缺少模型狀態表示找不到相容的結構化視覺路由。請啟用 Codex 外掛並完成驗證，或設定有效且明確的 visionModel。缺少模型時，擷取的畫面格會保持待處理狀態，並可在修正設定後進行分析。
• 等待 analysisIntervalMinutes，或在擷取到活動後選取 立即分析。
• 連續相同的畫面格會被視為閒置證據，不會進入分析批次。測試前請變更螢幕上的可見內容。
• 如果最新批次顯示錯誤，請修正模型或驗證問題，然後選取 立即分析。為避免模型費用重複產生，失敗的批次只會在執行該明確操作時重試。

相關內容

• 管理外掛
• Codex 執行框架
• 媒體理解
• 節點
• 節點疑難排解
• 控制介面