日志簿（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 的命令。

🖥️ 安装屏幕捕获工具

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）添加：

{
  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️⃣ 启用插件

openclaw plugins enable codex-supervisor
openclaw plugins enable logbook

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

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

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

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

3️⃣ 重启并验证

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 的核心逻辑分为捕获、观察、合成和清理四个阶段。下图直观展示了完整流程：

关键时序细节：

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

---

模型路由详解

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

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

⚠️ 重要隐私说明：

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

---

配置参数全解

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

{
  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。

❌ 捕获报告错误

openclaw nodes status --connected
openclaw nodes describe --node <id>
openclaw logs --follow

• 确认节点公开了 screen.snapshot 或 logbook.snapshot。
• macOS 节点：授予“屏幕录制”权限。
• Ubuntu 节点：检查屏幕捕获工具是否安装，并确保 Gateway 有权限执行（参见 Ubuntu 特别配置）。
• 检查 gateway.nodes.commands.deny 是否误包含 screen.snapshot。
• 连续失败 3 次后，Logbook 会暂停 10 个捕获周期再重试；未固定节点的场景可能自动切换节点。

❌ 捕获成功但无卡片生成

• 确认视觉模型可用。Codex 插件已启用且认证通过，或已设置有效 visionModel。
• 等待分析窗口结束，或点击 立即分析。
• 若屏幕内容一直不变（空闲帧），则不会生成观察记录。请改变屏幕内容后测试。
• 若批次失败，修复模型/认证后点击 立即分析 重试（仅显式操作会重试失败批次）。