OpenClaw Complete Documentation Guide: Setup, Configuration, and Skills

Automation: Running Background Work

OpenClaw runs work in the background through tasks, scheduled jobs, event hooks, and standing instructions. The automation page provides a quick decision guide:

• Scheduled Tasks (Cron): For exact timing (cron expressions, one-shot). Creates task records. Best for reports, reminders, background jobs.
• Heartbeat: For approximate timing (default every 30 minutes). Full main-session context. No task records. Best for inbox checks, calendar, notifications.
• Background Tasks: The task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, CLI operations. Use openclaw tasks list and openclaw tasks audit to inspect them.
• Task Flow: Durable multi-step flow orchestration with revision tracking. Use openclaw tasks flow list|show|cancel for inspection.
• Standing Orders: Persistent agent instructions injected into every session. Live in workspace files (typically AGENTS.md). Combine with cron for time-based enforcement.
• Hooks: Event-driven scripts triggered by agent lifecycle events (/new, /reset, /stop), session compaction, gateway startup, and message flow. Managed with openclaw hooks. For in-process tool-call interception, use Plugin hooks.
• Heartbeat: Periodic main-session turn (default every 30 minutes). Batches multiple checks in one agent turn. Use HEARTBEAT.md for a small checklist, or a tasks: block for due-only periodic checks. Empty heartbeat files skip as empty-heartbeat-file; due-only task mode skips as no-tasks-due. Heartbeats defer while cron work is active or queued.

Scheduled Tasks (Cron)

Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel, a webhook, or nowhere.

Quick Start

Add a one-shot reminder:

openclaw cron create "2027-02-01T16:00:00Z" \
  --name "Reminder" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

Check your jobs:

openclaw cron list
openclaw cron get <id>
openclaw cron show <id>

See run history:

openclaw cron runs -- <id>

How Cron Works

• Cron runs inside the Gateway process, not inside the model. The Gateway must be running for schedules to fire.
• Job definitions, runtime state, and run history persist in OpenClaw's shared SQLite state database, so restarts do not lose schedules.
• Every cron execution creates a background task record.
• One-shot jobs (--at) auto-delete after success by default; pass --keep-after-run to keep them.
• Per-run wall-clock budget: --timeout-seconds when set. Otherwise, isolated/detached agent-turn jobs are bounded by cron's own 60-minute watchdog before the underlying agent-turn timeout (agents.defaults.timeoutSeconds, default 48 hours) would ever apply; command jobs default to 10 minutes, and script payloads default to 5 minutes.
• On Gateway startup, overdue isolated agent-turn jobs are rescheduled instead of replayed immediately, keeping model/tool bootstrap work out of the channel-connect window.
• If you drive openclaw agent from system cron or another external scheduler, wrap it with a hard-kill escalation even though the CLI already handles SIGTERM/SIGINT. Gateway-backed runs ask the Gateway to abort accepted runs; --local runs get the same abort signal. For GNU timeout, prefer timeout -k 60 600 openclaw agent ... over plain timeout 600 ..., the -k value is the backstop if the process cannot drain in time. For systemd units, use a SIGTERM stop signal with a grace window (TimeoutStopSec) before the final kill.
• Reusing a --run-id while the original Gateway run is still active reports the duplicate as in-flight instead of starting a second run.

Schedule Types

Timestamps without a timezone are treated as UTC. Add --tz America/New_York to interpret an offset-less --at datetime, or to evaluate a cron expression, in that IANA timezone. Cron expressions without --tz use the Gateway host timezone. --tz is not valid with --every or --on-exit.

Recurring top-of-hour expressions (minute 0 with a wildcard hour field) are automatically staggered by up to 5 minutes to reduce load spikes. Use --exact to force precise timing, or --stagger 30s for an explicit window (cron schedules only).

Stream Sources

A stream schedule keeps an operator-authored argv command running under the Gateway and fires the job from its stdout and stderr lines. Stream schedules are event-driven, never time-due, and require cron.triggers.enabled: true because the long-lived command has the same unattended trust class as trigger scripts. Disabling or removing the job stops the process; Gateway shutdown waits for process-tree teardown. Fast failures restart with cron's built-in error backoff. Five consecutive runs shorter than 60 seconds leave the job in an error state and use the normal failure-alert path; manually re-enable the job to clear the restart cap.

openclaw cron add \
  --name "Build event stream" \
  --stream-command '["node","scripts/build-events.mjs"]' \
  --stream-mode match \
  --stream-match '^(failed|recovered):' \
  --stream-batch-ms 250 \
  --session isolated \
  --message "Investigate these build events."

mode: "line" (the default) accepts every line. mode: "match" accepts only lines matching the compiled match regex. A batch closes after batchMs of quiet (default 250 ms, clamped to 50, 5000) or at maxBatchBytes (default 16384, clamped to 1024, 65536). At the byte cap the batch ends with [truncated]. Match mode always evaluates complete lines against their full text, even past maxBatchBytes (only the delivered batch is truncated); a line cut at the bounded raw-intake limit is only a prefix, so it is treated as unmatched rather than letting an end-anchored pattern fire on the cut.

The batch is appended to the system-event text or agent-turn message. Command payloads are rejected for stream schedules because the source command and payload command would have ambiguous process ownership. Only one payload fire and one bounded pending batch are retained per job. Lines arriving while a payload runs, or before the built-in 30-second trigger interval has elapsed, coalesce into that pending batch rather than building an unbounded queue. One serialized owner records gate drops, payload errors, and not-running dispatches in streamDroppedBatches; bounded merges increment streamCoalescedBatches. Failed payloads are not retried because they may not be idempotent.

A logical source identity remains stable across supervised child restarts, but rotates when the source is disabled, removed, or replaced, so queued batches from the retired source cannot fire even after an A-to-B-to-A edit. After a stop completes, late callbacks from an old child are inert. V1 does not include a native WebSocket source; bridge one with an argv command such as websocat wss://example.invalid/events.

When a stream job also has trigger.script, the gate runs once per closed batch. The current batch is available as the deeply frozen trigger.streamBatch string alongside trigger.state. fire: false drops that batch after persisting gate state. fire: true keeps existing trigger message semantics, then appends the batch to the resulting payload. A stream job may instead use a script payload without a condition gate; that script receives the batch through the same trigger.streamBatch value. Combining a script payload with a condition gate is rejected because both would own the persisted trigger.state slot.

Dynamic Cadence (Pacing)

Recurring jobs can set pacing.min and/or pacing.max to duration strings such as 15m or 4h; at least one bound is required. Use --pacing-min and --pacing-max with cron add|edit (--clear-pacing removes both bounds). During an isolated run, a paced job can call the cron tool with action: "next_check" and in: "30m". The proposal applies only to that currently running job and is measured from successful run completion. OpenClaw silently clamps it to the configured bounds. Pacing without a proposal leaves the normal schedule unchanged. Failed, timed-out, and skipped runs discard the proposal, so existing retry and error-backoff behavior takes precedence. Manually forcing a recurring job is out-of-band and preserves its pending natural or paced slot. For condition-triggered jobs, the built-in minimum interval remains a lower bound even when a proposal requests an earlier check.

Day-of-Month and Day-of-Week Use OR Logic

Cron expressions are parsed by croner. When both the day-of-month and day-of-week fields are non-wildcard, croner matches when either field matches, not both. This is standard Vixie cron behavior.

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual: "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

This fires roughly 5-6 times a month instead of 0-1 times a month. To require both conditions, use croner's + day-of-week modifier (0 9 15 * +1), or schedule on one field and guard the other in your job's prompt or command.

Event Triggers (Condition Watchers)

An event trigger adds a headless condition script to an every, cron, or stream schedule. Time schedules evaluate it when due; stream schedules evaluate it for each closed batch. Cron runs the normal payload only when the script returns fire: true:

{
  schedule: {
    kind: "every",
    everyMs: 30000
  },
  trigger: {
    // Fires only when the observed status differs from the last evaluation.
    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \'.[].state\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",
    once: false,
  },
  payload: {
    kind: "agentTurn",
    message: "Investigate the CI status change."
  },
}

The script must return { fire, message?, state? }. The previous JSON state is available as the deeply frozen trigger.state; stream gates also receive the current batch as trigger.streamBatch. Return a new state value to persist it. State is capped at 16 KB. When a firing result includes message, cron appends it to the system-event text or agent-turn message before execution. once: true disables the job after its first successful fired payload. fire: false persists evaluation state and counters, then reschedules without creating run history. If a fired payload run fails, the returned state is not persisted, the next evaluation sees the previous state and can fire again, so write scripts as read-only checks and keep actions in the payload.

Trigger schedules have a built-in minimum interval of 30 seconds. Each evaluation has a 30-second wall-clock budget and up to 5 tool calls. Author watchers around actionable state, not only success: a watcher that goes quiet when its check fails or times out looks healthy while broken. Compare the observation with trigger.state and return fresh state to deduplicate; do not rely on model or process memory. When firing, make message self-contained because it becomes the fired run's complete event context.

Create a watcher from a local script file (- reads the script from stdin):

openclaw cron add \
  --name "PR CI watcher" \
  --every 30s \
  --trigger-script ./watch-pr-ci.js \
  --message "Respond to the CI status change" \
  --session isolated

Payloads

Every job carries exactly one payload kind, chosen by flag:

One additional payload kind, heartbeat, is system-owned: the gateway converges one heartbeat monitor job per heartbeat-enabled agent. It appears in cron list --all but cannot be created manually.

Auth Credential Semantics

Auth credential semantics keep selection-time and runtime auth behavior aligned. They are shared by:

• resolveAuthProfileOrder (profile ordering)
• resolveApiKeyForProfile (runtime credential resolution)
• openclaw models status --probe
• openclaw doctor auth checks (doctor-auth)

Stable Probe Reason Codes

Probe results carry a status bucket (ok, auth, rate_limit, billing, timeout, format, unknown, no_model) plus a stable reasonCode when the probe never reached a model call:

Eligibility checks report ok as the reason code for usable credentials.

Token Credentials

Token credentials (type: "token") support inline token and/or tokenRef.

Eligibility Rules

• A token profile is ineligible when both token and tokenRef are absent (missing_credential).
• expires is optional. When present it must be a finite number of Unix epoch milliseconds greater than 0 and no larger than the maximum JavaScript Date timestamp (8640000000000000).
• If expires is invalid (wrong type, NaN, 0, negative, non-finite, or beyond that maximum), the profile is ineligible with invalid_expires.
• If expires is in the past, the profile is ineligible with expired.
• tokenRef does not bypass expires validation.

Resolution Rules

• Resolver semantics match eligibility semantics for expires.
• For eligible profiles, token material may be resolved from the inline value or tokenRef.
• Unresolvable refs produce unresolved_ref in models status --probe output.

Agent Copy Portability

Agent auth inheritance is read-through. When an agent has no local profile, it resolves profiles from the default/main agent store at runtime without copying secret material into its own credential store (agents/<id>/agent/openclaw-agent.sqlite).

Explicit copy flows, such as openclaw agents add, use this portability policy:

• api_key and token profiles are portable unless copyToAgents: false.
• oauth profiles are not portable by default because refresh tokens can be single-use or rotation-sensitive.
• Provider-owned OAuth flows may opt in with copyToAgents: true only when copying refresh material across agents is known safe; the opt-in only applies when the profile carries inline access/refresh material.

Non-portable profiles remain available through read-through inheritance unless the target agent signs in separately and creates its own local profile.

Config-Only Auth Routes

auth.profiles entries with mode: "aws-sdk" are routing metadata, not stored credentials. They are valid when the target provider uses models.providers.<provider>.auth: "aws-sdk", the route the plugin-owned Amazon Bedrock setup writes. These profile ids may appear in auth.order and session overrides even when no matching entry exists in the credential store.

Do not write type: "aws-sdk" into the credential store; stored credentials are only api_key, token, or oauth. If a legacy auth-profiles.json has such a marker, openclaw doctor --fix moves it to auth.profiles and removes the marker from the store.

Explicit Auth Order Filtering

• When auth.order.<provider> or the auth-store order override is set for a provider, models status --probe only probes profile ids that remain in the resolved auth order for that provider. The stored override wins over auth.order config.
• A stored profile for that provider that is omitted from the explicit order is not silently tried later. Probe output reports it with reasonCode: excluded_by_auth_order and the detail Excluded by auth.order for this provider.

Probe Target Resolution

• Probe targets can come from auth profiles, environment credentials, or models.json (result source: profile, env, models.json).
• If a provider has credentials but OpenClaw cannot resolve a probeable model candidate for it, models status --probe reports status: no_model with reasonCode: no_model.

External CLI Credential Discovery

• Runtime-only credentials owned by external CLIs (Claude CLI for claude-cli, Codex CLI for openai, MiniMax CLI for minimax-portal) are discovered only when the provider, runtime, or auth profile is in scope for the current operation, or when a stored local profile for that external source already exists.
• Auth-store callers choose an explicit external-CLI discovery mode: none for persisted/plugin auth only, existing for refreshing already stored external CLI profiles, or scoped for a concrete provider/profile set.
• Read-only/status paths pass allowKeychainPrompt: false; they use file-backed external CLI credentials only and do not read or reuse macOS Keychain results.

OAuth SecretRef Policy Guard

SecretRef input is for static credentials only. OAuth credentials are runtime-mutable (refresh flows persist rotated tokens), so SecretRef-backed OAuth material would split mutable state across stores.

• If a profile credential is type: "oauth", SecretRef objects are rejected for any credential material field on that profile.
• If auth.profiles.<profile>.mode is "oauth", SecretRef-backed keyRef/tokenRef input for that profile is rejected.
• Violations are hard failures (thrown errors) in startup/reload secret preparation and profile resolution paths.

Legacy-Compatible Messaging

For script compatibility, probe errors keep this first line unchanged:

Auth profile credentials are missing or expired.

Human-friendly detail and the stable reason code follow on subsequent lines in the form ↳ Auth reason [code]: ....

Agent Runtime Architecture

OpenClaw owns the built-in agent runtime. Runtime code lives under src/agents/, model/provider transport lives under src/llm/, and plugin-facing contracts are exposed through openclaw/plugin-sdk/* barrels.

Runtime Layout

Boundaries

Core calls the built-in runtime through OpenClaw modules and SDK barrels; no external agent framework packages remain. Plugins use documented openclaw/plugin-sdk/* entrypoints and do not import src/** internals.

@earendil-works/pi-tui remains a third-party dependency: a terminal component toolkit used by the local TUI and session tool renderers. Internalizing it would be a separate vendoring effort.

Manifests

Resource packages declare OpenClaw resources in package.json metadata. Entries are file paths or globs relative to the package root:

{
  "openclaw": {
    "extensions": ["extensions/index.ts"],
    "skills": ["skills/*.md"],
    "prompts": ["prompts/*.md"],
    "themes": ["themes/*.json"]
  }
}

Resource types not listed in a manifest fall back to discovery of conventional extensions/, skills/, prompts/, and themes/ directories.

Runtime Selection

• The built-in runtime id is openclaw. The legacy alias pi normalizes to openclaw; codex-app-server normalizes to codex.
• Plugin harnesses register additional runtime ids (for example codex).
• Runtime policy is model/provider-scoped agentRuntime.id config (model entry wins over provider entry). Unset or default resolves to auto.
• auto selects a registered plugin harness that supports the effective provider route, otherwise the built-in OpenClaw runtime. A provider or model prefix alone never selects a harness.
• OpenAI may select codex implicitly only for an exact official HTTPS Platform Responses or ChatGPT Responses route with no authored request override. Completions adapters, custom endpoints, and routes with authored request behavior stay on openclaw; plaintext official HTTP endpoints are rejected. See OpenAI implicit agent runtime.

Model Runtime Generations

Gateway startup and config, plugin, or auth publication build one prepared model runtime generation per configured agent. Each generation owns the discovered auth template, model registry, and projected model catalog as one atomic snapshot. Agent runs fork mutable auth and registry stores from that snapshot; browse, status, cron, doctor, TUI, PDF, and image paths read the published catalog instead of repeating filesystem discovery.

Standalone embedded runtimes publish the same snapshot shape at their activation boundary. A failed or stale generation is never served alongside a newer partial generation; the lifecycle owner must publish a complete replacement first.

Troubleshooting

General Gateway Diagnostics

Run openclaw doctor after editing access-control config or auth settings. It catches many invalid allowlist and policy combinations before runtime. For auth-specific checks, use openclaw doctor --auth or doctor-auth.

Channel Troubleshooting

• If a channel does not connect, check that the Gateway is running and the channel plugin is installed. For official plugins, run openclaw plugins install @openclaw/<channel-name>.
• For Telegram, ensure the bot token is correct and the bot is not in privacy mode if you need ambient room events.
• For Slack, verify the channel ID (not the name) and that the app has the required scopes (channels:history, groups:history, mpim:history).
• For Discord, confirm the bot has the Server Members Intent enabled for channel audience access groups.

Ambient Room Troubleshooting

If the room shows typing or token usage but no visible message:

• Confirm the room is allowed by the channel allowlist and sender allowlist.
• Confirm requireMention: false is set at the room level you expect.
• Check whether messages.groupChat.unmentionedInbound or the agent override is "room_event".
• Inspect logs for suppressed final payload metadata or didSendViaMessagingTool: false.
• For normal group requests, keep or restore messages.groupChat.visibleReplies: "automatic" if you want final replies posted automatically. For ambient rooms using message_tool, use a model/runtime that reliably calls tools.
• If Telegram ambient rooms do not trigger at all, check BotFather privacy mode and verify the Gateway is receiving normal group messages.
• If Slack ambient rooms do not trigger, verify the channel key is the Slack channel ID and the app has the history scope for that room type.

Cron Troubleshooting

• If a cron job does not fire, confirm the Gateway is running. Cron runs inside the Gateway process.
• Check openclaw cron list to see if the job exists and is enabled.
• Check openclaw cron runs -- <id> for run history and errors.
• For stream schedules, verify the source command is correct and the Gateway has cron.triggers.enabled: true.
• For event triggers, check the script output and ensure it returns fire: true when conditions are met.
• If a job times out, adjust --timeout-seconds or check the agent's timeoutSeconds config.

Auth Troubleshooting

• Run openclaw models status --probe to check credential health. Look for reasonCode values like missing_credential, expired, or unresolved_ref.
• If a profile is excluded, check auth.order for that provider.
• If a SecretRef is unresolved, verify the secret exists and is accessible.
• For OAuth issues, ensure the refresh flow is working and the profile is not using SecretRef (which is rejected for OAuth).

Going Further

Now that you have the Gateway running and channels connected, explore these next steps from the documentation:

• Multi-agent routing: Set up isolated sessions per agent, workspace, or sender. See the Agents documentation.
• Standing Orders: Give the agent persistent instructions and authority boundaries using AGENTS.md files. Combine with cron for time-based enforcement.
• Task Flow: Orchestrate durable multi-step flows above individual tasks. Use openclaw tasks flow list|show|cancel for inspection.
• Plugin Development: Build your own channel plugins or harnesses using the openclaw/plugin-sdk/* entrypoints. See the Plugin SDK documentation.
• Security Hardening: Lock down channels with allowlists, access groups, and mention rules. Review the Security documentation.
• Remote Access: Set up SSH or Tailscale to access the Control UI from anywhere. See the Remote Access documentation.
• Mobile Nodes: Pair iOS and Android nodes for Canvas, camera, and voice-enabled workflows. See the Nodes documentation.
• ClawHub: Browse the plugin marketplace for community-maintained channels and tools. See the ClawHub documentation.