Skip to content
clawnifyPublic

About

The n8n for agents. A declarative, AI-native workflow format that agents can read, write, and run.

Resources

Security policy

Stars

12 stars

Watchers

1 watching

Forks

Repository files navigation

ClawFlow

ClawFlow

npm License Reddit Website

The n8n for agents. A declarative, AI-native workflow format that agents can read, write, and run — without infrastructure.


Install

npm install @clawnify/clawflow

Or as an OpenClaw plugin:

openclaw plugins install @clawnify/clawflow

From source:

git clone https://github.com/clawnify/clawflow.git
cd clawflow && npm install && npm run build

Why ClawFlow

Workflows today are written for agents, not by them. Visual canvas tools require humans to click nodes. Code-first orchestration frameworks have too much surface area for LLMs to generate reliably.

ClawFlow is a workflow format designed from first principles for agents. Three rules drove every design decision:

  1. An LLM must be able to write a valid workflow in a single turn. If the format is too complex, agents hallucinate. If it's too simple, real workflows can't be expressed.

  2. The format is the asset, not the runtime. Write once, run as an OpenClaw plugin today, run in a standalone server tomorrow.

  3. AI nodes are first-class citizens. do: ai and do: agent are core primitives with structured output, model selection, and schema validation — not HTTP calls with extra steps.


Features

AI-Native

  • do: ai — structured LLM calls with schema validation and model selection (fast, smart, best)
  • do: agent — delegate to real agents with full tool access (browser, exec, memory, MCP, CLI)
  • Agent-writable — any LLM can generate a valid flow from a natural language description

Control Flow

  • do: branch — multi-way routing with inline sub-flows per path
  • do: condition — if/else with automatic reconvergence
  • do: loop — iterate over arrays
  • do: parallel — concurrent execution with all or race modes

Durability

  • Memoized state — completed nodes aren't re-run on resume
  • Approval gates — do: wait pauses for human review, resumes with a token
  • External events — waitForEvent blocks until an external system pushes data
  • Per-node retry — exponential, linear, or constant backoff on any node
  • Scheduled triggers — cron schedules as first-class records: many per flow, each with its own inputs, paused without touching the flow

Portability

  • OpenClaw plugin — run flows as agent tools today
  • Standalone runner — self-hosted Node.js server (coming soon)
  • Static validation — catch bad references and missing fields before execution
  • Draft/publish versioning — edit safely, publish when ready, run any version

Quick Example

A flow is JSON. No custom syntax, no new language — just structured data that any LLM can generate from a description.

{
  "flow": "support-triage",
  "description": "Classify a ticket, draft a reply, get approval, send it",
  "inputs": {
    "body": { "type": "string", "required": true },
    "id":   { "type": "string", "required": true }
  },
  "nodes": [
    {
      "name": "classify",
      "do": "ai",
      "prompt": "Classify this ticket as billing, technical, or general",
      "input": "inputs.body",
      "schema": {
        "category": "billing | technical | general",
        "urgency": "low | medium | high",
        "summary": "string"
      },
      "model": "fast",
      "output": "classification"
    },
    {
      "name": "route",
      "do": "branch",
      "on": "classification.category",
      "paths": {
        "billing": [
          {
            "name": "handle-billing",
            "do": "agent",
            "task": "Draft a billing support reply for: {{ inputs.body }}",
            "output": "draft"
          }
        ],
        "technical": [
          {
            "name": "handle-technical",
            "do": "agent",
            "task": "Draft a technical support reply for: {{ inputs.body }}",
            "output": "draft"
          }
        ]
      },
      "default": [
        {
          "name": "handle-general",
          "do": "agent",
          "task": "Draft a general support reply for: {{ inputs.body }}",
          "output": "draft"
        }
      ]
    },
    {
      "name": "approve",
      "do": "wait",
      "for": "approval",
      "prompt": "Send this reply?\n\n{{ draft }}"
    },
    {
      "name": "send",
      "do": "http",
      "url": "https://helpdesk.example.com/api/reply",
      "method": "POST",
      "body": { "message": "{{ draft }}", "ticketId": "{{ inputs.id }}" },
      "retry": { "limit": 3, "delay": "2s", "backoff": "exponential" }
    }
  ]
}

Node Types

11 node types. This is intentional — the constraint is the feature. An LLM can reliably generate valid flows because there's nothing to hallucinate.

do: ai — LLM call

The most important node. A single LLM call that returns structured or freeform output.

{
  "name": "classify",
  "do": "ai",
  "prompt": "Classify this support ticket",
  "input": "inputs.body",
  "schema": {
    "category": "billing | technical | general",
    "confidence": "number",
    "summary": "string"
  },
  "model": "fast",
  "output": "classification"
}
Field Description
prompt The instruction to the model. Supports {{ templates }}.
input Dotted path to a value in flow state passed as context
schema Output shape. When set, enforces JSON mode. Keys are type hints.
model fast (Gemini 3 Flash), smart (Claude Sonnet 4.6), best (Minimax M2.5), or any model string
provider Named backend to run against — a key in providers config or a built-in (openrouter, anthropic, openai). Defaults to defaultProvider, then env auto-detect.
temperature 0–1, default 0 for deterministic workflow steps

Why schema matters: downstream nodes reference classification.category as a reliable string. Without schema, the output is freeform text and you're back to parsing.

Choosing a provider. By default an ai node auto-detects a backend from the environment (OPENROUTER_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY). To run flow AI through a specific backend — for per-caller credentials, quota, or attribution instead of a shared process-env key — configure named providers on the plugin and point nodes at them:

{
  "defaultProvider": "clawnify",
  "providers": {
    "clawnify": {
      "baseUrl": "https://api.clawnify.com/v1",
      "api": "openai-completions",
      "apiKeyEnv": "OPENCLAW_GATEWAY_TOKEN",
      "models": { "fast": "clawnify-lite", "smart": "clawnify-pro", "best": "clawnify-max" }
    }
  }
}

With defaultProvider set, every ai node routes through that provider (a stray OPENROUTER_API_KEY in the environment can no longer win), and a node's model tier maps to the provider's own model IDs. Any per-node provider overrides the default.


do: agent — delegate to a real agent

Runs a task through a real OpenClaw agent with full tool access (browser, exec, memory, MCP, CLI). The agent decides its own path to a result.

{
  "name": "scrape",
  "do": "agent",
  "task": "Navigate to https://example.com and extract the pricing table as JSON",
  "agent": "main",
  "timeout": "120s",
  "output": "data"
}

On OpenClaw, this delegates to openclaw agent --agent <id> --message "...". The agent gets full tool access — browser, shell, file system, memory, MCP. Falls back to a single AI call if the CLI is unavailable (standalone mode).

Field Description
task The instruction to the agent. Supports {{ templates }}.
agent OpenClaw agent ID (e.g. "main", "ops"). Uses config defaultAgent or "main" if omitted.
input Dotted path to context passed with the task
tools Hint for non-OpenClaw runtimes (OpenClaw agents have their own tool policy)

The distinction between ai and agent is intentional:

  • do: ai = deterministic, one-shot, structured output — use for classification, drafting, extraction
  • do: agent = open-ended, multi-step, uses tools — use for scraping, research, file operations

do: branch — multi-way routing

Routes the flow to a sub-flow based on a value in state. Each path is an array of nodes that executes as a self-contained block, then reconverges back into the main flow.

{
  "name": "route",
  "do": "branch",
  "on": "classification.category",
  "paths": {
    "billing": [
      { "name": "lookup-invoice", "do": "http", "url": "https://api.example.com/invoice/{{ inputs.id }}", "output": "invoice" },
      { "name": "draft-reply", "do": "ai", "prompt": "Draft billing reply for: {{ invoice }}", "output": "draft" }
    ],
    "technical": [
      { "name": "draft-reply", "do": "agent", "task": "Research and draft technical reply for: {{ inputs.body }}", "output": "draft" }
    ]
  },
  "default": [
    { "name": "draft-reply", "do": "ai", "prompt": "Draft a general reply for: {{ inputs.body }}", "output": "draft" }
  ]
}

Each path runs its full node sequence and merges state back. The default path handles any value not explicitly listed. No default + no matching path = runtime error (intentional — fail loudly).

Use branch for multi-way value matching, condition for boolean if/else logic. Both support full sub-flows and reconverge automatically.


do: condition — if/else with reconvergence

Runs inline sub-node blocks based on a boolean condition, then merges back into the main flow. Use condition for true/false logic, branch for multi-way value matching.

{
  "name": "check-transport",
  "do": "condition",
  "if": "extractOrder.transport_type == 'CLIENTE'",
  "then": [
    { "name": "pickup-note", "do": "code", "run": "'Client picks up'", "output": "note" }
  ],
  "else": [
    { "name": "delivery-note", "do": "code", "run": "'We deliver'", "output": "note" }
  ]
}
Field Description
if JS expression evaluated against flow state. Dotted paths are resolved.
then Nodes to run when condition is true
else Nodes to run when condition is false (optional — skipped if absent)

Supports comparison and logical operators:

"classification.priority == 'urgent'"
"validation.valid && items.length > 0"
"inputs.amount > 1000 || inputs.vip == true"

do: loop — iterate over a list

Runs a set of sub-nodes for each item in an array.

{
  "name": "process-tickets",
  "do": "loop",
  "over": "inbox.tickets",
  "as": "ticket",
  "nodes": [
    {
      "name": "summarize",
      "do": "ai",
      "prompt": "Summarize this ticket: {{ ticket }}",
      "output": "summary"
    }
  ],
  "output": "processed"
}

Iterations run sequentially. For concurrent execution, use do: parallel.


do: parallel — concurrent execution

Runs multiple nodes at the same time. Waits for all to complete (mode: "all") or the first to finish (mode: "race").

{
  "name": "research",
  "do": "parallel",
  "mode": "all",
  "nodes": [
    {
      "name": "web-search",
      "do": "agent",
      "task": "Search the web for recent cases of {{ topic }}",
      "output": "web_results"
    },
    {
      "name": "memory-lookup",
      "do": "memory",
      "action": "read",
      "key": "knowledge-{{ topic }}",
      "output": "memory_results"
    }
  ],
  "output": "research"
}

mode: "race" mirrors Cloudflare's Promise.race() pattern — the first branch to complete wins and the others are discarded. Useful for: try-cache-before-fetch, multi-model racing, fallback strategies.


do: http — external API call

{
  "name": "notify-slack",
  "do": "http",
  "url": "https://hooks.slack.com/services/{{ inputs.slackWebhook }}",
  "method": "POST",
  "body": { "text": "Ticket resolved: {{ classification.summary }}" },
  "retry": { "limit": 3, "delay": "1s", "backoff": "exponential" },
  "output": "slack_response"
}

All fields support {{ templates }}. Retry is strongly recommended for any outbound call.


do: memory — persistent key/value store

Read, write, or delete values that persist across flow runs.

{ "name": "save-result",  "do": "memory", "action": "write",  "key": "ticket-{{ inputs.id }}", "value": "{{ classification.category }}" }
{ "name": "load-history", "do": "memory", "action": "read",   "key": "ticket-{{ inputs.id }}", "output": "previous_category" }
{ "name": "cleanup",      "do": "memory", "action": "delete", "key": "ticket-{{ inputs.id }}" }

In the OpenClaw plugin, memory persists to ~/.openclaw/flow-memory/. In Cloudflare, it maps to KV or D1. Keys support templates.


do: wait — pause for human or external event

Two modes:

Approval gate — pauses the flow and returns a resumeToken. A human reviews and approves or denies via flow_resume.

{
  "name": "approve-send",
  "do": "wait",
  "for": "approval",
  "prompt": "Send this reply to the customer?\n\n{{ draft }}"
}

External event — blocks until an external system pushes the matching event via flow_send_event. Learned from Cloudflare's step.waitForEvent().

{
  "name": "await-payment",
  "do": "wait",
  "for": "event",
  "event": "stripe-payment-confirmed",
  "timeout": "24h",
  "output": "payment"
}

When a Stripe webhook arrives, the calling code does:

{ "tool": "flow_send_event", "instanceId": "...", "eventType": "stripe-payment-confirmed", "payload": { "amount": 4900 } }

The flow resumes with payment.amount = 4900 in state.


do: sleep — time-based pause

{ "name": "cool-down", "do": "sleep", "duration": "5m" }

Duration syntax: 30s, 5m, 2h, 1d. Maps directly to Cloudflare's step.sleep(). Does not count towards step limits.


do: code — inline JavaScript

{
  "name": "format-date",
  "do": "code",
  "input": "inputs.timestamp",
  "run": "new Date(input).toLocaleDateString('en-GB')",
  "output": "formatted_date"
}

Single expressions are returned automatically. Multi-statement bodies (containing ; or newlines) require an explicit return:

{
  "name": "calc",
  "do": "code",
  "input": "inputs",
  "run": "const total = input.price * input.qty;\nconst tax = total * 0.22;\nreturn { total, tax, grand: total + tax };",
  "output": "invoice"
}

No imports, no async, no filesystem access. state and input are frozen — return new values instead of mutating. For scripts or complex logic, use do: exec to run shell commands. For external APIs, use do: http.


Templates

Any string field supports {{ path.to.value }} interpolation resolved against flow state:

{{ inputs.body }}               # initial input payload (always available)
{{ classification.category }}   # node with output: "classification" → access .category
{{ inputs.user.email }}         # nested dotted path
{{ research.web_results }}      # array or object (serialized to JSON string)

Important: templates reference the output key, not the node name. If a node has "name": "get_data", "output": "api", reference it as {{ api }} — not {{ get_data }}.

Flow state starts as { inputs: <payload> } and grows as nodes complete. The caller (CLI, webhook server, scheduled trigger, parent flow, dashboard) is responsible for producing that payload — the flow definition itself stays trigger-agnostic. Schedules live in their own records, not in the flow (see Scheduling).


Scheduling

A flow runs when something invokes it: an agent, an HTTP call, or a trigger.

A trigger is a first-class record — not a field on the flow definition:

flow_trigger action: "create" flow: "daily-digest" cron: "0 9 * * *" tz: "Europe/Rome"
● daily-digest-ab12cd34
    flow: daily-digest (latest published)
    cron: 0 9 * * * [Europe/Rome]
    next: 2026-08-22T07:00:00.000Z

That separation is deliberate. A schedule is mutable operational state — paused at 2am, retimed, pointed at a different version — while a published flow version is an immutable artifact. Embedding one in the other would make "pause" mean "publish a new version", and would let an unrelated publish silently re-arm a schedule the draft happened to carry. Temporal made the same move from cron-in-workflow to a separate Schedules object, for the same reason.

Because triggers are their own records, one flow can have many, each with its own payload:

flow_trigger action: "create" flow: "digest" cron: "0 * * * *" inputs: '{"customer":"acme"}'
flow_trigger action: "create" flow: "digest" cron: "0 9 * * *" inputs: '{"customer":"globex"}'
Behavior Rule
Expression Standard 5-field cron; minimum interval 60s
Timezone IANA name (Europe/Rome); host local time when omitted
Version Latest published by default; pin with version: 2
Missed runs Not replayed — a host that was down at 09:00 waits for the next occurrence
Overlap A tick is skipped if the previous run is still going
Flow deleted Triggers are paused, not removed, so a restore keeps them
Approval Arming/pausing/deleting a schedule is gated like flow authoring

Records live in .clawflow/triggers/<id>.json, alongside .clawflow/versions/. Out-of-process callers — the Clawnify hook server and dashboard — read and write them by importing TriggerStore from dist, the same way they read published versions. The running scheduler re-reads the directory every 30s, so a schedule created or edited in the dashboard goes live without a restart.


Retry Policy

Any node can define per-node retry behavior. Learned directly from Cloudflare's WorkflowStepConfig:

{
  "retry": {
    "limit": 3,
    "delay": "2s",
    "backoff": "exponential"
  }
}
Field Values Default
limit integer 1 (no retry)
delay duration string or ms "0"
backoff constant, linear, exponential constant

Strongly recommended on do: http and do: ai nodes. Do not use on do: wait — retrying approval gates makes no sense.


Flow State and Durability

Every flow run gets a unique instanceId. The runner persists state after every completed node. JSON files in stateDir remain the default; native SQLite and PostgreSQL are explicit alternatives. All three store checkpoints, memoized outputs, traces, the running step and pending approvals.

What this means in practice:

  • A paused flow can be explicitly resumed after a gateway restart, using its stored checkpoint.
  • A node that took 30 seconds to run won't run again on resume — its memoized output is loaded from disk.
  • An approval-gated flow can stay paused for days. The state survives indefinitely.

Retention. Finished runs (completed, failed, cancelled) are deleted 30 days after their last update, together with their loop and branch instance files, by a daily sweep in the gateway process. Set runRetentionDays in the plugin config to change it; 0 keeps every run. Running, paused and waiting runs are never deleted.

Cancelling a run. flow_cancel { instanceId }, or POST /flows/runs/:instanceId/cancel on the flow server (optional body { "reason": "..." }), stops a run that has not finished. A run executing in the process stops on the step it is on: an agent step's openclaw agent process gets SIGTERM, on which the CLI aborts its turn in the gateway; an exec step's command is stopped with its whole process group; http and ai steps are aborted; a custom step gets ctx.abortSignal and is abandoned if it ignores it. The run ends with status cancelled, the interrupted step's trace entry too, and nothing after it runs. A run paused at an approval gate, or left running by a restart, is marked cancelled and its approval dropped; a runner in another process that still holds a run stops before its next step. The route answers 404 (run_not_found) for an unknown run and 409 (run_finished) for a finished one. Each attempt of a step is stopped the same way when it times out, before any retry starts; an agent step with no timeout gets 120 s per attempt.

Reading runs. flow_status lists runs newest first, 20 per page (limit, then cursor from the previous page). One run comes back whole when it is small, and otherwise as a summary: status, error, each state key with its size, and the trace without outputs. Read any single value with path, e.g. state.leads or trace.3.output; arrays and long strings come back a page at a time (offset, limit). flow_run and flow_resume return the same summary when a run is too large to read in one tool result. The same functions (listRuns, summarizeRun, readRunValue, sweepRuns) are exported for other hosts. With JSON storage, a small summary of each run is kept in flow-state/_index/, so a list reads a few hundred bytes per run instead of parsing every record; an entry older than its record is ignored, and the daily sweep fills in missing ones.

SQLite and PostgreSQL

Set storage in plugins.entries.clawflow.config (OpenClaw), or in the config passed to new FlowRunner(config) (standalone). No configuration means JSON; { "backend": "json" } selects it explicitly.

{
  "stateDir": "/path/to/flow-state",
  "storage": { "backend": "sqlite" }
}

SQLite uses Node's built-in node:sqlite, requiring Node 22.13+. It creates stateDir/clawflow.sqlite, or the file supplied as storage.path. Keep it on a local filesystem. WAL, full synchronization and a 5-second busy timeout are configured on each connection. New database files are mode 0600. Back up the SQLite database with a SQLite-aware backup tool, or stop every connection before copying it; copying just the main file while WAL writers are active can lose checkpoints.

{
  "storage": {
    "backend": "postgres",
    "connectionStringEnv": "CLAWFLOW_DATABASE_URL",
    "namespace": "my-agent"
  }
}

Set that environment variable through your deployment's secret manager to a PostgreSQL connection URL. The URL is never written into a checkpoint. TLS options are those of node-postgres; require certificate verification for remote connections. PostgreSQL is loaded only when selected and uses at most four pooled connections per store. Empty configuration, connection failures and unsupported schema versions fail the operation; they never silently fall back to local files.

Use a stable, distinct namespace for each independent installation sharing a database. A namespace separates keys, not permissions. Use dedicated database roles and databases or schema grants to isolate untrusted installations. The configured role needs permission to create and use the clawflow_* tables and indexes in its search path. Initial schema creation is transactional and versioned.

SQL backends commit each step's checkpoint, memo and summary together; a pause also commits its pending approval. Resume claims the paused run and consumes its approval in one transaction, so competing resumes cannot both claim it. Run lists read indexed summaries and use the same cursor/filter contract; retention deletes finished roots, their child records and approvals. A new run cannot overwrite an existing SQL run ID. : is reserved for engine-generated child IDs.

Flow definitions, published versions, trigger schedules and do: memory files remain in the workspace. This is execution storage, not a central history mirror or a distributed scheduler. Event waiters and immediate cancellation remain process-local (use runner.sendEvent() to select the store); another process's cancellation is observed at the next step. Changing storage does not add automatic recovery of an interrupted running step or exactly-once external side effects. Full checkpoint payloads are still rewritten at each step; the SQL indexes bound list payloads, not individual checkpoint size.

Reading and closing a configured store

The existing StateStore, listRuns(stateDir) and sweepRuns(stateDir, days) exports keep their JSON-file behavior. Database-aware consumers must use the configured store. Always await the methods on it, including those on runner.getStore() and runner.listApprovals(); JSON implementations can return synchronously.

import { createStateStore, readRunValue } from "@clawnify/clawflow";

const store = createStateStore(config.stateDir, config.storage);
try {
  const page = await store.listRuns({ limit: 20, status: "paused" });
  if (page.runs[0]) {
    const run = await store.get(page.runs[0].instanceId);
    if (run) console.log(readRunValue(run, "state.inputs"));
  }
} finally {
  await store.close();
}

store.listSubRuns(parentId, { limit, cursor, node?, flow?, status? }) pages all retained descendants, preserving their actual :-separated IDs. node filters the immediate node beneath that parent, including its nested descendants. It uses the same (createdAt DESC, instanceId DESC) order as listRuns. SQL count and page share one read transaction; different pages and get calls do not share a snapshot. JSON readers have no snapshot. Neither API provides an update cursor, revision, complete inventory guarantee, or deletion tombstones.

When the HTTP listener is enabled, authenticated management routes use the same configured runner:

  • GET /flows/runs?limit=20&cursor=...&flow=...&status=.... Optional include_oldest=1 adds oldest: { instanceId, updatedAt } | null across all matching runs, before cursor filtering. The store option is includeOldest: true. SQL count, oldest checkpoint and page share one transaction; this identifies old checkpoints without declaring runs dead.
  • GET /flows/runs/:instanceId for the complete record; optional path, offset, limit, max_chars use readRunValue. URL-encode actual instance IDs.
  • GET /flows/runs/:instanceId/subruns?limit=20&node=... for descendant summaries.
  • GET /flows/runs/:instanceId?include_subruns=1&node=... adds the last 20 iterations per node and counts of omitted iterations for detail views.
  • POST /flows/runs/:instanceId/resume with { "approved": true } or false. Approval resolves the definition through resolveRunnableFlow (published version preferred); decline atomically cancels and consumes its approval. A 202 is sent only after the durable resume claim, before later steps finish.

The configured listener prefix replaces /flows. These new routes require Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN> (or the host gateway's configured token; standalone hosts may supply controlToken to startFlowServer). Without a token they refuse access. Optional X-ClawFlow-Backend: sqlite|postgres|json refuses a stale runner whose backend differs from the caller's configuration. Storage errors return 503 without credentials or a JSON fallback. The existing run/trigger/cancel routes retain their prior authentication contract.

Run records do not yet bind an executed definition version/hash or trusted actor/session access scope. Keep the relevant definition unchanged while a run is paused. Do not infer historical provenance or access grants from missing fields. Management reads are operator access, not a per-user authorization layer.

For a standalone runner, call await runner.close() once its runs have settled. This closes the SQLite handle or PostgreSQL pool. Close a reader when it is no longer needed; avoid opening a new pool for each request in a long-lived host.

Importing existing JSON state

There is no automatic conversion on startup. Before switching storage:

  1. Stop every ClawFlow writer, including the gateway, flow HTTP service and scheduler. Keep the original state directory as the backup.

  2. From a source checkout with dependencies installed, run one of:

    npm run migrate:storage -- --writers-stopped --source /path/to/flow-state --sqlite /path/to/flow-state/clawflow.sqlite
    npm run migrate:storage -- --writers-stopped --source /path/to/flow-state --postgres-env CLAWFLOW_DATABASE_URL --namespace my-agent
  3. Verify the imported runs and approvals using createStateStore. Update every reader as well as the runner to use the same storage configuration, then restart.

The importer copies all run records, including child runs, and pending approvals; it ignores the derived _index directory. It never modifies or removes the JSON source. Each run and its approvals commit atomically, bounded by one record at a time. Identical records are accepted on retry; different destination records, malformed JSON and orphaned approvals stop the import. Earlier committed runs remain after an error, so repair the source while stopped and retry before starting the destination. Do not import again after the destination has begun executing: it will correctly refuse newer, conflicting records. Switching back to old JSON files after SQL writes would lose those newer checkpoints; this command does not export SQL back to JSON.

The same importer is exported as importJsonState(sourceDir, storageConfig) for hosts managing a stopped runtime. It copies execution state only; retain the workspace's definitions, versions, schedules and memory files too.

Storage tests

Run npm test on Node 22.13+ for JSON and native SQLite. Set CLAWFLOW_TEST_POSTGRES_URL to an isolated test database to include the real PostgreSQL suite. Tests create tables and records there. CI provisions PostgreSQL 16 and runs all three backends; production credentials are never needed.


Runtime Targets

The format is the spec. The runtime is swappable.

1. OpenClaw Plugin (current)

Thirteen tools registered in OpenClaw:

Tool Does
flow_create Create a new flow definition and save to file
flow_delete Move a flow and its published versions to .clawflow/bin/; pause schedules, keep run history
flow_restore_from_bin List bin contents or restore a deleted flow
flow_run Execute a flow (uses latest published version by default)
flow_resume Resume after an approval gate
flow_send_event Push an event into a waiting flow
flow_cancel Cancel a run that has not finished: the step it is on is stopped (an agent step's turn too)
flow_status List instances a page at a time, or inspect one (a summary when large, one value by path)
flow_list List all flows with metadata, expected inputs, and version info
flow_read Read a flow definition (draft or specific version), inspect single nodes
flow_publish Publish current draft as a new numbered version
flow_edit Edit nodes in a flow definition (set, update, add, remove, move, wrap, revert, list)
flow_trigger Schedule a flow on cron (create, update, list, pause, resume, delete, run_now)

Config:

{
  "plugins": {
    "entries": {
      "clawflow": {
        "enabled": true,
        "config": { "defaultModel": "smart" }
      }
    }
  },
  "agents": {
    "list": [{
      "id": "main",
      "tools": { "alsoAllow": ["flow_create", "flow_delete", "flow_restore_from_bin", "flow_run", "flow_resume", "flow_cancel", "flow_send_event", "flow_status", "flow_list", "flow_read", "flow_publish", "flow_edit", "flow_trigger"] }
    }]
  }
}

2. Standalone Node.js Runner (coming soon)

A small HTTP server wrapping the runner. Expose flows as endpoints, receive webhooks, manage instances via REST API. Self-hosted alternative to Cloudflare.

POST  /flows/:name/run       # start a flow instance
POST  /flows/resume          # resume paused flow
POST  /flows/event           # send event to waiting flow
GET   /flows/instances       # list all instances
GET   /flows/instances/:id   # get instance status

3. Flow Registry (coming soon)

A community library of reusable, shareable .flow definitions. Think npm for workflows — but agent-writable.

clawflow install support-triage
clawflow install github-pr-review
clawflow install invoice-processing
clawflow install lead-enrichment

Every flow in the registry is:

  • Parameterized (inputs declared in the inputs: block)
  • Runtime-agnostic (runs on OpenClaw or Cloudflare)
  • LLM-editable (agents can fork and modify them)

How Agents Build Workflows

This is the core loop that makes this different from every other workflow tool:

User:  "When a new GitHub PR is opened, have an AI review the diff,
        check if all tests pass, and if the review is positive
        post an approval — otherwise request changes with specific feedback"

Agent: [calls flow_run with an inline flow definition it just generated]

→ flow runs
→ AI reviews diff (do: ai)
→ checks CI status (do: http → GitHub API)
→ branches on review result (do: branch)
→ posts comment (do: http → GitHub API)

The agent doesn't need a visual canvas. It doesn't need to learn a DSL. It reads the node type descriptions from the tool definition and generates valid JSON in one turn.

System prompt for flow authorship

Add this to a skill or system prompt to enable an agent to write flows:

You can design and run workflows using flow_run.
Flows are JSON with a "flow" name and "nodes" array.

Node types: ai, agent, branch, condition, loop, parallel, http, memory, wait, sleep, code

Rules:
- Every node needs a unique "name"
- Use "output" to name a node's result — other nodes reference it via the output key: {{ outputKey.field }}
- Always add "schema" to ai nodes when downstream nodes need typed fields
- Use "retry" on all http nodes: { "limit": 3, "delay": "2s", "backoff": "exponential" }
- Use "do: agent" for open-ended research/tasks, "do: ai" for structured extraction
- "do: wait" with "for: approval" pauses for human review before side effects
- "do: parallel" runs nodes concurrently; use when steps are independent
- Prefer "model": "fast" for classification, "smart" for drafting, "best" for complex reasoning

Comparison

Visual canvas tools Code-first orchestration ClawFlow
AI nodes first-class ✗ partial ✓
Agent delegation ✗ partial ✓
LLM can write it ✗ ✗ ✓
Human readable ✓ ✗ ✓
Durable execution ✗ ✓ ✓
Per-step retry ✓ ✓ ✓
waitForEvent ✗ ✓ ✓
Parallel branches ✓ ✓ ✓
Runtime portable ✗ ✗ ✓
Self-hostable ✓ ✗ ✓

What's Next

  • Standalone HTTP runner (self-hosted, no OpenClaw dependency)
  • Observability: structured traces, token tracking
  • Flow registry: shareable, reusable community flows
  • Cloudflare Workers transpiler
  • Visual canvas

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        .flow definition                         │
│                   (JSON — the portable format spec)             │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                ┌──────────────┼──────────────┐
                │                             │
         ┌──────▼──────┐             ┌────────▼───────┐
         │  OpenClaw   │             │   Standalone   │
         │   Plugin    │             │  Node Server   │
         │             │             │  (coming soon) │
         │ 11 tools    │             │                │
         │ versioning  │             │ REST API       │
         │ run server  │             │ /run endpoint  │
         └──────┬──────┘             └────────────────┘
                │
         ┌──────▼──────────────────────────────┐
         │            FlowRunner               │
         │                                     │
         │  ┌─────────┐   ┌─────────────────┐  │
         │  │ State   │   │   Event Bus     │  │
         │  │ Store   │   │ (waitForEvent)  │  │
         │  │         │   │                 │  │
         │  │ memoize │   │ sendEvent()     │  │
         │  │ resume  │   │ per instanceId  │  │
         │  └─────────┘   └─────────────────┘  │
         │                                     │
         │  Node executors:                    │
         │  execAi · execAgent · execBranch    │
         │  execCondition · execLoop           │
         │  execParallel · execHttp            │
         │  execMemory · execWait · execSleep  │
         │  execCode · execExec                │
         └─────────────────────────────────────┘

Contributing

The most valuable contributions right now:

  1. Real-world flow definitions — try to describe a workflow you actually run, generate the flow JSON, and report where the format breaks down
  2. Node type proposals — what real workflow pattern can't be expressed with the current 11 node types?
  3. Runtime implementations — a Python runner, a Go runner, a Rust runner — anything that proves portability
  4. Bug reports — file issues at github.com/clawnify/clawflow

License

MIT


Built by Clawnify — AI agent hosting and orchestration.

About

The n8n for agents. A declarative, AI-native workflow format that agents can read, write, and run.

Resources

Security policy

Stars

12 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages