Logbook plugin

The Logbook plugin turns screen activity into an automatic work journal. It captures periodic screen snapshots from a paired node, summarizes them into timestamped observations, and builds timeline cards in the Control UI. It can also generate daily standup notes and answer questions about a tracked day.

OpenClaw-owned state stays on the Gateway under <state-dir>/logbook/, but model processing is not necessarily local. Sampled screenshots go to the configured vision route; observations and timeline text go to the default agent model. Use local model routes for both stages if screen content and derived activity text must stay on the machine.

Logbook is bundled and disabled by default. Enabling the plugin opts the Gateway into screen capture because captureEnabled defaults to true.

Before you begin

You need:

• A connected node that exposes screen.snapshot or logbook.snapshot. The macOS app node needs Screen Recording permission. A headless macOS node host (openclaw node host run) gets the plugin-provided logbook.snapshot command backed by the system screencapture tool.
• The bundled Codex plugin enabled and authenticated. Codex currently provides the structured image-extraction contract Logbook requires. Sign in with openclaw models auth login --provider openai; see Codex harness for other auth paths.
• A working default agent model. Logbook uses it to synthesize cards, standup notes, and day Q&A after the vision pass.

Quickstart

Enable the Codex and Logbook plugins:

openclaw plugins enable codex
openclaw plugins enable logbook

Configure an explicit vision model for deterministic startup:

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

If you use plugins.allow, include both codex and logbook. Restart the Gateway after changing plugin configuration, then inspect 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 include screen.snapshot or logbook.snapshot. Headless nodes advertise logbook.snapshot only after the plugin is active. See Node troubleshooting if the command is missing.

The Logbook tab appears only for an enabled plugin and an operator.write Control UI session. The status row should show Capturing without an error. A timeline card appears when the analysis window closes, or you can select Analyze now after activity has been captured.

How it works

1. Capture: every captureIntervalSeconds (default 30s), Logbook invokes the selected node's capture command and stores a scaled JPEG frame. Consecutive identical frames are marked idle and excluded from analysis.
2. Observe: once an analysis window (default 15 minutes) elapses, the plugin samples up to 16 active frames and sends them to the vision model, which returns timestamped activity observations ("VS Code: editing store.ts, fixing a type error"). A capture gap longer than two minutes or local midnight also closes the current window.
3. Synthesize: observations plus the last 45 minutes of existing cards are revised into timeline cards (10-60 minutes each) with a title, summary, category, main app, and any brief distractions.
4. Prune: frames older than retentionDays (default 14) are deleted. Cards, observations, and cached standups are kept.

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

Model and data flow

Logbook uses two separate model routes:

The full SQLite database is not sent to either model. Raw screenshots go only to the observation stage; card synthesis, standup, and Q&A receive 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.5",
          retentionDays: 14,
        },
      },
    },
  },
}

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

Without nodeId, Logbook prefers a connected app node exposing screen.snapshot, then falls back to a headless node exposing logbook.snapshot. In an unpinned setup, a failed node rotates behind other eligible nodes. The dashboard pause toggle is session-only and resets when the Gateway restarts; use captureEnabled: false for a persistent stop.

Vision model selection

Logbook resolves the observation model in this order:

1. plugins.entries.logbook.config.visionModel
2. the first image-capable Codex entry under tools.media.image.models
3. the first image-capable Codex entry under tools.media.models

Other media providers are skipped because they do not currently expose the structured extraction contract Logbook requires. Setting tools.media.image.enabled: false disables borrowed media defaults, but an explicit Logbook visionModel still applies.

Dashboard tab

• Timeline: expandable cards per activity with category colors, the main app, distraction chips, and a snapshot keyframe.
• Day at a glance: focus ratio, category breakdown, top apps.
• Daily standup: turns yesterday plus today into a ready-to-paste update.
• Ask your day: natural-language questions answered from the tracked timeline ("when did I review the gateway PR?").
• Analyze now: closes the current capture window immediately instead of waiting for the analysis interval.

Gateway methods

Logbook registers these Gateway RPC methods:

The 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 can contain anything on screen, including secrets. Frames never leave the machine except as sampled input to the configured observation model.
• Observations, recent cards, and questions can 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.
• Use local routes for both the structured observation model and default agent model when you need a fully local pipeline.
• Frames, the timeline database, and temporary captures are written with owner-only file permissions.
• Adding screen.snapshot to gateway.nodes.denyCommands is the screen-capture kill switch: it blocks app-node capture and Logbook's own logbook.snapshot command alike.
• Setting tools.media.image.enabled: false also stops Logbook from borrowing the media image models for analysis; only an explicit visionModel in the plugin config is used then.

Troubleshooting

The Logbook tab is missing

Check all three gates:

1. openclaw plugins list --enabled includes logbook.
2. The Gateway 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

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

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

Captures succeed but no cards appear

• A Model missing status means no compatible structured vision route was found. Enable and authenticate the Codex plugin, or set a valid explicit visionModel. Captured frames remain pending while the model is missing and can be analyzed after configuration is fixed.
• Wait for analysisIntervalMinutes, or select Analyze now after activity has been captured.
• Consecutive identical frames are idle evidence and do not enter analysis batches. Change the visible screen before testing.
• If the latest batch shows an error, fix the model or auth problem and select Analyze now. Failed batches are retried only on that explicit action to avoid repeated model spend.

Related

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