|
| 1 | +--- |
| 2 | +summary: "Optional automatic work journal built from periodic screen snapshots" |
| 3 | +read_when: |
| 4 | + - You want a Dayflow-style timeline of your day in the Control UI |
| 5 | + - You are enabling or configuring the bundled Logbook plugin |
| 6 | + - You want standup summaries or day recall grounded in screen activity |
| 7 | +title: "Logbook plugin" |
| 8 | +--- |
| 9 | + |
| 10 | +The Logbook plugin turns screen activity into an automatic work journal. It |
| 11 | +captures periodic screen snapshots from a paired node (for example the OpenClaw |
| 12 | +Mac app), summarizes them with a vision model into timestamped observations, |
| 13 | +and synthesizes those into timeline cards you can browse in the |
| 14 | +[Control UI](/web/control-ui). On top of the timeline it generates daily |
| 15 | +standup notes and answers questions about your day. |
| 16 | + |
| 17 | +Everything stays local: snapshots and the timeline database live under the |
| 18 | +Gateway state directory. Only analysis batches are sent to the model you |
| 19 | +configure, so pick a local model if snapshots must never leave the machine. |
| 20 | + |
| 21 | +## Default state |
| 22 | + |
| 23 | +Logbook is a bundled plugin and is disabled by default. Screen capture is |
| 24 | +opt-in. |
| 25 | + |
| 26 | +Enable it with: |
| 27 | + |
| 28 | +```bash |
| 29 | +openclaw plugins enable logbook |
| 30 | +openclaw gateway restart |
| 31 | +``` |
| 32 | + |
| 33 | +Then open the dashboard and pick the Logbook tab: |
| 34 | + |
| 35 | +```bash |
| 36 | +openclaw dashboard |
| 37 | +``` |
| 38 | + |
| 39 | +The Logbook tab is contributed through the plugin Control UI tab surface |
| 40 | +(`registerControlUiDescriptor` with `surface: "tab"`), so it appears in the |
| 41 | +sidebar only while the plugin is enabled on the connected gateway. |
| 42 | + |
| 43 | +## Requirements |
| 44 | + |
| 45 | +- A connected node that can capture the screen. The macOS app node advertises |
| 46 | + `screen.snapshot` by default (see [Nodes](/nodes)); headless macOS node |
| 47 | + hosts (`openclaw node host run`) get a plugin-provided `logbook.snapshot` |
| 48 | + command backed by the system `screencapture` tool when Logbook is enabled. |
| 49 | +- A vision model whose media-understanding provider supports structured |
| 50 | + extraction (the bundled Codex plugin does, for example `codex/gpt-5.5`). |
| 51 | + Logbook resolves the model in order: |
| 52 | + 1. `plugins.entries.logbook.config.visionModel` (`"provider/model"` ref) |
| 53 | + 2. the first image-capable Codex entry under `tools.media.image.models` or |
| 54 | + `tools.media.models` (other media providers do not currently expose the |
| 55 | + structured extraction contract Logbook requires) |
| 56 | +- Timeline card synthesis, standup notes, and "ask your day" answers use the |
| 57 | + default agent model via the plugin LLM runtime. |
| 58 | + |
| 59 | +## How it works |
| 60 | + |
| 61 | +1. **Capture**: every `captureIntervalSeconds` (default 30s) Logbook invokes |
| 62 | + `screen.snapshot` on the capture node and stores a scaled JPEG frame. |
| 63 | + Consecutive identical frames are marked idle and excluded from analysis. |
| 64 | +2. **Observe**: once an analysis window (default 15 minutes) elapses, the |
| 65 | + frames are sent to the vision model, which returns timestamped activity |
| 66 | + observations ("VS Code: editing store.ts, fixing a type error"). |
| 67 | +3. **Synthesize**: observations plus the last 45 minutes of existing cards are |
| 68 | + revised into timeline cards (10-60 minutes each) with a title, summary, |
| 69 | + category, main app, and any brief distractions. |
| 70 | +4. **Prune**: frames older than `retentionDays` (default 14) are deleted. |
| 71 | + Cards, observations, and standups are kept. |
| 72 | + |
| 73 | +Frames and the timeline database live under `<state-dir>/logbook/`. |
| 74 | + |
| 75 | +## Configuration |
| 76 | + |
| 77 | +```json |
| 78 | +{ |
| 79 | + "plugins": { |
| 80 | + "entries": { |
| 81 | + "logbook": { |
| 82 | + "enabled": true, |
| 83 | + "config": { |
| 84 | + "captureIntervalSeconds": 30, |
| 85 | + "analysisIntervalMinutes": 15, |
| 86 | + "screenIndex": 0, |
| 87 | + "maxWidth": 1440, |
| 88 | + "nodeId": "my-mac", |
| 89 | + "visionModel": "codex/gpt-5.5", |
| 90 | + "retentionDays": 14, |
| 91 | + "captureEnabled": true |
| 92 | + } |
| 93 | + } |
| 94 | + } |
| 95 | + } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +All keys are optional. Leave `nodeId` unset to use the first connected node |
| 100 | +that supports `screen.snapshot`. Set `captureEnabled: false` to keep the |
| 101 | +timeline UI available without capturing; the dashboard also has a session-only |
| 102 | +pause toggle. |
| 103 | + |
| 104 | +## Dashboard tab |
| 105 | + |
| 106 | +- **Timeline**: expandable cards per activity with category colors, the main |
| 107 | + app, distraction chips, and a snapshot keyframe. |
| 108 | +- **Day at a glance**: focus ratio, category breakdown, top apps. |
| 109 | +- **Daily standup**: turns yesterday plus today into a ready-to-paste update. |
| 110 | +- **Ask your day**: natural-language questions answered from the tracked |
| 111 | + timeline ("when did I review the gateway PR?"). |
| 112 | +- **Analyze now**: closes the current capture window immediately instead of |
| 113 | + waiting for the analysis interval. |
| 114 | + |
| 115 | +## Gateway methods |
| 116 | + |
| 117 | +Logbook registers Gateway RPC methods for the dashboard. `logbook.status`, |
| 118 | +`logbook.days`, and `logbook.timeline` return derived text and are readable |
| 119 | +with `operator.read`. Everything that returns raw screenshot pixels |
| 120 | +(`logbook.frames`, `logbook.frame`), spends model tokens (`logbook.standup`, |
| 121 | +`logbook.ask`), or mutates runtime state (`logbook.capture.set`, |
| 122 | +`logbook.analyze.now`) requires `operator.write`. The Control UI tab requires |
| 123 | +`operator.write` because the bundled view exposes those actions and raw frame |
| 124 | +previews; read-only clients may call the derived-text methods directly. |
| 125 | + |
| 126 | +## Privacy notes |
| 127 | + |
| 128 | +- Snapshots can contain anything on screen, including secrets. Frames never |
| 129 | + leave the machine except as model input for analysis batches. |
| 130 | +- Use a structured-extraction provider that runs locally, when available and |
| 131 | + explicitly configured, for a fully on-device pipeline. |
| 132 | +- Frames, the timeline database, and temporary captures are written with |
| 133 | + owner-only file permissions. |
| 134 | +- Adding `screen.snapshot` to `gateway.nodes.denyCommands` is the |
| 135 | + screen-capture kill switch: it blocks app-node capture and Logbook's own |
| 136 | + `logbook.snapshot` command alike. |
| 137 | +- Setting `tools.media.image.enabled: false` also stops Logbook from borrowing |
| 138 | + the media image models for analysis; only an explicit `visionModel` in the |
| 139 | + plugin config is used then. |
0 commit comments