openclaw.plugin.json

{
  "id": "openclaw-workflow",
  "name": "Workflow Orchestrator",
  "description": "YAML/JSON-driven workflow orchestration for OpenClaw agents with dependency graphs, parallel execution, retries, output gates, dry runs, cancellation, resume, and persisted run state.",
  "version": "1.0.0",
  "contracts": {
    "agentToolResultMiddleware": [
      "pi",
      "codex"
    ],
    "tools": [
      "workflow_run",
      "workflow_status",
      "workflow_list",
      "workflow_cancel",
      "write_output",
      "read_output",
      "list_outputs",
      "materialize_output",
      "workflow_state_get",
      "workflow_step_update",
      "workflow_step_complete",
      "workflow_observation_read",
      "workflow_observation_search",
      "workflow_observation_json_path",
      "workflow_runtime_patch_status"
    ]
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": true,
    "properties": {
      "workflowsDir": {
        "type": "string",
        "description": "Directory containing workflow definition files. Defaults to ~/.openclaw/workflows."
      },
      "runsDir": {
        "type": "string",
        "description": "Directory where workflow run state files are stored. Defaults to ~/.openclaw/workflow-runs."
      },
      "baseDir": {
        "type": "string",
        "description": "Base directory for resolving relative output file paths. Defaults to the gateway working directory."
      },
      "concurrency": {
        "type": "integer",
        "minimum": 1,
        "description": "Maximum number of workflow steps that can run in parallel. Defaults to 3."
      },
      "notifyChannel": {
        "type": "string",
        "description": "Channel ID or name for workflow progress notifications. If omitted, notifications are logged only."
      },
      "sessionModel": {
        "type": "string",
        "description": "Default model for spawned step sessions when a step does not specify its own model."
      },
      "pollIntervalMs": {
        "type": "integer",
        "minimum": 250,
        "description": "How often to poll step session status in milliseconds. Defaults to 5000."
      },
      "cronDeliveryMode": {
        "type": "string",
        "enum": [
          "none",
          "announce"
        ],
        "description": "Delivery mode for internal workflow step cron jobs. Defaults to none."
      },
      "cronDeliveryChannel": {
        "type": "string",
        "description": "Explicit delivery channel for cron jobs when cronDeliveryMode is announce, e.g. discord or whatsapp."
      },
      "cronDeliveryTo": {
        "type": "string",
        "description": "Optional explicit delivery target for cron jobs."
      },
      "sessionAdapter": {
        "type": "string",
        "enum": [
          "auto",
          "runtime-subagent",
          "legacy-api",
          "cli"
        ],
        "description": "Session adapter to use. For headless browser/application workflows, use runtime-subagent."
      },
      "cliTimeoutMs": {
        "type": "integer",
        "minimum": 1000
      },
      "cronAddTimeoutMs": {
        "type": "integer",
        "minimum": 1000
      },
      "cronRunTimeoutMs": {
        "type": "integer",
        "minimum": 1000
      },
      "cronPollTimeoutMs": {
        "type": "integer",
        "minimum": 1000
      },
      "cancelGraceMs": {
        "type": "integer",
        "minimum": 1000,
        "description": "Grace period to wait after requesting worker cancellation."
      },
      "autoResumeOnStartup": {
        "type": "boolean",
        "description": "When true, Gateway startup scans persisted workflow runs and automatically resumes runs that were still marked running."
      },
      "stateBackend": {
        "type": "string",
        "enum": [
          "filesystem",
          "redis",
          "redis-native",
          "redis-mcp",
          "auto",
          "dual"
        ],
        "description": "Requested workflow state backend. Default: filesystem."
      },
      "redisUrl": {
        "type": "string",
        "description": "Native Redis connection URL for workflow state/artifacts."
      },
      "redisPrefix": {
        "type": "string",
        "description": "Redis key prefix used by workflow state/artifact backends."
      },
      "redisPrefer": {
        "type": "string",
        "enum": [
          "native",
          "mcp",
          "auto"
        ],
        "description": "Preferred Redis transport when using stateBackend=redis or auto."
      },
      "redisMcpServer": {
        "type": "string",
        "description": "Explicit MCP server name for Redis access (for example MCP_DOCKER)."
      },
      "redisMcpConfigPath": {
        "type": "string",
        "description": "Optional MCPorter config path used when resolving MCP Redis servers."
      },
      "redisMcpRootDir": {
        "type": "string",
        "description": "Optional root directory used by MCPorter when resolving relative MCP paths."
      },
      "redisMcpCallTimeoutMs": {
        "type": "integer",
        "minimum": 1,
        "description": "Timeout for MCP Redis tool calls via MCPorter."
      },
      "redisMcpServerDefinition": {
        "type": "object",
        "description": "Optional inline MCP server definition translated to an MCPorter server."
      },
      "redisMcpToolPrefix": {
        "type": "string",
        "description": "Deprecated alias for redisMcpServer. Treated as an MCP server name, not a __ tool prefix."
      },
      "filesystemFallback": {
        "type": "boolean",
        "description": "When true, fallback to filesystem when Redis is unavailable."
      },
      "materializeOutputs": {
        "type": "string",
        "enum": [
          "never",
          "on_demand",
          "always"
        ],
        "description": "Controls when artifact outputs are materialized to filesystem paths."
      },
      "requireSealedToolResultMiddleware": {
        "type": "boolean",
        "default": true,
        "description": "When true, plugin startup fails if agentToolResultMiddleware could not be registered. Requires the openclaw-workflow trust patch to be applied. Defaults to true."
      },
      "sealedMaxPreviewBytes": {
        "type": "number",
        "default": 2048,
        "description": "Maximum bytes of a sealed tool-result payload to inline into the model context window. The rest is spooled to the artifact store and accessible via observation tools."
      }
    }
  },
  "uiHints": {
    "autoResumeOnStartup": {
      "label": "Auto-resume on Gateway startup",
      "help": "Resume interrupted workflow runs after Gateway restart.",
      "advanced": true
    },
    "workflowsDir": {
      "label": "Workflows directory",
      "help": "Folder containing .yml, .yaml, and .json workflow definitions.",
      "placeholder": "~/.openclaw/workflows"
    },
    "runsDir": {
      "label": "Run state directory",
      "help": "Folder where workflow run JSON state files are written.",
      "placeholder": "~/.openclaw/workflow-runs"
    },
    "baseDir": {
      "label": "Base directory",
      "help": "Relative output paths in workflow steps are resolved under this directory.",
      "placeholder": "/home/user/project"
    },
    "concurrency": {
      "label": "Max parallel steps",
      "help": "Per-workflow concurrency cap from 1 to 10.",
      "placeholder": "3"
    },
    "notifyChannel": {
      "label": "Notification channel",
      "help": "Optional channel for workflow progress messages.",
      "placeholder": "telegram"
    },
    "sessionModel": {
      "label": "Default step model",
      "help": "Used by steps that do not declare their own model.",
      "placeholder": "anthropic/claude-sonnet-4-6"
    },
    "pollIntervalMs": {
      "label": "Poll interval",
      "help": "Milliseconds between status checks for running step sessions.",
      "placeholder": "5000",
      "advanced": true
    },
    "stateBackend": {
      "label": "State backend",
      "help": "Choose filesystem, redis, auto, or dual backend resolution.",
      "placeholder": "auto",
      "advanced": true
    },
    "redisUrl": {
      "label": "Redis URL",
      "help": "Native Redis URL used when state backend resolves to redis-native.",
      "placeholder": "redis://localhost:6379",
      "advanced": true
    },
    "redisPrefer": {
      "label": "Redis transport preference",
      "help": "Prefer native Redis, MCP Redis, or allow automatic resolution.",
      "placeholder": "auto",
      "advanced": true
    },
    "redisMcpServer": {
      "label": "Redis MCP server",
      "help": "Explicit MCP server name used for Redis via MCPorter.",
      "placeholder": "MCP_DOCKER",
      "advanced": true
    },
    "redisMcpConfigPath": {
      "label": "MCPorter config path",
      "help": "Optional path to mcporter.json for Redis MCP resolution.",
      "placeholder": "~/.mcporter/mcporter.json",
      "advanced": true
    },
    "filesystemFallback": {
      "label": "Filesystem fallback",
      "help": "Fallback to filesystem when Redis is unavailable.",
      "advanced": true
    },
    "requireSealedToolResultMiddleware": {
      "label": "Require sealed middleware",
      "help": "Fail plugin startup if agentToolResultMiddleware could not be registered. Only effective after applying the openclaw-workflow trust patch.",
      "advanced": true
    },
    "sealedMaxPreviewBytes": {
      "label": "Sealed preview bytes",
      "help": "Bytes of a sealed tool result to inline into the model context. Remainder is spooled to artifact store.",
      "placeholder": "2048",
      "advanced": true
    }
  }
}