Claude Code에서 Nexith 사용하기
Claude Code는 Anthropic 프로토콜(/v1/messages, x-api-key)만 사용합니다. Nexith 게이트웨이에는 이 계층 어댑터가 내장되어 있어
프로토콜 경계만 번역하고, 내부적으로는 동일한 실행 파이프라인을 사용합니다 — 라우팅, 공급자 분배, 과금, 출구 정제 모두 재사용됩니다.
구성#
export ANTHROPIC_BASE_URL="https://api.nexith.ai"
export ANTHROPIC_API_KEY="nx-你的key"이 두 줄을 ~/.zshrc 또는 ~/.bashrc에 추가해 유지한 뒤, 프로젝트 디렉터리에서 평소처럼 claude를 사용하세요.
base URL에 대하여(가장 틀리기 쉬운 부분)#
/v1을 붙이지 마세요. 클라이언트가 base 뒤에 /v1/messages를 스스로 붙입니다:
| 작성한 값 | 클라이언트의 실제 요청 | 결과 |
|---|---|---|
https://api.nexith.ai |
https://api.nexith.ai/v1/messages |
✅ |
https://api.nexith.ai/v1 |
https://api.nexith.ai/v1/v1/messages |
❌ 실패 |
이는 Anthropic 공식 SDK의 규약과 일치합니다(공식 base는 https://api.anthropic.com이며 /v1을 붙이지 않습니다).
두 host 모두 사용 가능#
api.nexith.ai와 gateway.nexith.ai는 동일 백엔드의 두 진입점이므로 어느 쪽을 설정해도 됩니다.
(과거 안내: 2026-09-20 이전에는 api.nexith.ai가 모델 엔드포인트를 포워딩하지 않아
missing_api_key가 반환되었습니다 — key 정확성과 무관한 오류입니다. 현재는 수정되었습니다.)
자격 증명#
- Claude Code는
x-api-key를 보냅니다(Authorization아님). - 게이트웨이는 둘 다 받습니다:
Authorization: Bearer <token>우선,x-api-key를 폴백으로 사용합니다. - key는 platform.nexith.ai에서 생성하며
nx-+ 32자리 형태입니다.
지원 엔드포인트#
| 엔드포인트 | 설명 |
|---|---|
POST /v1/messages |
Anthropic Messages, tool use와 스트리밍 지원 |
POST /v1/messages/count_tokens |
token 카운트 |
POST /v1/chat/completions |
OpenAI 호환(동일 백엔드) |
POST /v1/responses |
OpenAI Responses(Codex 사용) |
GET /v1/models |
모델 목록 |
도구 호출#
검증 완료: 도구 정의는 input_schema를 통해 업스트림의 parameters로 그대로 변환됩니다. 응답은 Anthropic 규격에 따라
프레임으로 나뉩니다 — content_block_start(type: tool_use) → 여러 input_json_delta(파라미터는 업스트림 슬라이스대로
그대로 포워딩하며, JSON 파싱과 재직렬화를 하지 않으므로 긴 파라미터가 왕복에서 정밀도를 잃지 않습니다) → content_block_stop
→ message_delta(stop_reason: "tool_use" 포함).
tool_choice 매핑: auto → auto, any → required, tool → 지정 함수.
과금과 긴 작업#
- 과금은 실제 token으로 정산하며 정산 원장과 같은 소스입니다.
- 단일 요청에는 120초 상한이 있습니다(현재). 지나치게 긴 agent 루프에서 단일 턴이 120s를 넘으면 잘립니다 — 이 항목은 처리 중입니다.
- 컨텍스트가 32k를 넘는
nexith-core요청은 자동으로 더 강한 업스트림으로 업그레이드되며, 업그레이드된 등급으로 과금됩니다.
문제 해결#
401 missing_api_key
요청이 게이트웨이에 도달하지 않았음을 의미합니다. base URL에 /v1을 잘못 붙였는지(위 표 참고), 도메인 철자가 틀리지 않았는지 확인하세요.
401 invalid_api_key
요청은 게이트웨이에 도달했지만 key가 잘못되었습니다. nx-로 시작하는지, 여분의 공백이 없는지, 계정 잔액이 충분한지 확인하세요.
403 / 404
/v1/messages는 이 두 host에서만 제공됩니다. 다른 도메인(예: platform.nexith.ai)을 사용하면 동작하지 않습니다.
스트리밍이 멈춘 듯 보임 업스트림 모델이 긴 사고를 할 때는 데이터를 먼저 보내지 않습니다. 현재 게이트웨이에는 SSE 하트비트가 없어, 매우 긴 사고 중에는 클라이언트가 멈춘 것처럼 보일 수 있습니다. 이 항목은 이미 할 일 목록에 있습니다.