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 插件:
配置显式视觉模型以确保启动的确定性:
{
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 会话时显示。状态行应显示 捕获中,且没有错误。分析窗口关闭后会出现时间线卡片,你也可以在捕获到活动后选择 立即分析。
工作原理¶
- 捕获:每隔
captureIntervalSeconds(默认 30 秒),Logbook 调用选定节点的捕获命令,并存储缩放后的 JPEG 帧。连续相同的帧会被标记为空闲,并排除在分析之外。 - 观察:当分析窗口(默认 15 分钟)结束时,插件最多采样 16 个活动帧并发送给视觉模型,由模型返回带时间戳的活动观察结果(例如“VS Code:正在编辑 store.ts,修复一个类型错误”)。捕获间隔超过两分钟或本地午夜到达也会关闭当前窗口。
- 综合:观察结果加上最近 45 分钟的现有卡片会被整合为时间线卡片(每张覆盖 10-60 分钟),包含标题、摘要、类别、主要应用以及任何短暂干扰。
- 修剪:早于
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 按以下顺序解析观察模型:
plugins.entries.logbook.config.visionModeltools.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 选项卡缺失¶
检查以下三个条件:
openclaw plugins list --enabled包含logbook。- 插件或允许列表更改已成功应用;参见 应用更改并检查。
- 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