설치, 초기화, 프록시 연동, 자주 발생하는 오류 및 전체 배포 경로를 안내합니다.

먼저 공식 문서를 참조하십시오. docs.claude.com

📋 사전 요구 사항 먼저 Node.js 환경 설치를 완료하여 Node.js 18+가 올바르게 설치되었는지 확인하십시오.

⚡ 최초 설치 시 필독: 초기화 오류 건너뛰기

중계 채널을 사용할 때 Claude Code를 처음 실행하면 다음 오류가 발생합니다.

Claude Code를 처음 실행할 때 표시되는 오류 메시지입니다. 검은색 배경에 빨간색과 흰색 글자로 ‘Welcome to Cl…

Welcome to Claude Code
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

Claude Code는 처음 실행할 때 공식 API에 연결하여 초기화를 확인하려 하지만 중계 채널은 이 단계를 통과할 수 없기 때문입니다. 설치를 완료한 뒤 처음 실행하기 전에 다음 방법 중 하나로 이 단계를 건너뛰십시오.

첫 번째 방법: CC-Switch로 건너뛰기(권장)

CC-Switch 다운로드 페이지에서 macOS 또는 Windows용 최신 설치 패키지를 다운로드하십시오. CC-Switch 설정 도구를 열고 설정 → 일반으로 이동한 뒤 ‘Claude Code 최초 설치 확인 건너뛰기’ 옵션을 활성화합니다.

CC-Switch 설정 도구의 설정 페이지 중 ‘일반’ 탭입니다. 여러 설정 옵션 가운데 ‘Claude Code 최초 설치 확인…

두 번째 방법: 설정 파일 수동 수정

사용자 홈 디렉터리에서 ~/.claude.json 파일을 찾아 마지막에 "hasCompletedOnboarding": true 필드를 추가합니다.

⚠️ JSON 형식 주의 필드를 추가하기 전에 이전 필드 끝에 영문 쉼표를 추가해야 합니다. 그렇지 않으면 JSON 형식 오류로 Claude Code를 실행할 수 없습니다.

{
"installMethod": "unknown",
"autoUpdates": true,
"firstStartTime": "2025-07-14T06:11:03.877Z",
"userID": "xxxx",
"projects": {
"/home/your-user": {
"allowedTools": [],
"history": [],
"mcpContextUris": [],
"mcpServers": {},
"enabledMcpjsonServers": [],
"disabledMcpjsonServers": [],
"hasTrustDialogAccepted": false,
"projectOnboardingSeenCount": 0,
"hasClaudeMdExternalIncludesApproved": false,
"hasClaudeMdExternalIncludesWarningShown": false
}
},
"hasCompletedOnboarding": true
}

수정 후 저장하고 claude를 다시 실행하면 정상적으로 사용할 수 있습니다.

참고 출처: Claude Code 초기화 확인 건너뛰기

🚀 CC-Switch를 사용한 빠른 설정(권장)

CC-Switch 빠른 설정 도구를 설치했다면 설정 파일과 환경 변수를 수동으로 편집하지 않고도 그래픽 화면에서 Claude Code 설정을 간편하게 관리할 수 있습니다.

CC-Switch의 장점

직관적이고 사용하기 쉬운 그래픽 인터페이스
서로 다른 제공자 설정을 원클릭으로 전환
환경 변수와 설정 파일 자동 관리
설정 백업 및 복원 지원
터미널을 재시작하지 않고 설정 전환

설정 단계

CC-Switch를 실행하고 Claude Code 설정 추가

CC-Switch 앱에서 새 설정을 추가하는 화면입니다. 위쪽에는 ‘Claude 공급업체’와 ‘통합 공급업체’ 탭이 있으며 현재…

CC-Switch 앱을 엽니다.
위쪽의 ‘Claude’ 탭을 클릭합니다.
오른쪽 위의 주황색 ‘+’ 버튼을 클릭하여 새 설정을 추가합니다.

CC-Switch 앱의 새 설정 추가 화면입니다. ‘API Key’에는 암호화된 값이 표시되고 고객 지원에서 제공한 ‘sk’로 시…

제공자 설정 정보 입력

제공자 이름: 사용자 지정 이름(예: "guizhou")
API Base URL: https://api.llm-token.cn 입력
API Key: 플랫폼에서 발급받은 Claude 전용 토큰 key 붙여넣기
모델 선택: 필요에 따라 사용 가능한 Claude 모델 선택
‘저장’ 버튼 클릭

💡 팁

공식, Guizhou☁️ 등 서로 다른 여러 제공자 설정을 추가할 수 있습니다.
CC-Switch는 ~/.claude/settings.json 설정 파일을 자동으로 수정합니다.
설정을 전환한 뒤 Claude Code를 종료하고 다시 시작하면 적용됩니다.

설정 활성화 및 사용

설정 목록에서 방금 만든 ‘gptagent’ 설정을 찾습니다.
설정 오른쪽의 ‘현재 사용’ 버튼을 클릭하거나 설정 카드를 바로 클릭합니다.
설정이 ‘현재 사용’ 상태로 표시됩니다(녹색 태그).
Claude Code를 재시작하면 새 설정이 적용됩니다.

시스템 트레이에서 빠르게 전환

CC-Switch는 시스템 트레이를 통한 빠른 설정 전환을 지원합니다.

시스템 트레이의 CC-Switch 아이콘을 마우스 오른쪽 버튼으로 클릭합니다.
메뉴에서 Claude 분류를 선택합니다.
전환할 설정을 바로 선택합니다.
기본 화면을 열지 않아도 설정이 즉시 적용됩니다.

⚠️ 주의 사항

설정을 전환한 뒤 Claude Code를 재시작해야 적용됩니다.
CC-Switch에서 API 엔드포인트 속도를 테스트하여 가장 적합한 설정을 선택할 수 있습니다.

설정 후 채팅할 수 없나요?

다음 방법을 시도하고, 그래도 해결되지 않으면 고객 지원에 문의하십시오.

CC Switch 화면입니다. 위쪽에 ‘CC Switch’ 제목과 여러 아이콘이 있습니다. 왼쪽의 ‘Guizhou 클라우드 컴퓨팅…

CC Switch 설정 화면의 ‘프록시’ 탭입니다. ‘로컬 프록시’ 상태는 ‘실행 중’이며 파란색 화살표가 해당 상태를 가리킵니다…

Claude Code 배포 가이드 설정 페이지의 ‘코드’ 탭입니다. 위쪽에는 ‘홈으로 돌아가기’, ‘정보’ 등의 옵션이 있습니다.…

⌨️ 수동 명령줄 설정

CC-Switch를 사용하지 않는 경우 명령줄을 통해 Claude Code를 수동으로 설정할 수도 있습니다.

🖥️ Windows 플랫폼

시스템 요구 사항

Windows 10, 11

설치 단계

첫 번째 방법: Native Install(권장)

PowerShell 사용:

irm https://claude.ai/install.ps1 | iex

CMD 사용:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

두 번째 방법: NPM 설치(권장하지 않음)

⚠️ npm 설치는 권장하지 않음 npm 채널은 업데이트가 늦고 설치되는 버전이 대체로 오래되므로 위의 Native 방식을 우선 사용하십시오.

npm install -g @anthropic-ai/claude-code

설치 검증:

claude --version

환경 변수 설정

PowerShell을 사용하는 경우:

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.llm-token.cn", "User")

CMD를 사용하는 경우:

setx ANTHROPIC_AUTH_TOKEN "sk-xxx"
setx ANTHROPIC_BASE_URL "https://api.llm-token.cn"

💡 팁 sk-xxx를 본인의 전용 key로 교체하십시오. 설정 후 환경 변수가 적용되도록 터미널을 재시작합니다.

Claude 실행

터미널에서 프로젝트 디렉터리로 이동(cd 디렉터리)하거나 임의의 디렉터리에서 claude 명령을 입력하여 실행합니다.

🍏 macOS 플랫폼

시스템 요구 사항

MacOS 10.15 (Catalina) 이상

설치 단계

첫 번째 방법: Homebrew(권장)

brew install --cask claude-code

두 번째 방법: Curl Script

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

세 번째 방법: NPM 설치(권장하지 않음)

⚠️ npm 설치는 권장하지 않음 npm 채널은 업데이트가 늦고 설치되는 버전이 대체로 오래되므로 위의 Native 방식을 우선 사용하십시오.

npm install -g @anthropic-ai/claude-code

설치 검증

claude -v

정상적인 경우 다음과 비슷하게 출력됩니다: 1.0.108 (Claude Code)

환경 변수 설정

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.zshrc
source ~/.zshrc

💡 팁 sk-xxx를 본인의 전용 key로 교체하십시오.

터미널 재시작 및 Claude 실행

터미널을 재시작한 뒤 프로젝트 디렉터리로 이동(cd 디렉터리)하거나 임의의 디렉터리에서 claude 명령을 입력하여 실행합니다.

🐧 Linux 플랫폼

시스템 요구 사항

Linux 배포판(Ubuntu 18.04+, CentOS 7+, Debian 9+ 등)

설치 단계

첫 번째 방법: Curl Script(권장)

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

두 번째 방법: NPM 설치(권장하지 않음)

⚠️ npm 설치는 권장하지 않음 npm 채널은 업데이트가 늦고 설치되는 버전이 대체로 오래되므로 위의 Native 방식을 우선 사용하십시오.

npm install -g @anthropic-ai/claude-code

설치 검증

claude -v

환경 변수 설정

Ubuntu/Debian(Bash)

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.bashrc
source ~/.bashrc

Fedora/CentOS(Zsh)

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.llm-token.cn"' >> ~/.zshrc
source ~/.zshrc

💡 팁 sk-xxx를 본인의 전용 key로 교체하십시오.

터미널 재시작 및 Claude 실행

터미널을 재시작한 뒤 프로젝트 디렉터리로 이동(cd 디렉터리)하거나 임의의 디렉터리에서 claude 명령을 입력하여 실행합니다.

Your privacy choices

Claude Code 배포 가이드

⚡ 최초 설치 시 필독: 초기화 오류 건너뛰기

첫 번째 방법: CC-Switch로 건너뛰기(권장)

두 번째 방법: 설정 파일 수동 수정

🚀 CC-Switch를 사용한 빠른 설정(권장)

CC-Switch의 장점

설정 단계

설정 후 채팅할 수 없나요?

⌨️ 수동 명령줄 설정

🖥️ Windows 플랫폼

시스템 요구 사항

설치 단계

환경 변수 설정

🍏 macOS 플랫폼

시스템 요구 사항

설치 단계

설치 검증

환경 변수 설정

터미널 재시작 및 Claude 실행

🐧 Linux 플랫폼

시스템 요구 사항

설치 단계

설치 검증

환경 변수 설정

터미널 재시작 및 Claude 실행

자주 발생하는 문제

명령을 찾을 수 없다고 표시되나요?

연결에 실패했나요?

이 페이지의 섹션