Initial commit: OpenClaw Skill Collection

6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
2026-03-13 10:58:30 +08:00
commit 4c966a3ad2
884 changed files with 140761 additions and 0 deletions
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/auth-monitoring.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/auth-monitoring.md
@@ -0,0 +1,42 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Auth Monitoring
+
+# Auth monitoring
+
+OpenClaw exposes OAuth expiry health via `openclaw models status`. Use that for
+automation and alerting; scripts are optional extras for phone workflows.
+
+## Preferred: CLI check (portable)
+
+```bash  theme={null}
+openclaw models status --check
+```
+
+Exit codes:
+
+* `0`: OK
+* `1`: expired or missing credentials
+* `2`: expiring soon (within 24h)
+
+This works in cron/systemd and requires no extra scripts.
+
+## Optional scripts (ops / phone workflows)
+
+These live under `scripts/` and are **optional**. They assume SSH access to the
+gateway host and are tuned for systemd + Termux.
+
+* `scripts/claude-auth-status.sh` now uses `openclaw models status --json` as the
+  source of truth (falling back to direct file reads if the CLI is unavailable),
+  so keep `openclaw` on `PATH` for timers.
+* `scripts/auth-monitor.sh`: cron/systemd timer target; sends alerts (ntfy or phone).
+* `scripts/systemd/openclaw-auth-monitor.{service,timer}`: systemd user timer.
+* `scripts/claude-auth-status.sh`: Claude Code + OpenClaw auth checker (full/json/simple).
+* `scripts/mobile-reauth.sh`: guided re‑auth flow over SSH.
+* `scripts/termux-quick-auth.sh`: one‑tap widget status + open auth URL.
+* `scripts/termux-auth-widget.sh`: full guided widget flow.
+* `scripts/termux-sync-widget.sh`: sync Claude Code creds → OpenClaw.
+
+If you don’t need phone automation or systemd timers, skip these scripts.
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/cron-jobs.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/cron-jobs.md
@@ -0,0 +1,475 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cron Jobs
+
+# Cron jobs (Gateway scheduler)
+
+> **Cron vs Heartbeat?** See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for guidance on when to use each.
+
+Cron is the Gateway’s built-in scheduler. It persists jobs, wakes the agent at
+the right time, and can optionally deliver output back to a chat.
+
+If you want *“run this every morning”* or *“poke the agent in 20 minutes”*,
+cron is the mechanism.
+
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
+## TL;DR
+
+* Cron runs **inside the Gateway** (not inside the model).
+* Jobs persist under `~/.openclaw/cron/` so restarts don’t lose schedules.
+* Two execution styles:
+  * **Main session**: enqueue a system event, then run on the next heartbeat.
+  * **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default or none).
+* Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
+
+## Quick start (actionable)
+
+Create a one-shot reminder, verify it exists, and run it immediately:
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Reminder" \
+  --at "2026-02-01T16:00:00Z" \
+  --session main \
+  --system-event "Reminder: check the cron docs draft" \
+  --wake now \
+  --delete-after-run
+
+openclaw cron list
+openclaw cron run <job-id>
+openclaw cron runs --id <job-id>
+```
+
+Schedule a recurring isolated job with delivery:
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel slack \
+  --to "channel:C1234567890"
+```
+
+## Tool-call equivalents (Gateway cron tool)
+
+For the canonical JSON shapes and examples, see [JSON schema for tool calls](/automation/cron-jobs#json-schema-for-tool-calls).
+
+## Where cron jobs are stored
+
+Cron jobs are persisted on the Gateway host at `~/.openclaw/cron/jobs.json` by default.
+The Gateway loads the file into memory and writes it back on changes, so manual edits
+are only safe when the Gateway is stopped. Prefer `openclaw cron add/edit` or the cron
+tool call API for changes.
+
+## Beginner-friendly overview
+
+Think of a cron job as: **when** to run + **what** to do.
+
+1. **Choose a schedule**
+   * One-shot reminder → `schedule.kind = "at"` (CLI: `--at`)
+   * Repeating job → `schedule.kind = "every"` or `schedule.kind = "cron"`
+   * If your ISO timestamp omits a timezone, it is treated as **UTC**.
+
+2. **Choose where it runs**
+   * `sessionTarget: "main"` → run during the next heartbeat with main context.
+   * `sessionTarget: "isolated"` → run a dedicated agent turn in `cron:<jobId>`.
+
+3. **Choose the payload**
+   * Main session → `payload.kind = "systemEvent"`
+   * Isolated session → `payload.kind = "agentTurn"`
+
+Optional: one-shot jobs (`schedule.kind = "at"`) delete after success by default. Set
+`deleteAfterRun: false` to keep them (they will disable after success).
+
+## Concepts
+
+### Jobs
+
+A cron job is a stored record with:
+
+* a **schedule** (when it should run),
+* a **payload** (what it should do),
+* optional **delivery mode** (announce or none).
+* optional **agent binding** (`agentId`): run the job under a specific agent; if
+  missing or unknown, the gateway falls back to the default agent.
+
+Jobs are identified by a stable `jobId` (used by CLI/Gateway APIs).
+In agent tool calls, `jobId` is canonical; legacy `id` is accepted for compatibility.
+One-shot jobs auto-delete after success by default; set `deleteAfterRun: false` to keep them.
+
+### Schedules
+
+Cron supports three schedule kinds:
+
+* `at`: one-shot timestamp via `schedule.at` (ISO 8601).
+* `every`: fixed interval (ms).
+* `cron`: 5-field cron expression with optional IANA timezone.
+
+Cron expressions use `croner`. If a timezone is omitted, the Gateway host’s
+local timezone is used.
+
+### Main vs isolated execution
+
+#### Main session jobs (system events)
+
+Main jobs enqueue a system event and optionally wake the heartbeat runner.
+They must use `payload.kind = "systemEvent"`.
+
+* `wakeMode: "now"` (default): event triggers an immediate heartbeat run.
+* `wakeMode: "next-heartbeat"`: event waits for the next scheduled heartbeat.
+
+This is the best fit when you want the normal heartbeat prompt + main-session context.
+See [Heartbeat](/gateway/heartbeat).
+
+#### Isolated jobs (dedicated cron sessions)
+
+Isolated jobs run a dedicated agent turn in session `cron:<jobId>`.
+
+Key behaviors:
+
+* Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
+* Each run starts a **fresh session id** (no prior conversation carry-over).
+* Default behavior: if `delivery` is omitted, isolated jobs announce a summary (`delivery.mode = "announce"`).
+* `delivery.mode` (isolated-only) chooses what happens:
+  * `announce`: deliver a summary to the target channel and post a brief summary to the main session.
+  * `none`: internal only (no delivery, no main-session summary).
+* `wakeMode` controls when the main-session summary posts:
+  * `now`: immediate heartbeat.
+  * `next-heartbeat`: waits for the next scheduled heartbeat.
+
+Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
+your main chat history.
+
+### Payload shapes (what runs)
+
+Two payload kinds are supported:
+
+* `systemEvent`: main-session only, routed through the heartbeat prompt.
+* `agentTurn`: isolated-session only, runs a dedicated agent turn.
+
+Common `agentTurn` fields:
+
+* `message`: required text prompt.
+* `model` / `thinking`: optional overrides (see below).
+* `timeoutSeconds`: optional timeout override.
+
+Delivery config (isolated jobs only):
+
+* `delivery.mode`: `none` | `announce`.
+* `delivery.channel`: `last` or a specific channel.
+* `delivery.to`: channel-specific target (phone/chat/channel id).
+* `delivery.bestEffort`: avoid failing the job if announce delivery fails.
+
+Announce delivery suppresses messaging tool sends for the run; use `delivery.channel`/`delivery.to`
+to target the chat instead. When `delivery.mode = "none"`, no summary is posted to the main session.
+
+If `delivery` is omitted for isolated jobs, OpenClaw defaults to `announce`.
+
+#### Announce delivery flow
+
+When `delivery.mode = "announce"`, cron delivers directly via the outbound channel adapters.
+The main agent is not spun up to craft or forward the message.
+
+Behavior details:
+
+* Content: delivery uses the isolated run's outbound payloads (text/media) with normal chunking and
+  channel formatting.
+* Heartbeat-only responses (`HEARTBEAT_OK` with no real content) are not delivered.
+* If the isolated run already sent a message to the same target via the message tool, delivery is
+  skipped to avoid duplicates.
+* Missing or invalid delivery targets fail the job unless `delivery.bestEffort = true`.
+* A short summary is posted to the main session only when `delivery.mode = "announce"`.
+* The main-session summary respects `wakeMode`: `now` triggers an immediate heartbeat and
+  `next-heartbeat` waits for the next scheduled heartbeat.
+
+### Model and thinking overrides
+
+Isolated jobs (`agentTurn`) can override the model and thinking level:
+
+* `model`: Provider/model string (e.g., `anthropic/claude-sonnet-4-20250514`) or alias (e.g., `opus`)
+* `thinking`: Thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`; GPT-5.2 + Codex models only)
+
+Note: You can set `model` on main-session jobs too, but it changes the shared main
+session model. We recommend model overrides only for isolated jobs to avoid
+unexpected context shifts.
+
+Resolution priority:
+
+1. Job payload override (highest)
+2. Hook-specific defaults (e.g., `hooks.gmail.model`)
+3. Agent config default
+
+### Delivery (channel + target)
+
+Isolated jobs can deliver output to a channel via the top-level `delivery` config:
+
+* `delivery.mode`: `announce` (deliver a summary) or `none`.
+* `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`.
+* `delivery.to`: channel-specific recipient target.
+
+Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
+
+If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
+“last route” (the last place the agent replied).
+
+Target format reminders:
+
+* Slack/Discord/Mattermost (plugin) targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
+* Telegram topics should use the `:topic:` form (see below).
+
+#### Telegram delivery targets (topics / forum threads)
+
+Telegram supports forum topics via `message_thread_id`. For cron delivery, you can encode
+the topic/thread into the `to` field:
+
+* `-1001234567890` (chat id only)
+* `-1001234567890:topic:123` (preferred: explicit topic marker)
+* `-1001234567890:123` (shorthand: numeric suffix)
+
+Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
+
+* `telegram:group:-1001234567890:topic:123`
+
+## JSON schema for tool calls
+
+Use these shapes when calling Gateway `cron.*` tools directly (agent tool calls or RPC).
+CLI flags accept human durations like `20m`, but tool calls should use an ISO 8601 string
+for `schedule.at` and milliseconds for `schedule.everyMs`.
+
+### cron.add params
+
+One-shot, main session job (system event):
+
+```json  theme={null}
+{
+  "name": "Reminder",
+  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
+  "sessionTarget": "main",
+  "wakeMode": "now",
+  "payload": { "kind": "systemEvent", "text": "Reminder text" },
+  "deleteAfterRun": true
+}
+```
+
+Recurring, isolated job with delivery:
+
+```json  theme={null}
+{
+  "name": "Morning brief",
+  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
+  "sessionTarget": "isolated",
+  "wakeMode": "next-heartbeat",
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Summarize overnight updates."
+  },
+  "delivery": {
+    "mode": "announce",
+    "channel": "slack",
+    "to": "channel:C1234567890",
+    "bestEffort": true
+  }
+}
+```
+
+Notes:
+
+* `schedule.kind`: `at` (`at`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
+* `schedule.at` accepts ISO 8601 (timezone optional; treated as UTC when omitted).
+* `everyMs` is milliseconds.
+* `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
+* Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun` (defaults to true for `at`),
+  `delivery`.
+* `wakeMode` defaults to `"now"` when omitted.
+
+### cron.update params
+
+```json  theme={null}
+{
+  "jobId": "job-123",
+  "patch": {
+    "enabled": false,
+    "schedule": { "kind": "every", "everyMs": 3600000 }
+  }
+}
+```
+
+Notes:
+
+* `jobId` is canonical; `id` is accepted for compatibility.
+* Use `agentId: null` in the patch to clear an agent binding.
+
+### cron.run and cron.remove params
+
+```json  theme={null}
+{ "jobId": "job-123", "mode": "force" }
+```
+
+```json  theme={null}
+{ "jobId": "job-123" }
+```
+
+## Storage & history
+
+* Job store: `~/.openclaw/cron/jobs.json` (Gateway-managed JSON).
+* Run history: `~/.openclaw/cron/runs/<jobId>.jsonl` (JSONL, auto-pruned).
+* Override store path: `cron.store` in config.
+
+## Configuration
+
+```json5  theme={null}
+{
+  cron: {
+    enabled: true, // default true
+    store: "~/.openclaw/cron/jobs.json",
+    maxConcurrentRuns: 1, // default 1
+  },
+}
+```
+
+Disable cron entirely:
+
+* `cron.enabled: false` (config)
+* `OPENCLAW_SKIP_CRON=1` (env)
+
+## CLI quickstart
+
+One-shot reminder (UTC ISO, auto-delete after success):
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Send reminder" \
+  --at "2026-01-12T18:00:00Z" \
+  --session main \
+  --system-event "Reminder: submit expense report." \
+  --wake now \
+  --delete-after-run
+```
+
+One-shot reminder (main session, wake immediately):
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Calendar check" \
+  --at "20m" \
+  --session main \
+  --system-event "Next heartbeat: check calendar." \
+  --wake now
+```
+
+Recurring isolated job (announce to WhatsApp):
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Morning status" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize inbox + calendar for today." \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+Recurring isolated job (deliver to a Telegram topic):
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Nightly summary (topic)" \
+  --cron "0 22 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize today; send to the nightly topic." \
+  --announce \
+  --channel telegram \
+  --to "-1001234567890:topic:123"
+```
+
+Isolated job with model and thinking override:
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 1" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Weekly deep analysis of project progress." \
+  --model "opus" \
+  --thinking high \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+Agent selection (multi-agent setups):
+
+```bash  theme={null}
+# Pin a job to agent "ops" (falls back to default if that agent is missing)
+openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
+
+# Switch or clear the agent on an existing job
+openclaw cron edit <jobId> --agent ops
+openclaw cron edit <jobId> --clear-agent
+```
+
+Manual run (force is the default, use `--due` to only run when due):
+
+```bash  theme={null}
+openclaw cron run <jobId>
+openclaw cron run <jobId> --due
+```
+
+Edit an existing job (patch fields):
+
+```bash  theme={null}
+openclaw cron edit <jobId> \
+  --message "Updated prompt" \
+  --model "opus" \
+  --thinking low
+```
+
+Run history:
+
+```bash  theme={null}
+openclaw cron runs --id <jobId> --limit 50
+```
+
+Immediate system event without creating a job:
+
+```bash  theme={null}
+openclaw system event --mode now --text "Next heartbeat: check battery."
+```
+
+## Gateway API surface
+
+* `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`
+* `cron.run` (force or due), `cron.runs`
+  For immediate system events without a job, use [`openclaw system event`](/cli/system).
+
+## Troubleshooting
+
+### “Nothing runs”
+
+* Check cron is enabled: `cron.enabled` and `OPENCLAW_SKIP_CRON`.
+* Check the Gateway is running continuously (cron runs inside the Gateway process).
+* For `cron` schedules: confirm timezone (`--tz`) vs the host timezone.
+
+### A recurring job keeps delaying after failures
+
+* OpenClaw applies exponential retry backoff for recurring jobs after consecutive errors:
+  30s, 1m, 5m, 15m, then 60m between retries.
+* Backoff resets automatically after the next successful run.
+* One-shot (`at`) jobs disable after a terminal run (`ok`, `error`, or `skipped`) and do not retry.
+
+### Telegram delivers to the wrong place
+
+* For forum topics, use `-100…:topic:<id>` so it’s explicit and unambiguous.
+* If you see `telegram:...` prefixes in logs or stored “last route” targets, that’s normal;
+  cron delivery accepts them and still parses topic IDs correctly.
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/cron-vs-heartbeat.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/cron-vs-heartbeat.md
@@ -0,0 +1,279 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Cron vs Heartbeat
+
+# Cron vs Heartbeat: When to Use Each
+
+Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your use case.
+
+## Quick Decision Guide
+
+| Use Case                             | Recommended         | Why                                      |
+| ------------------------------------ | ------------------- | ---------------------------------------- |
+| Check inbox every 30 min             | Heartbeat           | Batches with other checks, context-aware |
+| Send daily report at 9am sharp       | Cron (isolated)     | Exact timing needed                      |
+| Monitor calendar for upcoming events | Heartbeat           | Natural fit for periodic awareness       |
+| Run weekly deep analysis             | Cron (isolated)     | Standalone task, can use different model |
+| Remind me in 20 minutes              | Cron (main, `--at`) | One-shot with precise timing             |
+| Background project health check      | Heartbeat           | Piggybacks on existing cycle             |
+
+## Heartbeat: Periodic Awareness
+
+Heartbeats run in the **main session** at a regular interval (default: 30 min). They're designed for the agent to check on things and surface anything important.
+
+### When to use heartbeat
+
+* **Multiple periodic checks**: Instead of 5 separate cron jobs checking inbox, calendar, weather, notifications, and project status, a single heartbeat can batch all of these.
+* **Context-aware decisions**: The agent has full main-session context, so it can make smart decisions about what's urgent vs. what can wait.
+* **Conversational continuity**: Heartbeat runs share the same session, so the agent remembers recent conversations and can follow up naturally.
+* **Low-overhead monitoring**: One heartbeat replaces many small polling tasks.
+
+### Heartbeat advantages
+
+* **Batches multiple checks**: One agent turn can review inbox, calendar, and notifications together.
+* **Reduces API calls**: A single heartbeat is cheaper than 5 isolated cron jobs.
+* **Context-aware**: The agent knows what you've been working on and can prioritize accordingly.
+* **Smart suppression**: If nothing needs attention, the agent replies `HEARTBEAT_OK` and no message is delivered.
+* **Natural timing**: Drifts slightly based on queue load, which is fine for most monitoring.
+
+### Heartbeat example: HEARTBEAT.md checklist
+
+```md  theme={null}
+# Heartbeat checklist
+
+- Check email for urgent messages
+- Review calendar for events in next 2 hours
+- If a background task finished, summarize results
+- If idle for 8+ hours, send a brief check-in
+```
+
+The agent reads this on each heartbeat and handles all items in one turn.
+
+### Configuring heartbeat
+
+```json5  theme={null}
+{
+  agents: {
+    defaults: {
+      heartbeat: {
+        every: "30m", // interval
+        target: "last", // where to deliver alerts
+        activeHours: { start: "08:00", end: "22:00" }, // optional
+      },
+    },
+  },
+}
+```
+
+See [Heartbeat](/gateway/heartbeat) for full configuration.
+
+## Cron: Precise Scheduling
+
+Cron jobs run at **exact times** and can run in isolated sessions without affecting main context.
+
+### When to use cron
+
+* **Exact timing required**: "Send this at 9:00 AM every Monday" (not "sometime around 9").
+* **Standalone tasks**: Tasks that don't need conversational context.
+* **Different model/thinking**: Heavy analysis that warrants a more powerful model.
+* **One-shot reminders**: "Remind me in 20 minutes" with `--at`.
+* **Noisy/frequent tasks**: Tasks that would clutter main session history.
+* **External triggers**: Tasks that should run independently of whether the agent is otherwise active.
+
+### Cron advantages
+
+* **Exact timing**: 5-field cron expressions with timezone support.
+* **Session isolation**: Runs in `cron:<jobId>` without polluting main history.
+* **Model overrides**: Use a cheaper or more powerful model per job.
+* **Delivery control**: Isolated jobs default to `announce` (summary); choose `none` as needed.
+* **Immediate delivery**: Announce mode posts directly without waiting for heartbeat.
+* **No agent context needed**: Runs even if main session is idle or compacted.
+* **One-shot support**: `--at` for precise future timestamps.
+
+### Cron example: Daily morning briefing
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Morning briefing" \
+  --cron "0 7 * * *" \
+  --tz "America/New_York" \
+  --session isolated \
+  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
+  --model opus \
+  --announce \
+  --channel whatsapp \
+  --to "+15551234567"
+```
+
+This runs at exactly 7:00 AM New York time, uses Opus for quality, and announces a summary directly to WhatsApp.
+
+### Cron example: One-shot reminder
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Meeting reminder" \
+  --at "20m" \
+  --session main \
+  --system-event "Reminder: standup meeting starts in 10 minutes." \
+  --wake now \
+  --delete-after-run
+```
+
+See [Cron jobs](/automation/cron-jobs) for full CLI reference.
+
+## Decision Flowchart
+
+```
+Does the task need to run at an EXACT time?
+  YES -> Use cron
+  NO  -> Continue...
+
+Does the task need isolation from main session?
+  YES -> Use cron (isolated)
+  NO  -> Continue...
+
+Can this task be batched with other periodic checks?
+  YES -> Use heartbeat (add to HEARTBEAT.md)
+  NO  -> Use cron
+
+Is this a one-shot reminder?
+  YES -> Use cron with --at
+  NO  -> Continue...
+
+Does it need a different model or thinking level?
+  YES -> Use cron (isolated) with --model/--thinking
+  NO  -> Use heartbeat
+```
+
+## Combining Both
+
+The most efficient setup uses **both**:
+
+1. **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
+2. **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders.
+
+### Example: Efficient automation setup
+
+**HEARTBEAT.md** (checked every 30 min):
+
+```md  theme={null}
+# Heartbeat checklist
+
+- Scan inbox for urgent emails
+- Check calendar for events in next 2h
+- Review any pending tasks
+- Light check-in if quiet for 8+ hours
+```
+
+**Cron jobs** (precise timing):
+
+```bash  theme={null}
+# Daily morning briefing at 7am
+openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce
+
+# Weekly project review on Mondays at 9am
+openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus
+
+# One-shot reminder
+openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
+```
+
+## Lobster: Deterministic workflows with approvals
+
+Lobster is the workflow runtime for **multi-step tool pipelines** that need deterministic execution and explicit approvals.
+Use it when the task is more than a single agent turn, and you want a resumable workflow with human checkpoints.
+
+### When Lobster fits
+
+* **Multi-step automation**: You need a fixed pipeline of tool calls, not a one-off prompt.
+* **Approval gates**: Side effects should pause until you approve, then resume.
+* **Resumable runs**: Continue a paused workflow without re-running earlier steps.
+
+### How it pairs with heartbeat and cron
+
+* **Heartbeat/cron** decide *when* a run happens.
+* **Lobster** defines *what steps* happen once the run starts.
+
+For scheduled workflows, use cron or heartbeat to trigger an agent turn that calls Lobster.
+For ad-hoc workflows, call Lobster directly.
+
+### Operational notes (from the code)
+
+* Lobster runs as a **local subprocess** (`lobster` CLI) in tool mode and returns a **JSON envelope**.
+* If the tool returns `needs_approval`, you resume with a `resumeToken` and `approve` flag.
+* The tool is an **optional plugin**; enable it additively via `tools.alsoAllow: ["lobster"]` (recommended).
+* If you pass `lobsterPath`, it must be an **absolute path**.
+
+See [Lobster](/tools/lobster) for full usage and examples.
+
+## Main Session vs Isolated Session
+
+Both heartbeat and cron can interact with the main session, but differently:
+
+|         | Heartbeat                       | Cron (main)              | Cron (isolated)            |
+| ------- | ------------------------------- | ------------------------ | -------------------------- |
+| Session | Main                            | Main (via system event)  | `cron:<jobId>`             |
+| History | Shared                          | Shared                   | Fresh each run             |
+| Context | Full                            | Full                     | None (starts clean)        |
+| Model   | Main session model              | Main session model       | Can override               |
+| Output  | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default) |
+
+### When to use main session cron
+
+Use `--session main` with `--system-event` when you want:
+
+* The reminder/event to appear in main session context
+* The agent to handle it during the next heartbeat with full context
+* No separate isolated run
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Check project" \
+  --every "4h" \
+  --session main \
+  --system-event "Time for a project health check" \
+  --wake now
+```
+
+### When to use isolated cron
+
+Use `--session isolated` when you want:
+
+* A clean slate without prior context
+* Different model or thinking settings
+* Announce summaries directly to a channel
+* History that doesn't clutter main session
+
+```bash  theme={null}
+openclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 0" \
+  --session isolated \
+  --message "Weekly codebase analysis..." \
+  --model opus \
+  --thinking high \
+  --announce
+```
+
+## Cost Considerations
+
+| Mechanism       | Cost Profile                                            |
+| --------------- | ------------------------------------------------------- |
+| Heartbeat       | One turn every N minutes; scales with HEARTBEAT.md size |
+| Cron (main)     | Adds event to next heartbeat (no isolated turn)         |
+| Cron (isolated) | Full agent turn per job; can use cheaper model          |
+
+**Tips**:
+
+* Keep `HEARTBEAT.md` small to minimize token overhead.
+* Batch similar checks into heartbeat instead of multiple cron jobs.
+* Use `target: "none"` on heartbeat if you only want internal processing.
+* Use isolated cron with a cheaper model for routine tasks.
+
+## Related
+
+* [Heartbeat](/gateway/heartbeat) - full heartbeat configuration
+* [Cron jobs](/automation/cron-jobs) - full cron CLI and API reference
+* [System](/cli/system) - system events + heartbeat controls
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/gmail-pubsub.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/gmail-pubsub.md
@@ -0,0 +1,254 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Gmail PubSub
+
+# Gmail Pub/Sub -> OpenClaw
+
+Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> OpenClaw webhook.
+
+## Prereqs
+
+* `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)).
+* `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)).
+* OpenClaw hooks enabled (see [Webhooks](/automation/webhook)).
+* `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint.
+  Other tunnel services can work, but are DIY/unsupported and require manual wiring.
+  Right now, Tailscale is what we support.
+
+Example hook config (enable Gmail preset mapping):
+
+```json5  theme={null}
+{
+  hooks: {
+    enabled: true,
+    token: "OPENCLAW_HOOK_TOKEN",
+    path: "/hooks",
+    presets: ["gmail"],
+  },
+}
+```
+
+To deliver the Gmail summary to a chat surface, override the preset with a mapping
+that sets `deliver` + optional `channel`/`to`:
+
+```json5  theme={null}
+{
+  hooks: {
+    enabled: true,
+    token: "OPENCLAW_HOOK_TOKEN",
+    presets: ["gmail"],
+    mappings: [
+      {
+        match: { path: "gmail" },
+        action: "agent",
+        wakeMode: "now",
+        name: "Gmail",
+        sessionKey: "hook:gmail:{{messages[0].id}}",
+        messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+        model: "openai/gpt-5.2-mini",
+        deliver: true,
+        channel: "last",
+        // to: "+15551234567"
+      },
+    ],
+  },
+}
+```
+
+If you want a fixed channel, set `channel` + `to`. Otherwise `channel: "last"`
+uses the last delivery route (falls back to WhatsApp).
+
+To force a cheaper model for Gmail runs, set `model` in the mapping
+(`provider/model` or alias). If you enforce `agents.defaults.models`, include it there.
+
+To set a default model and thinking level specifically for Gmail hooks, add
+`hooks.gmail.model` / `hooks.gmail.thinking` in your config:
+
+```json5  theme={null}
+{
+  hooks: {
+    gmail: {
+      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+      thinking: "off",
+    },
+  },
+}
+```
+
+Notes:
+
+* Per-hook `model`/`thinking` in the mapping still overrides these defaults.
+* Fallback order: `hooks.gmail.model` → `agents.defaults.model.fallbacks` → primary (auth/rate-limit/timeouts).
+* If `agents.defaults.models` is set, the Gmail model must be in the allowlist.
+* Gmail hook content is wrapped with external-content safety boundaries by default.
+  To disable (dangerous), set `hooks.gmail.allowUnsafeExternalContent: true`.
+
+To customize payload handling further, add `hooks.mappings` or a JS/TS transform module
+under `hooks.transformsDir` (see [Webhooks](/automation/webhook)).
+
+## Wizard (recommended)
+
+Use the OpenClaw helper to wire everything together (installs deps on macOS via brew):
+
+```bash  theme={null}
+openclaw webhooks gmail setup \
+  --account openclaw@gmail.com
+```
+
+Defaults:
+
+* Uses Tailscale Funnel for the public push endpoint.
+* Writes `hooks.gmail` config for `openclaw webhooks gmail run`.
+* Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
+
+Path note: when `tailscale.mode` is enabled, OpenClaw automatically sets
+`hooks.gmail.serve.path` to `/` and keeps the public path at
+`hooks.gmail.tailscale.path` (default `/gmail-pubsub`) because Tailscale
+strips the set-path prefix before proxying.
+If you need the backend to receive the prefixed path, set
+`hooks.gmail.tailscale.target` (or `--tailscale-target`) to a full URL like
+`http://127.0.0.1:8788/gmail-pubsub` and match `hooks.gmail.serve.path`.
+
+Want a custom endpoint? Use `--push-endpoint <url>` or `--tailscale off`.
+
+Platform note: on macOS the wizard installs `gcloud`, `gogcli`, and `tailscale`
+via Homebrew; on Linux install them manually first.
+
+Gateway auto-start (recommended):
+
+* When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
+  `gog gmail watch serve` on boot and auto-renews the watch.
+* Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` to opt out (useful if you run the daemon yourself).
+* Do not run the manual daemon at the same time, or you will hit
+  `listen tcp 127.0.0.1:8788: bind: address already in use`.
+
+Manual daemon (starts `gog gmail watch serve` + auto-renew):
+
+```bash  theme={null}
+openclaw webhooks gmail run
+```
+
+## One-time setup
+
+1. Select the GCP project **that owns the OAuth client** used by `gog`.
+
+```bash  theme={null}
+gcloud auth login
+gcloud config set project <project-id>
+```
+
+Note: Gmail watch requires the Pub/Sub topic to live in the same project as the OAuth client.
+
+2. Enable APIs:
+
+```bash  theme={null}
+gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+```
+
+3. Create a topic:
+
+```bash  theme={null}
+gcloud pubsub topics create gog-gmail-watch
+```
+
+4. Allow Gmail push to publish:
+
+```bash  theme={null}
+gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+  --role=roles/pubsub.publisher
+```
+
+## Start the watch
+
+```bash  theme={null}
+gog gmail watch start \
+  --account openclaw@gmail.com \
+  --label INBOX \
+  --topic projects/<project-id>/topics/gog-gmail-watch
+```
+
+Save the `history_id` from the output (for debugging).
+
+## Run the push handler
+
+Local example (shared token auth):
+
+```bash  theme={null}
+gog gmail watch serve \
+  --account openclaw@gmail.com \
+  --bind 127.0.0.1 \
+  --port 8788 \
+  --path /gmail-pubsub \
+  --token <shared> \
+  --hook-url http://127.0.0.1:18789/hooks/gmail \
+  --hook-token OPENCLAW_HOOK_TOKEN \
+  --include-body \
+  --max-bytes 20000
+```
+
+Notes:
+
+* `--token` protects the push endpoint (`x-gog-token` or `?token=`).
+* `--hook-url` points to OpenClaw `/hooks/gmail` (mapped; isolated run + summary to main).
+* `--include-body` and `--max-bytes` control the body snippet sent to OpenClaw.
+
+Recommended: `openclaw webhooks gmail run` wraps the same flow and auto-renews the watch.
+
+## Expose the handler (advanced, unsupported)
+
+If you need a non-Tailscale tunnel, wire it manually and use the public URL in the push
+subscription (unsupported, no guardrails):
+
+```bash  theme={null}
+cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
+```
+
+Use the generated URL as the push endpoint:
+
+```bash  theme={null}
+gcloud pubsub subscriptions create gog-gmail-watch-push \
+  --topic gog-gmail-watch \
+  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
+```
+
+Production: use a stable HTTPS endpoint and configure Pub/Sub OIDC JWT, then run:
+
+```bash  theme={null}
+gog gmail watch serve --verify-oidc --oidc-email <svc@...>
+```
+
+## Test
+
+Send a message to the watched inbox:
+
+```bash  theme={null}
+gog gmail send \
+  --account openclaw@gmail.com \
+  --to openclaw@gmail.com \
+  --subject "watch test" \
+  --body "ping"
+```
+
+Check watch state and history:
+
+```bash  theme={null}
+gog gmail watch status --account openclaw@gmail.com
+gog gmail history --account openclaw@gmail.com --since <historyId>
+```
+
+## Troubleshooting
+
+* `Invalid topicName`: project mismatch (topic not in the OAuth client project).
+* `User not authorized`: missing `roles/pubsub.publisher` on the topic.
+* Empty messages: Gmail push only provides `historyId`; fetch via `gog gmail history`.
+
+## Cleanup
+
+```bash  theme={null}
+gog gmail watch stop --account openclaw@gmail.com
+gcloud pubsub subscriptions delete gog-gmail-watch-push
+gcloud pubsub topics delete gog-gmail-watch
+```
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/poll.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/poll.md
@@ -0,0 +1,67 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Polls
+
+# Polls
+
+## Supported channels
+
+* WhatsApp (web channel)
+* Discord
+* MS Teams (Adaptive Cards)
+
+## CLI
+
+```bash  theme={null}
+# WhatsApp
+openclaw message poll --target +15555550123 \
+  --poll-question "Lunch today?" --poll-option "Yes" --poll-option "No" --poll-option "Maybe"
+openclaw message poll --target 123456789@g.us \
+  --poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
+
+# Discord
+openclaw message poll --channel discord --target channel:123456789 \
+  --poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
+openclaw message poll --channel discord --target channel:123456789 \
+  --poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
+
+# MS Teams
+openclaw message poll --channel msteams --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" --poll-option "Pizza" --poll-option "Sushi"
+```
+
+Options:
+
+* `--channel`: `whatsapp` (default), `discord`, or `msteams`
+* `--poll-multi`: allow selecting multiple options
+* `--poll-duration-hours`: Discord-only (defaults to 24 when omitted)
+
+## Gateway RPC
+
+Method: `poll`
+
+Params:
+
+* `to` (string, required)
+* `question` (string, required)
+* `options` (string\[], required)
+* `maxSelections` (number, optional)
+* `durationHours` (number, optional)
+* `channel` (string, optional, default: `whatsapp`)
+* `idempotencyKey` (string, required)
+
+## Channel differences
+
+* WhatsApp: 2-12 options, `maxSelections` must be within option count, ignores `durationHours`.
+* Discord: 2-10 options, `durationHours` clamped to 1-768 hours (default 24). `maxSelections > 1` enables multi-select; Discord does not support a strict selection count.
+* MS Teams: Adaptive Card polls (OpenClaw-managed). No native poll API; `durationHours` is ignored.
+
+## Agent tool (Message)
+
+Use the `message` tool with `poll` action (`to`, `pollQuestion`, `pollOption`, optional `pollMulti`, `pollDurationHours`, `channel`).
+
+Note: Discord has no “pick exactly N” mode; `pollMulti` maps to multi-select.
+Teams polls are rendered as Adaptive Cards and require the gateway to stay online
+to record votes in `~/.openclaw/msteams-polls.json`.
--- a/openclaw-knowhow-skill/docs/infrastructure/automation/webhook.md
+++ b/openclaw-knowhow-skill/docs/infrastructure/automation/webhook.md
@@ -0,0 +1,161 @@
+> ## Documentation Index
+> Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
+> Use this file to discover all available pages before exploring further.
+
+# Webhooks
+
+# Webhooks
+
+Gateway can expose a small HTTP webhook endpoint for external triggers.
+
+## Enable
+
+```json5  theme={null}
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks",
+  },
+}
+```
+
+Notes:
+
+* `hooks.token` is required when `hooks.enabled=true`.
+* `hooks.path` defaults to `/hooks`.
+
+## Auth
+
+Every request must include the hook token. Prefer headers:
+
+* `Authorization: Bearer <token>` (recommended)
+* `x-openclaw-token: <token>`
+* `?token=<token>` (deprecated; logs a warning and will be removed in a future major release)
+
+## Endpoints
+
+### `POST /hooks/wake`
+
+Payload:
+
+```json  theme={null}
+{ "text": "System line", "mode": "now" }
+```
+
+* `text` **required** (string): The description of the event (e.g., "New email received").
+* `mode` optional (`now` | `next-heartbeat`): Whether to trigger an immediate heartbeat (default `now`) or wait for the next periodic check.
+
+Effect:
+
+* Enqueues a system event for the **main** session
+* If `mode=now`, triggers an immediate heartbeat
+
+### `POST /hooks/agent`
+
+Payload:
+
+```json  theme={null}
+{
+  "message": "Run this",
+  "name": "Email",
+  "sessionKey": "hook:email:msg-123",
+  "wakeMode": "now",
+  "deliver": true,
+  "channel": "last",
+  "to": "+15551234567",
+  "model": "openai/gpt-5.2-mini",
+  "thinking": "low",
+  "timeoutSeconds": 120
+}
+```
+
+* `message` **required** (string): The prompt or message for the agent to process.
+* `name` optional (string): Human-readable name for the hook (e.g., "GitHub"), used as a prefix in session summaries.
+* `sessionKey` optional (string): The key used to identify the agent's session. Defaults to a random `hook:<uuid>`. Using a consistent key allows for a multi-turn conversation within the hook context.
+* `wakeMode` optional (`now` | `next-heartbeat`): Whether to trigger an immediate heartbeat (default `now`) or wait for the next periodic check.
+* `deliver` optional (boolean): If `true`, the agent's response will be sent to the messaging channel. Defaults to `true`. Responses that are only heartbeat acknowledgments are automatically skipped.
+* `channel` optional (string): The messaging channel for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `mattermost` (plugin), `signal`, `imessage`, `msteams`. Defaults to `last`.
+* `to` optional (string): The recipient identifier for the channel (e.g., phone number for WhatsApp/Signal, chat ID for Telegram, channel ID for Discord/Slack/Mattermost (plugin), conversation ID for MS Teams). Defaults to the last recipient in the main session.
+* `model` optional (string): Model override (e.g., `anthropic/claude-3-5-sonnet` or an alias). Must be in the allowed model list if restricted.
+* `thinking` optional (string): Thinking level override (e.g., `low`, `medium`, `high`).
+* `timeoutSeconds` optional (number): Maximum duration for the agent run in seconds.
+
+Effect:
+
+* Runs an **isolated** agent turn (own session key)
+* Always posts a summary into the **main** session
+* If `wakeMode=now`, triggers an immediate heartbeat
+
+### `POST /hooks/<name>` (mapped)
+
+Custom hook names are resolved via `hooks.mappings` (see configuration). A mapping can
+turn arbitrary payloads into `wake` or `agent` actions, with optional templates or
+code transforms.
+
+Mapping options (summary):
+
+* `hooks.presets: ["gmail"]` enables the built-in Gmail mapping.
+* `hooks.mappings` lets you define `match`, `action`, and templates in config.
+* `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
+* Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
+* TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
+* Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
+  (`channel` defaults to `last` and falls back to WhatsApp).
+* `allowUnsafeExternalContent: true` disables the external content safety wrapper for that hook
+  (dangerous; only for trusted internal sources).
+* `openclaw webhooks gmail setup` writes `hooks.gmail` config for `openclaw webhooks gmail run`.
+  See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow.
+
+## Responses
+
+* `200` for `/hooks/wake`
+* `202` for `/hooks/agent` (async run started)
+* `401` on auth failure
+* `400` on invalid payload
+* `413` on oversized payloads
+
+## Examples
+
+```bash  theme={null}
+curl -X POST http://127.0.0.1:18789/hooks/wake \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"New email received","mode":"now"}'
+```
+
+```bash  theme={null}
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-openclaw-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'
+```
+
+### Use a different model
+
+Add `model` to the agent payload (or mapping) to override the model for that run:
+
+```bash  theme={null}
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'x-openclaw-token: SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'
+```
+
+If you enforce `agents.defaults.models`, make sure the override model is included there.
+
+```bash  theme={null}
+curl -X POST http://127.0.0.1:18789/hooks/gmail \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'
+```
+
+## Security
+
+* Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
+* Use a dedicated hook token; do not reuse gateway auth tokens.
+* Avoid including sensitive raw payloads in webhook logs.
+* Hook payloads are treated as untrusted and wrapped with safety boundaries by default.
+  If you must disable this for a specific hook, set `allowUnsafeExternalContent: true`
+  in that hook's mapping (dangerous).