跳转至

Logbook 插件将屏幕活动转化为自动工作日志

它会从已配对节点捕获周期性的屏幕快照,将其归纳为带时间戳的观察结果,并在 Control UI 中构建时间线卡片。它还可以生成每日站会摘要,并回答关于某一天工作的问题。

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 harness。
  • 一个可用的默认智能体模型。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 的打开、查询、事务、维护和关闭都在主机持有的 worker 中运行。帧读取与修剪共享准入控制,因此预览和分析会在保留策略删除文件之前完成文件读取。

模型与数据流

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

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

键 默认值 范围或取值 行为
captureEnabled true 布尔值 控制新快照的持久总开关;当为 false 时,时间线仍然可用
captureIntervalSeconds 30 5-600 捕获尝试之间的延迟
analysisIntervalMinutes 15 3-120 目标观察窗口;间隙和午夜可能使其提前关闭
nodeId 未设置 节点 ID 或显示名称 将捕获固定到某个已连接节点;匹配不区分大小写
screenIndex 0 0-16 从零开始的显示器索引
maxWidth 1440 480-3840 请求的捕获大小上限;无头 macOS 会将其应用于最大尺寸
visionModel 未设置 provider/model 显式结构化路由;格式错误的引用会暂停分析,不支持的提供方会导致批次失败
retentionDays 14 1-365 删除旧帧;卡片、观察结果和站会摘要保留

未设置 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?”)。
  • 立即分析:立即关闭当前捕获窗口,而不等待分析间隔。

网关方法

Logbook 注册了以下 Gateway RPC 方法:

方法 参数 作用域 结果
logbook.status 无 operator.read 捕获、分析、模型、节点、Gateway 日期和 Gateway 时区状态
logbook.days 无 operator.read 带有时间线卡片计数和卡片时间范围的日期
logbook.timeline { day?: "YYYY-MM-DD" } operator.read 派生的卡片和日统计数据;默认为 Gateway 的当前日期
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。Control UI 选项卡也需要 operator.write,因为它会暴露这些操作和原始帧预览;只读客户端仍然可以直接调用派生文本方法。

隐私说明

  • 快照可能包含屏幕上的任何内容,包括机密。帧绝不会离开机器,除非作为配置的观察模型的采样输入。
  • 观察结果、最近的卡片和问题可能会在卡片合成、站会生成或问答过程中通过默认 Agent 模型离开机器。请对两条模型路由都应用提供商的数据处理政策。
  • 当您需要完全本地的流水线时,请为结构化观察模型和默认 Agent 模型都使用本地路由。
  • 帧、时间线数据库和临时捕获文件均以仅所有者可读写的文件权限写入。
  • 将 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 会退避十个捕获周期,然后重试。未固定的配置可以轮换到另一个符合条件的节点。

捕获成功但没有卡片出现

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw