피드로 돌아가기
Dev.toBackend
원문 읽기
Multi-protocol Translation Layer를 통한 AI CLI 도구 통합 게이트웨이 구축
"How I Made Claude Code, Codex, and Gemini CLI Share One Local API"
AI 요약
Context
Claude Code, Codex, Gemini 등 서로 다른 API 스키마와 Streaming 형식을 가진 AI 도구들의 파편화로 인한 개발 효율 저하 발생. 단순한 Proxy 설정만으로는 요청 페이로드 및 응답 스트림의 프로토콜 불일치 문제를 해결할 수 없는 아키텍처적 한계 존재.
Technical Solution
- Native Protocol 감지 및 상위 제공자 형식으로의 변환을 수행하는 Compatibility Layer 설계
- Codex CLI의 Zstd 압축 요청 처리를 위해 express.json() 미들웨어 적용 전 Raw Byte를 수집하는 전처리 루틴 구현
- SSE(Server-Sent Events) 이벤트 모델의 차이를 해소하기 위해 각 도구별 전용 Translator를 통한 실시간 스트림 재매핑 수행
- Multimodal 데이터 및 Tool Call 페이로드를 표준화하는 Normalizer를 도입하여 데이터 손실 없는 상호 운용성 확보
- 모호한 번역 시 'Fake Compatibility'를 배제하고 400 에러를 반환하는 Strict Compatibility Mode 채택
- Unit, Protocol-conversion, E2E Smoke Test의 3단계 검증 체계를 통해 런타임 안정성 확보
실천 포인트
1. 서로 다른 외부 API를 통합할 때 단순 Routing이 아닌 Payload Translation 계층 분리 검토
2. 클라이언트가 특수 인코딩(Zstd 등)을 사용하는 경우 미들웨어 적용 순서를 조정하여 Raw Body 접근 권한 확보
3. 스트리밍 응답 통합 시 각 프로토콜의 Event Semantic을 분석하여 상태 기반의 Bridge 설계 적용
4. 하위 호환성이 보장되지 않는 기능에 대해 침묵하는 대신 명시적 에러를 반환하는 Fail-fast 전략 수립