바로가기: 리스크 · 매트릭스 · 도구 화이트리스트 · JSON 스키마 · 타임아웃·서킷 · 로그 · 절차 · 체크리스트 · FAQ
연관 글: Instructor 스키마·재시도·서킷·Semantic Kernel.
운영 리스크 세 줄
1) 로컬만 새 도구 이름 → 게이트웨이와 불일치해 감사가 깨짐. 2) 파이썬 모델과 배포 스키마 드리프트 → 잘못된 JSON이 GPU를 태움. 3) HTTP·실행 데드라인 불일치 → 재시도가 쌓여 통합 메모리 압력 상승.
책임 분리 매트릭스
| 층 | 소유 | 대표 신호 |
|---|---|---|
| PydanticAI | 런 컨텍스트·도구 배선 | Toolset·deps |
| OpenClaw | 인증·화이트리스트·스키마 | 토큰·inputSchema |
| 퓨즈 | HTTP·실행 상한 | timeout·큐 상한 |
| 서킷 | 연속 실패 차단 | 창·쿨다운 |
| 실패 봉투 | 비밀 없는 오류 | id·stage·hint |
최소 권한 도구 화이트리스트
git 표에 이름·인자 스키마·파일 스코프·담당을 적고 PydanticAI와 게이트웨이에 동일 목록을 걸어 미등록 이름은 파이썬 전에 차단합니다. 읽기 전용과 append-only scratch를 기본으로 하고 홈 전체 마운트는 티켓이 있을 때만 허용하세요. 샌드박스는 IDE 브리지·헬스 프로브와 동일 기준을 씁니다.
JSON 스키마 검증
경로마다 단일 스키마를 두고 여기서 모델을 생성해 에이전트와 게이트웨이가 같은 필수 키·enum을 봅니다. 게이트웨이에서 추론 전 검증하고 실패 시 JSON 포인터와 짧은 힌트만 돌려 자동 수정 루프를 제한합니다.
타임아웃·서킷 브레이커
게이트웨이 실행 상한을 클라이언트 HTTP보다 몇 초 짧게 두고 큐 대기 상한으로 붐비는 통합 메모리를 먼저 감량합니다. 연속 검증 실패나 오류 응답이면 서킷을 열고 쿨다운 동안 JSONL의 스키마 포인터를 봅니다.
로그 필드(JSONL)
한 줄에 ts·correlation_id·route·model_alias·tool_name·latency_ms·outcome·schema_version과 가능하면 메모리 스냅샷을 넣고 프롬프트는 마스킹합니다.
export OPENAI_BASE_URL="http://127.0.0.1:8742/v1"
export PYDANTIC_AI_HTTP_TIMEOUT_S=62
export OPENCLAW_REQUEST_TIMEOUT_S=58
export OPENCLAW_BREAKER_THRESHOLD=3
export OPENCLAW_BREAKER_COOLDOWN_S=30재현 절차
- venv와 핀된 pydantic-ai·httpx, launchd 경로 기록
- OpenClaw 설치·doctor, 토큰 600, SSD 로그
- 127.0.0.1 리슨·SSH 터널, 공인 인그레스 차단
- 도구 표를 에이전트·게이트웨이에 동기화, 기동 시 불일치 실패
- 라우트별 스키마·퓨즈 후 클라이언트 타임아웃을 더 길게
- 정상·enum 위반·지연 스모크로 봉투·서킷 확인
운영 전 체크리스트
- 도구 이름 세 곳 일치
- 스키마 체크섬이 릴리스 노트에 있음
- 클라이언트 timeout ≥ 게이트웨이 퓨즈+여유
- 실패 봉투 필드가 온콜 문서에 있음
- SSH keepalive·담당자 기록
FAQ
게이트웨이 검증 끄기? 샌드박스만. 운영은 게이트웨이가 신뢰 경계.
재시도? 가벼운 JSON 수정은 에이전트, 서킷 이후 백오프는 OpenClaw.