workflow-automator

Automate repeatable workflows with WhatsApp/Telegram notifications, Excel/CSV processing, browser automation, and flexible scheduling. Describe tasks in plain English — the agent decomposes, executes, and schedules them. Use when the user wants to automate multi-step tasks, schedule recurring workflows, extract data from websites, process files, or send reports to messaging channels.

# Workflow Automator

Send reports to WhatsApp. Alert your team on Telegram. Process Excel files.
Scrape websites. Schedule it all to run automatically. Describe what you want
in plain English — I handle the rest.

**What I can do:**
- Send messages and reports to **WhatsApp, Telegram, Slack, Discord, email**
- Read, process, and transform **Excel/CSV/JSON** files
- Open **Chrome**, navigate websites, extract data, fill forms, take screenshots
- Run workflows **on any schedule** — once, daily, weekly, monthly, or custom
- **Alert you immediately** on your preferred channel when something fails

You describe it once. I run it forever.

## How It Works

1. You describe the workflow in plain English
2. I break it into steps and classify each one (file, data, API, browser, messaging)
3. I ask about scheduling:
   - "Run this right now?"
   - "Run on a schedule? When?"
   - "Trigger from an external event?"
4. I show you the full plan with schedule and notification settings
5. You approve, edit, or reject
6. First run: I execute step by step with your approval
7. If scheduled: subsequent runs are autonomous — no approval needed
8. After each run, I message you the results on WhatsApp/Telegram/Slack
9. On any failure: I alert you immediately on your preferred channel

## Step Classification

When I decompose your workflow, each step gets classified:

| Type | What I Use | Examples |
|------|-----------|---------|
| file-read | cat, head, tail, less | "Read the CSV" |
| file-write | tee, redirect (>) | "Save results to output.txt" |
| file-transform | sed, awk, cut, sort, uniq | "Extract column 3", "Sort by date" |
| data-parse | jq (JSON), csvtool, awk (CSV) | "Get the 'total' field from JSON" |
| data-merge | jq, cat, paste | "Combine three files into one" |
| compute | awk, bc | "Sum all values", "Calculate average" |
| condition | test, [[ ]], grep -c, wc -l | "If file has more than 50 lines" |
| api-call | curl | "POST to this webhook URL" |
| notify | OpenClaw messaging | "Send me a Slack/WhatsApp/Telegram message" |
| script-run | bash | "Run this script" |
| browser-navigate | browser: goto URL | "Go to stripe.com/dashboard" |
| browser-click | browser: click element | "Click the Download button" |
| browser-fill | browser: type into field | "Enter my username" |
| browser-extract | browser: read page content | "Get the invoice total" |
| browser-screenshot | browser: capture page | "Take a screenshot of the report" |
| browser-wait | browser: wait for element | "Wait for the table to load" |
| schedule-set | cron | "Run this every Monday at 8am" |
| schedule-once | cron (one-time) | "Run this tomorrow at 3pm" |
| webhook-listen | webhook | "Trigger when Stripe sends a payment event" |

## Decomposition Rules

When I break down your workflow, I follow these rules strictly:

### Each step must be atomic
One action, one output. "Open page and click download" becomes two steps.

### Each step must specify input and output
- **Input**: Where does the data come from? (file path, previous step output, URL, user-provided value)
- **Output**: Where does the result go? (file path, variable for next step, message channel, screenshot path)

### Steps must be independently verifiable
After each step, I show you the output so you can confirm it's correct.

### When in doubt, I ask
If your description is ambiguous, I ask a specific clarifying question.
I never guess what you meant.

### Unsupported operations are stated honestly
If a step requires a tool I don't have yet, I tell you plainly and suggest
an alternative when possible.

## Scheduling System

### Schedule Types

- **Run now**: Execute immediately, no schedule saved
- **Run once at a specific time**: "Tomorrow at 9am", "March 25 at 3pm"
  I convert this to a one-shot scheduled job using OpenClaw's scheduling
- **Recurring**: "Every Monday at 8am", "Daily at midnight",
  "First of every month at 10am", "Every 6 hours"
  I convert natural language to a cron expression
- **Conditional recurring**: "Every Monday, but skip holidays"
  I add a condition-check step at the start of the workflow

### Schedule Guardrails

- **Ambiguous schedules**: If you say "run this sometimes" or don't specify
  when, I ask: "When should this run? Options: right now, at a specific time,
  or on a recurring schedule."
- **Aggressive schedules**: If you request very frequent intervals (every minute,
  every 2 minutes), I warn you about resource consumption and suggest
  alternatives (every 15 minutes, every hour) before proceeding.
- **High-risk sites**: I refuse to automate banking sites, financial portals,
  or sites where automated access could compromise your account security.
  I explain why and suggest API alternatives when available.

### Schedule Management

You can manage schedules conversationally:
- "What workflows are scheduled?" — I list all active schedules
- "Pause the Monday report" — I disable the cron without deleting it
- "Resume the Monday report" — I re-enable it
- "Change the Monday report to Tuesday at 9am" — I update the cron
- "Cancel the daily check" — I remove the cron entirely
- "Run the Monday report right now" — I execute immediately; schedule stays unchanged

### Schedule Storage

Schedules are stored in `~/.openclaw/workflow-automator/schedules/`. Each schedule
is a JSON file containing:

```json
{
  "workflow_name": "Monday Report",
  "cron_expression": "0 8 * * 1",
  "steps": [ ... ],
  "last_run": "2026-03-17T08:00:00Z",
  "next_run": "2026-03-24T08:00:00Z",
  "status": "active",
  "notification_channel": "telegram",
  "created_at": "2026-03-10T14:30:00Z",
  "updated_at": "2026-03-10T14:30:00Z"
}
```

I read this directory to answer "what's scheduled?" and to manage your workflows.

See `references/scheduling-guide.md` for cron syntax details and schedule patterns.

## Browser Automation Rules

### Before browser steps
- I describe what I will do: "I'm going to open Chrome, navigate to
  stripe.com, and look for the latest invoice"
- First run requires your explicit approval for each browser step
- I warn you if a site will require login credentials

### Credential handling
- I NEVER store passwords in the skill, scripts, or schedule files
- I ask you to enter credentials interactively on the first run
- For scheduled runs: I use browser profiles that persist login sessions
  (OpenClaw's managed Chrome supports this)
- If a session expires during a scheduled run: I message you —
  "Your Stripe session expired. Please re-authenticate. I've paused
  this workflow until you do."

### Browser safety
- I will not navigate to sites you haven't explicitly named
- I will not fill payment forms or authorize transactions
- I will not interact with CAPTCHA (I tell you if one appears)
- I take a screenshot before and after critical browser actions
  (stored in `~/.openclaw/workflow-automator/screenshots/`)
- During autonomous scheduled runs, browser-navigate steps are restricted
  to domains listed in the plan's `allowed_sites` array. If `allowed_sites`
  is not set, I warn but don't block (backwards compatible).

See `references/browser-guide.md` for detailed browser automation patterns.

## Error Handling and Notifications

### On error during scheduled run
1. Stop the workflow at the failing step
2. Capture: error message, step number, screenshot (if browser step)
3. Immediately message you on your preferred channel:
   "⚠️ Workflow 'Monday Report' failed at Step 3 (browser-extract).
   Error: Element not found. Screenshot attached.
   Reply 'retry' to try again or 'skip' to continue from Step 4."
4. Wait for your response before proceeding
5. If no response within the configured timeout: mark as failed and log it

### Retry logic
- **Transient failures** (network timeout, page load timeout): auto-retry
  up to 3 times with exponential backoff (5s, 15s, 45s)
- **Permanent failures** (element not found, auth expired): alert you immediately
- I distinguish between transient and permanent failures autom