Logbook 插件

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 codexopenclaw plugins enable logbook

配置显式视觉模型，以获得确定性的启动行为：

{  plugins: {    entries: {      codex: {        enabled: true,      },      logbook: {        enabled: true,        config: {          visionModel: "codex/gpt-5.5",        },      },    },  },}

如果你使用 plugins.allow，请同时包含 codex 和 logbook。更改插件配置后重启 Gateway 网关，然后检查注册信息并打开仪表盘：

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

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

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

工作原理

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

日期边界和时间线时钟使用 Gateway 网关的本地时区，而不是浏览器时区。帧和 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 的已连接应用节点，然后回退到暴露 logbook.snapshot 的无头节点。在未固定节点的设置中，失败节点会轮转到其他符合条件的节点之后。仪表盘暂停开关仅限会话，并会在 Gateway 网关重启时重置；如需持久停止，请使用 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 仍然生效。

仪表盘标签页

• 时间线：按活动展示可展开卡片，包含类别颜色、主要应用、分心芯片和快照关键帧。
• 每日概览：专注比例、类别分解、热门应用。
• 每日站会：将昨天和今天整理成可直接粘贴的更新。
• 询问你的一天：基于已跟踪时间线回答自然语言问题（“我什么时候审阅了 gateway PR？”）。
• 立即分析：立即关闭当前捕获窗口，而不是等待分析间隔结束。

Gateway 网关方法

Logbook 注册这些 Gateway 网关 RPC 方法：

读取方法返回运行状态或派生文本。原始截图像素、会产生模型费用的操作和运行时变更需要 operator.write。Control UI 标签页也需要 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. Gateway 网关已在插件或允许列表更改后重启。
3. Control 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
• 媒体理解
• 节点
• 节点故障排查
• Control UI