【插件】Logbook 插件完全指南（适配 Ubuntu 24.04）

海兰2026-08-24 17:09

日志簿（Logbook） 屏幕活动自动沉淀为结构化的时间线、站会记录和可问答的工作日记。

概览

Logbook 是 OpenClaw 的内置插件，提供以下核心能力：

  • 自动捕获：定期从已配对的节点抓取屏幕快照（缩放为 JPEG）。
  • 智能观察 ：通过视觉模型将连续帧总结为带时间戳的活动描述（例如 "VS Code：正在编辑 store.ts，修复类型错误"）。
  • 一键站会：基于昨日/今日活动生成站会更新文本。
  • 时间线问答 ：用自然语言询问某天的活动（如 "我什么时候审查过 PR？"）。

所有状态保存在 Gateway 的 <state-dir>/logbook/ 目录下（SQLite 数据库 + 帧文件），模型处理可在本地或云端进行。

前提条件

在 Ubuntu 24.04 上使用 Logbook 前，请确保满足以下条件：

条件 说明
✅ 已连接节点 节点必须公开 screen.snapshot 或 logbook.snapshot 能力。 • macOS 应用节点 ：需授予"屏幕录制"权限。 • 无头 macOS 节点 ：由 openclaw node host run 提供 logbook.snapshot（依赖系统 screencapture）。 • Ubuntu 节点：需额外配置屏幕捕获工具（见下文）。
✅ Codex 插件 已启用并完成身份验证。Codex 提供 Logbook 所需的结构化图像提取契约。 运行 openclaw models auth login --provider openai 登录（其他提供方参考 Codex harness）。
✅ 默认智能体模型 用于卡片合成、站会生成和日期问答。必须可用且已配置。

Ubuntu 24.04 配置

在 Ubuntu 24.04 上运行 Logbook，您可能需要额外配置屏幕捕获能力，因为系统默认未提供类似 macOS screencapture 的命令。

🖥️ 安装屏幕捕获工具

bash 复制代码 
sudo apt update
sudo apt install gnome-screenshot   # GNOME 桌面（推荐）
# 或
sudo apt install scrot              # 轻量级命令行工具

📦 配置节点命令

若您的 Ubuntu 节点作为无头主机运行（openclaw node host run），您需要自定义 logbook.snapshot 命令，使其调用系统工具并输出 JPEG 到指定路径。

在节点配置中（如 ~/.openclaw/node/config.json5）添加：

json5 复制代码 
{
  commands: {
    "logbook.snapshot": {
      command: "gnome-screenshot -f {{output}} --filetype=jpeg",
      output: "file",
      // 或使用 scrot: "scrot -q 80 {{output}}"
    }
  }
}

注意 ：{``{output}} 是占位符，Logbook 会替换为临时文件路径。

🔐 权限与桌面环境

  • Wayland 支持 （Ubuntu 24.04 默认）：gnome-screenshot 可能需要额外权限或改用 grim + slurp 等工具。建议在 Xorg 会话下运行，或使用支持 Wayland 的捕获工具。
  • 服务权限 ：若将 Gateway 作为 systemd 服务运行，请确保服务用户有权访问显示器（设置 DISPLAY 和 XAUTHORITY 环境变量），且属于 video 组。

📁 状态目录

默认状态目录为 ~/.local/share/openclaw/gateway/（可通过环境变量 OPENCLAW_STATE_DIR 覆盖）。Logbook 数据位于 <state-dir>/logbook/。

快速开始

1️⃣ 启用插件

bash 复制代码 
openclaw plugins enable codex-supervisor
openclaw plugins enable logbook

2️⃣ 配置显式视觉模型（推荐）

编辑 Gateway 配置文件（通常为 ~/.openclaw/gateway/config.json5），增加：

json5 复制代码 
{
  plugins: {
    entries: {
      codex: { enabled: true },
      logbook: {
        enabled: true,
        config: {
          visionModel: "codex/gpt-5.6-sol",   // 使用 Codex 视觉模型
        },
      },
    },
  },
}

若使用了 plugins.allow，请确保包含 codex 和 logbook。

3️⃣ 重启并验证

bash 复制代码 
openclaw gateway restart
openclaw plugins inspect logbook --runtime --json
openclaw nodes status --connected
openclaw nodes describe --node <节点ID或名称>
openclaw dashboard
  • 节点描述中必须包含 screen.snapshot 或 logbook.snapshot。
  • 仪表板中会出现 Logbook 标签页（需当前会话拥有 operator.write 权限）。
  • 状态行显示 正在捕获，且无错误。

4️⃣ 开始捕获

无需额外操作，Logbook 将按默认间隔（30秒）自动捕获。您也可以点击 立即分析 强制结束当前窗口。

工作原理与数据流

Logbook 的核心逻辑分为捕获 、观察 、合成 和清理四个阶段。下图直观展示了完整流程：
#mermaid-svg-XCpVTE2ePkWalndw{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XCpVTE2ePkWalndw .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XCpVTE2ePkWalndw .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XCpVTE2ePkWalndw .error-icon{fill:#552222;}#mermaid-svg-XCpVTE2ePkWalndw .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XCpVTE2ePkWalndw .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XCpVTE2ePkWalndw .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XCpVTE2ePkWalndw .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XCpVTE2ePkWalndw .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XCpVTE2ePkWalndw .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XCpVTE2ePkWalndw .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XCpVTE2ePkWalndw .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XCpVTE2ePkWalndw .marker.cross{stroke:#333333;}#mermaid-svg-XCpVTE2ePkWalndw svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XCpVTE2ePkWalndw p{margin:0;}#mermaid-svg-XCpVTE2ePkWalndw .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-XCpVTE2ePkWalndw .cluster-label text{fill:#333;}#mermaid-svg-XCpVTE2ePkWalndw .cluster-label span{color:#333;}#mermaid-svg-XCpVTE2ePkWalndw .cluster-label span p{background-color:transparent;}#mermaid-svg-XCpVTE2ePkWalndw .label text,#mermaid-svg-XCpVTE2ePkWalndw span{fill:#333;color:#333;}#mermaid-svg-XCpVTE2ePkWalndw .node rect,#mermaid-svg-XCpVTE2ePkWalndw .node circle,#mermaid-svg-XCpVTE2ePkWalndw .node ellipse,#mermaid-svg-XCpVTE2ePkWalndw .node polygon,#mermaid-svg-XCpVTE2ePkWalndw .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XCpVTE2ePkWalndw .rough-node .label text,#mermaid-svg-XCpVTE2ePkWalndw .node .label text,#mermaid-svg-XCpVTE2ePkWalndw .image-shape .label,#mermaid-svg-XCpVTE2ePkWalndw .icon-shape .label{text-anchor:middle;}#mermaid-svg-XCpVTE2ePkWalndw .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XCpVTE2ePkWalndw .rough-node .label,#mermaid-svg-XCpVTE2ePkWalndw .node .label,#mermaid-svg-XCpVTE2ePkWalndw .image-shape .label,#mermaid-svg-XCpVTE2ePkWalndw .icon-shape .label{text-align:center;}#mermaid-svg-XCpVTE2ePkWalndw .node.clickable{cursor:pointer;}#mermaid-svg-XCpVTE2ePkWalndw .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XCpVTE2ePkWalndw .arrowheadPath{fill:#333333;}#mermaid-svg-XCpVTE2ePkWalndw .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XCpVTE2ePkWalndw .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XCpVTE2ePkWalndw .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XCpVTE2ePkWalndw .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XCpVTE2ePkWalndw .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XCpVTE2ePkWalndw .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XCpVTE2ePkWalndw .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XCpVTE2ePkWalndw .cluster text{fill:#333;}#mermaid-svg-XCpVTE2ePkWalndw .cluster span{color:#333;}#mermaid-svg-XCpVTE2ePkWalndw div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XCpVTE2ePkWalndw .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XCpVTE2ePkWalndw rect.text{fill:none;stroke-width:0;}#mermaid-svg-XCpVTE2ePkWalndw .icon-shape,#mermaid-svg-XCpVTE2ePkWalndw .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XCpVTE2ePkWalndw .icon-shape p,#mermaid-svg-XCpVTE2ePkWalndw .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XCpVTE2ePkWalndw .icon-shape .label rect,#mermaid-svg-XCpVTE2ePkWalndw .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XCpVTE2ePkWalndw .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XCpVTE2ePkWalndw .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XCpVTE2ePkWalndw :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
是
不同
是
否
否
启动 Logbook
捕获启用?
每隔 captureIntervalSeconds

调用节点 snapshot 命令
存储缩放后的 JPEG 帧
与上一帧相同?
标记为"空闲"并忽略
加入当前分析窗口
分析窗口结束?

（analysisIntervalMinutes

或午夜/>2分钟缺口）
从窗口采样最多16个活动帧
发送至视觉模型

（visionModel）
获得带时间戳的观察记录
结合最近45分钟卡片

合成时间线卡片
存入 SQLite 数据库
清理超过 retentionDays 的帧
等待下一轮捕获
仅显示历史时间线

不捕获新帧

关键时序细节：

  • 捕获间隔：默认 30 秒，可配置 5~600 秒。
  • 分析窗口 ：默认 15 分钟，可配置 3~120 分钟。窗口也会因以下情况提前关闭：
    • 两次捕获间隔 > 2 分钟（表示活动中断）。
    • 本地午夜（按 Gateway 时区）切换日期。
  • 卡片合成：会参考当前卡片中最近 45 分钟的内容，生成时长 10~60 分钟的卡片，包含标题、摘要、类别、主要应用和短暂分心标签。
  • 数据保留：过期帧自动删除（默认保留 14 天），但卡片、观察记录和站会记录永久保留。

模型路由详解

Logbook 使用两条独立的模型路由，分别处理像素级数据和文本派生数据。下表清晰说明：

阶段 输入数据 模型路由 说明
观察 最多 16 个采样帧（JPEG）+ 捕获时间 visionModel（显式配置）或借用 tools.media 的 Codex 条目 返回结构化活动观察（纯文本）
合成卡片 观察记录 + 最近时间线卡片（文本） 默认智能体模型（插件 LLM 运行时） 生成时间线卡片，含分类、摘要等
生成站会 所选日期 + 前一天的卡片（文本） 默认智能体模型 输出站会报告
日期问答 问题 + 所选日期卡片 + 近期观察（文本） 默认智能体模型 回答自然语言问题

⚠️ 重要隐私说明：

  • 完整的 SQLite 数据库不会发送给任何模型。
  • 原始屏幕截图仅在观察阶段发送给视觉模型。
  • 卡片合成、站会和问答只处理派生文本，不包含像素。

配置参数全解

所有配置键均为可选，数值会被舍入为整数并限制在合法范围。

json5 复制代码 
{
  plugins: {
    entries: {
      logbook: {
        enabled: true,
        config: {
          captureEnabled: true,          // 主开关
          captureIntervalSeconds: 30,    // 5-600
          analysisIntervalMinutes: 15,   // 3-120
          nodeId: "my-mac",              // 固定节点（ID或显示名）
          screenIndex: 0,                // 显示器索引（0-16）
          maxWidth: 1440,                // 缩放宽度上限（480-3840）
          visionModel: "codex/gpt-5.6-sol",
          retentionDays: 14,             // 1-365
        },
      },
    },
  },
}
键 默认值 范围 行为
captureEnabled true 布尔 持久开关；false 时停止捕获，但时间线仍可查看
captureIntervalSeconds 30 5-600 两次捕获的间隔（秒）
analysisIntervalMinutes 15 3-120 目标观察窗口长度（分钟），可能提前关闭
nodeId 未设置 字符串 固定到指定节点（匹配不区分大小写）；未设置时自动选择
screenIndex 0 0-16 多显示器时选择屏幕序号
maxWidth 1440 480-3840 缩放后的最大宽度，保持宽高比
visionModel 未设置 provider/model 显式指定视觉模型；格式错误会暂停分析
retentionDays 14 1-365 帧保留天数；卡片和记录不删除

节点选择逻辑 ：未设置 nodeId 时，优先选择公开 screen.snapshot 的应用节点，其次选择公开 logbook.snapshot 的无头节点。若首选节点失败，会轮换到其他符合条件节点。

仪表板功能

在 OpenClaw Dashboard 的 Logbook 标签页（需 operator.write）中，您可以使用：

  • 📅 时间线视图：按日期展示可展开的卡片，每张卡片有颜色分类、主应用、分心标签和关键帧缩略图。
  • 📊 日期概览：专注比例、类别分布、最常用应用统计。
  • 📝 每日站会：一键生成可直接粘贴的站会文本（基于昨天和今天的卡片）。
  • ❓ 询问当天活动：输入自然语言问题（如 "我今天几点开始工作的？"），系统基于时间线回答。
  • ⚡ 立即分析：强制结束当前捕获窗口，立即执行观察和合成，无需等待间隔结束。

Gateway RPC 方法

Logbook 注册以下 RPC 方法，供客户端或脚本调用：

方法 参数 权限 返回
logbook.status 无 operator.read 状态对象（捕获、分析、模型、节点、日期、时区）
logbook.days 无 operator.read 包含卡片数量和日期范围的日期列表
logbook.timeline { day?: "YYYY-MM-DD" } operator.read 指定日期的卡片和统计（默认今日）
logbook.frames { startMs, endMs } operator.write 时间范围内的帧元数据
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.read，而原始帧获取、模型费用操作和运行时变更需要 operator.write。仪表板标签页因涉及这些操作，也要求 operator.write。

隐私与安全

Logbook 设计时充分考虑了数据隐私：

  • 帧存储 ：所有原始截图均保存在本地 <state-dir>/logbook/，权限为 0700（仅所有者可访问）。
  • 数据传输 ：帧只会在观察阶段发送给配置的视觉模型。若使用云端模型，则像素数据会离开本机；若需完全本地化，请使用本地模型路由（如 Ollama 等）。
  • 派生文本：卡片、观察记录和问答内容通过默认智能体模型处理，同样可能离开本机。请依据各提供商的数据处理政策评估风险。
  • 终止开关 ：在 Gateway 配置中添加 gateway.nodes.commands.deny: ["screen.snapshot"] 可完全阻止屏幕捕获（同时影响应用节点和无头节点）。
  • 媒体模型禁用 ：设置 tools.media.image.enabled: false 会阻止 Logbook 借用媒体图像模型，仅使用显式指定的 visionModel（若有）。

故障排查

❌ Logbook 选项卡不显示

  • 确认 openclaw plugins list --enabled 包含 logbook。
  • 更改插件或允许列表后，务必重启 Gateway。
  • 当前会话必须拥有 operator.write 权限（只读会话不会显示交互式选项卡）。
  • 若使用 plugins.allow，必须同时包含 logbook 和 codex。

❌ 捕获报告错误

bash 复制代码 
openclaw nodes status --connected
openclaw nodes describe --node <id>
openclaw logs --follow
  • 确认节点公开了 screen.snapshot 或 logbook.snapshot。
  • macOS 节点：授予"屏幕录制"权限。
  • Ubuntu 节点 ：检查屏幕捕获工具是否安装，并确保 Gateway 有权限执行（参见 [Ubuntu 特别配置](#Ubuntu 特别配置)）。
  • 检查 gateway.nodes.commands.deny 是否误包含 screen.snapshot。
  • 连续失败 3 次后，Logbook 会暂停 10 个捕获周期再重试；未固定节点的场景可能自动切换节点。

❌ 捕获成功但无卡片生成

  • 确认视觉模型可用。Codex 插件已启用且认证通过，或已设置有效 visionModel。
  • 等待分析窗口结束，或点击 立即分析。
  • 若屏幕内容一直不变（空闲帧），则不会生成观察记录。请改变屏幕内容后测试。
  • 若批次失败，修复模型/认证后点击 立即分析 重试（仅显式操作会重试失败批次）。
相关推荐
好评1241 小时前
【Linux】Socket编程TCP
linux·网络·tcp/ip
潘高1 小时前
如何用 AI 做出高质量的 PPT
人工智能·ppt
云云只是个程序马喽1 小时前
短剧/推文/AI创作变现小程序完整落地方案：自研vs成熟系统成本对比+全流程实现指南
人工智能·小程序
大厂码农老A1 小时前
177K star，扒开DeepSeek Harness的营销，我看到了什么
人工智能·后端·deepseek
半个落月1 小时前
在浏览器里运行 DeepSeek-R1：React 对话界面与安全渲染（三）
前端·人工智能·react.js
深圳市益普科技有限公司1 小时前
先进封装爆发，封测厂的数字化准备好了吗？
人工智能
晴天161 小时前
LLM 与推理模型：从“快思考“到“慢思考“的范式跃迁-Day27
人工智能·深度学习
勇往直前plus1 小时前
Docker PostgreSQL 16 部署要点（Ubuntu 22）
ubuntu·docker·postgresql
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05历年考研数学一、数学二、数学三真题试卷及答案PDF06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费072026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法