ClawFlows Documentation

ClawFlows is a workflow system for OpenClaw that provides deterministic, versioned, and reusable workflows. It includes over 100 prebuilt workflows that can be enabled easily. Workflows are defined in plain text, making them easy to create, read, and share. Key benefits include:

• Reliability: Deterministic execution without scattered instructions.
• Version Control: Ability to modify, save, and rollback workflows.
• Community Support: Access to 100+ prebuilt workflows for various domains like Smart Home, Daily Routines, Health, and Finance.

The scheduler uses a specific directory structure in system/runs/ to track execution and prevent duplicate runs.

Crucial Rule: Run files are keyed by the scheduled time (the time the workflow was supposed to run), not the actual time the scheduler executed the task.

Directory Structure: system/runs/YYYY-MM-DD/workflow-name/HH:MM

Example: If a workflow named send-morning-briefing is scheduled for 07:00 and the scheduler runs at 06:50 on February 10, 2026, the run file must be created at: system/runs/2026-02-10/send-morning-briefing/07:00

If this file exists, the scheduler will skip the workflow for that time slot.

When you enable or create a workflow, ClawFlows checks for required services (e.g., email, calendar, messaging).

• Essential services: The CLI will notify you if they are missing and provide setup help.
• Optional services: The CLI will suggest them as improvements but allow the workflow to run without them.

When defining workflows that require sensitive information like API keys or credentials, do not hardcode the values. Instead, use the following placeholder syntax. This allows end-users to provide their own keys when they enable the workflow.

Syntax: {{SECRET:API_KEY_NAME}} — Description of what this key is for

Examples:

• {{SECRET:OPENAI_API_KEY}} — OpenAI API key for GPT calls
• {{SECRET:GITHUB_TOKEN}} — GitHub personal access token
• {{SECRET:SLACK_WEBHOOK}} — Slack webhook URL for notifications

Workflows can run automatically based on a schedule defined in their WORKFLOW.md file. You can use plain English descriptions for the schedule.

Supported formats include:

• Specific times: "8am", "7pm"
• Intervals: "every 2 hours"
• Relative times: "morning"

Example YAML configuration within a workflow file:

schedule: "8am, 6pm"

A workflow is a directory containing a WORKFLOW.md file and optional supporting files:

• WORKFLOW.md: Required. Contains instructions, frontmatter, and execution steps.
• config.env: Optional. Stores environment variables (e.g., EMAIL=user@example.com). The agent will prompt users to fill these in when enabling.
• scripts/: Optional. A directory for helper scripts (e.g., .sh or .py files) that the workflow can execute.

my-workflow/
├── WORKFLOW.md          # Instructions (frontmatter + steps)
├── config.env           # Optional: environment variables
└── scripts/             # Optional: helper scripts
    └── do-thing.sh

Maintain the 🏆 Top Contributors table in README.md by following these rules:

1. Increment Count: If the author already has a row, increment their workflow count.
2. New Contributors: If the author is new, add a new row.
3. Sorting: Keep the table sorted by count in descending order.
4. Emojis: Use 🥇 for 1st, 🥈 for 2nd, and 🥉 for 3rd. Use no emoji for 4th place and below.
5. CTA: The final row must always be a "You!" Call-To-Action (CTA) linking to docs/creating-workflows.md.

To completely remove ClawFlows, use the clawflows uninstall command. This performs a clean removal of:

• The CLI symlink
• The AGENTS.md block
• The scheduler cron job

Warning: The uninstaller will warn you about the deletion of your custom/ directory (where your personal workflows live) before proceeding.

When a scheduled workflow executes, you must create a run file to record the result and prevent re-execution. The file should be named after the scheduled time and contain a brief summary (2-5 lines) of the actions taken.

Use the following pattern to create the run log:

mkdir -p system/runs/YYYY-MM-DD/workflow-name
cat > system/runs/YYYY-MM-DD/workflow-name/HH:MM << 'EOF'
Brief summary of what the workflow did.
Include key results, numbers, or actions taken.
EOF

Example Log Content:

• "Sent briefing: 65°F, 3 meetings today, 2 priority tasks"
• "Triaged 12 emails: archived 8 junk, flagged 2 urgent, 2 need reply"
• "No calendar conflicts in next 48 hours. Next meeting: standup at 9am"

You can build your own workflows using the interactive CLI or submit them to the community.

Workflow Creation Workflow:

1. Create and test:
   • Run clawflows create to start the interactive builder.
   • Run clawflows run <your-workflow-name> to test it locally.
2. Submit:
   • Run clawflows submit <your-workflow-name> to submit for community review.
   • Follow the instructions provided after submission to open a pull request.

For a detailed guide, see the docs/creating-workflows.md documentation.

# 1. Create and test your workflow
clawflows create
clawflows run your-workflow-name

# 2. Submit it for review
clawflows submit your-workflow-name