WSL 또는 Linux에 Claude Code를 설치하고, DeepSeek의 Anthropic 호환 엔드포인트를 통해 라우팅하며, 연결을 확인하고, 일반적인 401, 403, 404 오류를 해결하는 방법을 알아보세요. 이 실용적인 가이드는 npm 설치...

WSL/Linux에서 DeepSeek으로 Claude Code 사용하기: 설치, 구성, 테스트 및 일반적인 오류 해결

DeepSeek와 함께 사용하는 Claude Code 표지

이것이 원본 튜토리얼의 핵심이며, 솔직히 많은 개발자가 계속 마주치는 정확한 문제를 해결합니다. Claude Code는 정상적으로 설치되지만, 실제 첫 세션은 지역 접근, 엔드포인트 라우팅 또는 모델 구성 때문에 실패하는 문제입니다.

그러니 이것을 막연한 “AI 코딩 도구 개요”로 만들기보다는 실용적으로 진행하겠습니다. 우리는 네 가지를 할 것입니다.

WSL 또는 Linux에 Claude Code 설치하기
DeepSeek을 통해 라우팅하기

CLI 디버깅에 시간을 낭비하기 전에 엔드포인트 테스트하기

처음에 자주 나타나는 일반적인 오류 수정하기

Claude Code와 DeepSeek 설정 흐름

이 설정이 중요한 이유

표면적으로 Claude Code는 또 하나의 터미널 기반 코딩 어시스턴트일 뿐입니다. 실제로 유용한 이유는 단순히 코드를 조금 아는 채팅창처럼 동작하는 것이 아니라, 저장소를 읽고, 명령을 실행하고, 파일을 검사하며, 실제 개발 워크플로 안에 머무를 수 있기 때문입니다.

마찰은 연결성 문제가 시작될 때 발생합니다.

제한된 네트워크 환경에서 작업하는 개발자에게 공식 기본 경로는 실제 장애물이 될 수 있습니다. 그래서 DeepSeek 방식이 매력적입니다. Claude Code 워크플로는 유지하면서, 백엔드 경로만 DeepSeek이 제공하는 Anthropic 호환 엔드포인트로 바꾸는 것입니다.

또한 여기서 이 가이드는 무작위로 “이 명령어들을 복사하세요”라고 하는 글보다 더 유용해집니다. 겉으로는 올바르게 보이는 설정과 실제로 작동하는 설정의 차이는 보통 다음에 달려 있습니다.

어떤 환경 변수를 설정하는지
어디에 영구 저장하는지
어떤 모델 이름을 사용하는지
claude를 실행하기 전에 엔드포인트를 테스트하는지

1단계: WSL 또는 Linux에 Claude Code 설치하기

원문 글은 npm 기반 설치 경로를 사용하며, WSL 또는 Linux에서 이미 Node가 준비되어 있다면 여전히 잘 작동합니다.

네트워크가 불안정하다면 먼저 공식 npm 레지스트리로 전환하고, Claude Code를 전역으로 설치한 다음, 이후 평소 사용하는 미러로 다시 전환하세요.

# 공식 npm 레지스트리로 전환

npm config set registry https://registry.npmjs.org

# Claude Code를 전역으로 설치

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

# 선호하는 미러로 다시 전환

npm config set registry https://registry.npmmirror.com

네트워크가 괜찮다면 짧은 버전만으로 충분합니다.

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

그런 다음 설치를 확인하세요.

claude --version

버전 번호가 표시되면 CLI 자체는 올바르게 설치된 것입니다. 이것이 모델 엔드포인트까지 준비되었다는 뜻은 아니지만, 로컬 설치 단계는 완료되었다는 의미입니다.

공식 설치 경로에 대한 간단한 참고

Anthropic의 현재 문서에서는 macOS, Linux, WSL용 네이티브 설치 프로그램도 권장합니다.

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

오늘날에는 이것이 더 “공식적인” 경로이지만, WSL 안에서 이미 Node 기반 도구를 사용하는 개발자에게는 npm 경로도 여전히 충분히 합리적이며, 원문 글의 워크플로와도 깔끔하게 맞아떨어집니다.

2단계: Claude 설정 디렉터리 준비하기

원문 게시물은 매우 현실적인 불편함을 지적합니다. 때로는 Claude Code의 로컬 설정을 편집하려고 할 때 곧바로 권한 문제에 부딪힙니다.

vim이나 다른 편집기가 ~/.claude에 쓸 수 없다면, 먼저 소유권과 권한을 수정하세요.

mkdir -p ~/.claude

chown -R "$USER":"$USER" ~/.claude

chmod -R 755 ~/.claude

화려한 작업은 아니지만 시간을 절약해 줍니다. 놀랄 만큼 많은 “Claude Code 설정 문제”가 실제로는 파일 권한 문제입니다.

3단계: Claude Code가 DeepSeek을 가리키도록 설정하기

이를 수행하는 합리적인 방법은 두 가지입니다.

임시 셸 환경 변수
영구적인 ~/.claude/settings.json

원문 글은 두 번째 방식을 사용하며, 반복 사용을 생각하면 저는 이것이 더 나은 일상적인 설정이라고 생각합니다.

설정 파일을 여세요.

vim ~/.claude/settings.json

그런 다음 다음과 같은 최소 동작 설정을 붙여 넣으세요.

{

"env": {

"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",

"ANTHROPIC_AUTH_TOKEN": "your-deepseek-api-key",

"ANTHROPIC_MODEL": "deepseek-v4-flash",

"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-flash"

}

이는 원본 가이드의 취지를 잘 반영합니다. 간단하고, 영구적이며, 바로 시작하기에 충분한 설정입니다.

실제로 어떤 모델을 사용해야 할까요?

간단한 원칙은 다음과 같습니다:

비용을 낮추고 일상적인 코딩을 더 빠르게 하고 싶다면 deepseek-v4-flash를 사용하세요
더 강력한 추론과 무거운 장문 컨텍스트 작업이 필요하다면 deepseek-v4-pro[1m]을 사용하세요

첫 설정을 성공시키는 것이 목표라면 Flash로 시작하세요. 파이프라인이 안정되면 더 어려운 작업에는 Pro로 이동할 수 있습니다.

4단계: Claude Code를 실행하기 전에 엔드포인트 테스트하기

이 단계는 이론적으로는 선택 사항이지만, 실제로는 추측하느라 시간을 낭비하지 않게 해줍니다.

CLI를 실행하기 전에 DeepSeek의 Anthropic 호환 엔드포인트를 직접 호출해 보세요:

curl -X POST https://api.deepseek.com/anthropic/v1/messages \

-H "Content-Type: application/json" \

-H "Authorization: Bearer your-deepseek-api-key" \

-d '{

"model": "deepseek-v4-flash",

"max_tokens": 10,

"messages": [

{

"role": "user",

"content": "test"

}

]

정상적인 JSON 응답을 받았다면 엔드포인트와 키가 정상적으로 작동 중이라는 뜻입니다.

이것이 중요한 이유는 두 가지 실패 유형을 분리해 주기 때문입니다:

API 라우팅 문제
Claude Code CLI 문제

curl 테스트부터 실패한다면 CLI를 탓하느라 시간을 낭비하지 마세요.

5단계: Claude Code 실행하기

설치와 엔드포인트 테스트가 모두 통과하면 Claude Code를 평소처럼 시작하세요:

claude

그 시점부터 CLI 측면의 경험은 대체로 평소와 비슷하게 느껴질 것입니다. 주요 차이는 단지 모델 트래픽이 이제 DeepSeek의 Anthropic 호환 인터페이스를 통해 라우팅된다는 점입니다.

가장 자주 보게 될 오류들

대부분의 “설정 튜토리얼”은 여기서 너무 예의를 차리다가 쓸모가 없어지므로, 솔직하게 말해보겠습니다.

1. E212: 쓰기용 파일을 열 수 없음

이는 보통 Claude 문제가 아닙니다. 파일시스템 권한 문제입니다.

해결 방법:

mkdir -p ~/.claude

chown -R "$USER":"$USER" ~/.claude

chmod -R 755 ~/.claude

2. Anthropic 서비스에 연결할 수 없음 또는 403 Forbidden

이는 보통 Claude Code가 여전히 기본 경로를 호출하려고 하거나, 엔드포인트 구성이 잘못되었다는 뜻입니다.

다음을 확인하세요:

ANTHROPIC_BASE_URL이 정확히 `https：//api.deepseek.com/anthropic`인지

구성 파일이 유효한 JSON인지
실수로 파일을 잘못된 경로에 저장하지 않았는지

3. 401 Unauthorized

이는 거의 항상 다음 중 하나입니다:

API 키가 잘못됨
키를 복사할 때 불필요한 공백이나 따옴표가 포함됨
DeepSeek 계정에 결제 또는 잔액 문제가 있음

이 문제를 너무 복잡하게 생각하지 마세요. 401은 보통 모델 문제가 아니라 키 문제입니다.

4. 404 Not Found

이는 흔히 모델 이름 실수 또는 경로 실수입니다.

먼저 다음을 확인하세요:

엔드포인트 경로：https://api.deepseek.com/anthropic

테스트용 요청 경로：/v1/messages

모델 문자열：deepseek-v4-flash 또는 deepseek-v4-pro[1m]

오래되었거나 잘못된 형식의 모델 이름을 입력했다면, 다른 모든 것이 올바르더라도 요청이 실패할 수 있습니다.

이 설정을 이해하는 더 나은 사고방식

이 설정을 이해하는 가장 유용한 방식은 “내가 Claude Code를 해킹하고 있다”라고 생각하는 것이 아닙니다.

오히려 다음에 가깝습니다:

Claude Code는 프런트엔드 워크플로이고, DeepSeek은 백엔드 모델 경로입니다.

이렇게 보면 설정을 디버깅하기가 더 쉬워집니다:

claude --version이 실패하면 설치 문제입니다
curl 테스트가 실패하면 API 경로 또는 인증 문제입니다
둘 다 성공했지만 세션이 여전히 깨진다면 Claude 측 구성 문제입니다

이런 분리만으로도 불필요한 시행착오를 많이 줄일 수 있습니다.

이전 튜토리얼 이후 달라진 점

생태계가 계속 움직이고 있기 때문에 이 점은 짚고 넘어갈 가치가 있습니다.

원래 튜토리얼은 최소 작동 설정에 초점을 맞추고 settings.json과 deepseek-v4-flash를 사용하며, 이는 여전히 유용합니다. 하지만 최신 공식 문서는 전체 그림을 더 명확하게 해주는 몇 가지 세부 사항을 추가했습니다:

Claude Code는 이제 Anthropic 문서에 공식 네이티브 설치 프로그램이 있습니다
DeepSeek에는 명확한 Claude Code 통합 가이드가 있습니다
DeepSeek는 Claude 스타일 모델 계열에 대한 모델 매핑을 문서화합니다
권장되는 전체 환경 변수 세트는 이전 커뮤니티 스니펫보다 더 광범위합니다

따라서 자신의 설정 노트를 다시 작성하고 있다면, 한 번 작동했던 첫 번째 구성에 가이드를 고정하지 마세요. 구조는 유지하되 세부 사항은 업데이트하세요.

We0 AI가 적합한 지점

Claude Code, DeepSeek, WSL, 터미널 우선 워크플로와 같은 도구로 구축하고 있다면, 설정 직후 보통 두 번째 문제가 나타납니다:

무언가를 만들 수는 있지만, 웹사이트가 여전히 그것을 충분히 명확하게 설명하지 못해 적합한 사용자를 끌어들이지 못한다는 점입니다.

바로 이것이 We0 AI가 만들어진 영역입니다.

We0 AI는 창업자, 크리에이터, 컨설턴트, 에이전시, 기술 팀이 제품이 무엇을 하는지 설명하고, 검색에서 노출되며, 호기심을 리드로 전환하는 쇼케이스 웹사이트를 구축하도록 돕습니다. 다시 말해, 단순히 “페이지를 온라인에 올리는” 것이 아니라 제품을 실제로 이해 가능하고 발견 가능하게 만드는 것입니다.

따라서 스택은 점점 더 정교해지고 있지만 배포가 여전히 혼란스럽다면, 그것이 다음으로 해결해야 할 병목 지점입니다.