메인 콘텐츠로 건너뛰기
코딩 에이전트가 이상하게 동작할 때, 에이전트 UI는 그 이유를 거의 알려 주지 않습니다. 도구 호출이 아무 말 없이 아무 일도 하지 않거나, 요청이 “provider error”로 실패하거나, 모델이 시스템 프롬프트를 무시하거나, 짧은 세션인데도 예상보다 훨씬 많은 비용이 듭니다. 대부분의 경우 답은 에이전트와 Venice 사이의 HTTP 트래픽에 있는데, 평소에는 이 트래픽을 볼 수 없습니다. 이 가이드에서는 에이전트와 Venice API 사이에 위치하는 작은 프록시를 내 컴퓨터에서 실행합니다. 에이전트는 프록시와 통신하고, 프록시는 모든 것을 변경 없이 Venice로 전달하며, 모든 요청과 응답은 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 게이트웨이 구축하기를 참고하세요.

사전 요구 사항


설정

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로 해석되는데, 프록시는 이 주소에서 수신하지 않습니다.
이 방법은 Cursor에서는 동작하지 않습니다. Cursor는 사용자 지정 모델 요청을 자체 서버에서 보내며, 이 서버는 내 컴퓨터의 프록시에 접근할 수 없습니다.
5

문제 재현하기

문제가 다시 발생할 때까지 평소처럼 에이전트를 사용한 다음, 프록시의 터미널 출력과 로그 파일을 확인하세요.

로그 읽기

venice-debug.jsonl의 각 줄은 완전한 JSON 객체이므로 jq로 원하는 대로 잘라 볼 수 있습니다. 가장 최근의 요청과 응답 보기:
실패했거나 중단된 요청만 보기:
에이전트가 실제로 보낸 모델, 파라미터, 도구 확인하기:
스트리밍된 chat completions의 텍스트 재구성하기:
세션의 모델별 총 토큰 수:
가장 느린 요청 찾기:

확인할 항목


코드를 작성하지 않고 확인하기

브라우저에서 클릭하며 트래픽을 살펴보고 싶다면, mitmproxy를 Venice 앞단의 리버스 프록시로 실행할 수 있습니다.
같은 방식으로 에이전트가 http://127.0.0.1:8787/api/v1을 가리키도록 한 다음, mitmweb UI에서 각 요청을 살펴보세요. Node 프록시는 스크립트로 다루기 쉽고 나중에 grep으로 검색할 수 있는 로그를 남깁니다. mitmproxy는 세션을 대화형으로 둘러보는 데 더 적합합니다.

로그를 비공개로 유지하기

Venice는 일반 추론에서 프롬프트나 응답을 저장하지 않지만(개인정보 보호 참고), 이 로그 파일은 저장합니다. 로그 파일에는 코드, 프롬프트, 도구 출력, 모델 응답이 평문으로 들어 있습니다.
  • 프로젝트 밖에서 프록시를 실행하거나 venice-debug.jsonl을 .gitignore에 추가하세요.
  • 디버깅이 끝나면 로그를 삭제하세요.
  • 전체 로그 항목을 공개 이슈에 붙여 넣지 마세요. 대신 status, error, 그리고 response의 관련 부분만 추려 내세요.
E2EE 모델의 경우 에이전트가 메시지 내용이 내 컴퓨터를 떠나기 전에 암호화하므로, 로그에는 읽을 수 있는 텍스트 대신 암호화된 페이로드가 표시됩니다.

마무리

작업이 끝나면 Ctrl+C로 프록시를 중지하고 에이전트의 base URL을 https://api.venice.ai/api/v1로 되돌리세요. 잊어버리더라도 프록시가 실행 중이 아니면 에이전트가 즉시 연결 오류로 실패하므로, 적어도 알아차리기는 쉽습니다. 읽어 주셔서 감사합니다! 다음에 에이전트가 “something went wrong”이라고 할 때는 무엇이 잘못되었는지 정확히 확인할 수 있기를 바랍니다.