안녕하세요, 개발자 여러분. 오늘은 Claude Code를 SSH 원격 서버에서 사용하는 방법을 처음부터 알려드리겠습니다. 저도 처음에 SSH와 Claude Code 연동할 때了不少 삽질을 했기에, 같은 고민을 하고 계신 분들을 위해 정성껏 정리해봤습니다.

SSH 원격 개발이 무엇인가요?

SSH(Secure Shell) 원격 개발은 내 컴퓨터가 아닌 다른 서버에서 코드를 작성하고 실행하는 방식입니다. 예를 들어:

이러한 상황에서 Claude Code를 사용하면 AI 도움받아 효율적으로 코딩할 수 있습니다.

필수 준비물

1단계: SSH 키 설정하기

SSH 키는 서버에 안전하게 접속하기 위한 전자 열쇠입니다. 공개키와 개인키 한 쌍으로 구성됩니다.

1-1. SSH 키 생성

# 로컬PC에서 SSH 키 생성
ssh-keygen -t ed25519 -C "[email protected]"


저장 위치 묻는 창이 나오면 Enter 치면 기본값 사용


비밀번호 입력창에서 원하는 비밀번호 입력 (선택사항)



생성된 공개키 확인

cat ~/.ssh/id_ed25519.pub

화면에 출력된 문자열(Public Key)을 복사해두세요. ssh-ed25519 AAAAC3...로 시작합니다.

1-2. 서버에 공개키 등록

# 서버에 접속
ssh username@your-server-ip


서버에서 공개키 파일 열기

mkdir -p ~/.ssh
nano ~/.ssh/authorized_keys

nano 에디터가 열리면刚才 복사한 공개키를 붙여넣고 Ctrl+O, Enter, Ctrl+X 순서로 저장합니다.

2단계: HolySheep AI API 설정

Claude Code는 기본적으로 Anthropic 서버에 직접 접속하는데, HolySheep AI를 사용하면:

2-1. HolySheep AI에서 API 키 발급받기

  1. HolySheep AI 가입하기
  2. 대시보드에서 "API Keys" 메뉴 클릭
  3. "Create New Key" 버튼 클릭하여 새 키 생성
  4. 생성된 키를 안전한 곳에 저장 (다시 확인할 수 없습니다)

2-2. 환경변수 설정

# HolySheep AI API 키 내보내기
export ANTHROPIC_API_KEY="YOUR_HOLYSHEEP_API_KEY"


원격 서버에서 영구적으로 설정하려면 bashrc에 추가

echo 'export ANTHROPIC_API_KEY="YOUR_HOLYSHEEP_API_KEY"' >> ~/.bashrc
source ~/.bashrc


설정 확인

echo $ANTHROPIC_API_KEY

3단계: Claude Code 설치하기

3-1. npm으로 설치

# Node.js가 없다면 먼저 설치

Ubuntu/Debian의 경우

sudo apt update && sudo apt install nodejs npm -y


Claude Code 설치

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


설치 확인

claude --version

3-2. Claude Code 기본 설정

# Claude Code 설정 파일 생성
mkdir -p ~/.config/claude
nano ~/.config/claude/settings.json

settings.json 파일에 다음과 같이 입력합니다:

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
  "temperature": 1
}

4단계: HolySheep AI 리버스 프록시 설정

이 부분이 핵심입니다. Claude Code가 HolySheep AI 서버를 Anthropic 서버로 인식하도록 설정해야 합니다.

4-1. Hosts 파일 수정

# 로컬PC에서 hosts 파일 열기

Linux/Mac의 경우

sudo nano /etc/hosts


Windows의 경우 관리자 권한으로 실행


notepad C:\\Windows\\System32\\drivers\\etc\\hosts

파일 맨 아래에 다음 줄을 추가합니다:

# HolySheep AI 리버스 프록시 설정
127.0.0.1 api.anthropic.com
127.0.0.1 auth.anthropic.com
127.0.0.1 api.openai.com
127.0.0.1 api.cohere.ai

4-2. 리버스 프록시 서버 실행

# Nginx 또는 Socat 설치

Ubuntu/Debian

sudo apt install socat -y


리버스 프록시 서버 실행 (터미널 하나를占用)

socat TCP-LISTEN:443,fork,reuseaddr,bind=127.0.0.1 TCP:api.holysheep.ai:443 &


또는 Python으로 간단한 프록시 서버 만들기

cat > ~/proxy_server.py << 'EOF'
import socket
import ssl

def proxy_handler(client_conn, client_addr):
    context = ssl.create_default_context()
    context.check_hostname = False
    context.verify_mode = ssl.CERT_NONE
    
    try:
        server_conn = socket.create_connection(('api.holysheep.ai', 443))
        server_ssl = context.wrap_socket(server_conn, server_hostname='api.holysheep.ai')
        
        while True:
            data = client_conn.recv(4096)
            if not data:
                break
            server_ssl.sendall(data)
            response = server_ssl.recv(4096)
            client_conn.sendall(response)
    except Exception as e:
        print(f"에러 발생: {e}")
    finally:
        client_conn.close()
        server_ssl.close()

server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
server.bind(('127.0.0.1', 443))
server.listen(5)
print("프록시 서버 실행 중... Ctrl+C로 종료")
while True:
    client_conn, client_addr = server.accept()
    import threading
    threading.Thread(target=proxy_handler, args=(client_conn, client_addr)).start()
EOF


서버 실행

python3 ~/proxy_server.py

5단계: SSH 터널링으로 안전하게 접속하기

SSH 터널링은 암호화된 통로를 만들어 안전하게 서버를 利用하는 방법입니다.

# SSH 터널링으로 서버 접속
ssh -L 8443:api.holysheep.ai:443 username@your-server-ip


서버에 접속한 후 새로운 터미널을 열어 Claude Code 실행


SSH 세션 안에서 실행

ssh username@your-server-ip


서버 내부에서 HolySheep API 설정

export ANTHROPIC_API_KEY="YOUR_HOLYSHEEP_API_KEY"
export ANTHROPIC_BASE_URL="https://api.holysheep.ai/v1"


Claude Code 실행

claude

6단계: 실전 예제 - 리모트 서버에서 프로젝트 만들기

이제 실제로 리모트 서버에서 Claude Code를 使用해 봅시다.

# SSH로 서버 접속
ssh username@your-server-ip


프로젝트 디렉토리 만들기

mkdir -p ~/my-project
cd ~/my-project


Claude Code에서 새 프로젝트 시작


아래 명령어를 입력하면 Claude Code가 AI 어시스턴트로 대화형으로 진행됩니다

claude


Claude Code 안에서 다음과 같이 요청할 수 있습니다:


"Python으로 간단한 웹 서버 만들어줘" 또는


"이 디렉토리의 파일들을 정리해주는 스크립트 작성해줘"

7단계: 설정 파일로 자동화하기

매번 설정하기 귀찮다면 스크립트로自動化합시다.

# ~/init-claude.sh 파일 생성
cat > ~/init-claude.sh << 'SCRIPT'
#!/bin/bash

echo "=== Claude Code + HolySheep AI 초기 설정 ==="


HolySheep API 키 입력 받기

read -p "HolySheep AI API 키를 입력하세요: " API_KEY


환경변수 설정

echo "export ANTHROPIC_API_KEY=\"$API_KEY\"" >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.holysheep.ai/v1"' >> ~/.bashrc


Claude Code 설치 확인

if ! command_exists claude; then
    echo "Claude Code 설치 중..."
    npm install -g @anthropic-ai/claude-code
fi


HolySheep AI 서버 연결 테스트

echo ""
echo "=== HolySheep AI 연결 테스트 ==="
curl -s -X POST https://api.holysheep.ai/v1/messages \
    -H "Content-Type: application/json" \
    -H "x-api-key: $API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

echo ""
echo "=== 설정 완료! Claude Code를 시작하세요 ==="
echo "claude 명령어를 입력하여 시작할 수 있습니다."
SCRIPT

chmod +x ~/init-claude.sh
./init-claude.sh

HolySheep AI 요금제 참고

모델가격 ($/MTok)적합한 용도
Claude Sonnet 4.5$15일반적인 코딩, 대화
Claude Opus 4$75복잡한 분석, 긴 코드
GPT-4.1$8빠른 응답 필요 시
Gemini 2.5 Flash$2.50비용 최적화, 대량 작업
DeepSeek V3.2$0.42가장 저렴한 옵션

HolySheep AI는 다양한 모델을 하나의 API 키로管理할 수 있어서 저는 여러 모델을比べる 용도로 자주 利用합니다. 특히 DeepSeek V3.2가 $0.42/MTok로 정말 저렴해서 테스트용으로 활용하기 좋습니다.

자주 발생하는 오류와 해결책

오류 1: "Could not connect to API" 에러

# 문제: Claude Code가 API 서버에 접속할 수 없음

해결: 환경변수와 연결 상태 확인



1단계: API 키 확인

echo $ANTHROPIC_API_KEY


2단계: 키가 비어있다면 다시 설정

export ANTHROPIC_API_KEY="YOUR_HOLYSHEEP_API_KEY"


3단계: 직접 API 연결 테스트

curl -X POST https://api.holysheep.ai/v1/messages \
    -H "Content-Type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{"model":"claude-sonnet-4-20250514","max_tokens":100,"messages":[{"role":"user","content":"test"}]}'


4단계: 응답이 오지 않으면 방화벽 또는 네트워크 확인

ping api.holysheep.ai
telnet api.holysheep.ai 443

오류 2: "Permission denied (publickey)" 에러

# 문제: SSH 서버 접속 시 공개키 인증 실패

해결: 공개키가 서버에 올바르게 등록되었는지 확인



1단계: 로컬PC에서 공개키 확인

cat ~/.ssh/id_ed25519.pub


2단계: 서버에 접속하여 authorized_keys 확인

ssh username@your-server-ip
cat ~/.ssh/authorized_keys


3단계: 공개키가 없다면 추가

cat ~/.ssh/id_ed25519.pub | ssh username@your-server-ip "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"


4단계: SSH 키 권한 확인

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys


5단계: SSH 디렉토리 권한 확인

ls -la ~/.ssh/

오류 3: "SSL certificate verify failed" 에러

# 문제: SSL 인증서 검증 실패

해결: CA 인증서를 업데이트하거나 검증 비활성화



방법 1: CA 인증서 업데이트

sudo apt update && sudo apt install ca-certificates -y
sudo update-ca-certificates


방법 2: Python requests에서 검증 비활성화 (개발용만)


Claude Code 설정에서 환경변수 추가

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt


방법 3: OpenSSL 업데이트

sudo apt install openssl -y


방법 4: HolySheep AI의 인증서가 유효한지 확인

echo | openssl s_client -connect api.holysheep.ai:443 2>&1 | openssl x509 -noout -text | head -20

오류 4: "Rate limit exceeded" 에러

# 문제: API 요청 제한 초과

해결: HolySheep AI 대시보드에서 사용량 확인 및 대기



1단계: 대시보드에서 사용량 확인


https://www.holysheep.ai/dashboard 에서 Usage 확인



2단계: 요청 사이에 딜레이 추가

sleep 2  # 요청 사이에 2초 대기


3단계: 모델을 더 저렴한 것으로 변경


예: Claude Sonnet 4.5 ($15) 대신 DeepSeek V3.2 ($0.42)

export ANTHROPIC_API_KEY="YOUR_HOLYSHEEP_API_KEY"


4단계: HTTP 요청으로 사용량 확인

curl https://api.holysheep.ai/v1/usage \
    -H "x-api-key: $ANTHROPIC_API_KEY"

오류 5: SSH 연결이 너무 느리거나 끊김

# 문제: SSH 연결 지연 또는 자동切断

해결: SSH 설정 최적화



~/.ssh/config 파일 생성 또는 수정

nano ~/.ssh/config


아래 내용 추가

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
    TCPKeepAlive yes
    Compression yes
    ForwardAgent yes


SSH 연결 시 압축 사용

ssh -C username@your-server-ip


연결 유지 데몬 사용 (매우 유용)


~/.bashrc에 추가

echo 'while true; do sleep 60; done' | \
    ssh -o ServerAliveInterval=60 username@your-server-ip "cat > /dev/null" &

마무리

SSH 원격 개발과 Claude Code, HolySheep AI를 함께 使用하면:

처음에는 설정이 복잡해 보이지만, 한 번 설정해두면 이후에는 매우 편리하게 使用할 수 있습니다. 저도 이 설정으로 리모트 개발 생산성이 많이提升되었습니다.

궁금한 점이 있으시면 댓글로 물어보세요. Happy coding!

👉 HolySheep AI 가입하고 무료 크레딧 받기

관련 리소스

관련 문서