日誌外掛

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

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

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

開始之前

你需要：

• 一個已連線且公開 screen.snapshot 或 logbook.snapshot 的節點。macOS app 節點需要「螢幕錄製」權限。無頭 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.5",        },      },    },  },}

如果你使用 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。如果缺少該命令，請參閱節點疑難排解。

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

運作方式

1. 擷取：每隔 captureIntervalSeconds（預設 30 秒），Logbook 會叫用所選節點的擷取命令，並儲存縮放後的 JPEG 影格。連續相同的影格會標記為閒置，並從分析中排除。
2. 觀察：分析視窗（預設 15 分鐘）結束後，外掛會最多取樣 16 個活動影格並將其傳送到視覺模型，模型會回傳帶有時間戳記的活動觀察（「VS Code：正在編輯 store.ts，修正型別錯誤」）。超過兩分鐘的擷取中斷或本機午夜也會關閉目前視窗。
3. 合成：觀察加上最近 45 分鐘的既有卡片，會被修訂為時間軸卡片（每張 10-60 分鐘），包含標題、摘要、分類、主要 app，以及任何簡短的分心事項。
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.5",          retentionDays: 14,        },      },    },  },}

所有 Logbook 設定鍵都是選用的。數值會四捨五入為整數，並限制在支援範圍內。

沒有 nodeId 時，Logbook 會優先使用公開 screen.snapshot 的已連線 app 節點，然後退回到公開 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 仍會套用。

儀表板分頁

• 時間軸：每個活動的可展開卡片，包含分類顏色、主要 app、分心事項晶片，以及快照關鍵影格。
• 一天概覽：專注比例、分類明細、熱門 app。
• 每日站會：將昨天加上今天轉成可直接貼上的更新。
• 詢問你的一天：從追蹤的時間軸回答自然語言問題（「我什麼時候審查 gateway PR？」）。
• 立即分析：立即關閉目前擷取視窗，而不是等待分析間隔。

閘道方法

Logbook 會註冊這些閘道 RPC 方法：

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

隱私注意事項

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

疑難排解

Logbook 分頁遺失

檢查三個關卡：

1. openclaw plugins list --enabled 包含 logbook。
2. 閘道已在外掛或 allowlist 變更後重新啟動。
3. 控制 UI 連線具有 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 harness
• 媒體理解
• 節點
• 節點疑難排解
• 控制 UI