n8n 工作流程管理 是做什麼的?
全面的 n8n 平台工作流程自動化管理,包含建立、測試、執行監控與效能最佳化功能。
⚠️ 關鍵:工作流程建立規則
建立 n8n 工作流程時,務必:
- ✅ 產生完整的工作流程,包含所有功能節點
- ✅ 包含實際的 HTTP 請求節點,用於 API 呼叫(ImageFX、Gemini、Veo、Suno 等)
- ✅ 加入程式碼節點,用於資料轉換與邏輯處理
- ✅ 建立所有節點之間的正確連線
- ✅ 使用真實的節點類型(n8n-nodes-base.httpRequest、n8n-nodes-base.code、n8n-nodes-base.set)
絕對不要:
- ❌ 建立「設定說明」佔位節點
- ❌ 產生僅含 TODO 註解的工作流程
- ❌ 製作需要手動新增節點的不完整工作流程
- ❌ 使用純文字節點取代實際功能
良好工作流程範例:
手動觸發 → 設定配置 → HTTP 請求(API 呼叫) → 程式碼(解析) → 回應
不良工作流程範例:
手動觸發 → 程式碼(「在此新增 HTTP 節點、設定 API...」)
務必建立包含所有必要節點且完整連線的功能性工作流程。
設定
所需的環境變數:
N8N_API_KEY— 您的 n8n API 金鑰(在 n8n 介面中透過「設定 → API」取得)N8N_BASE_URL— 您的 n8n 執行個體網址
透過 OpenClaw 設定檔配置憑證:
請在 ~/.config/openclaw/settings.json 中新增:
{
"skills": {
"n8n": {
"env": {
"N8N_API_KEY": "您的-api-金鑰",
"N8N_BASE_URL": "您的-n8n-網址"
}
}
}
}
或者每階段設定(不要在 shell rc 檔案中持續保留機密):
export N8N_API_KEY="您的-api-金鑰"
export N8N_BASE_URL="您的-n8n-網址"
驗證連線:
python3 scripts/n8n_api.py list-workflows --pretty
安全注意事項: 切勿在純文字 shell 設定檔(
~/.bashrc、~/.zshrc)中儲存 API 金鑰。請使用 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 <工作流程-id> --pretty
建立工作流程
# 從 JSON 檔案
python3 scripts/n8n_api.py create --from-file workflow.json
啟用/停用
python3 scripts/n8n_api.py activate --id <工作流程-id>
python3 scripts/n8n_api.py deactivate --id <工作流程-id>
測試與驗證
驗證工作流程結構
# 驗證現有工作流程
python3 scripts/n8n_tester.py validate --id <工作流程-id>
# 從檔案驗證
python3 scripts/n8n_tester.py validate --file workflow.json --pretty
# 產生驗證報告
python3 scripts/n8n_tester.py report --id <工作流程-id>
乾執行測試
# 使用資料測試
python3 scripts/n8n_tester.py dry-run --id <工作流程-id> --data '{"email": "[email protected]"}'
# 使用資料檔案測試
python3 scripts/n8n_tester.py dry-run --id <工作流程-id> --data-file test-data.json
# 完整測試報告(驗證 + 乾執行)
python3 scripts/n8n_tester.py dry-run --id <工作流程-id> --data-file test.json --report
測試套件
# 執行多個測試案例
python3 scripts/n8n_tester.py test-suite --id <工作流程-id> --test-suite test-cases.json
執行監控
列出執行記錄
# 最近的執行記錄(所有工作流程)
python3 scripts/n8n_api.py list-executions --limit 10 --pretty
# 特定工作流程的執行記錄
python3 scripts/n8n_api.py list-executions --id <工作流程-id> --limit 20 --pretty
取得執行詳細資訊
python3 scripts/n8n_api.py get-execution --id <執行-id> --pretty
手動執行
# 觸發工作流程
python3 scripts/n8n_api.py execute --id <工作流程-id>
# 帶資料執行
python3 scripts/n8n_api.py execute --id <工作流程-id> --data '{"key": "value"}'
效能最佳化
分析效能
# 完整效能分析
python3 scripts/n8n_optimizer.py analyze --id <工作流程-id> --pretty
# 分析特定時間範圍
python3 scripts/n8n_optimizer.py analyze --id <工作流程-id> --days 30 --pretty
取得最佳化建議
# 按優先順序排列的建議
python3 scripts/n8n_optimizer.py suggest --id <工作流程-id> --pretty
產生最佳化報告
# 可讀性報告,包含指標、瓶頸與建議
python3 scripts/n8n_optimizer.py report --id <工作流程-id>
取得工作流程統計資料
# 執行統計
python3 scripts/n8n_api.py stats --id <工作流程-id> --days 7 --pretty
Python API
基本用法
from scripts.n8n_api import N8nClient
client = N8nClient()
# 列出工作流程
workflows = client.list_workflows(active=True)
# 取得工作流程
workflow = client.get_workflow('工作流程-id')
# 建立工作流程
new_workflow = client.create_workflow({
'name': '我的工作流程',
'nodes': [...],
'connections': {...}
})
# 啟用/停用
client.activate_workflow('工作流程-id')
client.deactivate_workflow('工作流程-id')
# 執行記錄
executions = client.list_executions(workflow_id='工作流程-id', limit=10)
execution = client.get_execution('執行-id')
# 執行工作流程
result = client.execute_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('工作流程-id', days=7)
print(f"效能評分:{analysis['performance_score']}/100")
print(f"健康狀態:{analysis['execution_metrics']['health']}")
# 取得建議
suggestions = optimizer.suggest_optimizations('工作流程-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 <工作流程-id> --pretty
# 使用範例資料測試
python3 scripts/n8n_tester.py dry-run --id <工作流程-id> \
--data '{"email": "[email protected]", "name": "測試使用者"}'
# 如果測試通過,啟用工作流程
python3 scripts/n8n_api.py activate --id <工作流程-id>
2. 偵錯失敗的工作流程
# 檢查最近的執行記錄
python3 scripts/n8n_api.py list-executions --id <工作流程-id> --limit 10 --pretty
# 取得特定執行詳細資訊
python3 scripts/n8n_api.py get-execution --id <執行-id> --pretty
# 驗證工作流程結構
python3 scripts/n8n_tester.py validate --id <工作流程-id>
# 產生測試報告
python3 scripts/n8n_tester.py report --id <工作流程-id>
# 檢查最佳化問題
python3 scripts/n8n_optimizer.py report --id <工作流程-id>
3. 最佳化工作流程效能
# 分析當前效能
python3 scripts/n8n_optimizer.py analyze --id <工作流程-id> --days 30 --pretty
# 取得可行建議
python3 scripts/n8n_optimizer.py suggest --id <工作流程-id> --pretty
# 產生綜合報告
python3 scripts/n8n_optimizer.py report --id <工作流程-id>
# 檢視執行統計
python3 scripts/n8n_api.py stats --id <工作流程-id> --days 30 --pretty
# 使用乾執行測試最佳化
python3 scripts/n8n_tester.py dry-run --id <工作流程-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 <工作流程-id> --pretty
# 產生健康報告
python3 scripts/n8n_optimizer.py report --id <工作流程-id>
驗證檢查
測試模組會執行全面的驗證:
結構驗證
- ✓ 欄位是否齊全(nodes、connections)
- ✓ 所有節點都有名稱與類型
- ✓ 連線目標是否存在
- ✓ 無未連線的節點(警告)
配置驗證
- ✓ 需要憑證的節點已配置
- ✓ 必要參數已設定
- ✓ HTTP 節點已有網址
- ✓ Webhook 節點已有路徑
- ✓ 電子郵件節點已有內容
流程驗證
- ✓ 工作流程包含觸發節點
- ✓ 執行流程正確
- ✓ 無循環相依
- ✓ 已識別結束節點
最佳化分析
最佳化器會分析多個面向:
執行指標
- 總執行次數
- 成功/失敗率
- 健康狀態(極佳/良好/尚可/不佳)
- 錯誤模式
效能指標
- 節點數量與複雜度
- 連線模式
- 昂貴操作(API 呼叫、資料庫查詢)
- 平行執行機會
瓶頸偵測
- 序列化的昂貴操作
- 高失敗率
- 缺少錯誤處理
- 速率限制問題
最佳化機會
- 平行執行: 找出可同時執行的節點
- 快取: 針對重複的 API 呼叫建議快取
- 批次處理: 針對大型資料集建議批次處理
- 錯誤處理: 新增錯誤復原機制
- 複雜度降低: 拆分複雜的工作流程
- 逾時設定: 配置執行時間限制
效能評分
工作流程會根據以下項目獲得效能評分(0-100):
- 成功率: 越高越好(權重 50%)
- 複雜度: 越低越好(權重 30%)
- 瓶頸: 越少越好(嚴重:-20、高:-10、中:-5)
- 最佳化: 已實作的最佳實務(每項 +5)
評分解讀:
- 90-100: 極佳 - 已充分最佳化
- 70-89: 良好 - 有輕微改進空間
- 50-69: 尚可 - 建議進行最佳化
- 0-49: 不佳 - 存在重大問題
最佳實務
開發
- 規劃結構: 在建立前先設計工作流程節點與連線
- 先驗證: 部署前務必驗證
- 徹底測試: 使用多個測試案例執行乾執行
- 錯誤處理: 加入錯誤節點以提升可靠性
- 文件記錄: 在程式碼節點中為複雜邏輯加上註解
測試
- 範例資料: 建立逼真的測試資料檔案
- 邊界案例: 測試邊界條件與錯誤情況
- 增量式: 每次新增節點後進行測試
- 回歸測試: 變更後重新測試
- 類生產環境: 使用與生產環境相似的暫存環境
部署
- 先停用: 以停用狀態部署工作流程
- 逐步上線: 先以有限流量測試
- 密切監控: 仔細觀察首次執行情況
- 快速回退: 準備好遇到問題時立即停用
- 記錄變更: 保留修改的更新日誌
最佳化
- 基準指標: 在變更前記錄效能數據
- 一次一項變更: 隔離最佳化影響
- 衡量結果: 比較變更前後的指標
- 定期檢視: 每月安排最佳化檢視
- 成本意識: 監控 API 使用量與執行成本
維護
- 健康檢查: 每週審視執行統計
- 錯誤分析: 調查失敗模式
- 效能監控: 追蹤執行時間
- 憑證輪換: 定期更新憑證
- 清理: 封存或刪除未使用的工作流程
疑難排解
驗證錯誤
錯誤:環境中找不到 N8N_API_KEY
解決方法: 設定環境變數:
export N8N_API_KEY="您的-api-金鑰"
連線錯誤
錯誤:HTTP 401:未經授權
解決方法:
- 確認 API 金鑰正確
- 檢查 N8N_BASE_URL 是否設定正確
- 確認 n8n 中已啟用 API 存取
驗證錯誤
驗證失敗:節點缺少「name」欄位
解決方法: 檢查工作流程 JSON 結構,確保所有必要欄位皆存在
執行逾時
狀態:逾時 - 執行未完成
解決方法:
- 檢查工作流程是否有無限迴圈
- 測試時縮小資料集大小
- 最佳化昂貴操作
- 在工作流程設定中設定執行逾時
速率限制
錯誤:HTTP 429:請求過多
解決方法:
- 在 API 呼叫之間加入等待節點
- 實作指數退避
- 使用批次處理
- 檢查 API 速率限制
缺少憑證
警告:節點「HTTP_Request」可能需要憑證
解決方法:
- 在 n8n 介面中配置憑證
- 將憑證指派給節點
- 在啟用前測試連線
檔案結構
~/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 或造訪: https://docs.n8n.io/api/