跳轉到主要內容
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 codex
openclaw plugins enable logbook
設定明確的視覺模型，以確保啟動行為可預期： 
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
      logbook: {
        enabled: true,
        config: {
          visionModel: "codex/gpt-5.5",
        },
      },
    },
  },
}
如果你使用 plugins.allow，請同時包含 codex 和 logbook。變更外掛設定後重新啟動閘道，接著檢查註冊項目並開啟儀表板： 
openclaw gateway restart
openclaw plugins inspect logbook --runtime --json
openclaw nodes status --connected
openclaw 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 使用兩個不同的模型路由：
階段傳送的資料模型路由
觀察最多 16 個取樣 JPEG 影格及其擷取時間visionModel，或相容且借用的 tools.media Codex 項目
合成卡片帶有時間戳記的觀察和近期時間軸卡片透過外掛 LLM 執行階段使用預設代理模型
產生站會內容所選日期和前一天的卡片透過外掛 LLM 執行階段使用預設代理模型
詢問你的一天問題、所選日期的卡片，以及近期觀察透過外掛 LLM 執行階段使用預設代理模型
完整 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 設定鍵都是選用的。數值會四捨五入為整數，並限制在支援範圍內。
鍵預設值範圍或值行為
captureEnabledtrueboolean新快照的持久主開關；為 false 時時間軸仍可使用
captureIntervalSeconds305-600擷取嘗試之間的延遲
analysisIntervalMinutes153-120目標觀察視窗；中斷和午夜可能會讓它提早關閉
nodeId未設定節點 id 或顯示名稱將擷取固定到一個已連線節點；比對不區分大小寫
screenIndex00-16以零為基準的顯示器索引
maxWidth1440480-3840要求的擷取大小上限；無頭 macOS 會套用到最大維度
visionModel未設定provider/model明確的結構化路由；格式錯誤的參照會暫停分析，不支援的提供者會讓批次失敗
retentionDays141-365刪除舊影格；卡片、觀察和站會內容會保留
沒有 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 方法：
方法參數範圍結果
logbook.status無operator.read擷取、分析、模型、節點、閘道日期，以及閘道時區狀態
logbook.days無operator.read含時間軸卡片數量與卡片時間邊界的日期
logbook.timeline{ day?: "YYYY-MM-DD" }operator.read衍生卡片和日期統計；預設為閘道目前日期
logbook.frames{ startMs, endMs }operator.write要求的 epoch 毫秒範圍內的影格中繼資料
logbook.frame{ frameId }operator.write一個以 base64 表示的原始 JPEG 影格
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。控制 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 --connected
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow
  • 確認節點公開 screen.snapshot 或 logbook.snapshot。
  • 在擷取用的 Mac 上授予螢幕錄製權限。
  • 如果已設定 nodeId，請確認它符合節點 ID 或顯示名稱。
  • 檢查 gateway.nodes.denyCommands 未包含 screen.snapshot。
連續失敗三次後，Logbook 會退避十個擷取週期，然後重試。未釘選的設定可以輪換到另一個符合資格的節點。

​
擷取成功但沒有卡片出現

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

​
相關