{"skill":{"slug":"n8n","displayName":"n8n","summary":"Manage n8n workflows and automations via API. Use when working with n8n workflows, executions, or automation tasks - listing workflows, activating/deactivating, checking execution status, manually triggering workflows, or debugging automation issues.","description":"---\nname: n8n\ndescription: Manage n8n workflows and automations via API. Use when working with n8n workflows, executions, or automation tasks - listing workflows, activating/deactivating, checking execution status, manually triggering workflows, or debugging automation issues.\nmetadata: {\"openclaw\":{\"emoji\":\"\\u2699\\ufe0f\",\"requires\":{\"env\":[\"N8N_API_KEY\",\"N8N_BASE_URL\"]},\"primaryEnv\":\"N8N_API_KEY\"}}\n---\n\n# n8n Workflow Management\n\nComprehensive workflow automation management for n8n platform with creation, testing, execution monitoring, and performance optimization capabilities.\n\n## ⚠️ CRITICAL: Workflow Creation Rules\n\n**When creating n8n workflows, ALWAYS:**\n\n1. ✅ **Generate COMPLETE workflows** with all functional nodes\n2. ✅ **Include actual HTTP Request nodes** for API calls (ImageFX, Gemini, Veo, Suno, etc.)\n3. ✅ **Add Code nodes** for data transformation and logic\n4. ✅ **Create proper connections** between all nodes\n5. ✅ **Use real node types** (n8n-nodes-base.httpRequest, n8n-nodes-base.code, n8n-nodes-base.set)\n\n**NEVER:**\n- ❌ Create \"Setup Instructions\" placeholder nodes\n- ❌ Generate workflows with only TODO comments\n- ❌ Make incomplete workflows requiring manual node addition\n- ❌ Use text-only nodes as substitutes for real functionality\n\n**Example GOOD workflow:**\n```\nManual Trigger → Set Config → HTTP Request (API call) → Code (parse) → Response\n```\n\n**Example BAD workflow:**\n```\nManual Trigger → Code (\"Add HTTP nodes here, configure APIs...\")\n```\n\nAlways build the complete, functional workflow with all necessary nodes configured and connected.\n\n## Setup\n\n**Required environment variables:**\n- `N8N_API_KEY` — Your n8n API key (Settings → API in the n8n UI)\n- `N8N_BASE_URL` — Your n8n instance URL\n\n**Configure credentials via OpenClaw settings:**\n\nAdd to `~/.config/openclaw/settings.json`:\n```json\n{\n  \"skills\": {\n    \"n8n\": {\n      \"env\": {\n        \"N8N_API_KEY\": \"your-api-key-here\",\n        \"N8N_BASE_URL\": \"your-n8n-url-here\"\n      }\n    }\n  }\n}\n```\n\nOr set per-session (do **not** persist secrets in shell rc files):\n```bash\nexport N8N_API_KEY=\"your-api-key-here\"\nexport N8N_BASE_URL=\"your-n8n-url-here\"\n```\n\n**Verify connection:**\n```bash\npython3 scripts/n8n_api.py list-workflows --pretty\n```\n\n> **Security note:** Never store API keys in plaintext shell config files (`~/.bashrc`, `~/.zshrc`). Use the OpenClaw settings file or a secure secret manager.\n\n## Quick Reference\n\n### Workflow Management\n\n#### List Workflows\n```bash\npython3 scripts/n8n_api.py list-workflows --pretty\npython3 scripts/n8n_api.py list-workflows --active true --pretty\n```\n\n#### Get Workflow Details\n```bash\npython3 scripts/n8n_api.py get-workflow --id <workflow-id> --pretty\n```\n\n#### Create Workflows\n```bash\n# From JSON file\npython3 scripts/n8n_api.py create --from-file workflow.json\n```\n\n#### Activate/Deactivate\n```bash\npython3 scripts/n8n_api.py activate --id <workflow-id>\npython3 scripts/n8n_api.py deactivate --id <workflow-id>\n```\n\n### Testing & Validation\n\n#### Validate Workflow Structure\n```bash\n# Validate existing workflow\npython3 scripts/n8n_tester.py validate --id <workflow-id>\n\n# Validate from file\npython3 scripts/n8n_tester.py validate --file workflow.json --pretty\n\n# Generate validation report\npython3 scripts/n8n_tester.py report --id <workflow-id>\n```\n\n#### Dry Run Testing\n```bash\n# Test with data\npython3 scripts/n8n_tester.py dry-run --id <workflow-id> --data '{\"email\": \"test@example.com\"}'\n\n# Test with data file\npython3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json\n\n# Full test report (validation + dry run)\npython3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test.json --report\n```\n\n#### Test Suite\n```bash\n# Run multiple test cases\npython3 scripts/n8n_tester.py test-suite --id <workflow-id> --test-suite test-cases.json\n```\n\n### Execution Monitoring\n\n#### List Executions\n```bash\n# Recent executions (all workflows)\npython3 scripts/n8n_api.py list-executions --limit 10 --pretty\n\n# Specific workflow executions\npython3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 20 --pretty\n```\n\n#### Get Execution Details\n```bash\npython3 scripts/n8n_api.py get-execution --id <execution-id> --pretty\n```\n\n#### Manual Execution\n```bash\n# Trigger workflow\npython3 scripts/n8n_api.py execute --id <workflow-id>\n\n# Execute with data\npython3 scripts/n8n_api.py execute --id <workflow-id> --data '{\"key\": \"value\"}'\n```\n\n### Performance Optimization\n\n#### Analyze Performance\n```bash\n# Full performance analysis\npython3 scripts/n8n_optimizer.py analyze --id <workflow-id> --pretty\n\n# Analyze specific period\npython3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty\n```\n\n#### Get Optimization Suggestions\n```bash\n# Priority-ranked suggestions\npython3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty\n```\n\n#### Generate Optimization Report\n```bash\n# Human-readable report with metrics, bottlenecks, and suggestions\npython3 scripts/n8n_optimizer.py report --id <workflow-id>\n```\n\n#### Get Workflow Statistics\n```bash\n# Execution statistics\npython3 scripts/n8n_api.py stats --id <workflow-id> --days 7 --pretty\n```\n\n## Python API\n\n### Basic Usage\n\n```python\nfrom scripts.n8n_api import N8nClient\n\nclient = N8nClient()\n\n# List workflows\nworkflows = client.list_workflows(active=True)\n\n# Get workflow\nworkflow = client.get_workflow('workflow-id')\n\n# Create workflow\nnew_workflow = client.create_workflow({\n    'name': 'My Workflow',\n    'nodes': [...],\n    'connections': {...}\n})\n\n# Activate/deactivate\nclient.activate_workflow('workflow-id')\nclient.deactivate_workflow('workflow-id')\n\n# Executions\nexecutions = client.list_executions(workflow_id='workflow-id', limit=10)\nexecution = client.get_execution('execution-id')\n\n# Execute workflow\nresult = client.execute_workflow('workflow-id', data={'key': 'value'})\n```\n\n### Validation & Testing\n\n```python\nfrom scripts.n8n_api import N8nClient\nfrom scripts.n8n_tester import WorkflowTester\n\nclient = N8nClient()\ntester = WorkflowTester(client)\n\n# Validate workflow\nvalidation = tester.validate_workflow(workflow_id='123')\nprint(f\"Valid: {validation['valid']}\")\nprint(f\"Errors: {validation['errors']}\")\nprint(f\"Warnings: {validation['warnings']}\")\n\n# Dry run\nresult = tester.dry_run(\n    workflow_id='123',\n    test_data={'email': 'test@example.com'}\n)\nprint(f\"Status: {result['status']}\")\n\n# Test suite\ntest_cases = [\n    {'name': 'Test 1', 'input': {...}, 'expected': {...}},\n    {'name': 'Test 2', 'input': {...}, 'expected': {...}}\n]\nresults = tester.test_suite('123', test_cases)\nprint(f\"Passed: {results['passed']}/{results['total_tests']}\")\n\n# Generate report\nreport = tester.generate_test_report(validation, result)\nprint(report)\n```\n\n### Performance Optimization\n\n```python\nfrom scripts.n8n_optimizer import WorkflowOptimizer\n\noptimizer = WorkflowOptimizer()\n\n# Analyze performance\nanalysis = optimizer.analyze_performance('workflow-id', days=7)\nprint(f\"Performance Score: {analysis['performance_score']}/100\")\nprint(f\"Health: {analysis['execution_metrics']['health']}\")\n\n# Get suggestions\nsuggestions = optimizer.suggest_optimizations('workflow-id')\nprint(f\"Priority Actions: {len(suggestions['priority_actions'])}\")\nprint(f\"Quick Wins: {len(suggestions['quick_wins'])}\")\n\n# Generate report\nreport = optimizer.generate_optimization_report(analysis)\nprint(report)\n```\n\n## Common Workflows\n\n### 1. Validate and Test Workflow\n\n```bash\n# Validate workflow structure\npython3 scripts/n8n_tester.py validate --id <workflow-id> --pretty\n\n# Test with sample data\npython3 scripts/n8n_tester.py dry-run --id <workflow-id> \\\n  --data '{\"email\": \"test@example.com\", \"name\": \"Test User\"}'\n\n# If tests pass, activate\npython3 scripts/n8n_api.py activate --id <workflow-id>\n```\n\n### 2. Debug Failed Workflow\n\n```bash\n# Check recent executions\npython3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 10 --pretty\n\n# Get specific execution details\npython3 scripts/n8n_api.py get-execution --id <execution-id> --pretty\n\n# Validate workflow structure\npython3 scripts/n8n_tester.py validate --id <workflow-id>\n\n# Generate test report\npython3 scripts/n8n_tester.py report --id <workflow-id>\n\n# Check for optimization issues\npython3 scripts/n8n_optimizer.py report --id <workflow-id>\n```\n\n### 3. Optimize Workflow Performance\n\n```bash\n# Analyze current performance\npython3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty\n\n# Get actionable suggestions\npython3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty\n\n# Generate comprehensive report\npython3 scripts/n8n_optimizer.py report --id <workflow-id>\n\n# Review execution statistics\npython3 scripts/n8n_api.py stats --id <workflow-id> --days 30 --pretty\n\n# Test optimizations with dry run\npython3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json\n```\n\n### 4. Monitor Workflow Health\n\n```bash\n# Check active workflows\npython3 scripts/n8n_api.py list-workflows --active true --pretty\n\n# Review recent execution status\npython3 scripts/n8n_api.py list-executions --limit 20 --pretty\n\n# Get statistics for each critical workflow\npython3 scripts/n8n_api.py stats --id <workflow-id> --pretty\n\n# Generate health reports\npython3 scripts/n8n_optimizer.py report --id <workflow-id>\n```\n\n## Validation Checks\n\nThe testing module performs comprehensive validation:\n\n### Structure Validation\n- ✓ Required fields present (nodes, connections)\n- ✓ All nodes have names and types\n- ✓ Connection targets exist\n- ✓ No disconnected nodes (warning)\n\n### Configuration Validation\n- ✓ Nodes requiring credentials are configured\n- ✓ Required parameters are set\n- ✓ HTTP nodes have URLs\n- ✓ Webhook nodes have paths\n- ✓ Email nodes have content\n\n### Flow Validation\n- ✓ Workflow has trigger nodes\n- ✓ Proper execution flow\n- ✓ No circular dependencies\n- ✓ End nodes identified\n\n## Optimization Analysis\n\nThe optimizer analyzes multiple dimensions:\n\n### Execution Metrics\n- Total executions\n- Success/failure rates\n- Health status (excellent/good/fair/poor)\n- Error patterns\n\n### Performance Metrics\n- Node count and complexity\n- Connection patterns\n- Expensive operations (API calls, database queries)\n- Parallel execution opportunities\n\n### Bottleneck Detection\n- Sequential expensive operations\n- High failure rates\n- Missing error handling\n- Rate limit issues\n\n### Optimization Opportunities\n- **Parallel Execution:** Identify nodes that can run concurrently\n- **Caching:** Suggest caching for repeated API calls\n- **Batch Processing:** Recommend batching for large datasets\n- **Error Handling:** Add error recovery mechanisms\n- **Complexity Reduction:** Split complex workflows\n- **Timeout Settings:** Configure execution limits\n\n## Performance Scoring\n\nWorkflows receive a performance score (0-100) based on:\n\n- **Success Rate:** Higher is better (50% weight)\n- **Complexity:** Lower is better (30% weight)\n- **Bottlenecks:** Fewer is better (critical: -20, high: -10, medium: -5)\n- **Optimizations:** Implemented best practices (+5 each)\n\nScore interpretation:\n- **90-100:** Excellent - Well-optimized\n- **70-89:** Good - Minor improvements possible\n- **50-69:** Fair - Optimization recommended\n- **0-49:** Poor - Significant issues\n\n## Best Practices\n\n### Development\n1. **Plan Structure:** Design workflow nodes and connections before building\n2. **Validate First:** Always validate before deployment\n3. **Test Thoroughly:** Use dry-run with multiple test cases\n4. **Error Handling:** Add error nodes for reliability\n5. **Documentation:** Comment complex logic in Code nodes\n\n### Testing\n1. **Sample Data:** Create realistic test data files\n2. **Edge Cases:** Test boundary conditions and errors\n3. **Incremental:** Test each node addition\n4. **Regression:** Retest after changes\n5. **Production-like:** Use staging environment that mirrors production\n\n### Deployment\n1. **Inactive First:** Deploy workflows in inactive state\n2. **Gradual Rollout:** Test with limited traffic initially\n3. **Monitor Closely:** Watch first executions carefully\n4. **Quick Rollback:** Be ready to deactivate if issues arise\n5. **Document Changes:** Keep changelog of modifications\n\n### Optimization\n1. **Baseline Metrics:** Capture performance before changes\n2. **One Change at a Time:** Isolate optimization impacts\n3. **Measure Results:** Compare before/after metrics\n4. **Regular Reviews:** Schedule monthly optimization reviews\n5. **Cost Awareness:** Monitor API usage and execution costs\n\n### Maintenance\n1. **Health Checks:** Weekly execution statistics review\n2. **Error Analysis:** Investigate failure patterns\n3. **Performance Monitoring:** Track execution times\n4. **Credential Rotation:** Update credentials regularly\n5. **Cleanup:** Archive or delete unused workflows\n\n## Troubleshooting\n\n### Authentication Error\n```\nError: N8N_API_KEY not found in environment\n```\n**Solution:** Set environment variable:\n```bash\nexport N8N_API_KEY=\"your-api-key\"\n```\n\n### Connection Error\n```\nError: HTTP 401: Unauthorized\n```\n**Solution:** \n1. Verify API key is correct\n2. Check N8N_BASE_URL is set correctly\n3. Confirm API access is enabled in n8n\n\n### Validation Errors\n```\nValidation failed: Node missing 'name' field\n```\n**Solution:** Check workflow JSON structure, ensure all required fields present\n\n### Execution Timeout\n```\nStatus: timeout - Execution did not complete\n```\n**Solution:** \n1. Check workflow for infinite loops\n2. Reduce dataset size for testing\n3. Optimize expensive operations\n4. Set execution timeout in workflow settings\n\n### Rate Limiting\n```\nError: HTTP 429: Too Many Requests\n```\n**Solution:**\n1. Add Wait nodes between API calls\n2. Implement exponential backoff\n3. Use batch processing\n4. Check API rate limits\n\n### Missing Credentials\n```\nWarning: Node 'HTTP_Request' may require credentials\n```\n**Solution:**\n1. Configure credentials in n8n UI\n2. Assign credentials to node\n3. Test connection before activating\n\n## File Structure\n\n```\n~/clawd/skills/n8n/\n├── SKILL.md                    # This file\n├── scripts/\n│   ├── n8n_api.py             # Core API client (extended)\n│   ├── n8n_tester.py          # Testing & validation\n│   └── n8n_optimizer.py       # Performance optimization\n└── references/\n    └── api.md                 # n8n API reference\n```\n\n## API Reference\n\nFor detailed n8n REST API documentation, see [references/api.md](references/api.md) or visit:\nhttps://docs.n8n.io/api/\n\n## Support\n\n**Documentation:**\n- n8n Official Docs: https://docs.n8n.io\n- n8n Community Forum: https://community.n8n.io\n- n8n API Reference: https://docs.n8n.io/api/\n\n**Debugging:**\n1. Use validation: `python3 scripts/n8n_tester.py validate --id <workflow-id>`\n2. Check execution logs: `python3 scripts/n8n_api.py get-execution --id <execution-id>`\n3. Review optimization report: `python3 scripts/n8n_optimizer.py report --id <workflow-id>`\n4. Test with dry-run: `python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test.json`\n","tags":{"latest":"2.0.0"},"stats":{"comments":0,"downloads":19921,"installsAllTime":205,"installsCurrent":204,"stars":58,"versions":4},"createdAt":1768419094732,"updatedAt":1779076428283},"latestVersion":{"version":"2.0.0","createdAt":1770748031005,"changelog":"# Changelog - n8n Enhanced Workflow Management Skill\n\n## Version 2.0.0 - 10 Feb  2026\n\n### 🎉 Major Enhancement Release\n\nComplete redesign of the n8n skill with comprehensive workflow lifecycle management capabilities.\n\n### ✨ New Features\n\n#### Testing & Validation\n- **Structure Validation:** `n8n_tester.py` validates workflow integrity\n  - Node and connection validation\n  - Credential checking\n  - Configuration verification\n  - Flow analysis\n- **Dry-Run Testing:** Test workflows with sample data before activation\n- **Test Suites:** Run multiple test cases against workflows\n- **Validation Reports:** Human-readable test reports with errors and warnings\n\n#### Execution Monitoring\n- **Enhanced Execution Tracking:** Real-time execution monitoring\n- **Detailed Statistics:** Success/failure rates, execution patterns\n- **Error Analysis:** Identify and categorize failure patterns\n- **Retry Logic:** Built-in retry support for failed executions\n\n#### Performance Optimization\n- **Performance Analysis:** `n8n_optimizer.py` provides comprehensive metrics\n  - Execution metrics (success rate, failure patterns)\n  - Node analysis (complexity, expensive operations)\n  - Connection analysis (parallel paths, bottlenecks)\n  - Performance scoring (0-100)\n- **Bottleneck Detection:** Identify workflow performance issues\n  - Sequential expensive operations\n  - High failure rates\n  - Missing error handling\n- **Optimization Suggestions:** Actionable recommendations\n  - Parallel execution opportunities\n  - Caching strategies\n  - Batch processing\n  - Error handling improvements\n  - Complexity reduction\n- **Optimization Reports:** Human-readable performance reports\n\n### 📝 API Extensions\n\n#### n8n_api.py Enhancements\n- `validate_workflow()` - Validate workflow structure\n- `dry_run_workflow()` - Test workflow with mock data\n- `get_workflow_statistics()` - Get execution statistics\n- `analyze_workflow_performance()` - Performance analysis\n- CLI support for `create`, `validate`, and `stats` commands\n\n#### New Modules\n- **n8n_tester.py** - Testing and validation\n  - Structure validation\n  - Dry-run execution\n  - Test suite runner\n  - Report generation\n- **n8n_optimizer.py** - Performance optimization\n  - Performance analysis\n  - Bottleneck detection\n  - Optimization suggestions\n  - Report generation\n\n### 📚 Documentation\n\n#### New Documentation\n- **README.md** - Quick start guide with examples\n- **SKILL.md** - Comprehensive documentation (16KB)\n  - All CLI commands\n  - Python API examples\n  - Common workflows\n  - Best practices\n  - Troubleshooting guide\n- **templates/README.md** - Template documentation\n  - Template descriptions\n  - Configuration guides\n  - Test data examples\n- **CHANGELOG.md** - This file\n\n#### Updated Documentation\n- Enhanced quick reference\n- Added validation examples\n- Performance optimization guides\n- Template usage examples\n\n### 🗂️ File Structure\n\n```\n~/clawd/skills/n8n/\n├── README.md                   # Quick start guide\n├── SKILL.md                    # Comprehensive documentation\n├── CHANGELOG.md                # This file\n├── scripts/\n│   ├── n8n_api.py             # Core API client (extended)\n│   ├── n8n_tester.py          # NEW: Testing & validation\n│   └── n8n_optimizer.py       # NEW: Performance optimization\n└── references/\n    └── api.md\n```\n\n### 🔧 Technical Improvements\n\n- **Modular Design:** Separated concerns into specialized modules\n- **Error Handling:** Comprehensive error checking and reporting\n- **Import Flexibility:** Support for both direct and module imports\n- **Validation Logic:** Standalone validation without API dependency\n- **Performance Metrics:** Multi-dimensional workflow analysis\n- **Extensible Templates:** Easy to add new workflow templates\n\n### 📊 Metrics & Analysis\n\nNew performance metrics tracked:\n- Execution success/failure rates\n- Node complexity scores (0-100)\n- Performance scores (0-100)\n- Health status (excellent/good/fair/poor)\n- Bottleneck severity levels\n- Optimization priorities (high/medium/low)\n\n### 🎯 Use Cases\n\nThe enhanced skill now supports:\n1. **Rapid Prototyping:** Deploy templates and test within minutes\n2. **Quality Assurance:** Validate and test before production deployment\n3. **Performance Tuning:** Identify and resolve bottlenecks\n4. **Continuous Monitoring:** Track workflow health over time\n5. **Best Practices:** Built-in optimization recommendations\n\n### 🔄 Migration from v1.0\n\nNo breaking changes. All v1.0 functionality preserved and enhanced:\n- `list-workflows` - Still works\n- `get-workflow` - Still works\n- `activate` / `deactivate` - Still works\n- `list-executions` / `get-execution` - Still works\n- `execute` - Still works\n\nNew commands added:\n- `create` - Create workflows from templates or files\n- `validate` - Validate workflow structure\n- `stats` - Get execution statistics\n\n### 🐛 Bug Fixes\n\n- Fixed import issues in testing module\n- Added standalone validation for file-based workflows\n- Improved error messages for missing credentials\n- Enhanced connection validation logic\n\n### ⚡ Performance\n\n- Validation runs without API calls for file-based workflows\n- Efficient execution monitoring with configurable polling\n- Optimized statistics calculation for large execution histories\n\n### 🔐 Security\n\n- No credentials stored in templates (placeholders only)\n- Environment variable-based authentication\n- Validation runs safely without modifying workflows\n\n### 📦 Dependencies\n\nNo new dependencies\n- `requests` (existing)\n- `json`, `sys`, `argparse`, `pathlib`, `typing` (standard library)\n\n### 🚀 Future Roadmap\n\nPlanned for future releases:\n- Additional workflow templates (10+ total)\n- Workflow versioning and rollback\n- A/B testing framework\n- Cost tracking and optimization\n- Workflow dependencies and orchestration\n- Visual workflow builder web UI\n- AI-powered workflow optimization\n- Integration testing framework\n\n### 👥 Contributors\n\n- Enhanced n8n skill for Clawdbot/Thomas\n- Based on requirements for SaaS automation workflows\n\n### 📄 License\n\nPart of the Clawdbot skills library.\n\n---\n\n## Version 1.0.0 - January 2026\n\n### Initial Release\n\nBasic n8n API integration:\n- List workflows\n- Get workflow details\n- Activate/deactivate workflows\n- List and get executions\n- Manual workflow execution\n- Python API client\n- Basic CLI interface","license":null},"metadata":{"setup":[{"key":"N8N_API_KEY","required":true},{"key":"N8N_BASE_URL","required":true}],"os":null,"systems":null},"owner":{"handle":"thomasansems","userId":"s1759pf0b5r8mvs15r10wd6ak5846vjk","displayName":"thomasansems","image":"https://avatars.githubusercontent.com/u/8612092?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779913569165}}