日志簿插件

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.6-sol",        },      },    },  },}

如果你使用 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。如果缺少该命令，请参阅节点故障排查。

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

工作原理

1. 捕获：Logbook 每隔 captureIntervalSeconds（默认 30 秒）调用所选节点的捕获命令，并存储一张缩放后的 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.6-sol",          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