aitbc/.windsurf/skills/openclaw-management.md

description, title, version

description	title	version
OpenClaw agent management and coordination capabilities	OpenClaw Agent Management Skill	1.0

OpenClaw Agent Management Skill

This skill provides comprehensive OpenClaw agent management, communication, and coordination capabilities. Focus on agent operations, session management, and cross-agent workflows.

Prerequisites

• OpenClaw 2026.3.24+ installed and gateway running
• Agent workspace configured: ~/.openclaw/workspace/
• Network connectivity for multi-agent coordination

Critical: Correct OpenClaw Syntax

Agent Commands

# CORRECT — always use --message (long form), not -m
openclaw agent --agent main --message "Your task here" --thinking medium

# Session-based communication (maintains context across calls)
SESSION_ID="workflow-$(date +%s)"
openclaw agent --agent main --session-id $SESSION_ID --message "Initialize task" --thinking low
openclaw agent --agent main --session-id $SESSION_ID --message "Continue task" --thinking medium

# Thinking levels: off | minimal | low | medium | high | xhigh

Warning

: The -m short form does NOT work reliably. Always use --message. WARNING: --session-id is required to maintain conversation context across multiple agent calls.

Agent Status and Management

# Check agent status
openclaw status --agent all
openclaw status --agent main

# List available agents
openclaw list --agents

# Agent workspace management
openclaw workspace --setup
openclaw workspace --status

Agent Communication Patterns

Single Agent Tasks

# Simple task execution
openclaw agent --agent main --message "Analyze the system logs and report any errors" --thinking high

# Task with specific parameters
openclaw agent --agent main --message "Process this data: /path/to/data.csv" --thinking medium --parameters "format:csv,mode:analyze"

Session-Based Workflows

# Initialize session
SESSION_ID="data-analysis-$(date +%s)"

# Step 1: Data collection
openclaw agent --agent main --session-id $SESSION_ID --message "Collect data from API endpoints" --thinking low

# Step 2: Data processing  
openclaw agent --agent main --session-id $SESSION_ID --message "Process collected data and generate insights" --thinking medium

# Step 3: Report generation
openclaw agent --agent main --session-id $SESSION_ID --message "Create comprehensive report with visualizations" --thinking high

Multi-Agent Coordination

# Coordinator agent manages workflow
openclaw agent --agent coordinator --message "Coordinate data processing across multiple agents" --thinking high

# Worker agents execute specific tasks
openclaw agent --agent worker-1 --message "Process dataset A" --thinking medium
openclaw agent --agent worker-2 --message "Process dataset B" --thinking medium

# Aggregator combines results
openclaw agent --agent aggregator --message "Combine results from worker-1 and worker-2" --thinking high

Agent Types and Roles

Coordinator Agent

# Setup coordinator for complex workflows
openclaw agent --agent coordinator --message "Initialize as workflow coordinator. Manage task distribution, monitor progress, aggregate results." --thinking high

# Use coordinator for orchestration
openclaw agent --agent coordinator --message "Orchestrate data pipeline: extract → transform → load → validate" --thinking high

Worker Agent

# Setup worker for specific tasks
openclaw agent --agent worker --message "Initialize as data processing worker. Execute assigned tasks efficiently." --thinking medium

# Assign specific work
openclaw agent --agent worker --message "Process customer data file: /data/customers.json" --thinking medium

Monitor Agent

# Setup monitor for oversight
openclaw agent --agent monitor --message "Initialize as system monitor. Track performance, detect anomalies, report status." --thinking low

# Continuous monitoring
openclaw agent --agent monitor --message "Monitor system health and report any issues" --thinking minimal

Agent Workflows

Data Processing Workflow

SESSION_ID="data-pipeline-$(date +%s)"

# Phase 1: Data Extraction
openclaw agent --agent extractor --session-id $SESSION_ID --message "Extract data from sources" --thinking medium

# Phase 2: Data Transformation
openclaw agent --agent transformer --session-id $SESSION_ID --message "Transform extracted data" --thinking medium

# Phase 3: Data Loading
openclaw agent --agent loader --session-id $SESSION_ID --message "Load transformed data to destination" --thinking medium

# Phase 4: Validation
openclaw agent --agent validator --session-id $SESSION_ID --message "Validate loaded data integrity" --thinking high

Monitoring Workflow

SESSION_ID="monitoring-$(date +%s)"

# Continuous monitoring loop
while true; do
    openclaw agent --agent monitor --session-id $SESSION_ID --message "Check system health" --thinking minimal
    sleep 300  # Check every 5 minutes
done

Analysis Workflow

SESSION_ID="analysis-$(date +%s)"

# Initial analysis
openclaw agent --agent analyst --session-id $SESSION_ID --message "Perform initial data analysis" --thinking high

# Deep dive analysis
openclaw agent --agent analyst --session-id $SESSION_ID --message "Deep dive into anomalies and patterns" --thinking high

# Report generation
openclaw agent --agent analyst --session-id $SESSION_ID --message "Generate comprehensive analysis report" --thinking high

Agent Configuration

Agent Parameters

# Agent with specific parameters
openclaw agent --agent main --message "Process data" --thinking medium \
    --parameters "input_format:json,output_format:csv,mode:batch"

# Agent with timeout
openclaw agent --agent main --message "Long running task" --thinking high \
    --parameters "timeout:3600,retry_count:3"

# Agent with resource constraints
openclaw agent --agent main --message "Resource-intensive task" --thinking high \
    --parameters "max_memory:4GB,max_cpu:2,max_duration:1800"

Agent Context Management

# Set initial context
openclaw agent --agent main --message "Initialize with context: data_analysis_v2" --thinking low \
    --context "project:data_analysis,version:2.0,dataset:customer_data"

# Maintain context across calls
openclaw agent --agent main --session-id $SESSION_ID --message "Continue with previous context" --thinking medium

# Update context
openclaw agent --agent main --session-id $SESSION_ID --message "Update context: new_phase" --thinking medium \
    --context-update "phase:processing,status:active"

Agent Communication

Cross-Agent Messaging

# Agent A sends message to Agent B
openclaw agent --agent agent-a --message "Send results to agent-b" --thinking medium \
    --send-to "agent-b" --message-type "results"

# Agent B receives and processes
openclaw agent --agent agent-b --message "Process received results" --thinking medium \
    --receive-from "agent-a"

Agent Collaboration

# Setup collaboration team
TEAM_ID="team-analytics-$(date +%s)"

# Team leader coordination
openclaw agent --agent team-lead --session-id $TEAM_ID --message "Coordinate team analytics workflow" --thinking high

# Team member tasks
openclaw agent --agent analyst-1 --session-id $TEAM_ID --message "Analyze customer segment A" --thinking high
openclaw agent --agent analyst-2 --session-id $TEAM_ID --message "Analyze customer segment B" --thinking high

# Team consolidation
openclaw agent --agent team-lead --session-id $TEAM_ID --message "Consolidate team analysis results" --thinking high

Agent Error Handling

Error Recovery

# Agent with error handling
openclaw agent --agent main --message "Process data with error handling" --thinking medium \
    --parameters "error_handling:retry_on_failure,max_retries:3,fallback_mode:graceful_degradation"

# Monitor agent errors
openclaw agent --agent monitor --message "Check for agent errors and report" --thinking low \
    --parameters "check_type:error_log,alert_threshold:5"

Agent Debugging

# Debug mode
openclaw agent --agent main --message "Debug task execution" --thinking high \
    --parameters "debug:true,log_level:verbose,trace_execution:true"

# Agent state inspection
openclaw agent --agent main --message "Report current state and context" --thinking low \
    --parameters "report_type:state,include_context:true"

Agent Performance Optimization

Efficient Agent Usage

# Batch processing
openclaw agent --agent processor --message "Process data in batches" --thinking medium \
    --parameters "batch_size:100,parallel_processing:true"

# Resource optimization
openclaw agent --agent optimizer --message "Optimize resource usage" --thinking high \
    --parameters "memory_efficiency:true,cpu_optimization:true"

Agent Scaling

# Scale out work
for i in {1..5}; do
    openclaw agent --agent worker-$i --message "Process batch $i" --thinking medium &
done

# Scale in coordination
openclaw agent --agent coordinator --message "Coordinate scaled-out workers" --thinking high

Agent Security

Secure Agent Operations

# Agent with security constraints
openclaw agent --agent secure-agent --message "Process sensitive data" --thinking high \
    --parameters "security_level:high,data_encryption:true,access_log:true"

# Agent authentication
openclaw agent --agent authenticated-agent --message "Authenticated operation" --thinking medium \
    --parameters "auth_required:true,token_expiry:3600"

Agent Monitoring and Analytics

Performance Monitoring

# Monitor agent performance
openclaw agent --agent monitor --message "Monitor agent performance metrics" --thinking low \
    --parameters "metrics:cpu,memory,tasks_per_second,error_rate"

# Agent analytics
openclaw agent --agent analytics --message "Generate agent performance report" --thinking medium \
    --parameters "report_type:performance,period:last_24h"

Troubleshooting Agent Issues

Common Agent Problems

1. Session Loss: Use consistent --session-id across calls
2. Context Loss: Maintain context with --context parameter
3. Performance Issues: Optimize --thinking level and task complexity
4. Communication Failures: Check agent status and network connectivity

Debug Commands

# Check agent status
openclaw status --agent all

# Test agent communication
openclaw agent --agent main --message "Ping test" --thinking minimal

# Check workspace
openclaw workspace --status

# Verify agent configuration
openclaw config --show --agent main

Best Practices

Session Management

• Use meaningful session IDs: task-type-$(date +%s)
• Maintain context across related tasks
• Clean up sessions when workflows complete

Thinking Level Optimization

• off: Simple, repetitive tasks
• minimal: Quick status checks, basic operations
• low: Data processing, routine analysis
• medium: Complex analysis, decision making
• high: Strategic planning, complex problem solving
• xhigh: Critical decisions, creative tasks

Agent Organization

• Use descriptive agent names: data-processor, monitor, coordinator
• Group related agents in workflows
• Implement proper error handling and recovery

Performance Tips

• Batch similar operations
• Use appropriate thinking levels
• Monitor agent resource usage
• Implement proper session cleanup

This OpenClaw Agent Management skill provides the foundation for effective agent coordination, communication, and workflow orchestration across any domain or application.