윈도우11에서 Obsidian Mind를 설치할 때 Claude Code 네이티브 방식과 WSL2 방식의 차이점, 그리고 각 환경별 셋업 절차를 단계별로 정리합니다.
Claude Code로 Obsidian Mind를 사용하려는데 macOS나 Linux 기준 가이드만 보이고, 윈도우에서는 어디서부터 시작해야 할지 막막한 경험이 있을 것입니다. 특히 WSL을 설치해야 하는지, 네이티브로 되는지조차 혼란스러운 상황이 자주 발생합니다.
2025년 말부터 Claude Code가 윈도우 네이티브 설치를 공식 지원하면서 상황이 크게 달라졌습니다. Git Bash만 있으면 PowerShell에서 바로 실행 가능하고, 샌드박싱이 필요한 경우에만 WSL2를 선택하면 됩니다. 이 글에서는 두 경로 모두를 다룹니다.
이 가이드에서는 윈도우11 환경 사전 점검부터 Claude Code 설치(네이티브/WSL2), Obsidian Mind 볼트 클론, 첫 세션 실행까지 전체 흐름을 따라할 수 있도록 구성했습니다. 각 단계마다 발생할 수 있는 오류와 해결법도 함께 정리합니다.
🛠️ 준비물
- Windows 11 버전 21H2 이상 (winver로 확인)
- 관리자 권한이 있는 사용자 계정
- 인터넷 연결 (설치 파일 다운로드용)
- Anthropic 구독 (Claude Pro $20/월 이상) 또는 API 키
⏱️ 예상 소요시간: 네이티브 방식 약 15분, WSL2 방식 약 25~30분 (재부팅 포함)
☐ 오늘 할 일
- ☐ Windows 버전 및 가상화 지원 확인
- ☐ Git for Windows 설치 (네이티브) 또는 WSL2 활성화
- ☐ Claude Code 설치 및 인증
- ☐ Obsidian 설치 + obsidian-mind 볼트 클론
- ☐ 볼트 디렉터리에서 claude 실행, 첫 세션 확인
윈도우11 환경 사전 점검
설치를 시작하기 전에 윈도우11이 필요한 조건을 갖추고 있는지 확인합니다. 이 단계를 건너뛰면 설치 도중 원인을 알 수 없는 오류가 발생할 수 있습니다.
Step 1: Windows 버전 확인
Win + R
을 누르고 winver를 입력한 뒤 Enter를 누릅니다. 표시되는 창에서 "Version 21H2" 이상인지 확인합니다. 22H2, 23H2, 24H2 등 숫자가 더 크면 문제없습니다.
Step 2: 가상화(Virtualization) 활성화 확인
WSL2를 사용할 계획이라면 이 단계가 필수입니다. 네이티브 설치만 할 예정이라도 확인해 두면 나중에 유용합니다.
Ctrl + Shift + Esc
로 작업 관리자를 열고, 성능 탭 → CPU를 선택합니다. 오른쪽 하단에 "가상화: 사용"이라고 표시되면 됩니다. "사용 안 함"으로 나오면 BIOS 설정에서 Intel VT-x 또는 AMD-V를 활성화해야 합니다.
⚠️ BIOS 진입 방법은 메인보드 제조사마다 다릅니다. 보통 부팅 시
F2
,
F10
, 또는
Delete
키를 누르면 BIOS 설정 화면에 진입합니다.
네이티브 vs WSL2, 어떤 방식을 선택할까
Claude Code는 윈도우에서 두 가지 방식으로 설치할 수 있습니다. 대부분의 사용자에게는 네이티브 설치가 더 간단하고 빠릅니다. 아래 비교표를 참고하여 자신에게 맞는 방식을 선택하세요.
| 비교 항목 | 네이티브 (Git Bash) | WSL2 (Ubuntu) |
|---|---|---|
| 설치 난이도 | ⭐ 쉬움 (5분) | ⭐⭐ 보통 (20분+) |
| 필요한 사전 설치 | Git for Windows만 | WSL2 + Ubuntu + Node.js |
| 샌드박싱(격리 실행) | ❌ 미지원 | ✅ WSL2에서 지원 |
| 파일 I/O 성능 | Windows 파일시스템 그대로 | Linux FS 사용 시 빠름, /mnt/c/ 사용 시 느림 |
| 추천 대상 | 대부분의 사용자, 빠른 시작 | 보안 격리가 필요하거나 Linux 도구 사용자 |
Obsidian Mind의 핵심 기능을 이해하고 싶다면 Obsidian Mind 핵심 기능 정리를 먼저 읽어보시는 것을 권장합니다. 이 글에서는 설치 과정에만 집중합니다.
방법 A: 네이티브 설치 (Git Bash 기반)
2025년 말부터 Claude Code가 윈도우 네이티브를 공식 지원하면서, WSL 없이도 PowerShell에서 바로 설치하고 실행할 수 있게 되었습니다. 내부적으로 Git Bash를 사용하므로 Git for Windows가 반드시 필요합니다.
Step 1: Git for Windows 설치
git-scm.com에서 설치 파일을 다운로드합니다. 설치 과정에서 대부분 기본값을 유지하되, "Add Git to PATH" 옵션이 체크되어 있는지 반드시 확인하세요. 이 옵션이 빠지면 Claude Code가 Git Bash를 찾지 못합니다.
설치 완료 후 PowerShell을 열고 아래 커맨드로 확인합니다:
git --version
# 예상 결과: git version 2.x.xStep 2: Claude Code 설치
PowerShell을 열고(관리자 권한 불필요) 공식 설치 스크립트를 실행합니다:
irm https://claude.ai/install.ps1 | iex설치가 완료되면 터미널을 닫았다가 다시 열고 버전을 확인합니다:
claude --version⚠️ claude 명령어가 인식되지 않으면 PATH 문제일 가능성이 높습니다. 아래와 같이 PATH에 수동 추가합니다:
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$env:USERPROFILE\.local\bin", [EnvironmentVariableTarget]::User)추가 후 PowerShell을 완전히 닫고 새로 열어야 반영됩니다.
Step 3: Git Bash 경로 수동 설정 (필요한 경우)
Claude Code가 Git Bash 경로를 자동으로 찾지 못하는 경우, 설정 파일에서 직접 지정할 수 있습니다. ~/.claude/settings.json 파일을 열고(없으면 생성) 아래 내용을 추가합니다:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
방법 B: WSL2 환경 설치
보안 격리(샌드박싱)가 필요하거나 Linux 네이티브 도구를 활용하고 싶다면 WSL2 방식을 선택합니다. Claude Code의 샌드박싱 기능은 현재 macOS와 Linux(WSL2 포함)에서만 지원됩니다.
Step 1: WSL2 설치
PowerShell을 관리자 권한으로 열고 아래 커맨드를 실행합니다:
wsl --install이 한 줄로 WSL2와 기본 Ubuntu 배포판이 함께 설치됩니다. 완료되면 컴퓨터를 재부팅합니다. 재부팅 후 Ubuntu 터미널이 자동으로 열리며, 사용자 이름과 비밀번호를 설정합니다.
⚠️ "가상 머신 플랫폼" 관련 오류가 나오면, 앞서 확인한 BIOS 가상화 설정이 비활성화된 것입니다. BIOS에서 VT-x/AMD-V를 켜고 다시 시도하세요.
Step 2: Node.js 설치 (WSL Ubuntu 내부)
WSL Ubuntu 터미널에서 아래 커맨드를 순서대로 실행합니다:
# 패키지 목록 업데이트
sudo apt update
# nvm (Node Version Manager) 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 터미널 재시작 또는 설정 리로드
source ~/.bashrc
# Node.js LTS 버전 설치
nvm install --lts
# 설치 확인
node --version # v20.x 이상
npm --versionStep 3: Claude Code 설치 (WSL 내부)
# npm 글로벌 디렉터리 설정
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Claude Code 설치
npm install -g @anthropic-ai/claude-code
# 설치 확인
claude --version⚠️ sudo를 사용하지 않는 것이 좋습니다. sudo로 npm을 실행하면 파일 권한 문제가 발생할 수 있습니다. 위처럼 ~/.npm-global로 글로벌 경로를 설정하면 sudo 없이 설치가 가능합니다.
Step 4: 인증
네이티브든 WSL이든, 처음 claude를 실행하면 브라우저 인증 창이 열립니다. Claude Pro/Max 구독 계정으로 로그인하면 토큰이 저장되어 이후에는 자동으로 인증됩니다.
WSL에서 브라우저가 자동으로 열리지 않는 경우, 터미널에 표시되는 URL을
Ctrl
+ 클릭으로 직접 열 수 있습니다.
Obsidian Mind 볼트 클론과 Obsidian 연결
Claude Code 설치가 완료되었으면, 이제 Obsidian Mind 볼트를 가져오고 Obsidian 앱과 연결합니다.
Step 1: Obsidian 설치
obsidian.md/download에서 Windows Universal 설치 파일을 다운로드하고 실행합니다. 일반적인 윈도우 앱 설치와 동일합니다.
Step 2: 볼트 클론
네이티브 설치 사용자:
# PowerShell 또는 Git Bash에서 실행
git clone https://github.com/breferrari/obsidian-mind.git C:\Users\사용자명\obsidian-mindWSL2 설치 사용자:
# WSL Ubuntu 터미널에서 실행
git clone https://github.com/breferrari/obsidian-mind.git ~/obsidian-mind⚠️ WSL2 사용자 주의: 볼트를 /mnt/c/ 경로(윈도우 드라이브 마운트)에 두면 파일 읽기/쓰기 속도가 현저히 느려집니다. 반드시 Linux 파일시스템 내부(~/ 경로)에 클론하는 것을 권장합니다.
Step 3: Obsidian에서 볼트 열기
네이티브 사용자: Obsidian을 실행하고 "Open folder as vault"에서 C:\Users\사용자명\obsidian-mind를 선택합니다.
WSL2 사용자: Obsidian Windows 앱에서 WSL 내부 경로에 접근하려면, 네트워크 경로를 사용합니다. 파일 탐색기 주소창에 \\wsl$\Ubuntu\home\사용자명\obsidian-mind를 입력하면 WSL 파일시스템에 접근할 수 있습니다. 이 경로를 Obsidian의 "Open folder as vault"에서 지정합니다.
Step 4: Obsidian CLI 활성화
Obsidian 내에서 설정(Settings) → 일반(General)으로 이동하여 맨 아래 "Command line interface"를 활성화합니다. 이 설정이 켜져 있어야 Claude Code가 Obsidian의 기능을 온전히 활용할 수 있습니다. 해당 메뉴가 보이지 않을 경우 별도로 설치하여야 합니다. 제일 쉬운 방법이 Node 사용하는 것인데 아래 이미지 참고하세요. CLAUDE.md의 구조와 작성 원칙에 대한 자세한 내용은 CLAUDE.md 작성법 가이드에서 확인할 수 있습니다.
첫 세션 실행과 동작 확인
모든 설치가 끝났으면 실제로 Obsidian Mind가 제대로 작동하는지 확인합니다.
Step 1: 볼트 디렉터리에서 Claude Code 실행
네이티브 사용자:
cd C:\Users\사용자명\obsidian-mind
claudeWSL2 사용자:
cd ~/obsidian-mind
claudeStep 2: 세션 시작 테스트
Claude Code가 실행되면 아래 커맨드를 입력합니다:
start session정상적으로 작동한다면 Claude가 CLAUDE.md를 읽고, North Star 목표 파일을 확인하고, 최근 변경 사항을 스캔하는 과정이 터미널에 표시됩니다. 처음 실행 시에는 North Star 파일이 비어 있으므로 목표 작성을 안내받게 됩니다.
세션 훅과 North Star 워크플로를 본격적으로 활용하는 방법은 세션 훅 활용법 가이드에서 자세히 다루고 있습니다.
Step 3: 필자의 윈도우 환경 테스트 결과
필자가 Windows 11 24H2 환경에서 네이티브 방식으로 테스트한 결과, Git for Windows 설치부터 첫 세션 실행까지 약 12분이 소요되었습니다. WSL2 방식은 Ubuntu 설치와 재부팅을 포함하여 약 28분이 걸렸습니다. 네이티브 방식에서 볼트 경로에 한글이 포함되면 일부 스크립트에서 인코딩 문제가 발생할 수 있으므로, C:\Users\사용자명\obsidian-mind처럼 영문 경로를 사용하는 것이 안전합니다.
윈도우 환경 트러블슈팅
윈도우에서 발생할 수 있는 주요 문제와 해결 방법을 정리합니다.
| 증상 | 원인 | 해결 방법 |
|---|---|---|
claude이 인식되지 않음 |
PATH에 ~/.local/bin 미등록 |
위 PATH 추가 커맨드 실행 후 터미널 재시작 |
| Git Bash 경로를 찾지 못함 | Git 설치 경로가 기본값과 다름 | settings.json에 CLAUDE_CODE_GIT_BASH_PATH 수동 설정 |
| WSL 설치 후 Ubuntu가 안 열림 | BIOS 가상화 비활성화 | BIOS에서 VT-x/AMD-V 활성화 후 재부팅 |
| WSL2에서 파일 접근이 매우 느림 | 볼트가 /mnt/c/ 경로에 위치 |
Linux 파일시스템(~/)으로 볼트 이동 |
| Obsidian에서 WSL 볼트가 안 보임 | 네트워크 경로 미사용 | \\wsl$\Ubuntu\home\... 경로로 접근 |
| 이미지 붙여넣기가 안 됨 | Ctrl+V는 텍스트 전용 | Alt+V로 이미지 붙여넣기 또는 파일 드래그앤드롭 |
Obsidian Mind와 일반 볼트의 구조적 차이가 궁금하다면 Obsidian Mind vs 일반 볼트 비교 분석에서 각 방식의 장단점을 확인할 수 있습니다.
자주 묻는 질문
Q. 네이티브 설치 후 나중에 WSL2로 바꿀 수 있나요?
가능합니다. 두 방식은 독립적으로 설치되므로 WSL2를 추가로 설정하고 그 안에서 Claude Code를 별도로 설치하면 됩니다. 볼트는 git clone으로 새로 가져오면 되고, Obsidian에서 열어둔 볼트 경로만 변경하면 전환이 가능합니다.
Q. Claude Code 유료 구독 없이 Obsidian Mind를 쓸 수 있나요?
Obsidian Mind 볼트 템플릿 자체는 무료(MIT 라이선스)이지만, Claude Code를 실행하려면 Anthropic 유료 구독(Claude Pro 월 $20 이상) 또는 API 키가 필요합니다. Claude Code 없이 볼트 구조만 Obsidian에서 활용하는 것은 가능하지만, 세션 훅이나 자동 노트 생성 등 핵심 기능은 사용할 수 없습니다.
Q. Windows 10에서도 설치할 수 있나요?
네이티브 설치는 Windows 10에서도 가능합니다. WSL2를 사용하려면 Windows 10 버전 2004 이상이 필요합니다. 다만 Windows 11이 WSL2 통합이 더 안정적이므로 가능하면 업그레이드하는 것을 권장합니다.
Q. VS Code와 함께 사용할 수 있나요?
가능합니다. 네이티브 설치의 경우 VS Code의 내장 터미널에서 claude를 바로 실행할 수 있습니다. WSL2 환경이라면 VS Code의 "Remote - WSL" 확장을 설치한 뒤, WSL 터미널에서 code .를 실행하면 VS Code가 WSL 환경에 자동 연결됩니다.
Q. 볼트 경로에 한글 폴더명이 있으면 문제가 되나요?
일부 셸 스크립트에서 인코딩 관련 문제가 발생할 수 있습니다. 볼트 경로는 영문으로 유지하는 것을 권장합니다. 예를 들어 C:\Users\oscar\obsidian-mind 형태가 안전합니다. 볼트 내부 노트의 파일명은 한글이어도 Obsidian이 정상적으로 처리합니다.
Q. 네이티브 설치에서 샌드박싱이 안 되면 보안 위험이 있나요?
샌드박싱은 Claude Code가 접근할 수 있는 파일과 네트워크를 OS 수준에서 제한하는 기능입니다. 샌드박싱 없이도 Claude Code는 사용자가 지정한 프로젝트 폴더 내에서만 작업하도록 설계되어 있어 일반적인 개인 프로젝트에서는 큰 위험이 없습니다. 다만 민감한 코드를 다루는 경우 WSL2 환경의 샌드박싱을 활용하는 것이 더 안전합니다.
마무리
윈도우11에서 Obsidian Mind를 설치하는 과정을 네이티브와 WSL2 두 경로로 정리했습니다. 대부분의 경우 네이티브 설치가 가장 빠르고 간단한 선택이며, 보안 격리가 필요한 업무 환경에서는 WSL2를 고려하면 됩니다. 설치가 완료되었다면 Obsidian Mind 셋업 가이드에서 North Star 작성과 첫 세션 워크플로를 이어서 진행하세요.
💬 윈도우에서 설치하면서 만난 문제나 해결 팁이 있다면 댓글로 공유해 주세요. 다른 사용자에게 큰 도움이 됩니다.
🔖 나중에 다시 따라 하실 분은 이 글을 북마크해 두시면 편리합니다.
📤 주변에 윈도우에서 Claude Code를 시작하려는 분이 있다면 이 글을 공유해 주세요.
📚 다음에 읽으면 좋은 글
ℹ️ 이 블로그는 Google 애드센스를 통해 광고 수익을 얻을 수 있습니다. 자세한 내용은 개인정보처리방침을 참고하세요.
※ 이 글은 2026-04-05 기준으로 작성되었습니다. 최신 정보는 공식 사이트에서 확인하세요.
'생산성 & 옵시디안' 카테고리의 다른 글
| Obsidian Mind North Star와 세션 훅 활용법, 매일 컨텍스트를 이어가는 워크플로 (0) | 2026.04.06 |
|---|---|
| Obsidian Mind CLAUDE.md 작성법, AI가 볼트를 이해하는 운영 매뉴얼 설계 (0) | 2026.04.06 |
| Obsidian Mind 설치부터 첫 세션까지, Claude Code 볼트 셋업 완전 가이드 (0) | 2026.04.05 |
| 2026년 Obsidian Mind 핵심 기능 정리, 엔지니어를 위한 AI 볼트 템플릿 (0) | 2026.04.05 |
| 옵시디안 Sync 유료 구독? 무료 Syncthing 동기화 완전 가이드 (0) | 2026.03.01 |
