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": "Test User"}'
# 테스트 통과 시 활성화
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이 있음
- ✓ 웹훅 노드에 경로가 있음
- ✓ 이메일 노드에 콘텐츠가 있음
흐름 검증
- ✓ 워크플로우에 트리거 노드가 있음
- ✓ 적절한 실행 흐름
- ✓ 순환 종속성 없음
- ✓ 종료 노드 식별됨
최적화 분석
최적화 도구는 여러 차원을 분석합니다:
실행 메트릭
- 총 실행 횟수
- 성공/실패 비율
- 상태 (훌륭함/좋음/보통/나쁨)
- 오류 패턴
성능 메트릭
- 노드 수 및 복잡성
- 연결 패턴
- 고비용 작업 (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="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를 참조하거나 다음 사이트를 방문하세요: https://docs.n8n.io/api/