jq로 검색할 수 있는 로컬 로그 파일에 기록됩니다.
실제 요청 확인
에이전트가 보낸 그대로의 모델 ID, 메시지, 도구, 파라미터
스트리밍 유지
청크가 도착하는 즉시 전달되므로 에이전트가 평소처럼 동작합니다
의존성 없음
파일 하나, Node.js 18 이상, 설치할 것 없음
작동 방식
Authorization 헤더를 그대로 전달하므로 API 키는 에이전트 설정에 그대로 두면 되고, 모든 Venice 엔드포인트가 프록시를 통해 동작합니다: /chat/completions, /responses, /models, /embeddings 등. 에이전트에서 바꿀 것은 base URL뿐입니다.
프록시는 요청마다 다음을 기록합니다.
- 메서드, 경로, 요청 본문. API 키는 마지막 네 글자만 남기고 마스킹됩니다
- 응답 상태와 본문. 스트리밍 응답은 파싱된 청크 목록으로 저장됩니다.
- Venice가 반환하는
usage객체의 토큰 사용량 - 전체 소요 시간과 첫 바이트까지의 시간
- 남은 잔액, 속도 제한 상태, 모델 지원 중단 경고 등
x-venice-*및x-ratelimit-*응답 헤더
이 도구는 내 컴퓨터에서 쓰는 디버깅 도구입니다.
127.0.0.1에만 바인딩되고, 자체 인증이 없으며, 프롬프트와 코드를 평문으로 디스크에 기록합니다. 공유 게이트웨이로 배포하지 마세요. 게이트웨이가 필요하다면 Rust LLM 게이트웨이 구축하기를 참고하세요.사전 요구 사항
- Node.js 18 이상 (
node --version) - venice.ai/settings/api에서 발급한 Venice API 키
- Claude Code, Codex CLI, OpenCode, Cline, Aider 등 이미 Venice와 함께 동작하는 코딩 에이전트
- 로그를 읽기 위한
jq(선택 사항이지만 권장)
설정
1
프록시 만들기
다음 내용을 임시 디렉터리에 몇 가지 짚어 볼 점이 있습니다.
venice-debug-proxy.mjs로 저장합니다.venice-debug-proxy.mjs
- 스트리밍이 평소처럼 동작합니다. Venice에서 오는 각 청크는 도착하는 즉시 에이전트에 기록되고, 로그용으로 사본이 보관됩니다. 에이전트는 Venice에서 직접 받을 때와 똑같은 토큰 단위 스트림을 봅니다.
- 압축은 자동으로 처리됩니다. Node의
fetch가 응답의 압축을 풀기 때문에, 프록시는 헤더를 전달하기 전에content-encoding을 제거합니다. 그렇지 않으면 에이전트가 평문의 압축을 풀려고 시도하다가 실패합니다. - 연결 끊김이 전달됩니다. 에이전트에서 턴을 취소하면 프록시도 업스트림 요청을 중단하므로, Venice가 아무도 읽지 않는 토큰을 계속 생성하지 않습니다.
2
실행하기
PORT 또는 LOG_FILE을 설정하세요.3
curl로 확인하기
두 번째 터미널에서 프록시를 통해 요청을 보냅니다.프록시는 요청마다 한 줄을 출력합니다.“Say hello”치고는 프롬프트 토큰이 많습니다. 대부분은 Venice의 기본 시스템 프롬프트로,
venice_parameters.include_venice_system_prompt를 false로 설정하지 않으면 채팅 요청에 추가됩니다. 바로 이런 것을 프록시가 보여 줍니다.4
에이전트가 프록시를 가리키도록 설정하기
에이전트의 Venice 설정에서
https://api.venice.ai를 http://127.0.0.1:8787로 바꾸고 URL의 나머지 부분은 그대로 둡니다. 프록시가 전체 경로를 전달하므로, 에이전트 가이드에서 입력하라고 안내한 값은 그대로 동작합니다.OpenCode에 번들된 Venice 제공자와 Kilo Code의 기본 Venice 제공자는 base URL을 설정할 수 없으므로, 디버깅하는 동안에는 수동 제공자나 OpenAI 호환 제공자로 전환하세요.OpenCode에서는 디버그용 제공자에
venice-debug 같은 별도 ID를 지정하고 -m venice-debug/<model-id>로 실행하세요. /connect로 키를 저장한 적이 있다면, 설정에 apiKey가 지정되어 있어도 OpenCode는 venice 제공자 ID에 대해 저장된 키를 보냅니다.localhost 대신 127.0.0.1을 사용하세요. 일부 시스템에서는 localhost가 IPv6 주소 ::1로 해석되는데, 프록시는 이 주소에서 수신하지 않습니다.5
문제 재현하기
문제가 다시 발생할 때까지 평소처럼 에이전트를 사용한 다음, 프록시의 터미널 출력과 로그 파일을 확인하세요.
로그 읽기
venice-debug.jsonl의 각 줄은 완전한 JSON 객체이므로 jq로 원하는 대로 잘라 볼 수 있습니다.
가장 최근의 요청과 응답 보기:
확인할 항목
코드를 작성하지 않고 확인하기
브라우저에서 클릭하며 트래픽을 살펴보고 싶다면, mitmproxy를 Venice 앞단의 리버스 프록시로 실행할 수 있습니다.http://127.0.0.1:8787/api/v1을 가리키도록 한 다음, mitmweb UI에서 각 요청을 살펴보세요. Node 프록시는 스크립트로 다루기 쉽고 나중에 grep으로 검색할 수 있는 로그를 남깁니다. mitmproxy는 세션을 대화형으로 둘러보는 데 더 적합합니다.
로그를 비공개로 유지하기
Venice는 일반 추론에서 프롬프트나 응답을 저장하지 않지만(개인정보 보호 참고), 이 로그 파일은 저장합니다. 로그 파일에는 코드, 프롬프트, 도구 출력, 모델 응답이 평문으로 들어 있습니다.- 프로젝트 밖에서 프록시를 실행하거나
venice-debug.jsonl을.gitignore에 추가하세요. - 디버깅이 끝나면 로그를 삭제하세요.
- 전체 로그 항목을 공개 이슈에 붙여 넣지 마세요. 대신
status,error, 그리고response의 관련 부분만 추려 내세요.
마무리
작업이 끝나면Ctrl+C로 프록시를 중지하고 에이전트의 base URL을 https://api.venice.ai/api/v1로 되돌리세요. 잊어버리더라도 프록시가 실행 중이 아니면 에이전트가 즉시 연결 오류로 실패하므로, 적어도 알아차리기는 쉽습니다.
읽어 주셔서 감사합니다! 다음에 에이전트가 “something went wrong”이라고 할 때는 무엇이 잘못되었는지 정확히 확인할 수 있기를 바랍니다.