이 가이드는 완전 처음인 분을 대상으로 씁니다. "터미널"이 뭔지 몰라도 됩니다. 클로드 코드는 여러분 대신 코드 짜주고 파일 만들어주고 브라우저도 뒤져주는 AI인데, 지금은 그걸 여러분 컴퓨터에 붙이는 작업만 하면 돼요.
스텝은 14개. 하나씩 따라 하고, 잘 안 되면 Claude한테 물어보면 됩니다. 이 가이드도 그렇게 끝나요.
01
VS Code 설치
VS Code는 프로그래머용 텍스트 편집기예요. 이걸 Claude가 사는 집이라고 생각하면 편합니다.
브라우저(엣지-크롬)에서 code.visualstudio.com으로 들어가세요.
가운데 큰 Download 버튼이 보입니다. 자동으로 여러분 OS를 인식해서 Windows용을 줍니다. 만약 안 잡히면 버튼 옆 other platforms 눌러서 Windows x64 User Installer 받으세요.
받은 .exe 파일 더블클릭 → 라이선스 동의 → 다음, 다음, 설치. 중간에 나오는 옵션은 다 기본값으로 두면 돼요.
설치 끝나면 Visual Studio Code 시작 체크하고 마침.
이 화면이 뜨면 맞습니다. 큰 검정 버튼 누르면 됩니다.
tip
설치 중 "PATH에 추가"라는 체크박스가 나오면 반드시 체크하세요. 나중에 터미널에서 code . 같은 명령이 작동해야 하는데, 이거 안 하면 안 됩니다.
02
Claude Code 확장 설치
VS Code를 열면 왼쪽에 세로 아이콘 바가 있어요. 그중 네모 네 개(하나가 삐져나온 모양) 아이콘이 확장(Extensions)입니다.
확장 아이콘 클릭.
위쪽 검색창에 claude code 입력.
맨 위에 Anthropic이 만든 Claude Code for VS Code가 나옵니다. 아이콘은 주황색 별 모양.
초록색 Install 버튼 클릭. 몇 초 걸립니다.
확장 페이지에서 보이는 게 이 화면과 같은지 확인. Anthropic 표시 + 주황색 별 아이콘.
주의
짝퉁 확장이 있을 수 있어요. 반드시 제작자가 "Anthropic"인 걸 확인하세요. 파란색 체크 마크가 있으면 인증된 겁니다.
웹 Marketplace에서 이 화면이 뜨면 정상. 제작자 Anthropic - 파란 체크 - 초록 Install 버튼.
03
확장 활성화 - 로그인
설치가 끝나면 VS Code 오른쪽 위에 주황색 Claude 별 아이콘이 하나 생겨요. 이걸 눌러야 채팅창이 열립니다.
우측 상단 - 주황색 별 모양 아이콘. 이걸 눌러 Claude Code 패널을 엽니다.
주황색 별이 안 보일 때 - 확장이 활성화 안 됐을 가능성 높음. 아래 순서로 확인하세요.
확장 상태 확인 - 활성화 방법
왼쪽 세로 아이콘 바 아래쪽의 네모 네 개 (하나 삐져나온 모양) 아이콘 클릭 = 확장(Extensions).
상단 Installed 탭에서 Claude Code 찾기.
이름 옆의 버튼 상태를 확인:
Install 버튼이 보임 → 아직 설치 안 됨. 스텝 2로 돌아가서 설치.
Enable 버튼이 보임 → 비활성 상태. Enable 클릭하면 켜집니다.
Disable - Uninstall 버튼이 보임 → 이미 활성화됨 (Disable을 누르지 마세요. 그건 끄는 버튼).
Enable 눌렀거나 이미 활성 상태면 VS Code 오른쪽 위 별 아이콘이 나타납니다.
확장 페이지에서 이 화면이 뜨면 정상 활성화. Anthropic - 25,058,346 installs - Free 표시.
"이 폴더를 신뢰합니까?" 나오면
VS Code에서 폴더 열 때마다 처음이면 이 창이 뜹니다. Trust the authors of the files in this folder (또는 한국어 "이 폴더의 작성자를 신뢰합니다") 눌러주세요. 신뢰 안 하면 Claude가 해당 폴더에서 작업 못 합니다. 본인이 만든 폴더면 무조건 Trust.
로그인 - 첫 실행 시
주황 별 아이콘 클릭 → 채팅창 열림.
VS Code 오른쪽 아래 알림이 뜨면 Sign in with Claude 클릭.
브라우저에서 anthropic 로그인 페이지가 열립니다. Claude 계정으로 로그인하세요. (없으면 claude.ai에서 무료 계정 먼저 만드세요.)
페이지에 "Return to VS Code" 버튼 나오면 클릭. VS Code로 자동 복귀.
다시 VS Code에서 연결됨 알림 뜨면 완료.
돈 얘기 - 요금제Pro 요금제(월 20달러)부터 실사용 가능합니다. 무료 계정은 하루 몇 번 못 써요.
처음부터 비싼 걸 쓸 필요는 없습니다. 매일 쓰는 게 아니면 Pro로 시작하세요. 써보다가 사용량이 부족하면 구독 요금제를 올리면 됩니다 (Pro → Max). 사용한 만큼 추가 결제(pay-as-you-go)도 가능하지만 비싸요. 매일 쓸 정도면 상위 구독이 훨씬 효율적.
그리고 Pro 안에서 Fable 5.1로 전환해서 사용량을 한 번 다 써보는 걸 추천합니다. Fable은 Opus보다 더 똑똑한 모델인데, Pro 사용량 한도 안에서 이 놈으로 한 번 꽉 채워보는 것이 이 도구를 이해하는 가장 빠른 길입니다.
사용량은 5시간 뒤에 다시 채워집니다. 예를 들어 오후 2시에 첫 메시지 → 오후 7시 세션 종료 → 새로 시작. "첫 메시지 던진 순간부터 5시간"이 기준이라 한국시간·미국시간 구분 없이 여러분 시각으로 세면 됩니다. 그러니 한도 다 써도 몇 시간만 기다리면 다시 쓸 수 있어요. 그렇게 한두 번 돌려보고, 이 도구로 얼마나 일이 되는지 감이 오면 요금제를 올릴지 말지 판단하면 됩니다.
⚠️ 참고: Pro 이상 유료 요금제엔 주간 상한도 있어요. 5시간 리셋 위에 주당 총량 한도가 추가로 걸립니다. 매일 밤낮으로 쓰지만 않으면 개인 사용에 문제 없습니다.
04
폴더 열기 - 프로젝트 시작
Claude는 폴더 단위로 일합니다. 그러니까 먼저 "무슨 작업을 할 폴더인지"를 정해서 열어줘야 해요.
VS Code 상단 메뉴 → 파일(File) → 폴더 열기(Open Folder).
탐색기가 열리면, 바탕화면에 새 폴더 하나 만드세요. 이름은 아무거나 (내프로젝트, test, bumdongsan 등). 한글도 됩니다.
그 폴더 선택 → 폴더 선택 클릭.
처음이면 "이 폴더 만든 사람 믿나요?" 창이 나옵니다. 예(Yes, I trust).
왜?
Claude는 이 폴더 안의 파일만 봅니다. 폴더를 안 열면 아무것도 못 해요. 예를 들어 부동산 분석을 하려면 부동산용 폴더를 하나 만들고 거기서 계속 작업하면 됩니다.
05
Claude Code 실행
이제 진짜 대화창을 엽니다. 두 가지 방법 중 아무거나 됩니다.
방법 A - 사이드바에서 열기
VS Code 왼쪽 아이콘 바에서 주황색 별 아이콘(Claude)을 클릭.
오른쪽에 채팅창이 열립니다.
방법 B - 단축키
키보드 Ctrl + Esc - 채팅창이 바로 열립니다.
채팅창이 열리면 아래쪽 입력창에 그냥 한국어로 말 걸어보세요.
안녕, 이 폴더에 지금 뭐가 있는지 봐줘.
답이 오면 성공. 이제 여기가 여러분 새 작업실입니다.
실제 사용 화면 - 탐색기(왼쪽) - 편집기(가운데) - Claude Code(오른쪽) 3분할.
과거 대화 다시 보기 - 상단 시계 아이콘
Claude Code 패널 우측 상단에 시계 모양(⏱) 아이콘이 있어요. 이걸 누르면 지금까지 이야기했던 모든 세션이 목록으로 뜹니다.
Local 탭 - 이 PC에서 만들었던 세션들
Web 탭 - 웹(claude.ai)에서 이어받은 세션들
세션 이름을 검색해서 빠르게 찾을 수도 있음
세션 클릭하면 그때 나눈 대화가 그대로 복원돼 - 이어서 지시 가능
시계 아이콘(우측 상단 두 번째) 클릭 - Local/Web 탭 - 이전 세션 목록.
왜 유용한가 - 어제 하다 만 작업을 오늘 이어받거나, "그때 그거 어떻게 했지?" 다시 확인할 때 씁니다. 세션은 절대 자동으로 사라지지 않아요. 필요하면 버려두고 새 세션(+ 아이콘)으로 시작해도 되고.
06
/model - 지금 어떤 모델인지 확인 + 변경
Claude에는 여러 모델이 있어요. 지금 어떤 놈이 대답하는지 확인하고, 필요하면 바꿀 수 있습니다.
채팅창 입력줄에 /model 을 치고 엔터. (슬래시로 시작하는 건 "명령어" 입니다.)
/model
Current model: Sonnet 5
모델을 바꾸려면 /switch-model 을 칩니다. 목록이 나오고 ↑↓ 화살표로 골라서 엔터.
/switch-model
○ Haiku 4.5 - 빠름 - 저렴 - 짧은 답
○ Sonnet 5 - 균형 - 무난 (기본값)
● Opus 5 - 똑똑함 - 실제로 쓸만함
○ Fable 5.1 - 최상급 - 실험적 - 더 똑똑함
모델 4개 설명 - 짧게
이름
언제 씀
특징
Haiku 4.5
간단한 질문, 빠른 검색
제일 싸고 빠름. 복잡한 코딩엔 부족.
Sonnet 5
기본값
무난. 근데 답답할 수 있음. 조금만 복잡해도 놓치고 헛다리 짚음.
Opus 5
실작업 대부분
실제로 쓸만한 최소 기준. 여러 파일 수정-리서치-복잡한 지시가 가능.
Fable 5.1
어려운 문제, 긴 리서치, 체험용
가장 똑똑함. Opus보다 한 단계 위. 반드시 한 번 써봐야 감이 옵니다.
현실적 조언바로 Opus로 바꾸세요. Sonnet은 답답할 수 있어요 - 지시를 두세 번 반복해야 하고, 놓치는 게 많습니다. Opus부터 "어, 이거 진짜 쓸만하네" 라는 감이 옵니다.
그리고 Fable 5.1은 꼭 한 번 체험해보세요. Opus보다 더 똑똑합니다. 프로 요금제(20불짜리) 사용량 안에서 한번 다 써보는 걸 추천드립니다.첫 메시지 던진 순간부터 5시간이 지나면 다시 세션이 시작되니 한 달 동안 못 쓰는 게 아닙니다."이 정도까지 되는구나" 라는 생각을 할 수 있어요.
저는 기획은 Fable, 코딩은 Opus로 쓰긴 하지만, 요즘은 그냥 Fable로 쓰고 있습니다.
07
사용량 확인
얼마나 쓰고 있는지 궁금하면:
/status
현재 로그인 계정, 지금 모델, 이번 5시간 창의 사용률, 리셋까지 남은 시간이 다 나옵니다.
쿼터 구조
Claude 요금제는 롤링 5시간 세션으로 한도가 관리됩니다. 첫 메시지 던진 순간부터 정확히 5시간 뒤에 세션이 종료되고, 다음 메시지부터 새 세션이 시작돼요. 예: 오후 2시 첫 메시지 → 오후 7시 세션 종료 → 새로 시작. 한국시간·미국시간 구분 없이 여러분 시각으로 세면 됩니다. 한도 다 쓰면 세션 종료까지 못 씁니다.
Pro 이상 유료 요금제엔 주간 상한도 있어요. 5시간 리셋 위에 주당 총량 한도가 추가로 걸립니다.
더 자세한 사용량 (달 단위)는 브라우저에서 claude.ai/settings/usage로 가면 됩니다.
08
권한 - 자동모드 - Opus로 전환
Claude가 파일 만들 때마다, 명령어 실행할 때마다 "허락해줘" 물어봅니다. 이거 매번 답하기 귀찮으면 자동모드(auto)로 바꾸세요.
채팅창 우측 하단에 조그맣게 아이콘 두 개가 있어요.
왼쪽 아이콘 - 현재 모델 (여기서도 클릭해서 Opus로 바꿀 수 있음).
오른쪽 아이콘 - 권한 모드. 클릭하면 3단 선택:
default - 위험한 것만 물어봄. 기본.
plan - 계획만 세우고 실제 실행은 안 함. 미리보기용.
auto - 다 알아서. 안 물어봄. 가장 편함. 대신 감시는 해야 함.
모드 변경 단축키는 Shift + Tab 두 번. 한번 누르면 plan, 또 누르면 auto, 또 누르면 default로 돌아옵니다.
주의auto모드는 Claude가 파일도 지우고, 인터넷도 뒤지고, 브라우저도 열어요. 안 좋은 걸 시키면 안 좋은 결과가 나옵니다. 그래도 일상적 작업엔 auto가 압도적으로 편함. 이상하다 싶으면 ESC 눌러서 멈출 수 있습니다.
모델은 여기서 바로 Opus로 바꿔두면 좋아요. 복잡한 부동산 리서치 같은 건 Opus가 훨씬 낫습니다.
09
다른 기기에서 이어 쓰기 (데탑앱 - 폰)
PC에서 세션 하나 켜두면, 같은 대화를 데스크톱 앱이나 휴대폰 앱에서 이어받을 수 있습니다. 지하철에서 Claude한테 지시 내리는 게 가능해요.
준비 1 - Claude 앱 설치
브라우저 claude.ai/download 접속.
Windows용 데스크톱 앱 받아서 설치. Claude 계정으로 로그인.
휴대폰은 앱스토어/플레이스토어에서 Claude 검색 후 설치.
claude.ai/download 페이지. 데스크톱 앱 + 모바일 링크가 다 있습니다.
준비 2 - Claude 데스크탑 앱에서 새 Code 세션 시작
원격 연동은 Claude 데스크탑 앱의 Code 탭에서 시작합니다. VS Code에서 뭘 켜둘 필요 없어요.
Claude 데스크탑 앱 실행 → 상단의 Code 아이콘(</>) 클릭.
좌측 사이드바에서 「새로 생성」 클릭.
입력창 위 「로컬」 옆의 폴더 이름 클릭.
드롭다운에서 「폴더 열기…」 선택. (+는 폴더 추가용)
데스크탑 앱 Code 탭 - 좌측 새로 생성 - 입력창 위 로컬 옆 폴더 이름 클릭.
준비 3 - 작업 폴더 지정
파일 탐색기가 열립니다. 이번 작업에 쓸 폴더를 고르세요.
새 폴더가 필요하면 「새로운 폴더」로 만들면 됩니다.
원하는 폴더 안에 들어온 뒤 「열기」 클릭.
Finder/탐색기 창에서 작업할 폴더 하나 선택 후 열기. 없으면 새로운 폴더로 만들어도 OK.
준비 4 - 첫 요청 보내기
선택한 폴더 이름이 입력창 위에 보이는지 확인.
입력창에 하고 싶은 작업을 한국어로 그냥 적어서 보내면 됩니다.
이 폴더 안에 README.md 파일 하나를 만들어줘.
제목: 데스크탑 첫 프로젝트
본문: 이 폴더에서 자료와 결과물을 관리합니다.
폴더 이름 확인 → 요청 입력 → 전송. Claude가 PC에서 실제로 파일을 만듭니다.
준비 5 - 결과 확인 - 이어서 작업
왼쪽 사이드바에 새 프로젝트와 세션이 생깁니다.
대화창에서 방금 만든 파일(README.md 등) 생성 결과를 확인.
같은 폴더에서 수정-추가 요청을 이어서 보내면 됩니다. 휴대폰에서도 같은 세션이 그대로 이어져요.
왼쪽 - 새 프로젝트와 세션 생성 확인. 대화창에서 파일 결과-상세 내역 확인.
폰에서 이어받기
같은 계정으로 휴대폰 Claude 앱에 로그인해두면, 방금 만든 세션이 폰 Code 탭 목록에 자동으로 뜹니다. 폰에서 세션 탭하고 메시지 던지면 PC의 Claude가 받아서 실행 → 결과를 폰으로 답장. PC가 계속 켜져 있어야 이 흐름이 작동합니다.
이게 되려면PC가 계속 켜져 있어야 합니다. Claude Code는 여러분 PC에서 실제로 파일을 만들고 명령을 실행해요. PC 꺼지면 앱에서 아무리 명령해도 실행할 몸이 없어요.
작업 중엔 PC 절전모드도 끄세요. 설정 → 시스템 → 전원 → 화면 끄기 안 함, 절전 안 함. 리모컨처럼 쓰려면 24시간 켜두는 게 정석입니다.
10
국토부 실거래 API 키 신청
부동산 데이터 다루려면 국토부 실거래가 API가 필수. 무료입니다. 신청하면 승인 받는 구조이고, 몇 시간 정도 걸립니다.
이거 왜 해야 하나 - 미리 알려드리면API가 첫 세팅은 오래 걸릴 수 있지만, 세팅해두면 무궁무진하게 활용하실 수 있습니다! 평상시 부동산 전문 분석 유튜버가 해주는 그런 모든 자료들을 만들 수 있고, 지도에도 표시할 수 있어요. 시세 추이 그래프, 지역별 히트맵, 매매/전세 비교, 신축/구축 필터링, 지도 위 필지 표시 - 한 번 세팅해두면 여러분이 원하는 방식으로 무한히 뽑아 쓸 수 있습니다.
브라우저에서 data.go.kr 접속.
우측 상단 회원가입 → 개인 회원 → 이름-이메일 등록.
상단 검색창에 국토교통부 실거래가 입력.
결과 목록에서 원하는 부동산 종류별 실거래 자료 클릭 → 오픈API 탭.
우측 활용 신청 버튼 클릭.
data.go.kr 첫 화면. 여기서 검색으로 진입합니다.
부동산 종류별로 따로 신청 - 링크
실거래 API는 부동산 종류마다 별개입니다. 아래는 각 API 신청 페이지 직접 링크. 클릭 → 로그인 → 우측 활용신청. 처음 클릭 시 로그인 창이 뜨면 공공데이터포털 계정으로 로그인.
권장
처음이면 필요한 2~3개만 우선 신청하세요. 나중에 필요하면 추가 신청. 한 계정으로 여러 API를 다 받을 수 있고, 키는 모두 동일한 인증키 한 세트로 통일됩니다. 즉 승인만 각각 받으면 되고, 실제 호출 때는 같은 키로 다 됩니다.
참고
링크가 만약 바뀌었으면 data.go.kr에서 API 이름 그대로 검색하면 됩니다. 국토부 데이터라 제공 기관 - 국토교통부로 표시된 걸 고르세요. 혹시 검색으로 VWorld(브이월드) 링크가 뜨는 경우도 있는데, VWorld는 국토부가 운영하는 지도 사이트라 최종적으로는 같은 데이터로 이어집니다.
링크 눌러 들어가면 이 화면 - 활용신청 위치
위 표에서 API 링크를 누르면 이런 상세 페이지가 뜹니다. 아래쪽에 파란색 활용신청 버튼이 보여요. 이걸 눌러야 시작.
API 상세 페이지. 좌하단 파란색 "활용신청" 버튼이 시작점.
로그인 필수활용신청을 누르면 로그인 화면으로 넘어갑니다. 아직 회원가입 안 했으면 먼저 회원가입을 하고 오세요. (우측 상단 회원가입 버튼 - 개인회원 - 이름-이메일 등록.) 로그인 안 하고 신청 안 됩니다.
활용신청 이후 흐름
활용신청 클릭 → 로그인 (미로그인 시).
로그인 후 자동으로 신청 양식 페이지로 이동. (아래 신청서 입력 항목대로 채우면 됨.)
양식 다 채우고 이용약관 동의 3개 모두 체크 → 활용신청 클릭.
"신청이 완료되었습니다" 메시지 확인.
상단 마이페이지 → 오픈API → 개발계정으로 이동 → 방금 신청한 API가 승인 상태로 표시되는지 확인. 보통 즉시 자동승인이지만 몇 시간 걸릴 수도 있음.
승인 후 개발계정 상세 페이지에서 일반 인증키(Encoding) - 일반 인증키(Decoding) 두 종류 복사 → .env로 옮기기 (스텝 13).
신청서 입력 - 이렇게 채우세요
신청서에 이것저것 묻는데, 여기 붙여넣기용 예시를 준비했습니다. 정직해도 되고, 예시 그대로 써도 문제없어요. 어차피 심사관은 사람이 아니라 자동승인입니다.
활용 목적
개인 학습 및 부동산 시장 분석용으로 활용 예정입니다.
개인 학습 목적으로 아파트 매매 실거래 데이터를 수집-분석하여 서울-경기 지역 부동산 시장 동향을 파악하고, 관심 지역의 시세 추이를 시각화하는 개인 프로젝트에 활용하고자 합니다.
서비스 유형
웹 사이트 개발 또는 기타 선택.
서비스 정보 (URL, 있으면)
없으면 그냥 개인 프로젝트라고 적어도 됩니다.
개인 프로젝트 (운영 중인 도메인 없음)
일일 트래픽 예상
개인용이면 낮게. 10,000건 정도가 무난.
일 10,000건 이내 (개인 학습 용도)
이용약관 동의
다 체크. 특히 재배포 금지 조항이 있는데, 개인 용도면 상관 없어요.
tip
입력 필드가 헷갈리면 이걸 Claude한테 물어봐도 됩니다. "공공데이터포털 API 신청서에서 활용목적 뭐라고 쓸까?" 라고 하면 상황 맞게 초안 뽑아줍니다.
신청 → 마이페이지 → 오픈API → 개발계정에서 승인 상태 확인. 보통 즉시 또는 몇 시간 내에 자동승인. 승인되면 일반 인증키(Encoding/Decoding) 두 종류가 발급됩니다.
11
지도 API - 무료로 지도 띄우는 방법 3가지
부동산 데이터 뽑으면 결국 지도에 찍고 싶어져요. 지도는 서비스마다 특성이 달라요. 목적에 따라 3가지 방식이 있고, 각각 장단점이 있습니다. 아래 요약 보고 골라서 세팅하면 됩니다.
지도 3가지 방식 비교
방식
언제 씀
특징
1. 카르토 (Carto)
빠르게 할 때
디자인이 예쁨. 다만 일정 부분 이상 확대하면 회원가입해서 API 키를 받아야 함. 간단한 방법.
2. 브이월드 (VWorld) 추천
정식으로 할 때
디테일한 지도 사용 가능. 시간은 걸리지만 행정구역이 한글로 표시되고, 다양한 레이어를 표현할 수 있음. 국토부가 관리.
3. 오픈스트리트 (OpenStreetMap)
카르토가 안 될 때
돈 안 들이고 즉시 가능. 추천하지는 않지만 Carto가 안 될 때 대체용. 한국 지적도 없음.
방법 1 - 카르토 (Carto) - 빠르고 예쁨
카르토(Carto)는 클라우드 지도 서비스입니다. 회원가입 없이 기본 지도를 띄울 수 있고, 디자인이 깔끔해서 인기가 많아요. 다만 일정 확대 배율 이상으로 들어가거나 트래픽이 늘어나면 워터마크가 뜨거나 API 키를 요구합니다.
tip
발급받은 키는 나중에 Claude가 자동으로 지도에 붙여줍니다. Claude한테 "VWorld 지도 API 키 XXXXXX 써서 서울 지도 띄우는 HTML 하나 만들어줘. 지적도 레이어까지" 이렇게 말하면 됩니다.
방법 3 - OpenStreetMap (가입 안 함 - 즉시 가능) - 대체용
완전 가입 없이 지도만 띄우고 싶으면 OpenStreetMap(OSM)을 쓰면 됩니다. 전 세계 오픈소스 지도 프로젝트. API 키 필요 없음.
Claude한테 그냥 이렇게 말하면 끝나요.
가입 필요 없는 OpenStreetMap으로 지도 하나 띄워줘.
Leaflet + OSM 타일 조합.
필지 좌표 몇 개 찍는 예시까지 포함.
Claude가 index.html 하나 만들어서 브라우저에서 여는 순간 지도가 뜹니다. 코드도, 계정도, 키도 필요 없습니다.
한계
OSM은 한국 지적도(필지 경계선)가 없고, 행정구역 이름이 영문/기본값으로 표시될 수 있어요. 도로-건물-행정경계는 잘 나옵니다. 추천하지는 않지만 Carto가 안 될 때 대체용으로.
12
받은 API 키를 Claude에게 주기 - 조르기
키를 받았으면 Claude한테 넘기면 됩니다. 이때 중요한 게 말투예요. 그냥 "이 키 줬으니까 알아서 다 해줘" 라고 하면 됩니다. 세세히 설명할 필요 없어요.
국토부 실거래 API 키 받았어. 아래 키로 서울 강남구 아파트 매매
최근 3개월 데이터 좀 뽑아줘. 자동으로.
Decoding 키: abcDEF123456xxxxxxxxxxxxxxxxxxxxxx==
Encoding 키: abcDEF123456xxxxxxxxxxxxxxxxxxxxxx%3D%3D
Claude가 알아서 Python 스크립트 만들고 API 호출해서 결과 뽑아줍니다. 처음엔 이렇게 직접 붙여넣는 방식이 제일 빨라요.
Claude가 미적거리면 - 조르기
Claude가 종종 "이건 어떻게 하실 건가요?", "확인 한번 해주시겠어요?", "이러이러한 방법이 있는데 어떤 걸 원하세요?" 이렇게 묻습니다. 이때 딱 이렇게 말하세요.
묻지 말고 그냥 자동으로 다 해줘.
결정도 알아서 하고, 필요하면 폴더도 만들고, 스크립트도 짜고,
실행해서 결과까지 보여줘. 진행상황은 중간에 알려주고.
이 한 마디로 대부분 해결됩니다. Claude는 원래 안전하게 동작하려고 자주 확인하는 성향이 있어요. 확인이 성가시면 미리 "자동으로 다 해줘"라고 못박아 두세요. 안 되면 한 번 더 "묻지 말라니까" 하면 됩니다.
이 도구 잘 쓰는 사람들의 공통점조릅니다. "안 됩니다"에는 "돼. 다시 찾아봐", "복잡합니다"에는 "복잡해도 돼. 해줘", "이렇게 하시겠어요?"에는 "응. 시작해". Claude는 이 정도 톤에 최적화돼 있어요. 이유 있는 부탁도, 이유 없는 명령도 다 잘 받습니다.
진짜 잘 조르는 한 마디는 이거예요.
그냥 자동으로 다 하면 안 돼? 가능한 방법 찾아봐.
안 되면 왜 안 되는지 알려주고, 대안 몇 개 같이 뽑아줘.
이 한 마디에 Claude가 "안 됩니다"에서 "이렇게 하면 됩니다"로 태세 전환하는 경우가 정말 많습니다. 물러서지 마세요.
보안 - 이 방법도 완벽하진 않음채팅창에 키를 붙여넣는 순간, 그 키는 이미 Claude(Anthropic) 서버로 전송됩니다. Claude Code로 작업하려면 어차피 그렇긴 하지만, 인식은 해두세요:
① 개인 계정 - 개인 프로젝트라면 편의를 위해 이 방식 써도 됨. Anthropic은 Enterprise급 신뢰 서비스이고, API 키 자체는 여러분 것.
② 회사 데이터-민감 서비스면 이 방식 금지. 아래 안전한 방법으로.
③ 스크린샷-블로그-튜토리얼 공유 시 키 부분 반드시 가리기. 노출됐으면 즉시 재발급.
진짜 안전한 방법 - 이렇게 해야 합니다Claude에게 키를 아예 알려주지 않는 방식이 최선입니다. 다음 스텝의 .env 파일을 여러분이 직접 만들어 채우고, Claude에게는 "이 .env 참조해서 써줘"라고만 하면, 키 값은 Claude 서버에 절대 안 갑니다. Claude는 파일에 "이런 변수가 있다"는 것만 인지하고, 실제 값은 여러분 PC에서만 사용됩니다.
13
.env 파일 - 키 보안 관리
키가 하나 두 개일 땐 상관없는데, 카카오맵-네이버-국토부-기상청 등등 늘어나면 관리가 번거로워집니다. 그리고 실수로 인터넷에 올리면 큰일이에요. 그래서 .env 파일이라는 걸 씁니다.
.env 파일이란?
여러 키를 한 파일에 모아두고, 코드에서는 이름으로만 부르는 방식입니다. 파일 자체는 .gitignore에 넣어서 절대 공유 안 되게 처리해요.
방법 A - 편한 방법 (Claude에게 키 알려줌)
가장 편함. 대신 키가 Anthropic 서버로 감. 개인용이면 실용적.
이 폴더에 .env 파일 만들어줘. 그리고 .gitignore에 .env 추가해줘.
그리고 아래 키들을 .env에 넣어줘.
MOLIT_API_KEY=abcDEF123456xxxxxxxxxxxxxxxxxxxxxx==
KAKAO_MAP_KEY=987xyz...
앞으로 API 호출할 땐 이 .env 파일에서 키 불러다 쓰도록 해줘.
방법 B - 안전한 방법 (권장)
여러분이 직접 .env를 만들고 채웁니다. Claude는 키 값을 절대 보지 않아요.
먼저 Claude에게 구조만 만들어달라고 합니다.
이 폴더에 빈 .env 파일 하나 만들어주고, .gitignore에 .env 추가해줘.
그리고 .env.example도 하나 만들어서 필요한 변수 이름들만
값 없이 적어줘. 예: MOLIT_API_KEY= (값 비워둠)
파일 열기 - Ctrl+O → .env 타이핑 → Enter. VS Code 편집기에 열립니다.
여러분이 직접 키 값을 붙여넣고 저장 (Ctrl+S). 이 순간 값은 여러분 PC에만 존재.
Claude에게 "이제 .env에 키 넣었어. API 호출할 때 이거 참조해서 써줘"라고만 하면, Claude는 os.getenv("MOLIT_API_KEY") 같은 형태로 코드를 만듭니다. 파일을 굳이 열지 않아요.
왜 이게 안전한가 - 지갑 비유로
.env는 여러분의 지갑이라고 생각하세요.
Claude에게 "지갑 안에 돈 있어, 그 돈으로 뭐 사와" 라고만 하면 Claude는 지갑을 안 열어봐요. 필요할 때 꺼내서 쓰기만 합니다. 코드에 os.getenv("KEY_NAME") 이런 식으로 이름만 참조해서 짜요. 값은 실행 중 여러분 PC 메모리에만 있고, Anthropic 서버로 값 자체는 안 갑니다. 이름만 감.
⚠️ 다만 여러분이 직접 "지갑 열어서 보여줘" = "이 .env 파일 열어봐" 시키면 그건 열어줍니다. 그때는 값이 대화창에 들어와서 서버로 전송돼요. 그러니 원칙은 하나예요.
.env는 내가 채우고, Claude에게 굳이 그 내용을 보게 시키지 않는다. 이 두 가지만 지키면 안전합니다.
Windows에서 .env 파일 보이게 하기
.env는 이름이 점(.)으로 시작하는 파일입니다. Windows에서는 기본적으로 숨김 파일로 취급돼서 파일 탐색기에 안 보일 수 있어요. VS Code에서는 잘 보이지만, Windows 탐색기에서도 봐야 할 때가 있죠.
파일 탐색기 열기 (Win + E).
상단 메뉴 보기(View) 클릭.
표시(Show) → 숨긴 항목(Hidden items) 체크.
이제 .env가 회색으로 살짝 흐리게 보입니다.
Windows 10 이하는 보기 → 옵션 → 폴더 및 검색 옵션 변경 → 보기 탭 → 숨김 파일 - 폴더 - 드라이브 표시 순서.
한 걸음 더
나중에 여러 프로젝트를 하게 되면 키를 한 곳에 모아두고 여러 프로젝트에서 참조하는 구조가 더 편합니다. 이것도 Claude한테 "내 홈 폴더 밑에 _secrets 폴더 만들고 거기서 관리하게 해줘" 라고 하면 알아서 해줍니다. (값은 여전히 여러분이 직접 채우세요.)
절대 금지
① .env를 GitHub 같은 곳에 업로드하지 마세요. ② 스크린샷-블로그-튜토리얼에 키 원문 노출 금지. ③ 노출됐으면 즉시 재발급이 정답입니다. 이것도 이상하면 Claude한테 "노출된 것 같은데 어떻게 해?" 물어보면 재발급 절차 안내해줍니다.
실제 사례 - 이 가이드 만드는 중 일어난 사고
이 페이지를 만드는 중 Claude 자신이 예시 토큰 자리에 제 실제 텔레그램 봇 토큰을 넣어 배포했습니다. 이전 세션 요약본에 남아있던 실제 값을 "리얼한 예시"로 그대로 옮겨 쓴 것.
발견 후 흐름 - ① 사용자가 스크린샷 보고 지적 → ② 가짜 토큰으로 교체-재배포 → ③ CF 엣지 캐시 갱신 대기 → ④ BotFather에서 /revoke로 토큰 무효화 → ⑤ .env 갱신 - 봇 재시작.
교훈 3가지 ① AI에게 예시 토큰 만들라고 시킬 때도 "가짜값으로"라고 명시하세요. AI가 컨텍스트에 있는 실제 값을 무심코 인용할 수 있습니다.
② 배포 전 마지막으로 grep으로 검사하세요. grep -E "^[0-9]{8,}:[A-Za-z0-9_-]{30,}" 파일 같은 걸로 실수 잡기.
③ 노출됐으면 revoke가 유일한 정답. 페이지 캐시-검색엔진-SNS 스크린샷 등 어디까지 퍼졌는지 모르니 미련 없이 재발급.
14
"집요하게" - 이 도구를 잘 쓰는 3원칙
여기까지 오면 도구는 다 세팅됐어요. 마지막으로, Claude Code를 잘 굴리는 사람과 못 굴리는 사람의 차이가 뭔지 알려드릴게요. 이거 하나입니다.
잘 굴리는 사람은 집요합니다.
Claude가 처음에 "안 됩니다", "복잡합니다", "이 방법은 어렵습니다"라고 하면, 대부분의 사람은 거기서 포기합니다. 그런데 한 번 더 밀어붙이면 됩니다. 정말로 됩니다.
이 네 마디만 외우세요
Claude가 못 한다고 할 때, 미적거릴 때, 진행이 안 보일 때, 이걸 그대로 치세요.
방법 찾아줘."안 된다고 말고 되는 방법 찾아줘. 대안 3개 뽑아봐."
자동으로 해줘."수동으로 물어보지 말고 알아서 다 해줘. 결정도 알아서."
진행상황 알려줘."작업 시작-중간-끝에 상황 요약해서 알려줘. 침묵하지 말고."
빨리 해줘."오래 걸리면 병렬로 돌려. 확인 절차 줄이고 우선 실행부터."
번외
텔레그램으로 Claude 원격 조종하기 (MCP 연동)
PC에서 세션 돌리는 건 좋은데, 지하철에서-카페에서-자기 전 침대에서 Claude한테 뭘 시키고 싶을 때가 있습니다. 텔레그램 봇을 만들어서 붙이면 메신저로 Claude한테 지시할 수 있어요. Claude는 여러분 PC에서 실행되고, 결과를 텔레그램 메시지로 답을 주면서, 텔레그램을 통해 원격으로 시킬 수 있습니다. (마찬가지로 PC는 켜져있어야 합니다.)
먼저 알아두세요 - 종종 오류가 납니다
텔레그램 MCP 연동은 가끔 답변이 안 오는 오류가 발생합니다. Claude 앱/확장 버전이 업데이트되거나, 네트워크가 끊겼다 붙거나, 세션이 오래돼서 그런 경우가 많아요. 대부분의 경우 Claude 창(VS Code나 데스크탑 앱)을 껐다가 다시 켜면 정상 복구됩니다. 안 되면 PC 자체를 껐다 켜기. 이 부분을 알고 계셔야 합니다.
개념
이걸 MCP(Model Context Protocol)라고 합니다. Claude가 외부 도구랑 연결되는 표준. 텔레그램 MCP는 텔레그램 봇을 Claude의 도구로 등록해서, "새 메시지 왔어? 답장 보내"를 Claude가 할 수 있게 만들어줍니다.
전체 흐름 - 한눈에
1
텔레그램 앱에서 BotFather 접속
텔레그램은 봇을 만드는 계정도 봇입니다. @BotFather가 만들어주는 봇.
↓
2
/newbot 명령 → 이름 - 아이디 정하기
이름은 아무거나. 아이디는 반드시 _bot으로 끝나야 함 (예: my_claude_relay_bot).
↓
3
봇 토큰 받기
BotFather가 긴 문자열 하나 줍니다. 예: 1234567890:AABBccDDeeFFggHHiiJJkkLLmmNNooPPqqRR. 이걸 절대 남한테 공유하지 마세요. 아무나 이걸 알면 여러분 봇을 조종할 수 있습니다.
봇 링크 눌러서 여러분 봇과 대화 시작 → /start 한 번 눌러주세요. 이거 안 하면 봇이 여러분한테 답 못 보냅니다.
봇 규칙 - 알아두면 좋음
① 봇은 사람이 먼저 대화 걸어야 메시지 보낼 수 있어요. 그래서 위 스텝 7이 중요.
② 봇 토큰은 절대 공유 금지. 실수로 유출되면 /revoke 로 재발급.
③ 봇은 기본적으로 여러분한테만 답 보내게 해야 합니다. Claude MCP가 이걸 chat_id 화이트리스트로 관리합니다. 안 하면 아무나 여러분 Claude를 부릴 수 있어요.
Claude 세션에 붙이는 정확한 문장
봇 토큰 받았으면 Claude 채팅창에 이걸 그대로 붙여넣으세요.
텔레그램 MCP 붙여서 이 세션이랑 연결해줘.
봇 토큰: 1234567890:AABBccDDeeFFggHHiiJJkkLLmmNNooPPqqRR
(예시. 여러분 토큰으로 바꿔주세요.)
절차:
1. telegram-mcp 설치
2. 토큰을 MCP 설정에 저장
3. 내 chat_id 자동 감지 - 화이트리스트 등록
4. 테스트 메시지 하나 나한테 보내서 연결 확인
전부 자동으로 해줘. 확인 절차 최소화.
Claude가 스텝별로 진행하면서 중간에 "봇한테 /start 눌러주세요"같은 액션을 요청할 수 있어요. 시키는 대로 해주면 됩니다.
동작 확인
연결이 되면 여러분 텔레그램으로 "연결 완료. 이제 여기서 메시지 보내면 PC의 Claude가 받습니다." 같은 메시지가 와야 합니다. 안 오면 봇한테 /start를 다시 눌러보고, Claude한테 "연결 안 됐어. 다시 시도해줘"라고 하세요.
이걸 언제 씀
① 퇴근길에 "오늘 실거래 뽑아서 요약해둬." → 도착하면 준비돼 있음.
② 주말 아침 "이번주 분당 상가 매물 변화 알려줘." → 침대에서 확인.
③ 미팅 중 급한 확인 필요할 때 "이 프로젝트 진행 어디까지 됐어?" → 폰으로 답 받음.
PC가 켜져 있어야 이게 됩니다 (스텝 9의 24시간 언급 참조).
한 단계 더 - 세션마다 봇 하나씩 (멀티봇)
Claude Code 세션을 여러 개 동시에 돌릴 수 있어요. 프로젝트별로, 작업 성격별로 세션을 나누고 각 세션마다 다른 봇을 붙이면, 텔레그램에서 여러 봇으로 여러 세션을 동시에 조종할 수 있습니다.
텔레그램에 여러 개의 봇이 각기 다른 Claude Code 세션을 조종. 봇 이름-아이콘도 세션 성격별로 다르게.
구조는 간단합니다 - 세션 N개 + 봇 N개 + 각 세션이 자기 봇 토큰만 알고 있음. 세션끼리 서로 모르고 각자 독립적으로 돕니다.
멀티봇 세팅 순서
BotFather에서 /newbot 을 원하는 봇 수만큼 반복. 예: my_claude_data_bot, my_claude_blog_bot, my_claude_finance_bot. 각 봇의 토큰을 별도로 저장.
Claude 데스크탑 앱에서 세션을 여러 개 생성 (스텝 9 데스크탑 앱 - Code 탭 참고). 세션마다 다른 폴더 선택.
세션 1을 열고: "텔레그램 MCP 붙여줘. 봇 토큰은 [봇1 토큰]. 이 세션만 이 봇에 연결해줘."
세션 2를 열고: "텔레그램 MCP 붙여줘. 봇 토큰은 [봇2 토큰]. 이 세션만 이 봇에 연결해줘."
… 원하는 만큼 반복.
텔레그램에서 각 봇에게 /start 한 번씩 눌러 연결 확인.
활용 예시
🔹 봇1 (마이클로드1) - 데이터/부동산 - 실거래-매물 수집-분석 세션에 연결
🔹 봇2 (마이클로드2) - 블로그 - 초안 작성-이미지 정리 세션에 연결
🔹 봇3 (마이클로드3) - 코드/QA - 코딩-테스트 세션에 연결
각 봇의 이름-아바타 이모지-프로필 사진을 다르게 설정하면 텔레그램 대화 목록에서 한눈에 구분됩니다. BotFather에서 /setname, /setuserpic, /setdescription으로 봇마다 개성 부여 가능.
관리 팁
① 봇이 많아지면 토큰 관리 필수. 각 봇 토큰을 .env에 이름 구분해서 저장 (예: TG_TOKEN_DATA=, TG_TOKEN_BLOG=).
② 세션이 많아지면 PC 리소스도 그만큼 씀. 4~6개까지가 실용적.
③ 세션끼리는 서로 못 봐요. 결과를 공유하려면 공용 폴더에 파일 저장해두고 다른 세션에서 참조.
다시 강조 - 오류 나면 창 껐다 켜기
쓰다 보면 텔레그램 봇이 답을 안 하거나, 이상한 오류 메시지가 뜨는 경우가 있습니다. 대부분 원인은 ① Claude 앱/확장 버전 업데이트가 백그라운드로 진행된 경우 ② 세션이 너무 오래 열려 있어 텔레그램 연결이 끊긴 경우 ③ 네트워크가 잠깐 불안정했던 경우.
해결책 3단계 - 순서대로 시도.
① Claude 채팅 창(VS Code 패널 or 데스크탑 앱 창)을 껐다가 다시 켜기. 90%는 이걸로 해결.
② 그래도 안 되면 Claude 데스크탑 앱 전체 종료 후 재실행. 트레이 아이콘도 꺼주세요.
③ 그래도 안 되면 PC 재부팅. 최후의 방법. 이걸로 100% 됩니다.
이 오류는 여러분 잘못이 아니에요. 이유는 정확히 모르지만 가끔 불안정할 때가 있어요. 이 부분을 알고 계셔야 합니다. 껐다 켜면 됩니다.
번외 2
Claude Code - 터미널로 설치하기 (Windows)
지금까지는 VS Code 확장과 Claude 데스크탑 앱으로 Claude Code를 썼습니다. 이 둘로 대부분 충분하지만, 터미널(명령창)에서 직접 실행하는 방식도 있어요. 원격 서버-자동화 스크립트-GitHub Actions 같은 데선 이게 필요합니다.
이 스텝 - 언제 필요한가
지금은 몰라도 됩니다. VS Code + 데스크탑 앱만으로 다 되니까요. 나중에 여러분이 "어? 서버에서도 Claude 돌리고 싶은데" 하는 순간이 오면 그때 여기 돌아오세요. 참고용으로 남겨두는 파트입니다.
1단계 - Windows PowerShell 열기
Windows 시작 메뉴 클릭 → 검색창에 PowerShell 입력.
결과에서 Windows PowerShell 클릭. (참고: x86이 붙은 건 제외 - 32비트 버전이라 쓰지 마세요.)
파란 창이 열리고 PS C:\Users\사용자이름> 같은 프롬프트가 뜨면 준비 완료.
PDF 원본 자료 - Windows PowerShell로 irm https://claude.ai/install.ps1 | iex 한 줄 붙여넣기.
2단계 - 설치 한 줄 붙여넣고 Enter
PowerShell 창에 이거 그대로 붙여넣고 Enter:
irm https://claude.ai/install.ps1 | iex
irm은 인터넷에서 내려받는 명령, iex는 그걸 실행. 즉 "claude.ai에 있는 설치 스크립트를 지금 여기서 돌려라"는 뜻입니다.
설치 진행상황이 창에 쭉 뜹니다. 한 1~2분.
마지막에 Installation complete! 표시가 나오면 성공.
설치가 끝나면 PowerShell을 닫았다가 다시 열어주세요. 그래야 새로 생긴 명령어를 인식합니다.
3단계 - 설치 확인
다시 연 PowerShell에서:
claude --version
버전 번호(예: 2.1.68)가 나오면 설치 성공. 만약 "claude 명령을 찾을 수 없습니다"가 뜨면 아래 PATH 연결이 필요합니다.
PDF 원본 - 설치 정상 확인 화면과 PATH 연결 예시.
명령이 안 잡힐 때 - PATH 연결
PATH는 Windows가 명령을 찾을 폴더 목록입니다. Claude 설치 폴더가 여기에 없으면 claude가 안 잡혀요. 아래 한 줄로 현재 창에만 임시로 붙일 수 있습니다.
$env:PATH += ";$env:USERPROFILE\.local\bin"
claude --version
영구적으로 붙이려면:
Windows 검색창에서 환경 변수 입력 → 시스템 환경 변수 편집 클릭.
환경 변수(N) 버튼 클릭.
사용자 변수 목록에서 Path 선택 → 편집.
새로 만들기 클릭 → %USERPROFILE%\.local\bin 입력 → 확인.
PowerShell 창을 모두 닫고 다시 열기.
이제 어느 PowerShell 창에서든 claude --version이 인식됩니다.
4단계 - 첫 실행 - 계정 연결
설치 후 처음 실행할 때는 로그인부터 해야 합니다.
claude
실행하면 로그인 방식을 물어봅니다.
PDF 원본 - 첫 실행 시 로그인 방식 선택 화면.
구독 계정(Claude account) 선택 - Pro/Max 구독자면 이거로.
브라우저가 열리며 anthropic 로그인 페이지가 뜹니다. Pro 계정으로 로그인-승인.
완료되면 PowerShell 창으로 돌아옵니다. Claude 준비 완료.
5단계 - 다음부터는 - 작업 폴더에서 실행
설치는 한 번만. 이후에는 작업할 폴더로 이동해서 claude 실행만 하면 됩니다.
cd C:\Users\사용자이름\Desktop\내프로젝트
claude
cd는 "이 폴더로 이동". 그 다음 claude를 입력하면 그 폴더에서 Claude Code가 시작됩니다. 이후는 VS Code에서 쓰던 것과 똑같이 한국어로 요청하면 돼요.
VS Code 터미널에서도 됨
VS Code 하단의 터미널 창(Ctrl + `)에서도 claude가 그대로 작동합니다. VS Code에서 폴더 열어놓은 상태로 터미널 → claude를 치면 확장 설치 없이도 채팅이 시작돼요. 이 방식이 더 편한 분들도 있습니다.
터미널 방식 - 언제 유리한가
① 서버-CI/CD 환경 - GUI 없는 리눅스 서버, GitHub Actions에서 자동화할 때.
② 스크립트 자동화 - 스케줄러(cron-launchd)로 정기적으로 Claude 돌리기.
③ 가벼운 사용 - VS Code-데스크탑 앱 안 깔고 CLI 하나로 끝.
일반적 사용에는 VS Code 확장 + 데스크탑 앱이 더 쉬워요. 이 스텝은 필요할 때만 참고.
진짜 마지막 - 이 가이드 보다가 막히면, 그냥 Claude한테 "이 가이드 3번 스텝에서 막혔어, 화면에 X가 안 보여" 하고 스크린샷 붙여서 물어보세요. 이 도구는 원래 그렇게 쓰라고 있는 겁니다. 튜토리얼은 지도고, Claude가 옆에서 걷는 사람입니다.