n8nワークフロー管理
n8nプラットフォーム向けの包括的なワークフロー自動化管理を提供します。作成、テスト、実行監視、パフォーマンス最適化機能を備えています。
⚠️ 重要: ワークフロー作成ルール
n8nワークフローを作成する際は、常に次のルールに従ってください:
- ✅ 完全なワークフローを作成し、すべての機能ノードを含める
- ✅ API呼び出し（ImageFX、Gemini、Veo、Sunoなど）には実際のHTTPリクエストノードを含める
- ✅ データ変換とロジックのためにコードノードを追加する
- ✅ すべてのノード間に適切な接続を作成する
- ✅ 実際のノードタイプ（n8n-nodes-base.httpRequest、n8n-nodes-base.code、n8n-nodes-base.set）を使用する
絶対に避けること:
- ❌ 「セットアップ手順」のようなプレースホルダーノードを作成しない
- ❌ TODOコメントのみのワークフローを生成しない
- ❌ 手動でノードを追加する必要がある不完全なワークフローを作成しない
- ❌ テキストのみのノードを実際の機能の代用として使用しない
良いワークフローの例:
手動トリガー → 設定 → HTTPリクエスト（API呼び出し） → コード（パース） → レスポンス
悪いワークフローの例:
手動トリガー → コード（「ここにHTTPノードを追加し、APIを設定...」）
必要なノードをすべて構成・接続した、完全で機能するワークフローを常に構築してください。
セットアップ
必要な環境変数:
N8N_API_KEY— n8n APIキー（n8n UIの設定→APIから取得）N8N_BASE_URL— n8nインスタンスのURL
OpenClaw設定経由で認証情報を構成:
~/.config/openclaw/settings.json に以下を追加:
{
"skills": {
"n8n": {
"env": {
"N8N_API_KEY": "your-api-key-here",
"N8N_BASE_URL": "your-n8n-url-here"
}
}
}
}
またはセッションごとに設定（シェルrcファイルにシークレットを永続化しないでください）:
export N8N_API_KEY="your-api-key-here"
export N8N_BASE_URL="your-n8n-url-here"
接続を確認:
python3 scripts/n8n_api.py list-workflows --pretty
セキュリティ注意: APIキーをプレーンテキストでシェル設定ファイル（
~/.bashrc、~/.zshrc）に保存しないでください。OpenClaw設定ファイルまたは安全なシークレットマネージャーを使用してください。
クイックリファレンス
ワークフロー管理
ワークフロー一覧表示
python3 scripts/n8n_api.py list-workflows --pretty
python3 scripts/n8n_api.py list-workflows --active true --pretty
ワークフロー詳細取得
python3 scripts/n8n_api.py get-workflow --id <workflow-id> --pretty
ワークフロー作成
# JSONファイルから
python3 scripts/n8n_api.py create --from-file workflow.json
有効化/無効化
python3 scripts/n8n_api.py activate --id <workflow-id>
python3 scripts/n8n_api.py deactivate --id <workflow-id>
テストと検証
ワークフロー構造の検証
# 既存のワークフローを検証
python3 scripts/n8n_tester.py validate --id <workflow-id>
# ファイルから検証
python3 scripts/n8n_tester.py validate --file workflow.json --pretty
# 検証レポートを生成
python3 scripts/n8n_tester.py report --id <workflow-id>
ドライランテスト
# データを使ってテスト
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data '{"email": "[email protected]"}'
# データファイルを使ってテスト
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json
# 完全なテストレポート（検証 + ドライラン）
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test.json --report
テストスイート
# 複数のテストケースを実行
python3 scripts/n8n_tester.py test-suite --id <workflow-id> --test-suite test-cases.json
実行監視
実行一覧表示
# 最近の実行（全ワークフロー）
python3 scripts/n8n_api.py list-executions --limit 10 --pretty
# 特定のワークフローの実行
python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 20 --pretty
実行詳細取得
python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty
手動実行
# ワークフローのトリガー
python3 scripts/n8n_api.py execute --id <workflow-id>
# データを指定して実行
python3 scripts/n8n_api.py execute --id <workflow-id> --data '{"key": "value"}'
パフォーマンス最適化
パフォーマンス分析
# 完全なパフォーマンス分析
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --pretty
# 特定期間の分析
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty
最適化提案の取得
# 優先度順の提案
python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty
最適化レポートの生成
# メトリクス、ボトルネック、提案を含む人間が読めるレポート
python3 scripts/n8n_optimizer.py report --id <workflow-id>
ワークフロー統計情報の取得
# 実行統計
python3 scripts/n8n_api.py stats --id <workflow-id> --days 7 --pretty
Python API
基本的な使い方
from scripts.n8n_api import N8nClient
client = N8nClient()
# ワークフロー一覧表示
workflows = client.list_workflows(active=True)
# ワークフロー詳細取得
workflow = client.get_workflow('workflow-id')
# ワークフロー作成
new_workflow = client.create_workflow({
'name': 'My Workflow',
'nodes': [...],
'connections': {...}
})
# 有効化/無効化
client.activate_workflow('workflow-id')
client.deactivate_workflow('workflow-id')
# 実行
executions = client.list_executions(workflow_id='workflow-id', limit=10)
execution = client.get_execution('execution-id')
# ワークフロー実行
result = client.execute_workflow('workflow-id', data={'key': 'value'})
検証とテスト
from scripts.n8n_api import N8nClient
from scripts.n8n_tester import WorkflowTester
client = N8nClient()
tester = WorkflowTester(client)
# ワークフロー検証
validation = tester.validate_workflow(workflow_id='123')
print(f"有効: {validation['valid']}")
print(f"エラー: {validation['errors']}")
print(f"警告: {validation['warnings']}")
# ドライラン
result = tester.dry_run(
workflow_id='123',
test_data={'email': '[email protected]'}
)
print(f"ステータス: {result['status']}")
# テストスイート
test_cases = [
{'name': 'テスト1', 'input': {...}, 'expected': {...}},
{'name': 'テスト2', 'input': {...}, 'expected': {...}}
]
results = tester.test_suite('123', test_cases)
print(f"成功: {results['passed']}/{results['total_tests']}")
# レポート生成
report = tester.generate_test_report(validation, result)
print(report)
パフォーマンス最適化
from scripts.n8n_optimizer import WorkflowOptimizer
optimizer = WorkflowOptimizer()
# パフォーマンス分析
analysis = optimizer.analyze_performance('workflow-id', days=7)
print(f"パフォーマンススコア: {analysis['performance_score']}/100")
print(f"健全性: {analysis['execution_metrics']['health']}")
# 提案の取得
suggestions = optimizer.suggest_optimizations('workflow-id')
print(f"優先アクション: {len(suggestions['priority_actions'])}")
print(f"クイックウィン: {len(suggestions['quick_wins'])}")
# レポート生成
report = optimizer.generate_optimization_report(analysis)
print(report)
よく使われるワークフロー
1. ワークフローの検証とテスト
# ワークフロー構造の検証
python3 scripts/n8n_tester.py validate --id <workflow-id> --pretty
# サンプルデータでテスト
python3 scripts/n8n_tester.py dry-run --id <workflow-id> \
--data '{"email": "[email protected]", "name": "テストユーザー"}'
# テストが成功したら有効化
python3 scripts/n8n_api.py activate --id <workflow-id>
2. 失敗したワークフローのデバッグ
# 最近の実行を確認
python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 10 --pretty
# 特定の実行詳細を取得
python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty
# ワークフロー構造を検証
python3 scripts/n8n_tester.py validate --id <workflow-id>
# テストレポートを生成
python3 scripts/n8n_tester.py report --id <workflow-id>
# 最適化の問題を確認
python3 scripts/n8n_optimizer.py report --id <workflow-id>
3. ワークフローパフォーマンスの最適化
# 現在のパフォーマンスを分析
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty
# 実行可能な提案を取得
python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty
# 包括的なレポートを生成
python3 scripts/n8n_optimizer.py report --id <workflow-id>
# 実行統計を確認
python3 scripts/n8n_api.py stats --id <workflow-id> --days 30 --pretty
# ドライランで最適化をテスト
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json
4. ワークフローの健全性監視
# アクティブなワークフローを確認
python3 scripts/n8n_api.py list-workflows --active true --pretty
# 最近の実行ステータスを確認
python3 scripts/n8n_api.py list-executions --limit 20 --pretty
# 各重要なワークフローの統計を取得
python3 scripts/n8n_api.py stats --id <workflow-id> --pretty
# 健全性レポートを生成
python3 scripts/n8n_optimizer.py report --id <workflow-id>
検証チェック
テストモジュールは包括的な検証を実行します:
構造検証
- ✓ 必須フィールドの存在（nodes、connections）
- ✓ すべてのノードに名前とタイプがある
- ✓ 接続先が存在する
- ✓ 切断されたノードがない（警告）
設定検証
- ✓ 認証情報が必要なノードが設定されている
- ✓ 必須パラメータが設定されている
- ✓ HTTPノードにURLがある
- ✓ Webhookノードにパスがある
- ✓ メールノードにコンテンツがある
フロー検証
- ✓ ワークフローにトリガーノードがある
- ✓ 正しい実行フロー
- ✓ 循環依存がない
- ✓ 終了ノードが特定されている
最適化分析
最適化ツールは複数の次元を分析します:
実行メトリクス
- 総実行数
- 成功率/失敗率
- 健全性ステータス（優良/良好/普通/不良）
- エラーパターン
パフォーマンスメトリクス
- ノード数と複雑さ
- 接続パターン
- コストのかかる操作（API呼び出し、データベースクエリ）
- 並列実行の機会
ボトルネック検出
- 逐次的な高コスト操作
- 高い失敗率
- エラーハンドリングの欠如
- レート制限の問題
最適化の機会
- 並列実行: 同時実行可能なノードを特定
- キャッシュ: 繰り返しのAPI呼び出しに対するキャッシュを提案
- バッチ処理: 大規模データセットに対するバッチ処理を推奨
- エラーハンドリング: エラー回復メカニズムを追加
- 複雑性の低減: 複雑なワークフローを分割
- タイムアウト設定: 実行制限を設定
パフォーマンススコアリング
ワークフローはパフォーマンススコア（0-100）を受け取ります。これは以下に基づきます:
- 成功率: 高いほど良い（重み50%）
- 複雑さ: 低いほど良い（重み30%）
- ボトルネック: 少ないほど良い（重大: -20、高: -10、中: -5）
- 最適化: 実装されたベストプラクティス（1つあたり+5）
スコアの解釈:
- 90-100: 優良 - 十分に最適化されている
- 70-89: 良好 - 軽微な改善が可能
- 50-69: 普通 - 最適化を推奨
- 0-49: 不良 - 重大な問題がある
ベストプラクティス
開発
- 構造を計画: 構築前にワークフローノードと接続を設計する
- まず検証: デプロイ前に必ず検証する
- 徹底的にテスト: 複数のテストケースでドライランを使用する
- エラーハンドリング: 信頼性のためにエラーノードを追加する
- ドキュメント: コードノード内の複雑なロジックにコメントを付ける
テスト
- サンプルデータ: 現実的なテストデータファイルを作成する
- エッジケース: 境界条件とエラーをテストする
- 段階的: 各ノード追加ごとにテストする
- 回帰: 変更後に再テストする
- 本番環境に近い: 本番環境を模したステージング環境を使用する
デプロイ
- まず非アクティブ: ワークフローを非アクティブ状態でデプロイする
- 段階的ロールアウト: 最初は限られたトラフィックでテストする
- 注意深く監視: 最初の実行を注意深く観察する
- 迅速なロールバック: 問題が発生した場合に備えて非アクティブ化できるようにする
- 変更を文書化: 変更ログを保持する
最適化
- ベースラインメトリクス: 変更前にパフォーマンスを記録する
- 一度に1つの変更: 最適化の影響を分離する
- 結果を測定: 変更前後のメトリクスを比較する
- 定期的なレビュー: 毎月の最適化レビューを計画する
- コスト意識: API使用量と実行コストを監視する
メンテナンス
- 健全性チェック: 毎週の実行統計レビュー
- エラー分析: 失敗パターンを調査する
- パフォーマンス監視: 実行時間を追跡する
- 認証情報のローテーション: 定期的に認証情報を更新する
- クリーンアップ: 未使用のワークフローをアーカイブまたは削除する
トラブルシューティング
認証エラー
エラー: 環境変数N8N_API_KEYが見つかりません
解決策: 環境変数を設定:
export N8N_API_KEY="your-api-key"
接続エラー
エラー: HTTP 401: 認証されていません
解決策:
- APIキーが正しいか確認
- N8N_BASE_URLが正しく設定されているか確認
- n8nでAPIアクセスが有効になっているか確認
検証エラー
検証に失敗: ノードに'name'フィールドがありません
解決策: ワークフローJSON構造を確認し、すべての必須フィールドが存在することを確認
実行タイムアウト
ステータス: タイムアウト - 実行が完了しませんでした
解決策:
- ワークフローに無限ループがないか確認
- テスト用にデータセットサイズを減らす
- 高コストな操作を最適化
- ワークフロー設定で実行タイムアウトを設定
レート制限
エラー: HTTP 429: リクエストが多すぎます
解決策:
- API呼び出し間に待機ノードを追加
- 指数バックオフを実装
- バッチ処理を使用
- APIのレート制限を確認
認証情報の欠落
警告: ノード'HTTP_Request'に認証情報が必要な可能性があります
解決策:
- n8n UIで認証情報を設定
- 認証情報をノードに割り当て
- 有効化する前に接続をテスト
ファイル構成
~/clawd/skills/n8n/
├── SKILL.md # このファイル
├── scripts/
│ ├── n8n_api.py # コアAPIクライアント（拡張版）
│ ├── n8n_tester.py # テストと検証
│ └── n8n_optimizer.py # パフォーマンス最適化
└── references/
└── api.md # n8n APIリファレンス
APIリファレンス
詳細なn8n REST APIドキュメントについては、references/api.mdを参照するか、以下のURLにアクセスしてください: https://docs.n8n.io/api/
Su
…
[翻訳のため省略]