什么是 SoulFlow？

SoulFlow 是一个强大的框架，旨在协调 OpenClaw 生态系统内复杂的多步 AI 操作。通过利用 Openclaw Skills，开发者可以定义一系列任务序列——从安全审计到功能开发——这些任务在具有完整工具访问权限的隔离 Agent 会话中执行。这确保了工作流的每一步都保持专注并免受上下文干扰，从而最大限度地提高 AI 工作者的效率和准确性。

该框架允许用户将自然语言请求转化为结构化执行。无论您是在管理开发流水线还是自动化重复的研究任务，SoulFlow 都提供了基础设施，以弥合简单聊天交互与复杂自主 Agent 之间的差距。通过将其集成到您的 Openclaw Skills 库中，您可以获得创建量身定制的自定义工作流的能力。

下载入口:https://github.com/openclaw/skills/tree/main/skills/0xtommythomas-dev/soulflow

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

SoulFlow 应用场景

• 自动安全审计：扫描代码库、排查漏洞优先级并应用修复。
• 简化错误分流：Agent 调查根本原因并验证解决方案。
• 端到端功能开发：包括架构规划、实现和质量审查。
• 内容创作流水线：自主处理研究、起草和发布。
• 运维自动化：用于部署、健康检查以及失败时的自动回滚。

1. 用户通过自然语言或命令行发起请求。
2. SoulFlow 识别合适的工作流并创建一个专用的 soulflow-worker Agent。
3. 系统通过 WebSocket 使用挑战-响应身份验证连接到本地网关。
4. 每个定义的步骤都在新会话中执行，以确保完全隔离。
5. 变量和输出在步骤之间传递，允许 Agent 使用之前操作的结果。
6. 完成后，框架会自动通知主会话并将执行状态保存为 JSON。

SoulFlow 配置指南

确保您已安装 Node.js 22+ 以及 OpenClaw 2026.2.x 或更高版本。使用以下命令初始化并测试连接：

cd ~/.openclaw/workspace/soulflow
node soulflow.js test

要在终端手动运行特定工作流：

node soulflow.js run  ""

SoulFlow 数据架构与分类体系

SoulFlow 在工作区目录内组织数据，以保持持久性和可审计性。以下结构用于管理 Openclaw Skills 数据：

name: soulflow
description: General-purpose AI workflow framework for OpenClaw. Build custom multi-step workflows for any task — dev, ops, research, content, or automation. Ships with dev workflow examples.
homepage: https://github.com/0xtommythomas-dev/soulflow
metadata: 
  clawdbot:
    emoji: "??"
    requires:
      bins: ["node"]
      config_files:
        - "~/.openclaw/openclaw.json"
    permissions:
      config: 
        read: ["~/.openclaw/openclaw.json"]
        write: ["~/.openclaw/openclaw.json"]
      gateway: modify
      agents: create
      filesystem: 
        read: ["~/.openclaw/workspace"]
        write: ["~/.openclaw/workspace/.soulflow", "~/.openclaw/agents/soulflow-worker"]
      credentials: inherit
    security_note: "Creates a dedicated 'soulflow-worker' agent with full tool access (read, write, edit, exec, browser) to execute workflow steps. Reads gateway config (~/.openclaw/openclaw.json) for authentication token. Modifies gateway config to add/manage worker agent. Worker inherits authProfiles from existing agents (grants access to external services like GitHub, cloud providers). All operations run locally with your existing OpenClaw permissions. Only install if you trust the skill author and have reviewed the code."

SoulFlow — Workflow Framework for OpenClaw

A framework for building custom AI workflows. Each workflow is a series of steps that execute in isolated agent sessions with full tool access. Define your workflow in JSON, invoke it naturally, and let the agents handle the execution.

What you can build:

• Development pipelines (security audits, bug fixes, feature development)
• Content workflows (research → draft → edit → publish)
• Operations automation (deploy → verify → rollback-on-fail)
• Research pipelines (gather → analyze → synthesize → report)
• Any multi-step task that benefits from isolated, focused agent sessions

Ships with 3 example dev workflows to show you how it works. Build your own for anything.

Quick Start

Natural language (easiest): Just tell your agent what you need:

• "Run a security audit on my project at ~/myapp"
• "Fix this bug: users can't login with Google OAuth in ~/webapp"
• "Build a referral system for ~/webapp"

Your agent reads this SKILL.md and invokes SoulFlow automatically.

Command line:

cd ~/.openclaw/workspace/soulflow

# Run a security audit
node soulflow.js run security-audit "Audit the codebase at ~/project for vulnerabilities"

# Fix a bug
node soulflow.js run bug-fix "Login returns 500 when email has uppercase letters in ~/myapp"

# Build a feature
node soulflow.js run feature-dev "Add dark mode toggle to the settings page in ~/myapp"

How It Works

SoulFlow connects to your local OpenClaw gateway via WebSocket and runs each workflow step as an isolated agent session. A dedicated soulflow-worker agent is auto-created with minimal context — no memory bleed from your main agent.

Each step:

1. Gets a fresh session (no context bloat)
2. Receives the task + output from previous steps
3. Has full tool access (read, write, edit, exec, browser)
4. Must complete its work and report results

Auto-notifications (v1.1.0+): When workflows complete, SoulFlow automatically notifies the main agent session with results. No need to manually check status.

Example Workflows (Included)

These are examples to show what's possible. Build your own for any domain.

security-audit

Scan → Prioritize → Fix → Verify Development example: Reads your source files, identifies vulnerabilities by severity, applies fixes, then verifies them.

bug-fix

Triage → Fix → Verify Development example: Investigates the root cause by reading code, applies the fix, then verifies it didn't introduce regressions.

feature-dev

Plan → Implement → Review Development example: Architects the implementation plan, writes the code, then reviews for quality and correctness.

Want content workflows? Research pipelines? Deploy automation? Create your own .workflow.json — see Custom Workflows below.

Commands

node soulflow.js run  ""    # Run a workflow
node soulflow.js list                       # List available workflows
node soulflow.js runs                       # List past runs
node soulflow.js status [run-id]            # Check run status
node soulflow.js test                       # Test gateway connection

Natural Language (via your agent)

The agent knows how to invoke SoulFlow for you. Just describe what you want:

Security audits:

• "Audit my app for security issues"
• "Check ~/myapp for vulnerabilities"
• "Scan the codebase for security problems"

Bug fixes:

• "Fix this bug: login fails when..."
• "There's a problem with the payment flow"
• "Users are seeing 500 errors when they..."

Features:

• "Build a referral system"
• "Add dark mode to the settings page"
• "Implement OAuth login with Google"

How it works:

1. You tell your agent what you need
2. Your agent reads this SKILL.md
3. Agent invokes node soulflow.js run ""
4. SoulFlow runs the workflow and reports back

Pattern matching: The agent matches your message to workflows:

• Security audit → keywords: "audit", "security", "scan", "vulnerabilit"
• Bug fix → keywords: "fix", "bug", "broken", "not working", "error"
• Feature dev → keywords: "build", "add", "implement", "create", "feature"

No workflow matches? Agent will ask which workflow you want or suggest creating a custom one.

Custom Workflows

You can create workflows for ANY task. Define them in JSON and place in the workflows/ directory.

Creating via Chat

Tell your agent:

"Create a SoulFlow workflow for [your use case]"

Examples:

• "Create a workflow for content publishing: research topic → draft article → edit → publish to blog"
• "Create a workflow for deployment: run tests → build → deploy → verify health checks → rollback if failed"
• "Create a workflow for weekly reports: gather metrics → analyze trends → generate summary → send email"

Your agent will:

1. Design the workflow steps
2. Write the .workflow.json file to workflows/
3. Show you how to run it

Manual Creation

Create a .workflow.json file in the workflows/ directory:

{
  "id": "my-workflow",
  "name": "My Custom Workflow",
  "version": 1,
  "description": "What this workflow does",
  "steps": [
    {
      "id": "step1",
      "name": "First Step",
      "input": "Do this thing: {{task}}",
      "expects": "STATUS: done",
      "maxRetries": 1
    },
    {
      "id": "step2",
      "name": "Second Step",
      "input": "Now do this based on step 1:

{{step1_output}}

Original task: {{task}}",
      "expects": "STATUS: done",
      "maxRetries": 1
    }
  ]
}

Variables

• {{task}} — The user's original task description
• {{stepid_output}} — Full output from a previous step (e.g. {{scan_output}})
• Any KEY: value lines in step output become variables (e.g. ROOT_CAUSE: ... → {{root_cause}})

Prompt Tips

For best results, write prompts that:

• Explicitly tell the agent to use tools: "Use read to examine the file", "Use edit to apply the fix"
• Say "Do NOT just describe — actually do it"
• End with "When done, end with: STATUS: done"

Architecture

• Zero dependencies — Pure Node.js 22 (native WebSocket)
• Gateway-native — Connects via WebSocket with challenge-response auth
• Session isolation — Each step in a fresh session
• Dedicated worker — Auto-creates soulflow-worker agent with minimal brain files
• JSON state — Run history saved to ~/.openclaw/workspace/.soulflow/runs/
• 10-minute timeout per step (configurable)

Requirements

• OpenClaw 2026.2.x or later
• Node.js 22+ (for native WebSocket)
• Gateway with token auth configured

Security & Permissions

What SoulFlow does to your OpenClaw instance:

1. Reads your gateway config (~/.openclaw/openclaw.json) to obtain the authentication token needed to connect via WebSocket
2. Modifies your gateway config (~/.openclaw/openclaw.json) via config.patch to register the soulflow-worker agent
3. Creates a dedicated worker agent (soulflow-worker) with minimal brain files (SOUL.md only, no memory/history)
4. Copies authProfiles from existing agents — Worker inherits credentials for external services (GitHub, cloud providers, etc.) that your other agents use
5. Grants the worker full tool access (read, write, edit, exec, browser) — this is required for workflows to actually perform tasks
6. Writes run state to ~/.openclaw/workspace/.soulflow/runs/ as JSON files

Why these permissions are needed:

• Config read/write: Required to authenticate with the gateway and register the worker agent (same as openclaw CLI tool)
• Agent creation: Each workflow step runs in an isolated session to prevent context bleed
• authProfiles inheritance: Allows workflows to interact with external services (e.g., git push, cloud API calls) using your existing credentials
• Full tools: Workflows need real capabilities (e.g., security-audit reads files, bug-fix edits code, deploy-pipeline pushes to git)
• Filesystem write: Stores workflow history and allows workflows to create/modify files

Security considerations:

• Worker agent has NO access to your main agent's memory or history
• Worker DOES inherit your external service credentials (authProfiles) — can access GitHub, cloud APIs, etc.
• Workflows run with YOUR permissions (same as running commands yourself)
• Malicious workflows could read/modify files, run commands, or access external services
• Only install SoulFlow if you trust the skill author (review code on GitHub first)
• Only run workflows you trust — custom workflows from untrusted sources could exfiltrate data or misuse credentials
• Run SoulFlow in isolated/sandboxed environments if processing untrusted workflows

Recommended practices:

• Review built-in workflows before first use (especially security-audit and bug-fix)
• Inspect custom .workflow.json files before running
• Review GitHub repo (https://github.com/0xtommythomas-dev/soulflow) before installation
• Run on non-production OpenClaw instances when testing new workflows
• Back up important files before running workflows that modify code
• Use BYOK (bring your own keys) mode if you want isolated credentials per workflow
• Monitor ~/.openclaw/workspace/.soulflow/runs/ for workflow execution logs

For Agents: How to Invoke SoulFlow

When the user requests a workflow (security audit, bug fix, feature build, etc.), you should:

1. Identify the workflow by matching keywords:

   • Security audit: "audit", "security", "scan", "vulnerabilit"
   • Bug fix: "fix", "bug", "broken", "not working", "error"
   • Feature dev: "build", "add", "implement", "create", "feature"
   • Custom: check workflows/*.workflow.json for other options

2. Extract the task description — the user's description of what they want done

3. Invoke SoulFlow using exec:

   cd /root/.openclaw/workspace/soulflow && node soulflow.js run  ""
   

4. Monitor the run — SoulFlow will output the run ID, then show progress as each step completes

5. Report results — When complete, relay the final status to the user

Example:

User: "Run a security audit on ~/myapp"
You: [exec] cd /root/.openclaw/workspace/soulflow && node soulflow.js run security-audit "Audit ~/myapp for vulnerabilities"

Creating workflows for users: If the user asks you to create a custom workflow:

1. Design the workflow steps based on their requirements
2. Write a .workflow.json file to /root/.openclaw/workspace/soulflow/workflows/
3. Show them how to run it

See CONTRIBUTING.md for workflow design best practices.