USER MANUAL · PRODUCTIVITY

Runbooks

Automate routine operations with versioned runbooks on the OpenClaw-native path — triggered manually, on schedule, via webhook, or by event.

/runbooks

Overview#

Runbooks let you codify repeatable operational procedures — agent restarts, config rollouts, batch approvals, health remediations — into versioned automation definitions. Instead of manually executing the same steps each time, define them once and let ClawButler handle orchestration, retries, and audit logging.

Each runbook now centers on the OpenClaw-native path. Typed steps, approval gates, verification, and evidence keep operational automation on the main governance rail instead of presenting multiple runtime backends as equal first-class options.

Prerequisites#

Prerequisites

At least one connector configured and synced (see Connectors)

Expected Results#

After creating runbooks and triggering executions, you will see:

-Runbook registry listing all definitions with name, version, backend, and trigger type
-Version history for each runbook showing changes across revisions
-Execution timeline with step-by-step progress, timestamps, and output logs
-Run status indicators (pending, running, completed, failed, cancelled)

Web Operations#

Navigate to the Runbooks page from the sidebar under Productivity.

Runbook Registry

The registry shows all runbook definitions in your organization. Each card displays the runbook name, current version, execution path, and trigger type. Click any runbook to view its definition, version history, and past executions. Use the Create button to define a new runbook with typed steps, trigger configuration, and approval or verification controls.

Trigger Configuration

Each runbook supports one or more trigger types. Manual triggers let you start an execution on demand from the Web UI or CLI. Schedule triggers run on a cron expression (e.g., every day at 09:00 UTC). Webhook triggers expose a unique URL that external systems can POST to. Event triggers fire automatically when a matching audit event occurs (e.g., agent health degradation).

Execution View

When a runbook runs, the execution view shows a real-time event timeline. Each step appears as a row with its name, status (pending, running, completed, failed), start/end timestamps, and output. Steps execute sequentially by default. If a step fails, the runbook halts and marks the run as failed unless a retry policy is configured.

Approval & Verification

Runbook steps can require human approval before proceeding (TCC Step 04). When a step is marked as requiring approval, the execution pauses and creates an approval request. The designated approver can review the step context and approve or reject it. After the final step completes, you can mark the run as verified to confirm the outcome met expectations.

CLI Operations#

List all runbooks in your organization

Terminal

$ ap runbook list

View runbook definition, steps, and version history

Terminal

$ ap runbook show <id>

Trigger a new execution of a runbook

Terminal

$ ap runbook trigger <id>

View execution history and run details for a runbook

Terminal

$ ap runbook runs <id>

FAQ#

Q: What happens if a runbook step fails mid-execution?

A: The execution halts at the failed step and the run status changes to 'failed'. You can inspect the step output to diagnose the issue, then re-trigger the runbook. Steps that completed before the failure are not rolled back automatically — each step should be designed to be idempotent.

Q: Can I cancel a running runbook?

A: Yes. From the execution view, click the Cancel button. The currently running step will complete, but no further steps will be dispatched. The run status changes to 'cancelled'.

Q: How do I choose between backends?

A: The default path is openclaw_native. Use it when steps need to interact directly with your OpenClaw gateway, approvals, and evidence chain. Legacy compatibility shims may still exist internally, but they are no longer the recommended product path.