Claude Code с внешним Anthropic-совместимым API: воспроизводимый порядок отладки

개요

Claude Code CLI가 Anthropic Messages 프로토콜과 호환되는 외부 API 게이트웨이를 사용할 때 발생하는 문제를 디버깅하는 방법을 설명하며, 주로 API 게이트웨이 설정 및 환경 변수 구성 오류에 집중합니다.

주요 내용

• DaoXE API 게이트웨이 소개: DaoXE는 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, OpenAI 호환 이미지 생성 등을 지원하는 멀티모달, 멀티프로토콜 API 게이트웨이입니다.
• Anthropic 호환 API 디버깅: Claude Code CLI가 Anthropic Messages 프로토콜을 사용하는 외부 게이트웨이와 통신할 때 발생하는 문제를 해결하기 위한 단계별 디버깅 절차를 제공합니다.
• 환경 변수 설정: ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN 환경 변수를 올바르게 설정하는 것이 중요하며, ANTHROPIC_BASE_URL은 호스트의 루트 주소로 설정해야 합니다.
• curl을 이용한 프로토콜 검증: Claude Code CLI를 실행하기 전에 curl 명령어를 사용하여 API 게이트웨이의 Anthropic Messages 프로토콜 작동 여부를 먼저 확인합니다. 이를 통해 실제 모델 ID를 확인하고 간단한 메시지 요청을 보낼 수 있습니다.
• curl 성공 시 Claude Code CLI 문제 진단: curl이 성공했지만 Claude Code CLI가 실패하는 경우, ANTHROPIC_BASE_URL에 /v1이 포함되었는지, 환경 변수가 올바른 터미널에서 설정되었는지, 토큰 변수 이름이 올바른지, 모델 ID가 정확한지, 설정 파일이 최신인지 등을 확인해야 합니다.
• 영구 설정: 환경 변수를 셸 프로필 파일(~/.zshrc 또는 ~/.bashrc)에 추가하여 매번 설정하는 번거로움을 줄일 수 있습니다.
• 디버깅 순서의 중요성: curl로 프로토콜 자체를 검증하는 첫 단계를 통해 문제의 범위를 API 게이트웨이 또는 클라이언트 구성 문제로 좁혀, 모델이나 프롬프트 자체의 문제로 오해하는 시간을 줄일 수 있습니다.
• 다양한 클라이언트 및 프로토콜: 클라이언트(Cline, Roo, Continue 등)는 OpenAI Chat Completions를, Claude Code CLI 및 Anthropic SDK는 Anthropic Messages를 사용하는 경우가 많으므로, 각 클라이언트가 사용하는 실제 프로토콜 경로에 맞춰 설정을 최적화해야 합니다.

시사점

이 디버깅 절차는 Claude Code CLI와 Anthropic API를 연동할 때 발생할 수 있는 복잡한 설정 문제를 효과적으로 해결하고, 개발자가 문제의 근본 원인을 신속하게 파악하여 개발 시간을 단축하는 데 기여합니다.