이 페이지에서: 문제 · 매트릭스 · 절차 · 수치 · 트러블슈팅 · FAQ
재시도·차단은 JSON Schema·재시도, 라우팅은 LiteLLM·OpenClaw, RAG 결합 시 Haystack 2.x와 실패 봉투를 맞추세요.
이 구조가 푸는 문제
첫째 로컬 검증과 운영 호출의 스키마 불일치. 둘째 긴 생성이 통합 메모리를 점유해 동시 작업 정지. 셋째 원시 스택 대신 상관관계·힌트가 필요합니다. 게이트웨이가 계약을 강제해야 파이프라인 전체가 같은 오류 형태를 봅니다.
통제 매트릭스: 누가 무엇을 소유하는가
| 층 | 책임 | 대표 노브 |
|---|---|---|
| Instructor + Pydantic | 개발자 경험, 모델, 빠른 반복. | response_model, SDK 내부 재시도. |
| OpenClaw 게이트웨이 | 인증, JSON Schema 집행, 라우팅, 로깅. | 베어러 토큰 파일, 라우트별 inputSchema. |
| 타임아웃 차단 | 요청당 벽시계와 대기열 상한. | request_timeout_seconds, 큐 깊이 알림. |
| 서킷 브레이커 | 검증·업스트림 오류가 연속일 때 개방. | 연속 실패 횟수, 쿨다운 초. |
| 실패 봉투 | 호출자에게 구조화된 사유 코드. | stage, code, hint, 마스킹된 상세. |
스키마 단일 소스를 git에 두고 게이트웨이 JSON Schema와 Pydantic을 함께 파생하세요.
재현 가능한 설치·게이트웨이·툴체인
1) python3 -m venv .venv 후 pip install instructor openai pydantic을 requirements.txt에 핀.
2) Node 22로 OpenClaw CLI 설치, ~/.openclaw에 설정·로그, openclaw doctor --json 녹색 확인.
3) 게이트웨이 127.0.0.1:${PORT}, 토큰 chmod 600, 외부는 SSH 터널만.
4) OPENAI_BASE_URL=http://127.0.0.1:${PORT}/v1로 instructor.from_openai·response_model, 낮은 temperature.
5) 게이트웨이에 draft-07 스키마 등록, 추론 전 검증·조기 거절.
6) 게이트웨이 타임아웃 < SDK 타임아웃, 연속 검증 실패 시 서킷·쿨다운.
7) 실패는 correlation_id·stage·hint 한 줄, 프롬프트 미포함.
# 예시 환경(시크릿은 git 밖에 보관)
export OPENAI_API_KEY="${OPENAI_API_KEY}"
export OPENAI_BASE_URL="http://127.0.0.1:8742/v1"
export INSTRUCTOR_MAX_RETRIES=2
export OPENCLAW_REQUEST_TIMEOUT_S=58
export OPENCLAW_BREAKER_THRESHOLD=3
export OPENCLAW_BREAKER_COOLDOWN_S=30
export STRUCTURED_LOG_PATH="$HOME/openclaw-scratch/logs/instructor.jsonl"
# launchd·systemd 플래그에도 동일 값을 넣어 재부팅 후에도 동일하게 유지하세요.인용할 수 있는 수치
- SDK 타임아웃은 게이트웨이보다 +5초 이상.
- 큐 깊이가 정상 동시성 ×4 초과 시 알림.
- M4급 병렬 검증 시 통합 메모리 약 20% 여유.
- JSONL 주간 로테이션, 파일 ~200MB 압축.
트러블슈팅 요약
스키마 루프: 게이트웨이 스키마와 model_json_schema() diff, 열거·additionalProperties 확인.
서킷 오탐: 동시성 낮춤, 검증 로그, Instructor 이중 재시도 여부.
터널 지연: ControlMaster, 킵얼리브 ~30초.
FAQ
게이트웨이 검증 생략? 운영은 비파이썬 호출까지 동일 계약이 필요해 신뢰 경계에서 유지합니다. 단일 스키마 파일에서 파생하면 중복 관리 부담은 줄어듭니다.
재시도는 어디? JSON 수리는 Instructor, 전송·업스트림은 OpenClaw 백오프.
실패 요약? 상관관계·단계·힌트 한 줄, 프롬프트·시크릿 제외.
첫 타임아웃? 중간 구조화 작업은 약 육십 초에서 시작하고 작은 스키마는 이십오 초 전후로 낮춘 뒤 p95를 확인하세요.