curl은 되는데 Claude Code는 연결되지 않을 때, 같은 프로토콜부터 확인하기

API 요청은 curl에서 성공하는데 Claude Code에서는 실패한다면, 먼저 두 요청이 같은 종류인지 확인하세요. OpenAI Chat Completions 요청의 성공은 해당 경로와 인증 정보가 작동했다는 점만 보여 줍니다. Anthropic Messages 요청이나 스트리밍 응답, Claude Code를 실행하는 프로세스까지 작동한다는 뜻은 아닙니다.

Ofox와 Claude Haiku 5.5로 이 차이를 재현했습니다. 모델은 Chat Completions를 통해 답변했습니다. 일부러 경로를 맞지 않게 설정한 Messages 요청은 HTTP 401을 반환했습니다. 올바른 Anthropic 호환 경로에서는 READY가 반환됐고, 최소한의 Claude Code 요청도 완료됐습니다. HTTP 테스트의 경로와 프로토콜 조합을 바로잡자 응답이 성공했습니다. Claude Code 세션이 실패하는 상황은 재현하지 못했으므로, 이것이 클라이언트 오류를 해결하는 방법이라고 확정할 수는 없으며 모든 연결 오류의 원인이 base URL이라고 볼 수도 없습니다.

이 안내서는 이미 작동하는 API 인증 정보가 있지만 코딩 클라이언트가 실패하는 원인을 구분해야 하는 개발자를 위한 것입니다. 공급자를 처음 설정하는 경우에는 Claude Code 설정 안내를 참고하세요. 여기서는 실패한 계층을 찾아낼 때까지 기존 프로젝트 설정을 그대로 유지합니다.

테스트에서 실제로 확인한 내용

테스트에는 Claude Code 2.1.296, Ofox 모델 ID anthropic/claude-haiku-5.5, 민감한 내용이 없는 짧은 프롬프트를 사용했습니다. 이는 개별 요청 테스트이며, 가용성이나 속도 벤치마크가 아닙니다.

경로가 맞지 않았던 요청에는 잘못된 경로와 해당 경로에 적합하지 않은 인증 방식이 함께 사용됐습니다. 둘 중 하나만 따로 바꾸면 무엇이 먼저 실패할지는 이 결과만으로 확인할 수 없습니다. 특히 401 응답은 API 키 자체가 유효하지 않았다는 증거가 아닙니다. 같은 인증 정보가 올바른 경로에서는 작동했습니다.

요청이 완료됐는데도 클라이언트는 네임스페이스가 포함된 모델 식별자에 대해 unrecognized_model 경고를 출력했습니다. 진단할 때 이 경고를 기록하되, 응답 실패와 동일시하거나 모든 기능이 지원된다고 추론하지 마세요. 이 테스트에서는 도구를 비활성화했으며 코딩 작업 흐름, MCP, 계정 전환, 장시간 스트리밍 세션은 테스트하지 않았습니다.

엔드포인트, 본문, 인증 정보 맞추기

테스트할 항목을 하나의 조합으로 기록하세요. 공급자, base URL, 최종 경로, 모델 ID, 인증 헤더, 요청 본문 형식이 여기에 포함됩니다. 공급자 간 매핑을 확인하지 않은 채 한 공급자의 예제에 나온 모델 이름을 다른 공급자 설정에 복사하지 마세요.

이 Anthropic 호환 설정에서는 OpenAI SDK에 사용하는 base URL 끝에 /v1을 붙이는 것으로 대체할 수 없습니다. 전체 /v1/messages URL을 경로 접두사를 기대하는 base 필드에 붙여 넣어서도 안 됩니다.

Anthropic의 게이트웨이 문서는 게이트웨이 설정과 기반 공급자를 구분합니다. 또한 서드파티 게이트웨이를 통해 라우팅되는 Claude 이외의 모델을 지원한다고 보장하지 않는다고 명시합니다. 이 테스트에서는 Claude 모델을 사용했습니다. 다른 모델로 텍스트 요청이 작동하더라도 Claude Code와 완전히 호환된다는 뜻은 아닙니다.

10월 12일에 캡처한 실제 Ofox 공개 코드 예제 인터페이스입니다. Anthropic 경로와 모델을 보여 주며, CLI 테스트 결과를 캡처한 화면은 아닙니다.

최소 Messages 요청 보내기

평소 사용하는 시크릿 관리 방식으로 환경 변수를 설정하고, 키는 환경 변수에 보관하세요. 스크린샷, 기사 댓글, 명령 기록, 공유 진단 파일에 키를 넣지 마세요. 다음 POSIX 셸 예제는 OFOX_API_KEY가 이미 설정돼 있다고 가정합니다.

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 45 \
  'https://api.ofox.ai/anthropic/v1/messages' \
  -H "x-api-key: $OFOX_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  --data '{"model":"anthropic/claude-haiku-5.5","max_tokens":64,"messages":[{"role":"user","content":"Reply with READY only."}]}'

성공으로 인정하려면 Messages 응답의 content에 READY가 포함된 텍스트 블록이 있어야 합니다. HTTP 결과와 응답 본문을 함께 확인하세요. HTML 로그인 페이지, 비어 있는 성공 응답 본문, 오류 객체는 유효한 모델 응답으로 인정되지 않습니다.

명령이 실패하면 가능한 경우 HTTP 상태 코드, 오류 유형, 요청 ID를 저장하세요. 공급자에게 문제를 알릴 때 요청 ID를 사용하고, 인증 헤더와 개인 프롬프트는 제외하세요. 연결 시간 초과, 인증서 오류, HTTP 401은 서로 다른 계층에서 발생하므로 같은 방식으로 해결하면 안 됩니다.

프로젝트 작업 없이 클라이언트 실행하기

테스트에 사용한 버전에서는 --bare가 최소 클라이언트 모드를 설정하고, --tools ""는 텍스트 전용 테스트에서 도구를 비활성화합니다. 버전에 따라 달라질 수 있는 플래그를 복사하기 전에 사용 중인 버전에서 claude --help를 확인하세요.

claude --version

(
  unset ANTHROPIC_AUTH_TOKEN
  export ANTHROPIC_BASE_URL='https://api.ofox.ai/anthropic'
  export ANTHROPIC_API_KEY="$OFOX_API_KEY"
  claude --bare -p 'Reply with READY only.' \
    --model 'anthropic/claude-haiku-5.5' \
    --tools '' --no-session-persistence --output-format json
)

괄호는 이러한 환경 변수 변경이 테스트에만 적용되도록 제한합니다. 비어 있는 임시 디렉터리에서 실행했습니다. 이 방법은 프로젝트 설정을 다시 쓰거나 조직의 제어를 제거하지 않습니다. 조직에서 공급자를 제한한다면 승인된 목적지를 사용하세요. 이 절차는 관리 정책을 우회하기 위한 것이 아닙니다.

통과 기준은 종료 상태 0, is_error: false, 예상한 결과입니다. 테스트 실행에서 프로세스는 시작부터 끝까지 2.64초가 걸렸습니다. CLI의 비용 필드는 Ofox 청구 내역과 대조하지 않았으므로 게이트웨이에서 확정된 청구액으로 사용하면 안 됩니다. 올바른 답변이 반환됐더라도 확인된 것은 이 최소 연결뿐입니다.

두 테스트 결과가 다를 때

Messages 요청은 성공하지만 클라이언트가 실패한다면 프로세스 환경을 비교하세요. 셸에서 시작한 프로세스와 IDE에서 실행한 프로세스에는 서로 다른 환경 변수가 전달될 수 있습니다. 실행 설정을 바로잡은 뒤 해당 클라이언트를 다시 시작하고, 실제 적용된 공급자와 모델을 확인하세요. 환경 변수 전체를 출력하지 마세요. 여기에 키가 포함될 수 있습니다.

다음으로 설정 적용 범위를 살펴보세요. Claude Code는 설정 안내에서 사용자, 프로젝트, 로컬, 관리형 설정을 설명합니다. 가장 최근에 수정한 파일의 값이 적용됐다고 가정하지 말고 실제 적용된 값을 확인하세요. 설정을 바꾸기 전에 사본을 보관하세요. 특정 저장소에서만 문제가 발생한다면, 먼저 전역 설정을 바꾸기보다 해당 저장소의 프로젝트 설정을 깨끗한 테스트와 비교하세요.

DeepSeek 전용 연결 설정은 별도의 공급자 프로토콜을 다루는 DeepSeek Claude Code 설정 문서를 참고하세요. 해당 문서의 직접 엔드포인트와 이 Ofox 예제를 섞지 마세요.

단계별로 실제 작업에 복귀하기

최소 테스트가 통과하면 평소 사용하는 프로젝트, 의도한 모델, 위험이 없는 읽기 전용 도구 요청, 일반 작업 흐름 순으로 한 번에 한 계층씩 다시 추가하세요. 각 단계마다 기대한 작업과 사용 기록을 확인하세요. 이후 문제가 생겼을 때 무엇이 바뀌었는지 좁혀 볼 수 있도록 성공한 테스트를 기준점으로 남겨 두세요.

유용한 문제 보고에는 클라이언트 버전, 운영체제, 공급자 경로, 민감 정보를 가린 모델 설정, 실패 시각, 요청 ID, 문제를 재현하는 최소 프롬프트가 포함됩니다. 어떤 확인이 통과했는지도 별도로 적으세요. “curl은 됩니다”라는 말은 어떤 프로토콜을 테스트했는지 알 수 있을 때 비로소 유용한 증거가 됩니다.