Logbook Plugin: Automatic Work Journal from Screen Snapshots

The Logbook plugin automatically records screen activity as a work journal. It periodically takes screenshots from a connected node, creates timestamped summaries of the activity, and displays timeline cards in the Control UI. The plugin can also produce daily standup notes and respond to questions about a specific workday.

State managed by OpenClaw stays on the Gateway under <state-dir>/logbook/, though model processing may occur remotely. Captured screenshots are sent to the configured vision route, while observations and timeline text use the default agent model. To keep both screen content and derived activity text on the local machine, configure local model routes for each stage.

Logbook ships bundled but is disabled by default. Enabling the plugin automatically activates screen capture on the Gateway because captureEnabled defaults to true.

Before you begin

These prerequisites are required:

• A connected node exposing screen.snapshot or logbook.snapshot. The macOS app node must have Screen Recording permission. A headless macOS node host (openclaw node host run) uses the plugin-provided logbook.snapshot command, which relies on the system screencapture tool.
• The bundled Codex plugin must be enabled and authenticated. Codex provides the structured image extraction contract that Logbook depends on. Sign in using openclaw models auth login --provider openai; alternative authentication methods are described in the Codex harness.
• A working default agent model. After the vision pass, Logbook uses this model to generate cards, standup notes, and day Q&A responses.

Quickstart

Enable both the Codex and Logbook plugins:

openclaw plugins enable codex
openclaw plugins enable logbook

Set an explicit vision model to ensure deterministic startup:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
      logbook: {
        enabled: true,
        config: {
          visionModel: "codex/gpt-5.6-sol",
        },
      },
    },
  },
}

If you use plugins.allow, include both codex and logbook. Restart the Gateway after modifying the plugin configuration, then check the registrations and open the dashboard:

openclaw gateway restart
openclaw plugins inspect logbook --runtime --json
openclaw nodes status --connected
openclaw nodes describe --node <idOrNameOrIp>
openclaw dashboard

The node description must contain screen.snapshot or logbook.snapshot. Headless nodes advertise logbook.snapshot only after the plugin becomes active. If the command is missing, refer to Node troubleshooting.

The Logbook tab appears only when the plugin is enabled and an operator.write Control UI session is active. The status row should display Capturing with no errors. A timeline card appears when the analysis window closes, or you can click Analyze now after capturing some activity.

How it works

1. Capture: every captureIntervalSeconds (default 30s), Logbook runs the capture command on the selected node and saves a scaled JPEG frame. Consecutive identical frames are marked as idle and excluded from analysis.
2. Observe: after an analysis window (default 15 minutes) passes, the plugin samples up to 16 active frames and submits them to the vision model. The model returns timestamped activity observations, for example "VS Code: editing store.ts, fixing a type error". A capture gap exceeding two minutes or local midnight also ends the current window.
3. Synthesize: observations combined with the last 45 minutes of existing cards are refined into timeline cards (each 10-60 minutes long) that include a title, summary, category, primary application, and any brief distractions.
4. Prune: frames older than retentionDays (default 14) are removed. Cards, observations, and cached standups are preserved.

Day boundaries and timeline clocks follow the Gateway's local timezone, not the browser's timezone. Frames and the SQLite timeline database are stored under <state-dir>/logbook/.

Model and data flow

Logbook relies on two separate model routes:

The full SQLite database is never sent to either model. Raw screenshots are only used during the observation stage; card synthesis, standup generation, and Q&A receive only derived text.

Configuration

{
  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,
        },
      },
    },
  },
}

All Logbook configuration keys are optional. Numeric values are rounded to integers and clamped to the supported range.

Without nodeId, Logbook first tries a connected app node that exposes screen.snapshot, and if that is not available, it falls back to a headless node exposing logbook.snapshot. In an unpinned setup, when a node fails, it is replaced by the next eligible node. The pause toggle on the dashboard only lasts for the current session and is cleared when the Gateway restarts; for a permanent stop, use captureEnabled: false.

Vision model selection

The observation model is resolved by Logbook in the following order:

1. plugins.entries.logbook.config.visionModel
2. The first Codex entry under tools.media.models that supports images

Other media providers are skipped since they do not currently offer the structured extraction contract required by Logbook. When tools.media.image.enabled: false is set, borrowed media defaults are disabled, though an explicit Logbook visionModel still takes effect.

Dashboard tab

• Timeline: expandable cards for each activity with category colors, the primary app, distraction chips, and a snapshot keyframe.
• Day at a glance: focus ratio, category breakdown, and top applications.
• Daily standup: transforms yesterday and today into a ready-to-paste summary.
• Ask your day: natural-language queries answered from the tracked timeline, for example "when did I review the gateway PR?".
• Analyze now: immediately closes the current capture window rather than waiting for the analysis interval.

Gateway methods

The following Gateway RPC methods are registered by Logbook:

Read methods return operational state or derived text. Raw screenshot pixels, model-spending actions, and runtime mutations require operator.write. The Control UI tab also requires operator.write because it exposes those actions and raw frame previews; a read-only client can still call the derived-text methods directly.

Privacy notes

• Snapshots may capture anything on screen, including secrets. Frames never leave the machine except as sampled input to the configured observation model.
• Observations, recent cards, and questions may leave the machine through the default agent model during card synthesis, standup generation, or Q&A. Apply the provider's data-handling policy to both model routes.
• For a fully local pipeline, use local routes for both the structured observation model and the default agent model.
• Frames, the timeline database, and temporary captures are written with owner-only file permissions.
• Adding screen.snapshot to gateway.nodes.commands.deny acts as the screen-capture kill switch: it prevents app-node capture and Logbook's own logbook.snapshot command.
• Setting tools.media.image.enabled: false also prevents Logbook from borrowing the media image models for analysis; only an explicit visionModel in the plugin config is used in that case.

Troubleshooting

The Logbook tab is missing

Verify all three conditions:

1. openclaw plugins list --enabled includes logbook.
2. The Gateway was restarted after the plugin or allowlist change.
3. The Control UI connection has operator.write; read-only sessions do not receive the interactive tab descriptor.

If plugins.allow is set, it must include both logbook and codex for the recommended configuration.

Capture reports an error

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

• Ensure the node exposes screen.snapshot or logbook.snapshot.
• Grant Screen Recording permission on the capture Mac.
• If nodeId is configured, verify it matches the node id or display name.
• Confirm that gateway.nodes.commands.deny does not contain screen.snapshot.

After three consecutive failures, Logbook backs off for ten capture ticks and then retries. In an unpinned setup, it can rotate to another eligible node.

Captures succeed but no cards appear

• A Model missing status indicates that no suitable structured vision path could be located. Activate and authorize the Codex plugin, or configure a working explicit visionModel. While the model is absent, captured frames stay queued and become analyzable once the setup is corrected.
• Either wait for analysisIntervalMinutes or click Analyze now once some activity has been recorded.
• Repeated, unchanged frames count as idle evidence and are excluded from analysis batches. Before running a test, ensure the screen content changes.
• When the most recent batch reports an error, resolve the model or authentication issue and then press Analyze now. Failed batches are only reprocessed when you take that explicit step, preventing unnecessary model usage charges.

Related

• Manage plugins
• Codex harness
• Media understanding
• Nodes
• Node troubleshooting
• Control UI