Windows + WSL로 Claude Code / claude-obsidian 쓰기 가이드
누구나 따라할 수 있게 쓴 가이드예요. 전문 용어가 나오면 처음 한 번은 괄호로 풀어서 설명해요.
이 문서는 언제 보면 되나요?
Windows에서 Claude Code(claude 명령)를 쓰다가, Obsidian 위키(D:\ClaudeWiki)에 뭔가 쓰려고 하면 오류가 날 때
오류 메시지에 UNSUPPORTED_PLATFORM, directory-descriptor confinement, flock 같은 말이 보일 때
WSL(Windows 안에서 리눅스를 함께 돌리는 기능)을 처음 설정해서 Claude Code + claude-obsidian 플러그인을 새로 깔아야 할 때
왜 이런 일이 생기나요? (배경)
claude-obsidian 플러그인은 위키에 실제로 글을 저장할 때 fcntl.flock이라는 리눅스 전용 잠금 기능을 써요. Windows에는 이 기능이 없어서, 저장·ingest(원본 자료를 위키 글로 만들어 등록하는 것)·/canvas 반영 같은 "실제로 쓰는" 동작이 전부 막혀요. 읽는 것(검색·조회)은 Windows에서도 문제없어요.
그래서 "쓰는 작업"만 WSL 쪽에서 해야 해요. 아래를 순서대로 따라오세요.
1단계: WSL이 설치돼 있는지 확인
Windows PowerShell을 열고:
wsl --status
Ubuntu 같은 배포판 이름이 나오면 설치된 거예요 → 2단계로
"찾을 수 없다"는 메시지가 나오면 설치가 필요해요:
wsl --install
설치 후 컴퓨터를 재부팅해야 해요.
2단계: WSL(Ubuntu) 안에 Claude Code 설치
시작 메뉴에서 "Ubuntu"를 검색해서 실행하세요. 검은 화면(터미널)이 뜨면 아래를 순서대로 입력합니다.
설치:
curl -fsSL https://claude.ai/install.sh | bash
PATH(터미널이 프로그램을 찾는 폴더 목록) 등록 — 설치 메시지에 이 줄이 안내로 나와요. 그대로 실행하세요:
✏️ 바로잡음: wiki-ingest 스킬 문서를 실제로 열어보니, "위키 폴더 바깥의 경로는 정식 출처로 인정하지 않는다"는 규칙이 있었어요. 그래서 원본 경로를 곧바로 가리키게 시키는 것보다, 먼저 inbox/(위키 안의 대기 폴더)에 복사해 넣고 나서 등록을 지시하는 게 이 플러그인이 원래 의도한 방식이에요. 아래는 그 방식으로 수정한 지시문이에요.
WSL에서 /mnt/d/ClaudeWiki로 들어가 claude를 켠 뒤, 아래처럼 지시하면 돼요 (원본 폴더는 상황에 맞게 바꾸세요):
1. 아래 원본 폴더의 .md 파일을 전부 D:\ClaudeWiki\inbox\ 로 복사해줘 (같은 이름은 덮어써도 됨):
원본 폴더: /mnt/c/Users/<사용자명>/.claude/projects/<프로젝트 폴더명>/memory/
(MEMORY.md 색인 파일은 제외)
2. claude-obsidian 플러그인의 wiki-ingest 스킬로 inbox/ 안의 내용을 위키에 등록해줘.
내용이 안 바뀐 파일은 SHA-256(내용 지문) 비교로 자동 스킵된다고 들었어 — 그러니
이미 등록된 것까지 포함해서 전체를 다시 넣으라고 시켜도 안전해.
지켜야 할 것:
- 먼저 실제로 쓰기 전에 계획(몇 개가 새 항목이고 몇 개가 스킵되는지, 어느 폴더로
분류할지)을 보여주고 확인받을 것 — 바로 쓰지 말 것.
- 위키의 기존 구조를 따라서 분류할 것.
- git remote는 절대 추가하지 말 것.
⚠️ 이 지시문은 처음에도, 나중에 또 쓸 때도 그대로 재사용할 수 있어요 — 자세한 건 6단계 참고.
6단계: 다음번부터는 어떻게 지시하나요? (매일 다르게 안 써도 돼요)
결론: 처음과 똑같은 지시문을 그대로 또 써도 돼요. "이번엔 새로 생긴 것만"처럼 매번 다르게 지시할 필요가 없어요.
왜 그런가요? wiki-ingest 스킬은 파일마다 SHA-256(내용을 보고 만드는 고유 지문 같은 값)을 계산해서, 위키에 이미 등록된 내용과 똑같으면 자동으로 건너뛰도록 설계돼 있어요. 그래서:
5단계 지시문을 그대로 다시 실행 → 이미 등록된 메모(내용 안 바뀜)는 자동 스킵
그 사이에 새로 생긴 메모만 새로 등록됨
그 사이에 내용이 수정된 메모는 바뀐 부분만 갱신됨
언제 실행하면 되나요? 꼭 "매일"일 필요는 없어요. 며칠에 한 번, 혹은 생각날 때 아래를 반복하면 돼요:
cd /mnt/d/ClaudeWiki
claude
→ 위에서 켠 뒤 5단계 지시문 그대로 붙여넣기
즉, "복사(덮어쓰기) → 등록 지시" 이 두 줄짜리 루틴 하나만 기억하시면 돼요. 매번 새 문구를 고민하지 않으셔도 됩니다.
자주 겪는 문제
증상
원인
해결
claude: command not found
설치 후 PATH 등록을 안 함
2단계의 PATH 등록 명령 다시 실행
위키에 쓰다가 UNSUPPORTED_PLATFORM / flock 오류
Windows에서 시도함
WSL로 옮겨서 /mnt/d/ClaudeWiki에서 실행
WSL에서 이전 프로젝트 기록(메모)이 안 보임
Windows 경로(D:\...)와 WSL 경로(/mnt/d/...)는 저장 위치(해시 폴더)가 다름
정상 동작 — 필요하면 원본 경로를 직접 지정해서 읽게 하면 됨
요약 체크리스트
[ ] wsl --status로 WSL 설치 확인
[ ] WSL 안에서 curl -fsSL https://claude.ai/install.sh | bash로 Claude Code 설치