Logbook 插件

The Logbook plugin turns screen activity into an automatic work journal. It captures periodic screen snapshots from a paired node, summarizes them into timestamped observations, and builds timeline cards in the Control UI. It can also generate daily standup notes and answer questions about a tracked day.

OpenClaw 拥有的状态保留在 Gateway 的 <state-dir>/logbook/ 下，但模型处理不一定在本地进行。采样的截图会发送到已配置的视觉路由；观察结果和时间线文本会发送到默认代理模型。如果屏幕内容和派生的活动文本必须保留在机器上，请为这两个阶段都使用本地模型路由。

Logbook 已内置且默认禁用。启用该插件会使 Gateway 开启屏幕捕获，因为 captureEnabled 默认为 true。

开始之前¶

你需要：

• 一个已连接的节点，该节点暴露 screen.snapshot 或 logbook.snapshot。macOS 应用节点需要屏幕录制权限。无头 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-6-astra",
        },
      },
    },
  },
}

如果使用 plugins.allow，请同时包含 codex 和 logbook。插件配置更改会在默认混合重载模式下自动生效（参见 热重载）。如果 Gateway 处于离线状态，请先启动它，然后检查注册信息并打开仪表盘：

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

节点描述必须包含 screen.snapshot 或 logbook.snapshot。无头节点只有在插件激活后才会通告 logbook.snapshot。如果缺少该命令，请参见 节点故障排查。

Logbook 标签页仅在插件已启用且存在 operator.write Control UI 会话时显示。状态行应显示 正在捕获 且没有错误。当分析窗口关闭时会出现时间线卡片，或者在活动已被捕获后，你可以选择 立即分析。

工作原理¶

1. 捕获：每隔 captureIntervalSeconds（默认 30 秒），Logbook 会调用所选节点的捕获命令，并存储一个缩放后的 JPEG 帧。连续相同的帧会被标记为空闲，并排除在分析之外。
2. 观察：当一个分析窗口（默认 15 分钟）经过后，插件会采样最多 16 个活动帧，并将它们发送到视觉模型，视觉模型会返回带时间戳的活动观察结果（“VS Code：正在编辑 store.ts，修复一个类型错误”）。超过两分钟的捕获间隙或本地午夜也会关闭当前窗口。
3. 综合：观察结果加上最近 45 分钟的现有卡片会被修订为时间线卡片（每张 10-60 分钟），包含标题、摘要、类别、主要应用以及任何简短的分心事项。
4. 修剪：早于 retentionDays（默认 14）的帧会被删除。卡片、观察结果和缓存的站会笔记会保留。

日期边界和时间线时钟使用 Gateway 的本地时区，而不是浏览器的时区。帧和 SQLite 时间线数据库位于 <state-dir>/logbook/ 下。

启动会在捕获开始之前完成存储恢复和修剪。关闭会停止新工作，并等待已准入的数据库和模型操作完成后再关闭存储。SQLite 的打开、查询、事务、维护和关闭都在主机拥有的工作线程中运行。帧读取和修剪共享准入控制，因此预览和分析会在保留策略删除文件之前完成读取。

模型与数据流¶

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-6-astra",
          retentionDays: 14,
        },
      },
    },
  },
}

所有 Logbook 配置键都是可选的。数值会被四舍五入为整数，并限制在支持的范围内。

在没有 nodeId 的情况下，Logbook 优先选择暴露 screen.snapshot 的已连接应用节点，然后回退到暴露 logbook.snapshot 的无头节点。在未固定设置中，失败的节点会轮换到其他 符合条件的节点之后。仪表板暂停开关仅作用于当前会话，并在插件重新加载或 Gateway 重启时重置；如需持久停止，请使用 captureEnabled: false。

视觉模型选择¶

Logbook 按以下顺序解析观察模型：

1. plugins.entries.logbook.config.visionModel
2. tools.media.models 下第一个支持图像的 Codex 条目

其他媒体提供商会被跳过，因为它们未暴露 Logbook 所需的结构化提取契约。设置 tools.media.image.enabled: false 会禁用借用的媒体默认值，但显式的 Logbook visionModel 仍然生效。

仪表板选项卡¶

• 时间线：每个活动都有可展开卡片，包含类别颜色、主应用、干扰标签和快照关键帧。
• 一日概览：专注比例、类别细分、热门应用。
• 每日站会：将昨天和今天转换为可直接粘贴的更新。
• 询问你的一天：根据跟踪的时间线回答自然语言问题（“我什么时候审查了 gateway PR？”）。
• 立即分析：立即关闭当前捕获窗口，而不是等待分析间隔。

Gateway 方法¶

Logbook 注册以下 Gateway RPC 方法：

只读方法返回运行状态或派生文本。原始截图像素、消耗模型的操作和运行时变更需要 operator.write。Control UI 选项卡也需要 operator.write，因为它暴露了这些操作和原始帧预览；只读客户端仍可直接调用 派生文本方法。

隐私说明¶

• 快照可能包含屏幕上的任何内容，包括机密信息。帧不会离开本机，除非作为采样输入发送到已配置的观察模型。
• 观察、最近卡片和问题可能在卡片合成、站会生成或问答期间通过默认代理模型离开本机。请将提供商的数据处理策略应用于两条模型路由。
• 当需要完全本地流水线时，请为结构化观察模型和默认代理模型都使用本地路由。
• 帧、时间线数据库和临时捕获会以仅所有者可访问的文件权限写入。
• 将 screen.snapshot 添加到 gateway.nodes.commands.deny 是屏幕捕获的紧急停止开关：它会同时阻止应用节点捕获和 Logbook 自身的 logbook.snapshot 命令。
• 设置 tools.media.image.enabled: false 还会阻止 Logbook 借用媒体图像模型进行分析；此时仅使用插件配置中显式的 visionModel。

故障排除¶

Logbook 选项卡缺失¶

检查所有三个关卡：

1. openclaw plugins list --enabled 中包含 logbook。
2. 插件或允许列表更改已成功应用；参见 应用更改并检查。
3. Control 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.commands.deny 是否不包含 screen.snapshot。

连续三次失败后，Logbook 会回退十个捕获 tick，然后重试。未固定的设置可以轮换到另一个符合条件的节点。

捕获成功但没有卡片出现¶

• 模型缺失 状态表示未找到兼容的结构化视觉路由。启用并认证 Codex 插件，或设置有效的显式 visionModel。在模型缺失期间，捕获的帧保持待处理状态，配置修复后可以进行分析。
• 等待 analysisIntervalMinutes，或在捕获到活动后选择 立即分析。
• 连续的相同帧是空闲证据，不会进入分析批次。测试前请更改可见屏幕。
• 如果最新批次显示错误，请修复模型或认证问题，然后选择 立即分析。失败的批次仅在该显式操作时重试，以避免重复模型消耗。

相关¶

• 管理插件
• Codex harness
• 媒体理解
• 节点
• 节点故障排除
• Control UI