바로가기: 프레임워크 구분 · 화이트리스트 · 스키마·퓨즈 · 서킷 · 실패 요약 · 재현 절차 · 트러블슈팅 · 체크리스트 · FAQ
연관 글: LangGraph 도구·원격 Mac·CrewAI 멀티에이전트 라우팅·PydanticAI 게이트웨이·JSON 스키마·재시도·서킷.
LangGraph·CrewAI와 무엇이 다른가
LangGraph는 그래프·체크포인트·재개, CrewAI는 역할·팀 라우팅에 강합니다. Strands Agents는 에이전트·도구·모델 호출을 한 워크플로 축으로 묶으므로, 나가는 HTTP를 OpenClaw 한 벽으로 고정하는 편이 유리합니다. 여기서는 그 벽에 화이트리스트·스키마·서킷·봉투만 얹는 순서를 다룹니다.
| 스택 | 초점 | 게이트웨이에 넘길 신호 |
|---|---|---|
| LangGraph | 노드·체크포인트·interrupt | 그래프 밖 도구 호출만 단일 URL로 |
| CrewAI | 팀·태스크·에이전트 역할 | 공용 모델·도구 트래픽 집결 |
| Strands Agents | 에이전트 워크플로·도구 체인 | 모든 completion·tool RPC |
최소 권한 도구 화이트리스트
도구 이름·inputSchema·스코프·담당 표를 git에 두고 Strands와 OpenClaw allowlist 해시를 맞춥니다. CI로 게이트 미등록 이름이면 기동 실패시키면 재현성이 오릅니다. 처음은 읽기 전용·append-only 작업 디렉터리만 허용하세요.
JSON 스키마 검증과 타임아웃 계단
인자·구조화 출력을 동일 JSON Schema로 게이트에서만 검증합니다(앱 측은 개발용). 게이트 실행 상한을 Strands HTTP보다 짧게 두고, 백오프는 재시도·서킷 글과 맞춥니다.
연속 실패 시 서킷
스키마 실패·5xx·타임아웃을 한 카운터로 창 안 N회면 서킷·쿨다운. 응답에는 짧은 운영 코드만 넣어 프롬프트 오염을 막습니다. 메모리 압박 시 게이트 동시 상한을 먼저 줄입니다.
실패 요약 봉투(상류 회신)
상류에는 correlation_id·단계·JSON 포인터·한 줄 힌트만 보냅니다. 스택·토큰·입력은 JSONL·마스킹. 격리는 sessions_spawn 글과 짝지으면 됩니다.
# Strands → OpenClaw 루프백 (예시 이름; 실제 키는 사용 중 SDK에 맞출 것)
export OPENAI_BASE_URL="http://127.0.0.1:8742/v1"
export STRANDS_HTTP_TIMEOUT_S=62
export OPENCLAW_REQUEST_TIMEOUT_S=58
export OPENCLAW_BREAKER_THRESHOLD=4
export OPENCLAW_BREAKER_COOLDOWN_S=45재현 절차(원격 Mac)
- 전용 계정·워크스페이스에
python3 -m venv .venv후 Strands·호환 클라이언트를 핀하고,OPENAI_API_KEY자리에 게이트웨이 Bearer만 쓰도록 문서화합니다. - OpenClaw 설치·업그레이드 후
openclaw doctor --json으로 라우트를 고정하고, 토큰 파일은chmod 600·디스크는 SSD 로그 파티션에 둡니다. - 게이트웨이는
127.0.0.1에만 리슨하고, 노트북에서는 SSH 로컬 포워딩으로만 붙습니다. 공인 인그레스는 닫습니다. - 도구 표를 Strands 레지스트리와 OpenClaw 설정에 동시에 렌더링합니다. 한쪽만 갱신되면 배포 파이프라인이 실패하게 합니다.
- 라우트별
inputSchema·실행 퓨즈를 게이트에 두고, 정상·enum 위반·인위 지연 스모크로 봉투 필드와 서킷 전환을 확인합니다. - JSONL에
ts·correlation_id·tool_name·latency_ms·outcome·schema_version를 한 줄로 남기고, 상류에는 봉투만 올립니다.
트러블슈팅(자주 막히는 지점)
- 403/알 수 없는 도구: 표 해시 불일치입니다. 게이트웨이와 Strands의 생성물을 diff하고, 캐시된 구 설정이 없는지 확인합니다.
- 스키마는 맞는데 타임아웃만 난다: 클라이언트 초가 게이트 퓨즈보다 짧은 역전이 흔합니다. 수치를 다시 계단 맞춤합니다.
- 서킷이 텍스트 응답에도 열린다: 구조화 출력이 스키마를 통과하지 못한 완료는 실패로 집계하세요. 자연어가 아무리 그럴듯해도 운영 집계는 스키마 기준입니다.
- 봉투가 비어 있다: 상류 어댑터가 모델 메시지 전체를 넘기도록 되어 있는지 확인하고, 게이트웨이 오류 매핑 레이어를 단일 모듈로 고정합니다.
운영 전 체크리스트
- 도구 이름·스키마 버전이 세 곳(Strands·게이트·문서)에서 일치
- Bearer 회전 절차와 담당자 연락처가 런북에 있음
- 서킷·쿨다운 임계가 온콜 플레이북과 일치
- SSH keepalive·기계 시간 동기화 기록
FAQ
CrewAI와 동시에 쓰나요? 팀 라우팅은 CrewAI에 두고, 공용 모델·도구 HTTP는 동일 OpenClaw로 모으면 계약이 하나로 유지됩니다.
LangGraph 체크포인트는? 그래프 상태는 LangGraph에 남기고, 외부 도구만 게이트를 통과시키는 하이브리드가 흔합니다. 전체를 이중으로 감싸면 지연이 겹칩니다.