npm package: @synergenius/flow-weaver-openclaw-plugin
Description: Flow Weaver plugin for OpenClaw — deterministic workflow engine for AI agents
Author: Ricardo Morais
Latest version: 0.1.1

# Flow Weaver Plugin for OpenClaw

Native OpenClaw plugin that brings Flow Weaver's deterministic workflow engine to your AI assistant. Build, validate, compile, and run workflows through natural conversation.

## How it Works

The plugin exposes two tools to OpenClaw: `fw_search` and `fw_execute`. The agent searches for the right tool, then executes it. This keeps the system prompt small (2 tool schemas instead of 45+) while making every Flow Weaver capability available.

```
User: "Build me a workflow that validates input and transforms it"

OpenClaw calls: fw_search({ query: "create workflow" })
  -> Returns: fw_create (scaffold from template)

OpenClaw calls: fw_execute({ tool: "fw_create", params: { template: "sequential", filePath: "workflow.ts" }})
  -> Workflow created

OpenClaw calls: fw_execute({ tool: "fw_diagram", params: { filePath: "workflow.ts" }})
  -> ASCII diagram shown in chat
```

## Installation

```bash
openclaw plugins install @synergenius/flow-weaver-openclaw-plugin
```

Or from source:

```bash
git clone https://github.com/synergenius-fw/flow-weaver-openclaw-plugin
cd flow-weaver-openclaw-plugin
npm install && npm run build
openclaw plugins install ./
```

## Configuration

Add to your `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "flow-weaver": { "enabled": true }
    }
  }
}
```

No other configuration needed. The plugin auto-discovers installed Flow Weaver packs.

## Available Tools

All `fw` CLI commands have matching tools. Use `fw_search` to discover them:

### Workflow Lifecycle
| Tool | CLI Equivalent | Description |
|---|---|---|
| `fw_create` | `fw create` | Create workflow from template |
| `fw_validate` | `fw validate` | Validate workflow graph |
| `fw_compile` | `fw compile` | Compile to deterministic TypeScript |
| `fw_run` | `fw run` | Execute workflow with params |
| `fw_diagram` | `fw diagram` | Generate ASCII/SVG/HTML diagram |
| `fw_describe` | `fw describe` | Describe structure (JSON/text/mermaid) |
| `fw_diff` | `fw diff` | Compare two workflows semantically |
| `fw_modify` | `fw modify` | Add/remove nodes and connections |
| `fw_status` | `fw status` | Report stub vs implemented nodes |
| `fw_implement` | `fw implement` | Replace stub with implementation |
| `fw_strip` | `fw strip` | Remove generated code |
| `fw_migrate` | `fw migrate` | Migrate to current syntax |

### Query & Documentation
| Tool | CLI Equivalent | Description |
|---|---|---|
| `fw_query` | `fw query` | Query nodes, connections, topology |
| `fw_docs` | `fw docs` | Browse reference documentation |
| `fw_context` | `fw context` | Load LLM context bundle |
| `fw_templates` | `fw templates` | List available templates |
| `fw_grammar` | `fw grammar` | Output annotation grammar (EBNF) |

### Marketplace
| Tool | CLI Equivalent | Description |
|---|---|---|
| `fw_market_search` | `fw market search` | Search npm for packs |
| `fw_market_install` | `fw market install` | Install a pack |
| `fw_market_uninstall` | `fw market uninstall` | Remove a pack |
| `fw_market_list` | `fw market list` | List installed packs |
| `fw_market_init` | `fw market init` | Scaffold new pack project |
| `fw_market_pack` | `fw market pack` | Generate/validate manifest |
| `fw_market_publish` | `fw market publish` | Publish to npm |

### Platform & Cloud
| Tool | CLI Equivalent | Description |
|---|---|---|
| `fw_login` | `fw login` | Authenticate with platform |
| `fw_logout` | `fw logout` | Clear credentials |
| `fw_auth` | `fw auth` | Check auth status |
| `fw_account` | `fw account` | Show account details |
| `fw_deploy` | `fw deploy` | Deploy to cloud |
| `fw_undeploy` | `fw undeploy` | Remove deployment |
| `fw_cloud_status` | `fw cloud-status` | Show deployments |
| `fw_connect` | `fw connect` | Connect device to platform |
| `fw_apikey` | `fw apikey` | Manage API keys |
| `fw_ai` | `fw ai` | Manage AI provider credentials |
| `fw_org` | `fw org` | Manage organizations |

### Deployment
| Tool | CLI Equivalent | Description |
|---|---|---|
| `fw_export` | `fw export` | Export as serverless function |
| `fw_openapi` | `fw openapi` | Generate OpenAPI spec |
| `fw_doctor` | `fw doctor` | Check environment health |
| `fw_init` | `fw init` | Create new project |

## Pack Integration

When you install a Flow Weaver pack (e.g. `@synergenius/flow-weaver-pack-weaver`), its tools automatically become available through `fw_search` and `fw_execute` on the next Gateway restart.

```bash
# In your OpenClaw workspace
npm install @synergenius/flow-weaver-pack-weaver
# Restart OpenClaw Gateway
# Pack tools now available: fw_weaver_run, fw_weaver_swarm, etc.
```

## Architecture

```
OpenClaw Agent
  |
  |-- fw_search(query) --> Internal Registry (45+ tools)
  |                              |
  |-- fw_execute(tool, params) --+-- Core tools (runCommand API)
                                 |-- Pack MCP tools (handleToolCall)
                                 +-- Pack CLI commands (handleCommand)
```

- **Two-tool pattern**: Only `fw_search` and `fw_execute` are registered with OpenClaw, keeping the system prompt minimal
- **Internal registry**: All tools stored server-side with searchable names, descriptions, and tags
- **Pack auto-discovery**: Scans workspace `node_modules` for `flowweaver.manifest.json` at startup
- **Path validation**: All file operations validated to stay within workspace boundaries
- **Atomic writes**: Workflow metadata uses write-then-rename for crash safety

## Slash Commands

Quick-access commands that don't require the LLM:

| Command | Description |
|---|---|
| `/fw-workflows` | List all workflows |
| `/fw-run <name>` | Run a workflow |
| `/fw-diagram <name>` | Show diagram |
| `/fw-deploy <name>` | Deploy to cloud |
| `/fw-costs` | Show AI token usage |
| `/fw-status` | Show deployments |
| `/fw-login` | Authenticate |

## HTTP Routes (Studio Bridge)

The plugin exposes HTTP routes for the Flow Weaver Studio to connect:

| Route | Method | Description |
|---|---|---|
| `/flow-weaver/workflows` | GET | List workflows |
| `/flow-weaver/workflows/:id` | GET | Get workflow details |
| `/flow-weaver/workflows/:id` | PUT | Update workflow |
| `/flow-weaver/webhooks/:id` | POST | Trigger workflow via webhook |

## Testing Proxy

A test proxy (`proxy.mjs`) is included for development. It translates OpenAI chat completions API requests into Claude CLI calls, enabling manual testing of the plugin through OpenClaw.

```bash
# Live mode - auto-sends to Claude CLI
node proxy.mjs --port 8787

# Approval mode - queue requests for manual review
node proxy.mjs --port 8787 --approval

# Dry-run mode - log requests without calling Claude
node proxy.mjs --port 8787 --dry-run
```

Configure OpenClaw to use the proxy:
```json
{
  "models": {
    "providers": {
      "claude-proxy": {
        "baseUrl": "http://host.docker.internal:8787",
        "api": "openai-completions",
        "models": [{ "id": "claude", "name": "Claude via Proxy", "contextWindow": 200000, "maxTokens": 64000 }]
      }
    }
  }
}
```

## Development

```bash
npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run 178 tests
npm run lint          # ESLint check
npm run typecheck     # TypeScript strict check
```

## Requirements

- OpenClaw >= 2026.3.0
- Node.js >= 22
- `@synergenius/flow-weaver` >= 0.32.2

## License

MIT

This plugin requires `@synergenius/flow-weaver` as a peer dependency, which is licensed under the [Flow Weaver Library License](https://github.com/synergenius-fw/flow-weaver/blob/main/LICENSE). Use of this plugin is subject to that dependency's license terms.