🚀 OpenClaw PSAM - Parallel Sub-Agent Orchestrator

Break down complex tasks into parallel sub-agents with intelligent model selection and real-time progress tracking

An OpenClaw plugin that orchestrates multiple AI sub-agents to work on complex tasks in parallel, with smart model selection, persistent state tracking, and automated resource management.

简体中文文档 | English

✨ Key Features

🧩 Intelligent Task Decomposition - Automatically break down complex tasks into manageable subtasks
🎯 Smart Model Selection - Choose optimal AI models based on task complexity and cost
📊 Real-time Progress Tracking - Monitor all sub-agents with detailed status updates
🔄 Persistent State Management - Task states survive system restarts
📝 Complete Activity Logging - JSONL format logs for debugging and analysis
🧹 Auto Resource Cleanup - Automatic cleanup of old tasks and progress files
⚙️ Dynamic Configuration - Add/remove models and adjust settings at runtime

🎯 Quick Start

Installation

Navigate to your OpenClaw extensions directory:

cd ~/.openclaw/extensions

Clone or copy the plugin:

git clone https://github.com/Ryandawson2019/openclaw-psam.git
# or
cp -r /path/to/openclaw-psam ~/.openclaw/extensions/

Build the plugin:

cd openclaw-psam
npm install
npm run build

Restart OpenClaw:

openclaw gateway restart

Your First Orchestrated Task

Via Tool Call:

parallel_subagent_orchestrator_orchestrate({
  task_description: "Analyze Q1 sales data and create summary reports",
  priority: "high",
  subtask_count: 3
})

Via Natural Language (Recommended):

Please help me analyze Q1 sales data in parallel and create summary reports, split into 3 subtasks

Or simply:

Help me analyze Q1 sales data in parallel, split into 3 subtasks

The plugin will:

✅ Break down your task into 3 subtasks
✅ Select optimal models for each subtask
✅ Return execution instructions
✅ Track progress of all sub-agents
✅ Report results back to you

📚 Documentation

Available Tools

1. 🎬 `parallel_subagent_orchestrator_orchestrate`

Create and launch a new orchestrated task with multiple sub-agents.

Parameters:

Parameter	Type	Required	Description
`task_description`	`string`	✅	Clear description of what needs to be done
`priority`	`string`	❌	`high` \| `medium` \| `low` (default: medium)
`models`	`string`	❌	Comma-separated list of specific models to use
`subtask_count`	`number`	❌	Number of subtasks: 1-5 (default: 1)

Example:

{
  "task_description": "Research and summarize latest AI trends in 2024",
  "priority": "high",
  "subtask_count": 4
}

Returns:

task_id - Unique identifier for tracking
subtasks - Array of generated subtasks
spawn_instructions - Ready-to-use execution commands

2. 📊 `parallel_subagent_orchestrator_orchestrate_status`

Query the current status of any orchestrated task or subtask.

Parameters:

Parameter	Type	Required	Description
`task`	`string`	❌	Filter by main task ID
`session`	`string`	❌	Filter by sub-agent session ID
`status_filter`	`string`	❌	`pending` \| `running` \| `completed` \| `failed` \| `aborted`

Examples:

// Get all tasks
{}

// Get specific task
{ "task": "task-abc-123" }

// Get only running tasks
{ "status_filter": "running" }

3. ⚙️ `parallel_subagent_orchestrator_orchestrate_config`

Manage available AI models for task orchestration.

Examples:

// List all available models
{ "action": "list" }

// Add a new model
{
  "action": "add",
  "model_id": "anthropic/claude-sonnet-4-5"
}

// Set model preference with note
{
  "action": "prefer",
  "model_id": "anthropic/claude-sonnet-4-5",
  "note": "Best for complex reasoning tasks"
}

// Replace entire model list
{
  "action": "replace",
  "models": "anthropic/claude-sonnet-4-5,gemini-2.0-flash,gpt-4o-mini"
}

// Reset to default models
{ "action": "reset" }

4. 🛑 `parallel_subagent_orchestrator_orchestrate_abort`

Terminate a specific sub-agent session.

Parameters:

Parameter	Type	Required	Description
`session_id`	`string`	✅	The sub-agent session to terminate

5. 💉 `parallel_subagent_orchestrator_orchestrate_inject`

Send a message to a running sub-agent session.

Parameters:

Parameter	Type	Required	Description
`session_id`	`string`	✅	Target sub-agent session ID
`message`	`string`	✅	Message content to inject

6. 📜 `parallel_subagent_orchestrator_orchestrate_history`

Retrieve message history from a sub-agent session.

Parameters:

Parameter	Type	Required	Description
`session_id`	`string`	✅	Sub-agent session ID
`include_tools`	`boolean`	❌	Include tool calls (default: false)
`limit`	`number`	❌	Max messages to return (default: 50)

Resource Management Tools

7. ⏰ `parallel_subagent_orchestrator_check_timeouts`

Identify and optionally abort long-running sub-agent sessions.

Parameters:

Parameter	Type	Required	Description
`timeout_minutes`	`number`	❌	Threshold in minutes, 5-1440 (default: 120)
`auto_abort`	`boolean`	❌	Auto-abort timed-out sessions (default: false)

8. 🧹 `parallel_subagent_orchestrator_cleanup`

Manual cleanup of old tasks, progress files, and zombie session detection.

Parameters:

Parameter	Type	Required	Description
`older_than_days`	`number`	❌	Delete tasks older than N days (default: 7)
`include_completed`	`boolean`	❌	Clean completed progress files (default: true)
`report_only`	`boolean`	❌	Preview without cleanup (default: false)

🎯 Model Configuration

The plugin includes a default model list that works out of the box. You can customize models at runtime using the orchestrate_config tool.

Default Models (Included)

Model	Speed	Cost	Context	Best For
`anthropic/claude-sonnet-4-5`	Medium	Medium	200K	Complex reasoning, analysis
`anthropic/claude-haiku-4-5`	Fast	Low	200K	Quick tasks, summaries
`gemini-2.0-flash`	Very Fast	Very Low	1M	High-volume parallel tasks
`gemini-2.0-pro`	Medium	Medium	2M	Advanced reasoning, coding

Note: This is a built-in default list. You don't need to configure it unless you want to customize it.

📂 File Structure

openclaw-psam/
├── state/
│   └── tasks.json           # Persistent task state
├── logs/
│   └── task_activity.jsonl   # Activity log (JSONL format)
├── models.json               # Model capabilities config (auto-created)
├── config.json              # Plugin settings (optional)
├── index.ts                 # Main plugin code
└── package.json

⚙️ Configuration

Create config.json in the plugin directory to customize behavior:

{
  "enableAutoCleanup": true,
  "cleanupIntervalMs": 21600000,
  "sessionTimeoutMs": 7200000,
  "autoAbortTimeout": false
}

Settings:

Setting	Type	Default	Required	Description
`enableAutoCleanup`	boolean	`true`	❌	Enable periodic resource cleanup
`cleanupIntervalMs`	number	`21600000`	❌	Cleanup interval (6 hours)
`sessionTimeoutMs`	number	`7200000`	❌	Session timeout (2 hours)
`autoAbortTimeout`	boolean	`false`	❌	Auto-abort timed-out sessions
`wecomSenderSkillName`	string	`"wecom-sender"`	❌	Optional: Skill for notifications (requires wecom-sender plugin)
`monitoringAgentModel`	string	`"gemini-2.0-flash"`	❌	Optional: Model for status reports (must be available)

Notes:

All configuration fields are optional - the plugin works without any config
wecomSenderSkillName: Only needed if you have the wecom-sender plugin installed and want notifications
monitoringAgentModel: Only needed if you want to override the default monitoring model

🔄 Progress Reporting

Sub-agents report progress using sessions_send tool with formatted messages:

Format: [PSAM-PROGRESS] subtask-id | Step N/M | Description

Examples:

[PSAM-PROGRESS] sub-abc-123 | Step 2/5 | Analyzing user data...
[PSAM-PROGRESS] sub-abc-123 | Step 4/5 | Generating visualizations...
[PSAM-COMPLETE] sub-abc-123 | Result: Analysis complete, 3 insights found
[PSAM-FAILED] sub-xyz-789 | Reason: Data source unavailable

📖 Usage Examples

Natural Language (Recommended)

You can simply describe what you need in plain language:

Please help me analyze this project's code and find potential security issues

Please research the latest AI frameworks in parallel and generate a comparison report

Help me analyze sales data, split into 3 subtasks

OpenClaw will automatically call the orchestrate tool with appropriate parameters.

Tool-Based Examples

Example 1: Research Task

parallel_subagent_orchestrator_orchestrate({
  task_description: "Research top 10 AI frameworks and create comparison table",
  priority: "medium",
  subtask_count: 5
})

Example 2: Code Analysis

parallel_subagent_orchestrator_orchestrate({
  task_description: "Analyze codebase for security vulnerabilities",
  priority: "high",
  models: "anthropic/claude-sonnet-4-5"
})

Example 3: Multi-Language Translation

parallel_subagent_orchestrator_orchestrate({
  task_description: "Translate documentation to Spanish, French, and German",
  subtask_count: 3,
  priority: "low"
})

⚠️ Architecture Notes

Plugin SDK Limitations

OpenClaw plugins cannot directly call other tools due to SDK architecture. The orchestrate tool returns spawn instructions that must be executed manually by the agent.

Workflow:

1. Call orchestrate → Get task plan + spawn instructions
2. Use sessions_spawn → Execute subtasks
3. Call orchestrate_status → Track progress

This is by design - plugins follow a "receive parameters → return results" pattern without side effects.

🐛 Error Handling

Error	Cause	Solution
`API_UNAVAILABLE`	Internal tools unavailable	Use returned spawn instructions manually
`NO_MODEL_AVAILABLE`	No matching models	Add model via config or specify in request
`SESSION_NOT_FOUND`	Invalid session ID	Check session ID in status query
`SESSION_NOT_RUNNING`	Session already ended	No action needed

💻 Development

Build from Source

git clone https://github.com/Ryandawson2019/openclaw-psam.git
cd openclaw-psam
npm install
npm run build

Testing

# Restart OpenClaw to load changes
openclaw gateway restart

# Check plugin loaded successfully
openclaw doctor

Debug Logs

Successful loading shows:

[plugins] OpenClaw PSAM Orchestrator plugin loaded
[plugins] Loaded N models from /path/to/models.json
[plugins] All tools registered successfully

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Keywords

openclaw, openclaw-plugin, psam, orchestrator, subagent, multi-agent, task-management, parallel, automation, ai, agents, plugin, typescript, resource-management, cleanup

📞 Support

📧 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Docs: Full Documentation

⭐ Star this repo if it helped you!

Made with ❤️ by OpenClaw community

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
config.json		config.json
index.ts		index.ts
models.json		models.json
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🚀 OpenClaw PSAM - Parallel Sub-Agent Orchestrator

✨ Key Features

🎯 Quick Start

Installation

Your First Orchestrated Task

📚 Documentation

Available Tools

1. 🎬 parallel_subagent_orchestrator_orchestrate

2. 📊 parallel_subagent_orchestrator_orchestrate_status

3. ⚙️ parallel_subagent_orchestrator_orchestrate_config

4. 🛑 parallel_subagent_orchestrator_orchestrate_abort

5. 💉 parallel_subagent_orchestrator_orchestrate_inject

6. 📜 parallel_subagent_orchestrator_orchestrate_history

Resource Management Tools

7. ⏰ parallel_subagent_orchestrator_check_timeouts

8. 🧹 parallel_subagent_orchestrator_cleanup

🎯 Model Configuration

Default Models (Included)

📂 File Structure

⚙️ Configuration

🔄 Progress Reporting

📖 Usage Examples

Natural Language (Recommended)

Tool-Based Examples

Example 1: Research Task

Example 2: Code Analysis

Example 3: Multi-Language Translation

⚠️ Architecture Notes

Plugin SDK Limitations

🐛 Error Handling

💻 Development

Build from Source

Testing

Debug Logs

🤝 Contributing

📄 License

🔗 Keywords

📞 Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. 🎬 `parallel_subagent_orchestrator_orchestrate`

2. 📊 `parallel_subagent_orchestrator_orchestrate_status`

3. ⚙️ `parallel_subagent_orchestrator_orchestrate_config`

4. 🛑 `parallel_subagent_orchestrator_orchestrate_abort`

5. 💉 `parallel_subagent_orchestrator_orchestrate_inject`

6. 📜 `parallel_subagent_orchestrator_orchestrate_history`

7. ⏰ `parallel_subagent_orchestrator_check_timeouts`

8. 🧹 `parallel_subagent_orchestrator_cleanup`

Packages