Claude Code

Claude Code는 Anthropic이 제공하는 터미널 코딩 도구입니다. API 주소, API Key 및 모델 ID를 설정하면 Claude Code에서 AGTCloud의 Anthropic Messages 호환 진입점을 사용할 수 있습니다.

이 튜토리얼은 Claude Code CLI만 설명합니다. 모델마다 도구 호출, 확장된 사고 및 실험 기능의 지원 범위가 다를 수 있으므로 현재 API Key에 표시되며 Anthropic Messages를 지원하는 모델을 선택합니다.

준비 사항

시작하기 전에 다음 사항을 확인합니다.

터미널 환경과 Git을 준비합니다.
AGTCloud에 가입하고 로그인합니다.
API Keys 페이지에서 토큰을 생성합니다.
모델 목록에서 현재 토큰으로 사용할 수 있는 Anthropic 프로토콜 모델 ID를 찾습니다.

Claude Code 설치

운영 체제에 맞는 설치 방식을 선택합니다. 네이티브 설치 스크립트는 자동으로 업데이트되며 Homebrew 및 WinGet 설치는 해당 패키지 관리자로 직접 업데이트해야 합니다.

curl -fsSL https://claude.ai/install.sh | bash

설치 후 터미널을 다시 열고 버전을 확인합니다.

claude --version
claude doctor

claude doctor는 설치 상태와 설정 파일을 검사합니다. 터미널에서 claude를 찾을 수 없다고 표시되면 터미널을 다시 열고 설치 디렉터리가 PATH에 추가되어 있는지 확인합니다.

AGTCloud 설정

Claude Code는 ANTHROPIC_BASE_URL에 지정된 주소로 요청을 보냅니다. 여기에는 AGTCloud API Origin만 입력하고 끝에 /v1을 추가하지 않습니다. Claude Code가 직접 /v1/messages를 요청하기 때문입니다.

임시 설정

다음 설정은 현재 터미널 세션에서만 적용됩니다. your-api-key와 MODEL_ID를 자신의 토큰 및 모델 ID로 교체합니다.

unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

환경 변수	역할
`ANTHROPIC_BASE_URL`	Claude Code 요청을 이 페이지에 표시된 AGTCloud API 주소로 보냅니다
`ANTHROPIC_API_KEY`	`X-Api-Key` Header로 AGTCloud API Key를 보냅니다
`ANTHROPIC_MODEL`	현재 세션에서 기본으로 사용할 모델 ID를 지정합니다

충돌하는 인증 변수 제거

시스템에 ANTHROPIC_AUTH_TOKEN이 설정되어 있으면 Claude Code가 이를 Bearer Token으로 사용하여 ANTHROPIC_API_KEY보다 우선할 수 있습니다. 이 튜토리얼의 설정을 사용하기 전에 해당 변수를 제거합니다.

영구 설정

터미널을 열 때마다 자동 적용하려면 같은 설정을 shell 설정 파일 또는 Windows 사용자 환경 변수에 기록할 수 있습니다. API Key가 로컬에 평문으로 저장되므로 개인의 신뢰할 수 있는 장치에서만 이 방식을 사용합니다.

~/.zshrc를 편집하고 다음을 추가합니다.

export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

저장한 뒤 설정을 불러옵니다.

source ~/.zshrc

모델 선택

MODEL_ID는 교체해야 하는 위치를 나타내며 실제 모델 이름이 아닙니다. 모델 목록에서 현재 API Key로 사용할 수 있고 Anthropic Messages를 지원하는 모델 ID를 복사합니다.

Claude Code에 들어간 뒤 /model로 현재 세션의 모델을 확인하고 전환할 수도 있습니다. 모델 선택기가 모든 AGTCloud 모델을 자동으로 표시하는지는 현재 Claude Code 버전과 API Key에 따라 다릅니다. 대상 모델이 표시되지 않으면 ANTHROPIC_MODEL로 모델 ID를 직접 지정합니다.

실행 및 연결 검증

프로젝트 디렉터리로 이동

cd /path/to/your/project

Claude Code 시작

claude

첫 실행에서 환경 변수의 API Key를 사용할지 묻는 경우 터미널 안내에 따라 확인합니다.

현재 설정 확인

Claude Code에서 다음을 실행합니다.

/status

인증 출처가 API Key인지 확인하고 Base URL이 이 페이지에 표시된 AGTCloud API 주소인지 검사합니다. Base URL에 중복 /v1이 없어야 합니다.

읽기 전용 테스트 수행

README.md가 있는 테스트 프로젝트에 다음을 입력합니다.

README.md를 읽고 이 프로젝트의 용도를 세 가지로 요약해 주세요. 어떤 파일도 수정하지 마세요.

내용이 정상적으로 반환되고 AGTCloud 콘솔에 해당 호출 기록이 표시되면 기본 연결이 설정된 것입니다.

설정 확인 후 간단한 질문을 보내 모델이 정상적으로 응답하는지 확인할 수 있습니다.

자주 묻는 질문

증상	우선 확인할 항목	조치
`claude` 명령을 찾을 수 없음	설치 결과 및 `PATH`	터미널을 다시 열고 `claude doctor`를 실행하며 필요한 경우 공식 설치 명령을 다시 실행합니다
실행 후에도 로그인 요구	Claude Code를 실행한 터미널에서 API Key가 적용되는지 여부	`ANTHROPIC_API_KEY`를 확인하고 터미널을 다시 연 뒤 실행합니다
API Key가 적용되지 않음	`ANTHROPIC_AUTH_TOKEN`이 함께 설정되어 있는지 여부	충돌하는 변수를 제거하고 `/status`로 인증 출처를 확인합니다
`401` 반환	API Key, 환경 변수 및 토큰 상태	유효한 API Key를 다시 복사하고 `/status`로 인증 출처를 확인합니다
`403` 반환	토큰 권한, 모델 권한 및 계정 상태	콘솔에서 토큰과 모델의 사용 가능 범위를 확인합니다
`404` 반환	Base URL 및 모델 ID	Base URL에는 `https://api.agtcloud.cn`만 입력하고 `/v1`을 추가하지 않으며 모델 ID를 다시 복사합니다
모델을 찾거나 사용할 수 없음	현재 API Key에 표시되는 모델 및 프로토콜 지원	Anthropic Messages 지원 모델을 선택하고 `ANTHROPIC_MODEL`로 전체 ID를 지정합니다
일부 도구 또는 고급 기능 사용 불가	모델 기능 및 게이트웨이 호환성	기본 대화로 먼저 검증하며 고급 기능은 선택한 모델과 현재 어댑터의 실제 결과를 기준으로 합니다

원인을 찾기 어려우면 요청 시각, 모델 ID, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록하고 오류 및 문제 해결을 확인합니다. 전체 API Key를 제출하지 않습니다.

보안 권장 사항

Claude Code 전용 API Key를 생성하여 권한 관리와 자격 증명 비활성화를 쉽게 합니다.
실제 Key를 코드, 저장소, 스크린샷, 로그 또는 공유 스크립트에 기록하지 않습니다.
공유 장치 또는 팀 환경에서는 운영 체제의 자격 증명 관리나 조직의 통합 키 배포 방식을 우선 사용합니다.
API Key 유출이 의심되면 즉시 콘솔에서 비활성화하거나 삭제하고 새 Key를 생성합니다.

다음으로 API Key, Base URL 및 인증과 Anthropic Messages을 읽을 수 있습니다.

이 페이지의 내용