클라우드 코드 커스텀 API 엔드포인트: 제3자 게이트웨이 설정 및 중국어 오픈소스 모델 사용

클라우드 코드는 Anthropic 호환형 엔드포인트 대신 제공자 엔드포인트를 직접 사용하지 않고 설정할 수 있습니다. 이는 게이트웨이 관리형 워크플로우를 테스트하고 게이트웨이에서 노출되는 모델 ID를 사용하여 중국어 오픈소스 모델을 테스트할 수 있게 합니다. 현재 ECAIX 모델 카탈로그에 포함된 중국어 오픈소스 모델을 포함합니다.

이 가이드는 제공자별 제3자 호환성 워크플로우입니다. Anthropic의 공식 클라우드 코드 게이트웨이 문서는 클라우드 코드를 게이트웨이를 통해 비클라우드 모델로 라우팅하는 것을 지원하지 않습니다. ECAIX는 Anthropic이 공식적으로 지원하지 않는 이 워크플로우가 공식적으로 지원된다고 주장하지 않습니다. 비클라우드 모델은 모든 클라우드 코드 기능이 제공하지 않을 수 있습니다.

빠른 시작

기존 호환성 경계에 대해 이해가 있다면, 먼저 다음 단계를 수행하세요:

1. 현재 ECAIX 모델 카탈로그에서 활성화된 모델 ID를 선택하세요.
2. ECAIX API 키를 생성하고 소스 제어에서 보관하지 마세요.
3. ANTHROPIC_BASE_URL를 https://ecaix.com/api/ai/v1/anthropic로 설정하세요.
4. 아래 디아그노스틱 요청을 보냅니다. HTTP 상태 코드를 기록하세요.
5. 읽기 전용 테스트 프로젝트에서 claude -p로 클라우드 코드를 실행하세요.
6. 도구, 스트리밍, 컨텍스트 한계, 및 권한을 별도로 테스트하세요.

발행 시점의 검증 상태

이 표는 의도된 구성 예시입니다. 구성 예시는 측정된 호환성 결과와 다릅니다.

이 설정이 변경하는 것

설정은 네 가지 별도의 부분으로 구성됩니다:

1. 클라우드 코드는 코딩 작업을 생성하고 요청을 보냅니다.
2. Anthropic 호환형 게이트웨이는 Anthropic 스타일 엔드포인트에서 요청을 받습니다.
3. 모델 ID는 게이트웨이에서 노출되는 업스트림 모델을 선택합니다.
4. API 키는 요청을 인증하고 계정, 할당량, 권한을 결정합니다.

엔드포인트 변경은 비클라우드 모델을 클라우드 모델로 변환하지 않습니다. 단지 호환 가능한 API 표면이 요청을 받게만 합니다. 도구 사용, 컨텍스트 처리, 모델 별칭, 스트리밍 행동, 권한 흐름은 클라이언트 버전과 게이트웨이 구현에 따라 다를 수 있습니다.

시작하기 전에

필요한 것:

• 환경 변수 또는 설정 기반 엔드포인트 구성에 지원되는 클라우드 코드 설치.
• ECAIX API 키.
• 현재 ECAIX 모델 카탈로그에 존재하는 모델 ID.
• 소스 제어에 API 키를 저장하지 않고 작은 테스트 요청을 실행할 수 있는 터미널.

카탈로그는 시간이 지남에 따라 변경됩니다. 모델 ID를 구성 파일로 복사하기 전에 ECAIX 모델 디렉토리를 열고 사용하려는 스타일의 모델이 활성화되고 API에 사용할 수 있는지 확인하세요.

게이트웨이 엔드포인트 구성

클라우드 코드는 많은 설치에서 ~/.claude/settings.json에 설정을 저장합니다. 정확한 설정 스키마는 변경될 수 있으므로, 다음을 시작 패턴으로 사용하고 설치된 버전 문서와 비교하세요.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ecaix.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_ECAIX_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"
  },
  "model": "deepseek-v4.1-flash"
}

실제 API 키가 포함된 이 파일을 공공 저장소에 커밋하지 마세요. 로컬 환경 변수, 비밀 관리자, 또는 클라우드 코드 설치가 권장하는 크레덴셜 메커니즘을 선호하세요.

테스트 중인 동안 셸 세션에서 엔드포인트를 구성할 수도 있습니다:

export ANTHROPIC_BASE_URL="https://ecaix.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_ECAIX_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4.1-flash"

특정 클라우드 코드 릴리스에 지원되는 변수 이름 및 설정이 변경될 수 있습니다. 클라이언트가 ANTHROPIC_MODEL을 무시하는 경우, 해당 버전 문서에 설명된 모델 필드 또는 모델 별칭 메커니즘을 사용하세요. 게이트웨이는 최종 모델 ID를 인식해야 합니다.

Anthropic 호환형 엔드포인트 확인

인터랙티브 코딩 세션을 시작하기 전에 작은 요청을 보냅니다. 이는 엔드포인트, 인증, 모델 ID 문제와 클라우드 코드 특유의 문제에서 분리됩니다.

아래 명령은 응답 헤더와 응답 본문을 별도로 저장한 다음 HTTP 상태 코드를 출력합니다. 실제 인증된 키는 로컬 셸에서만 사용하세요. 절대 기사, 이슈, 공유 로그에 붙여넣지 마세요.

curl -sS -D /tmp/ecaix-anthropic-headers.txt \
  -o /tmp/ecaix-anthropic-response.json \
  -w '\nHTTP %{http_code}\n' \
  "${ANTHROPIC_BASE_URL}/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ]
  }'

예상 해석:

• 200: 응답 구조를 확인하고 반환된 모델 또는 사용량 필드를 확인하세요.
• 401 또는 403: 키, 헤더, 계정, 권한 범위를 확인하세요. 다음에 프롬프트를 변경하기 전에 확인하세요.
• 404: 기본 URL, /messages 접두사, 엔드포인트 배포를 확인하세요.
• 400: 요청을 가장 작은 유효한 본문으로 줄이고 모델 특이 필드를 확인하세요.
• 5xx 또는 타임아웃: 요청 시간과 응답 본문을 기록하고 게이트웨이, 업스트림, 클라이언트 타임아웃 행동을 분리하세요.

성공적인 응답은 키, 엔드포인트, 요청 형식, 모델 ID가 해당 요청을 위해 잘 작동했음을 확인합니다. 모든 클라우드 코드 기능이 작동할 것을 증명하지 않습니다.

모델 ID 선택

ECAIX 카탈로그는 중국 제공자에서 제공하는 모델 가족을 포함합니다. 작업에 따라 모델의 시작 모델은 이름만으로 결정되지 않습니다.

코딩 및 일반 개발

현재 DeepSeek, Qwen, GLM, 또는 Seed 코딩 가능 모델 중 하나에서 시작하세요. 카탈로그에 노출되는 ID 중 하나인 deepseek-v4.1-flash, qwen3.8-flash, glm-5.3, 또는 seed-2.0-code와 같은 모델을 시작하세요. 가용성과 기능은 변할 수 있으므로, 모델 페이지를 확인하고 구성 파일을 발행하기 전에 현재 모델 페이지를 항상 확인하세요.

긴 컨텍스트 및 리포지토리 작업

대형 리포지토리나 긴 기술 문서에 대해 컨텍스트 길이를 비교하세요. 더 큰 컨텍스트 창은 자동으로 리포지토리 결과가 더 좋다고 의미하지 않습니다: 프롬프트 구조, 도구 지원, 출력 한계, 그리고 게이트웨이의 요청 한계도 중요합니다.

도구 호출 및 에이전트 워크플로우

워크플로우가 함수 호출이나 도구를 필요로 한다면, 모델과 엔드포인트 문서를 확인하세요. 일부 제공자는 OpenAI 호환형 API를 통해 도구 호출을 노출합니다. 다른 제공자는 다른 필드 이름을 노출하거나 도구 동작의 일부만 지원합니다. 작은 도구 호출 테스트를 먼저 수행하세요. 실제 리포지토리나 외부 시스템에 모델을 접근할 때 사용하세요.

중국어 개발 작업

중국어 오픈소스 모델은 코드베이스, 문서, 이슈 트랙, 또는 팀 워크플로우에 중국어 자료가 포함된 경우 유용할 수 있습니다. 모델을 자체 프롬프트와 리포지토리 샘플로 평가하세요. 일반 순위만 신뢰하지 마세요.

테스트 후 API 요청이 성공하면 Claude 코드 테스트

API 요청이 직접 성공하면 읽기 전용 또는 위험이 적은 명령부터 시작하세요:

claude -p "Explain what this repository does without editing files."

다음으로 좁은 범위 내의 작업을 테스트하세요. 예를 들어:

claude -p "List the likely entry points for the web application. Do not modify files."

진행적으로 더 demanding한 테스트를 진행하세요:

1. 평문 응답
2. 간단한 코드 설명
3. 저장소 탐색
4. 가용성 테스트 브랜치에서 제어된 편집
5. 도구 사용 또는 다단계 작업
6. 스트리밍 및 긴 문맥 처리

API 요청이 성공한 것으로 가정하지 마세요. Claude 세션과 동일하게 권한 프로MP트, 도구 호출, 스트리밍, 문맥 제한, 파일 편집이 동작하는지 확인할 수 없습니다.

올바른 API 경로 선택

Claude Code는 단일 클라이언트 워크플로이드입니다. 필요한 클라이언트 및 기능에 따라 적절한 API 경로는 다음과 같습니다:

ECAIX에서는 Anthropic Messages 문서 및 Chat Completions 문서 참조하여 Anthropic 스타일 경로와 OpenAI 호환 클라이언트를 사용하세요. 모델 디렉토리 및 가격 페이지를 확인하여 현재 모델 및 가격 정보 확인하세요.

호환성 매트릭스

다음 매트릭스는 출판 시점의 증거 경계입니다. 모든 기능이 지원되는 것은 아닙니다:

이 구분은 최소 요청이 성공한 것으로 완전한 Claude Code 호환성 인증이 되는 것은 아닙니다.

모델 상세 페이지 및 현재 ID

모델 이름 복사 대신 블로그 포스트에서 오래된 모델 이름을 복사하지 마세요:

• DeepSeek v4.1 플래시
• Qwen 3.8 플래시
• GLM 5.3
• Kimi K3

이 링크는 현재 모델 ID, 문맥 정보, 페이지 수준 상세 정보를 확인하는 입구입니다. 게시 후 변경될 수 있습니다.

오류가 발생할 경우 변수를 한 번에 변경하지 마세요:

1. HTTP 상태 코드와 응답 본문 저장
2. 기본 URL과 엔드포인트 접미사 확인
3. API 키가 로컬에 presence하고 예상 범위인지 확인
4. 모델 카탈로그에서 정확한 모델 ID 확인
5. 유효한 최소 요청으로 재시도
6. 클라이언트 요청을 Claude Code가 보낸 요청과 비교
7. 이후 라우팅, 타임아웃, 또는 도구 스키마 차이점 조사

모델을 찾지 못함은 철자 오류, 권한 문제, 게이트웨이 매핑 문제, 또는 업스트림 제공자 실패를 구별합니다. 401 및 403에 대해 모델 변경은 일반적으로 첫 번째 해결책이 아닙니다. 텍스트 성공/도구 실패의 경우 도구 스키마가 아닌 다른 평문 프롬프트로 테스트해야 합니다.

일반적인 오류

보안 및 데이터 처리

게이트웨이를 별도의 서비스 경계로 취급하세요. 소스 코드나 고객 데이터를 전송하기 전에 다음을 검토하세요:

• 어떤 서비스에 프롬프트와 파일 내용이 전송되는지 확인
• 요청과 응답이 로깅되는지 확인
• API 키가 저장되고 회전되는 방식 확인
• 모델 라우팅이 실제 업스트림 연결인지, 다른 제공자의 폴백 라우팅인지 확인
• 클라이언트가 호출할 수 있는 도구 확인
• 키를 테스트 후 취소하는 방법 확인

공공 이슈, 문서, 스크린샷, 또는 공유된 셸 히스토리에 프로덕션 API 키를 붙여넣지 마세요.

공식 Claude Code 지원과 차이점

공식 Anthropic 문서는 Claude Code 지원의 권위자입니다. 제3자 게이트웨이는 호환 가능한 요청 형식을 노출할 수 있지만, 공식 지원과 호환성은 다릅니다. 이 워크플로우를 안전하게 설명하는 방법은 다음과 같습니다:

• 이 게이트웨이 구성에서 지원됨: 엔드포인트, 인증 헤더, 모델 ID, 그리고 ECAIX가 테스트한 기능
• 자동으로 지원되지 않음: 모든 Claude Code 기능, Claude 외 모델의 동작, 제공자 고유 도구 의미, 클라이언트 버전 변경
• 변경 후 재테스트 필요: 모델 가용성, 요청 필드, 문맥 제한, 스트리밍, 도구 호출, 가격

FAQ

이 워크플로우에 Claude 구독이 필요한가?

클라우드 코드 설치, 계정 조건, 그리고 게이트웨이 구성에 따라 결정됩니다. 이 문서는 Anthropic의 구독 또는 제품 요구 사항을 변경하지 않습니다. 공식 Claude Code 문서와 사용하려는 게이트웨이의 조건을 확인하세요.

카탈로그에서 사용할 수 있는 모델 ID를 사용할 수 있나요?

네. 현재 공개된, 활성화된, 그리고 엔드포인트 및 계정에 호환되는 모델 ID를 사용해야 합니다. 모델이 카탈로그에 존재할 수 있지만 특정 API 스타일이나 키에 접근할 수 없는 경우입니다.

Anthropic 호환 엔드포인트는 도구 호출을 보장합니까?

네. 프로토콜 호환성과 도구 동작은 별개의 검증입니다. 작은 함수 호출 테스트를 실행하고 모델의 현재 문서를 확인한 후 자동화된 워크플로우에서 도구를 사용하세요.

현재 모델과 가격은 어디에서 확인할 수 있나요?

ECAIX 모델 디렉토리와 가격 페이지를 참조하세요. 이 페이지는 현재 가용성 및 표시된 가격의 원천입니다. 이 문서에서 복사한 오래된 모델 ID나 가격은 사용하지 마세요.

요약

안전한 통합 순서는 다음과 같습니다:

1. 공식 Claude Code 및 게이트웨이 문서를 읽기
2. 공개하지 않도록 ECAIX API 키를 생성
3. 모델에서 현재 가용한 모델 ID를 선택
4. ANTHROPIC_BASE_URL와 키를 로컬로 구성
5. /api/ai/v1/anthropic/messages를 최소 요청으로 테스트
6. Claude Code를 읽기 전용 작업으로 테스트
7. 도구, 스트리밍, 문맥, 권한을 별도로 테스트
8. 클라이언트, 게이트웨이, 모델, 또는 엔드포인트가 변경될 때마다 호환성을 재확인

다음 단계로 Anthropic Messages API 문서를 읽고 현재 모델 카탈로그를 검토하고 API 키에서 키를 생성하세요.

실용적인 호환성 체크리스트

용도 있는 팀에서 통합을 사용할 수 있도록 각 테스트의 결과를 기록하세요:

이 체크리스트는 단일 성공적인 인사이트보다 더 유용합니다. 게이트웨이는 텍스트 요청을 수락할 수 있지만 도구, 스트리밍, 컨텍스트 윈도우, 또는 모델 별칭에 대해 다른 설정이 필요할 수 있습니다.

사용하지 않는 경우

기밀한 생산 저장소에 이 설정을 사용하기 전에 로깅, 보존, 라우팅, 및 접근 제어에 대해 이해해야 합니다. 제공자 호환 엔드포인트가 원본 제공자의 같은 보안 행위를 제공하지는 않습니다. 또한 시스템 프롬프트, 도구 권한, 또는 컨텍스트 계산을 원본 제공자와 동일하게 제공하지는 않습니다. 규제 또는 기밀 작업에 사용하려면 내부 보안 검토를 완료하고 조직이 승인한 배포 경로를 사용하세요.

설정 유지

다음 중 어떤 변화가 발생할 때 설정을 검토하세요:

• Claude Code가 업그레이드됩니다.
• 게이트웨이가 Anthropic 호환 구현을 변경합니다.
• 모델 ID가 변경되거나 제거되거나 다른 원천으로 매핑됩니다.
• 스트리밍, 도구, 컨텍스트 한도, 또는 오류 처리 방식이 변경됩니다.
• ECAIX가 라이브 카탈로그에서 표시하는 모델이나 API 한도를 변경합니다.

설정을 작은, 문서화된 테스트 프로젝트에 유지하세요. 이는 클라이언트 또는 모델 업데이트 후 클라이언트 행동 비교를 쉽게 하고, 생산 저장소를 노출시키지 않음으로써 생산 저장소에 노출되지 않도록 합니다.

출처

• Anthropic Claude Code: 다른 LLM 게이트웨이
• DeepSeek API 문서
• Qwen Quickstart
• Zhipu OpenAI API 호환성