코딩 에이전트의 불투명성 해결하기: ccglass를 통한 Claude Code 및 Codex 요청 검사

AI 코딩 에이전트(AI coding agents)는 더 이상 단순한 자동 완성(autocomplete)처럼 느껴지지 않을 정도로 발전하고 있습니다.

Claude Code, Codex, OpenCode, Cursor, Cline 및 기타 에이전트 기반 코딩 시스템(agentic coding systems)과 같은 도구들은 파일을 읽고, 코드를 수정하며, 명령어를 실행하고, 도구를 호출하며, 에러를 검사하고, 여러 턴(turn)에 걸쳐 작업을 계속 수행할 수 있습니다.

이는 매우 유용하지만, 동시에 점점 더 불투명해지고 있습니다.

에이전트에게 버그 수정을 요청하면, 보통 터미널에서 최종 결과와 몇 가지 도구 호출(tool calls) 정도만 볼 수 있습니다. 하지만 다음과 같은 사항들은 알기 어렵습니다:

모델이 어떤 시스템 프롬프트(system prompt)를 받았는가?
요청(request)에 어떤 메시지들이 포함되었는가?
어떤 도구 스키마(tool schemas)가 모델에게 보여졌는가?
왜 다른 도구 대신 특정 도구를 선택했는가?
어떤 도구 결과(tool result)가 다음 턴으로 전달되었는가?
작업에 얼마나 많은 토큰(tokens)을 사용했는가?
캐시(cache)가 사용되었는가?
어떤 요청이 느렸는가?
세션 비용이 얼마나 발생했는가?

작은 실험을 할 때는 추측해도 괜찮습니다. 하지만 실제 업무에서 추측은 나쁜 디버깅(debugging) 전략입니다.

그것이 바로 제가 ccglass를 만든 이유입니다.

GitHub: https://github.com/jianshuo/ccglass

ccglass란 무엇인가?

ccglass는 AI 코딩 에이전트를 위한 로컬 관찰성(observability) 도구입니다.

이 도구는 로컬 프록시(local proxy)를 실행하여 모델의 요청(requests)과 응답(responses)을 캡처하고, 이를 웹 대시보드에 보여줍니다.

목표는 간단합니다. Claude Code, Codex, DeepSeek-TUI, Kimi, OpenCode, Ollama, OpenRouter 및 기타 에이전트 클라이언트(agent clients)가 모델에 실제로 무엇을 보내고 있는지 쉽게 확인하는 것입니다.

ccglass는 다음을 보여줄 수 있습니다:

시스템 프롬프트 (system prompts)
사용자 및 어시스턴트 메시지 기록 (user and assistant message history)
도구 스키마 (tool schemas)
도구 호출 및 도구 결과 (tool calls and tool results)
가공되지 않은 요청 및 응답 본문 (raw request and response bodies)
토큰 사용량 (token usage)
캐시 사용량 (cache usage)
예상 비용 (estimated cost)
지연 시간 (latency)
턴 간 차이 (turn-to-turn diffs)

이것은 또 다른 코딩 에이전트가 아닙니다. 여러분이 이미 사용하고 있는 에이전트들을 위한 가시성 계층(visibility layer)입니다.

왜 일반적인 HTTP 프록시를 사용하지 않나요?

Charles, mitmproxy 또는 Proxyman과 같은 범용 도구들은 훌륭하지만, AI 코딩 에이전트를 전통적인 프록시 설정으로 검사하는 것은 까다로울 수 있습니다.

일부 클라이언트는 HTTP_PROXY / HTTPS_PROXY 설정을 안정적으로 준수하지 않습니다. 어떤 클라이언트는 자체적인 네트워킹 동작 방식을 가지고 있으며, 어떤 클라이언트는 제공자(provider)별 특정 베이스 URL (base URL) 설정을 사용하기도 합니다. 클라이언트를 패치(patching)하는 방식은 불안정합니다.

ccglass는 더 타겟팅된 접근 방식을 취합니다.

ccglass는 로컬 프록시 (local proxy)를 시작한 다음, 다음과 같은 적절한 베이스 URL (base URL) 환경 변수를 사용하여 대상 에이전트를 실행하거나 구성합니다:

ANTHROPIC_BASE_URL
OPENAI_BASE_URL

에이전트는 모델 트래픽 (model traffic)을 로컬 프록시로 전송합니다. ccglass는 이를 기록(log)하고, 실제 업스트림 API (upstream API)로 전달하며, 그 결과를 대시보드 (dashboard)에 렌더링합니다.

즉, CA 인증서 (CA certificate)를 설치하거나, TLS를 복호화하거나, 클라이언트 소스 코드를 수정하지 않고도 LLM 트래픽을 검사할 수 있다는 의미입니다.

빠른 시작 (Quick start)

npm으로 ccglass를 설치하세요:

npm install -g ccglass

그 다음 실행하세요:

ccglass

특정 클라이언트를 직접 시작할 수도 있습니다:

ccglass claude
ccglass codex
ccglass opencode
...

예를 들어:

ccglass codex

실행 시, ccglass는 로컬 대시보드 URL을 출력합니다:

dashboard: http://127.0.0.1:57633

해당 URL을 열면 에이전트가 작동함에 따라 요청이 나타나는 것을 확인할 수 있습니다.

무엇을 디버깅할 수 있나요?

1. 프롬프트 (Prompt) 및 컨텍스트 (context) 문제

때때로 에이전트는 사용자가 기대했던 컨텍스트를 보지 못해 잘못된 결정을 내리곤 합니다.

ccglass를 사용하면 터미널 출력값을 보고 추측하는 대신, 모델로 전송된 실제 메시지를 검사할 수 있습니다.

다음과 같은 질문에 답할 수 있습니다:

파일 내용이 요청에 포함되었는가?
이전 도구 (tool) 결과가 포함되었는가?
긴 대화 내용이 중요한 지시 사항을 묻어버렸는가?
시스템 프롬프트 (system prompt)가 동작을 제한했는가?

2. 도구 호출 (Tool call) 동작

코딩 에이전트의 성능은 도구 루프 (tool loop)의 성능과 직결됩니다.

ccglass를 통해 모델에 보여지는 도구들, 모델이 선택한 도구 호출, 도구에 전달된 인자 (arguments), 그리고 다음 요청으로 다시 피드백된 결과를 검사할 수 있습니다.

이는 에이전트가 다음과 같은 상황일 때 유용합니다:

잘못된 도구 (tool)를 선택함
동일한 명령을 반복함
사용 가능한 도구를 사용하지 못함
도구 스키마 (tool schema)로 인해 혼란을 겪음
제공자 (provider)에 따라 다르게 동작함

3. 토큰 (Token) 및 비용 급증

장시간 실행되는 에이전트 세션은 토큰을 빠르게 소모할 수 있습니다.

ccglass는 요청(request) 및 세션(session)별 토큰 사용량, 캐시 (cache) 사용량, 예상 비용, 그리고 지연 시간 (latency)을 보여줍니다.

이를 통해 다음과 같은 현상을 더 쉽게 발견할 수 있습니다:

컨텍스트 (context)로 유입되는 거대한 도구 결과값
반복되는 대규모 프롬프트 (prompt)
낮은 캐시 히트 (cache hit) 동작
느린 요청
큰 가치를 더하지 못한 비용이 많이 드는 턴 (turn)

4. 제공자 (Provider) 및 프록시 (proxy) 문제

로컬 게이트웨이 (local gateway), OpenAI 호환 엔드포인트 (OpenAI-compatible endpoints), Anthropic 호환 엔드포인트 (Anthropic-compatible endpoints), OpenRouter, Ollama, Bedrock, Vertex 또는 내부 프록시를 사용하는 경우, 요청 형태 (request shape)가 중요합니다.

ccglass는 클라이언트가 보낸 내용과 업스트림 (upstream)이 기대한 내용을 비교할 수 있도록 도와줍니다.

이는 특히 다음과 같은 사항을 디버깅할 때 유용합니다:

커스텀 base_url 설정
Anthropic 대 OpenAI 호환 페이로드 (payload) 차이
누락된 도구 호출 (tool call) 필드
잘못된 형식의 도구 인자 (tool arguments)
제공자별 라우팅 (routing)

요청 내보내기 (Exporting requests)

더 깊은 조사나 버그 보고를 위해 캡처된 요청을 내보낼 수 있습니다:

ccglass export <session>/<seq> --format raw
ccglass export <session>/<seq> --format md
ccglass export <session>/<seq> --format json
...

이를 통해 에이전트, 제공자 또는 게이트웨이 프로젝트에 문제를 보고할 때 유용한 증거를 첨부하기가 더 쉬워집니다.

대상 사용자

ccglass는 다음과 같은 경우에 유용합니다:

Claude Code, Codex, OpenCode 또는 유사한 코딩 에이전트를 집중적으로 사용하는 경우
코딩 에이전트를 기반으로 도구를 구축하는 경우
LLM 게이트웨이 또는 프록시를 유지 관리하는 경우
프롬프트, 컨텍스트 또는 도구 호출 (tool-call) 동작을 디버깅하는 경우
토큰 사용량과 비용을 이해하고자 하는 경우
서로 다른 제공자 또는 에이전트 클라이언트를 비교하고자 하는 경우
트레이스 (trace)를 SaaS 서비스로 보내는 대신 로컬 우선 관측성 (local-first observability)을 중시하는 경우

Codex에 관한 참고 사항

Codex는 여러 인증 (auth) 및 전송 (transport) 경로를 가집니다.

API 키 모드에서는 구성 가능한 base URL을 통한 라우팅이 로컬 프록시 검사에 효과적으로 작동합니다.

Codex가 ChatGPT 로그인을 통해 인증될 때, 일부 트래픽은 OPENAI_BASE_URL을 준수하지 않는 WebSocket 경로를 사용할 수 있습니다. 이 경우 ccglass와 같은 로컬 프록시 (local proxy) 도구는 해당 트래픽을 볼 수 없습니다.

Codex 라우팅 (routing)을 디버깅할 때 이러한 차이는 매우 중요합니다.

이것이 왜 중요한지에 대한 생각

코딩 에이전트 (coding agents)가 점점 더 유능해짐에 따라, 개발자들은 에이전트의 동작을 이해하기 위한 더 나은 도구가 필요합니다.

이제 흥미로운 질문은 단지 다음과 같은 것에 그치지 않습니다:

에이전트가 올바른 코드를 생성했는가?

또한 다음과 같은 질문도 포함됩니다:

에이전트는 왜 그런 방식으로 동작했는가?

이에 답하기 위해서는 프롬프트 (prompts), 컨텍스트 (context), 도구 (tools), 요청 (requests), 지연 시간 (latency), 그리고 비용 (cost)에 대한 가시성 (visibility)이 필요합니다.

ccglass는 그 방향을 향한 작은 오픈 소스 (open-source) 단계입니다.