AI 활용 가이드

오픈클로(OpenClaude) 윈도우 설치 가이드 — 한 CLI 에서 클로드·GPT·딥시크·로컬 모델 다 돌리는 법

AI 디코드 2026. 4. 28. 14:00

오픈클로(OpenClaude) 윈도우 설치 가이드 — 한 CLI 에서 클로드·GPT·딥시크·로컬 모델 다 돌리는 법

AI 활용 가이드 2026. 04. 28. 약 36분 읽기

윈도우 11 기준 오픈클로 설치 완전 매뉴얼. Node.js 설치부터 Git Bash 세팅·환경 변수 등록·MCP 가져오기·Ollama 로컬 모델 추가까지 스크린샷과 함께 단계별로.

이 가이드로 만드는 것

윈도우 11 머신에 오픈클로(OpenClaude)를 깔아 한 CLI 에서 클로드 소넷 · GPT-5 · 제미나이 2.5 프로 · 딥시크 V4 · 올라마(Ollama) 로컬 큐웬 3 같은 모델을 자유롭게 갈아끼우며 코딩 작업을 돌리는 환경을 만듭니다.

예상 소요 시간: 30~45분 (Ollama 로컬 모델 다운로드 시간 별도)
대상 독자: 윈도우 11 사용 중이며 클로드 코드 또는 코덱스 CLI 한번 써본 적 있는 개발자. 처음이어도 단계마다 풀어 씁니다.
테스트 환경: Windows 11 Pro · Git Bash · Node.js 20.18

핵심 결론 — 오픈클로는 "클로드 코드 본체에 모델 어댑터 레이어 한 장만 더 얹은" OSS 포크다. Node.js 설치 → 깃허브 클론 → npm install → 환경 변수에 키 등록 → 실행. 클로드 코드 쓰던 사람이라면 ``%USERPROFILE%\.claude.json`` 설정과 MCP 가 거의 그대로 인식된다. 윈도우는 PowerShell 보다 Git Bash 가 가이드 따라하기 편함.

준비물 체크리스트 (윈도우 11 기준)

설치 전에 아래 항목을 미리 챙겨 두면 중간에 막히는 일이 적습니다.

  • [ ] Windows 11 (10 도 가능하지만 11 권장) — 무료
  • [ ] Node.js 20+ LTS — 오픈클로 런타임 (nodejs.org, 무료)
  • [ ] Git for Windows (Git Bash 포함) — 깃 + 유닉스 셸 환경 (git-scm.com, 무료)
  • [ ] Visual Studio Code (옵션이지만 권장) — 에디터 (code.visualstudio.com, 무료)
  • [ ] OpenAI API 키 — 선택, GPT-5 쓸 때 (유료, platform.openai.com)
  • [ ] 앤트로픽 API 키 — 선택, 클로드 소넷 쓸 때 (유료, console.anthropic.com)
  • [ ] 제미나이 API 키 — 선택, 무료 한도 있음 (aistudio.google.com)
  • [ ] 딥시크 API 키 — 선택, 매우 저렴 (platform.deepseek.com)
  • [ ] Ollama for Windows (옵션) — 로컬 모델 호스팅 (ollama.com, 무료)
  • [ ] NVIDIA RTX 4090 / 5090 24GB+ (옵션) — Ollama 로 35B 클래스 모델 띄울 때
📖 용어 풀이
Git Bash: 윈도우에서 리눅스 셸 명령어(``ls``·``cat``·``export``)를 쓸 수 있게 해 주는 터미널. Git for Windows 설치 시 함께 깔립니다.
OpenAI 호환 API: OpenAI 의 ``chat/completions`` 포맷을 그대로 받는 엔드포인트. 딥시크·셀라스·올라마 등 거의 모든 OSS 추론 서버가 이 포맷을 따라가요.
MCP(Model Context Protocol): 외부 도구·DB·서비스를 LLM 에 붙일 때 쓰는 공통 어댑터.
슬래시 커맨드: CLI 안에서 ``/model``·``/init``·``/save`` 같은 명령으로 워크플로를 호출하는 클로드 코드 기능.
npm: Node.js 패키지 매니저. ``npm install`` 로 의존성 설치, ``npm link`` 로 전역 등록.

이미지: Node.js 윈도우 다운로드 페이지 (출처: nodejs.org/en/download)

Step 1 — Node.js 와 Git for Windows 설치

오픈클로의 두 가지 필수 의존성을 먼저 깝니다.

1-1. Node.js 20 LTS 설치

  1. nodejs.org 접속 → 좌측의 LTS 버튼(20.x 또는 22.x) 클릭 → node-vXX.X.X-x64.msi 다운
  2. 다운받은 .msi 파일 더블 클릭 → "Next" 계속 → "Automatically install the necessary tools" 체크박스 켜고 설치 (Python·Visual Studio Build Tools 자동 설치)
  3. 설치 끝나면 PowerShell 재시작

설치 확인 — PowerShell 또는 Git Bash 에서:

node -v
# v20.x.x 또는 v22.x.x

npm -v
# 10.x.x 또는 그 이상

⚠️ 주의: Node.js 18 이하는 일부 스트리밍 API 가 깨집니다. 반드시 20 이상.

1-2. Git for Windows 설치

  1. git-scm.com/download/win 접속 → 자동 다운로드 시작
  2. 다운받은 .exe 더블 클릭
  3. 설치 옵션은 거의 다 기본값으로 가되, 다음 두 가지만 확인:
  4. "Git Bash Here" 체크박스 켜져 있어야 함 (탐색기 우클릭에서 Git Bash 실행)
  5. "Use Git from the command line and also from 3rd-party software" 선택

설치 확인 — Git Bash 열고:

git --version
# git version 2.x.x.windows.x

⚠️ 주의: 이후 가이드는 Git Bash 기준으로 진행합니다. PowerShell 쓰면 export$env:KEY="..." 로 달라지는 등 문법이 미묘하게 다릅니다.


이미지: 오픈클로 깃허브 저장소 (출처: github.com/Gitlawb/openclaude)

Step 2 — 오픈클로 클론 및 설치

작업 폴더를 정한 뒤 깃허브에서 클론합니다.

2-1. 작업 폴더로 이동

탐색기에서 C:\Users\내사용자명\Desktop 같은 곳에 ai-tools 폴더를 만들고, 그 폴더 안에서 우클릭 → "Open Git Bash here".

# 또는 Git Bash 에서 직접 이동
cd /c/Users/$USER/Desktop
mkdir ai-tools
cd ai-tools

2-2. 오픈클로 클론

git clone https://github.com/Gitlawb/openclaude.git
cd openclaude

2-3. 의존성 설치

npm install

설치는 보통 2~5분. 인터넷 느리면 10분까지 잡으세요. 노란색·빨간색 경고가 좀 떠도 빌드가 끝까지 가면 OK.

설치 끝났는지 확인:

ls
# README.md  package.json  src/  bin/  ...

./openclaude --help
# Usage: openclaude [options] [command] ...

⚠️ 주의: ./openclaude 가 안 먹으면 node bin/openclaude.js --help 로 직접 호출. 또는 npm link 한 번 실행 후 openclaude --help (전역 등록).

2-4. (선택) 보안 검사

비공식 OSS 포크라 의존성에 알려진 취약점이 없는지 한 번 체크하면 안전.

npm audit
# found 0 vulnerabilities  ← 이상적

# 만약 취약점이 잡히면
npm audit fix

이미지: Anthropic Claude Console 진입 화면 (출처: platform.claude.com)

Step 3 — API 키를 .env 파일에 등록

오픈클로의 핵심은 여러 프로바이더 키를 동시에 등록해 두고 슬래시 커맨드로 갈아끼우는 것입니다. 가장 안전한 방법은 프로젝트 루트의 .env 파일.

3-1. .env 파일 만들기

Git Bash 에서:

# openclaude 폴더 안에서
touch .env

# VS Code 로 편집
code .env

3-2. 가진 키 모두 등록

.env 파일에 아래 형식으로. 콜론(:)이 아니라 등호(=) 임에 주의.

# 가진 키만 등록. 모르는 건 빈 줄로 두면 됨.
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
DEEPSEEK_API_KEY=sk-...
GROQ_API_KEY=gsk_...

# 로컬 올라마 사용 시 (Step 7 에서 다룸)
OLLAMA_HOST=http://localhost:11434

3-3. .gitignore 등록 (필수)

키가 그대로 깃허브에 푸시되는 사고를 막기 위해 .gitignore 에 한 줄 추가.

echo ".env" >> .gitignore

⚠️ 주의: 이미 .env 를 커밋해 버렸다면 git rm --cached .env 로 추적에서 빼고 git commit -am "remove .env from tracking".gitignore 등록. 이미 푸시했다면 즉시 해당 키들 폐기 후 재발급.

3-4. 영구 환경 변수로 등록 (선택)

매번 cd openclaude 하기 귀찮으면 윈도우 시스템 환경 변수에 직접 등록.

  1. 윈도우 시작 메뉴에서 "환경 변수" 검색 → "시스템 환경 변수 편집" 클릭
  2. 우측 하단 "환경 변수" 버튼 → "사용자 변수" 영역의 "새로 만들기"
  3. 변수 이름: OPENAI_API_KEY, 변수 값: sk-... 식으로 등록
  4. 모든 창 확인 누르고 닫기 → 터미널 재시작

Step 3-B — API 키 대신 구독 기반 OAuth 로그인 (선택)

API 키 종량제 대신 이미 가지고 있는 구독을 그대로 쓰고 싶다면 OAuth 로그인 옵션이 있습니다. 클로드 프로($20/월) · 챗GPT 플러스($20/월) · 깃허브 코파일럿 비즈니스($19/월) 같은 정액 구독에 포함된 사용량을 같은 CLI 안에서 호출할 수 있습니다.

A. 클로드 프로/맥스 구독 OAuth (가장 자주 쓰는 길)

오픈클로는 클로드 코드 본체를 그대로 가져온 만큼 claude login 흐름이 살아 있습니다.

./openclaude login anthropic
# 브라우저가 자동으로 열림 → console.anthropic.com 로그인
# → 권한 승인 → 토큰이 ~/.openclaude/auth.json 에 자동 저장

이후 ANTHROPIC_API_KEY 환경 변수가 없어도 클로드 모델이 동작하고, 사용량은 클로드 프로/맥스 구독 한도 안에서 차감됩니다.

⚠️ 주의: 클로드 프로 구독은 시간당 메시지 수 제한이 있습니다 (5시간당 약 45 메시지). 클로드 맥스($100/월)는 약 5배. 한도 초과 시 일시 차단되니 무거운 작업은 API 키 종량제로 대체.

B. 챗GPT 플러스 / 코덱스 구독 OAuth

OpenAI 의 codex CLI 가 OAuth 로그인을 지원하고, 오픈클로는 그 토큰을 그대로 인식합니다.

# 코덱스 CLI 먼저 설치
npm install -g @openai/codex

# 챗GPT 계정으로 OAuth 로그인
codex login
# 브라우저 → chatgpt.com 로그인 → 권한 승인

# 오픈클로에서 코덱스 라우팅 사용
./openclaude --model codex:gpt-5
# 또는 슬래시 커맨드로
> /model codex:gpt-5

토큰은 ~/.codex/auth.json 에 저장되고, 사용량은 챗GPT 플러스/팀 구독에서 차감.

⚠️ 주의: 챗GPT 플러스 구독으로 호출할 수 있는 모델은 OpenAI 가 제한합니다 (GPT-5·GPT-4.1·o4-mini 등). API 전용 모델(특수 파인튜닝 등)은 OAuth 로 못 부름.

C. 깃허브 코파일럿 비즈니스/엔터프라이즈 OAuth

코파일럿 구독자는 깃허브 모델스(GitHub Models) 를 통해 여러 모델에 접근할 수 있습니다. 오픈클로는 이걸 그대로 라우팅.

# gh CLI 로 로그인
gh auth login
# 깃허브 토큰이 ~/.config/gh/hosts.yml 에 저장

# 오픈클로에서 깃허브 모델스 호출
./openclaude --model gh:gpt-4o
./openclaude --model gh:claude-sonnet-4.6
./openclaude --model gh:llama-4-405b

⚠️ 주의: 깃허브 코파일럿 무료 플랜(개인)은 모델스 기능이 제한됩니다. 비즈니스/엔터프라이즈 구독자만 풀 라우팅 사용 가능.

D. 토큰 저장 위치 정리 (윈도우)

구독 토큰 저장 위치 (윈도우)
클로드 프로/맥스 %USERPROFILE%\.openclaude\auth.json
챗GPT 플러스 (Codex) %USERPROFILE%\.codex\auth.json
깃허브 코파일럿 (gh) %USERPROFILE%\AppData\Roaming\gh\hosts.yml

세 토큰은 모두 평문 JSON 또는 YAML 입니다. 타인과 공유 금지, 회사 노트북이면 BitLocker 등으로 디스크 암호화 권장.


이미지: Claude Code 공식 Docs (출처: code.claude.com/docs/en/overview)

Step 4 — 첫 실행과 모델 선택

이제 오픈클로를 실행하면서 첫 모델을 지정합니다.

4-1. 기본 실행

# openclaude 폴더 안에서
./openclaude

처음 뜨면 환영 메시지와 함께 모델 선택 프롬프트가 나옵니다. 등록된 키 기준으로 사용 가능한 모델 목록이 표시됩니다.

4-2. 처음부터 특정 모델로 시작

./openclaude --model claude-sonnet-4.6
./openclaude --model gpt-5
./openclaude --model gemini-2.5-pro
./openclaude --model deepseek-v4

4-3. CLI 안에서 모델 갈아끼우기

CLI 에 진입한 뒤에는 슬래시 커맨드로 즉시 교체 가능.

> /model gemini-2.5-pro
모델 변경: gemini-2.5-pro
> 현재 폴더의 코드 구조를 분석해 줘
[Gemini 2.5 Pro 응답...]
> /model deepseek-v4
모델 변경: deepseek-v4
> 위 분석을 바탕으로 README.md 초안을 만들어 줘
[DeepSeek V4 응답...]

⚠️ 주의: 처음 호출은 모델 콜드 스타트로 5~15초 걸릴 수 있음. 두 번째부터는 1~3초로 빨라집니다.


이미지: Model Context Protocol 공식 문서 — MCP 아키텍처 (출처: modelcontextprotocol.io)

Step 5 — 클로드 코드 MCP 설정 그대로 가져오기

클로드 코드를 이미 쓰고 있다면 %USERPROFILE%\.claude.json 의 MCP 설정이 거의 그대로 인식됩니다. Git Bash 에서 한 줄 복사.

# 윈도우의 %USERPROFILE% = Git Bash 의 ~ 또는 $HOME
cp ~/.claude.json ~/.openclaude.json

확인:

ls -la ~/.openclaude.json
# -rw-r--r-- 1 사용자 사용자 ... .openclaude.json

오픈클로 안에서 MCP 상태 확인:

> /mcp
연결된 MCP 서버:
  ✓ filesystem
  ✓ memory
  ✓ context7
  ✓ github

새 MCP 를 추가하고 싶으면:

> /mcp add playwright npx @playwright/mcp@latest
✓ playwright MCP 연결됨

⚠️ 주의: MCP 서버 중 일부는 클로드 모델 컨텍스트에 최적화돼 있어, 다른 모델(특히 8B 이하 소형)에서는 도구 호출이 깨질 수 있습니다. 클로드 소넷 4.6 · GPT-5 · 제미나이 2.5 프로 같은 도구 호출 안정성 상위 모델을 우선 사용.


이미지: Claude Code Skills/슬래시 커맨드 docs (출처: code.claude.com/docs/en/slash-commands)

Step 6 — 자주 쓰는 슬래시 커맨드 익히기

오픈클로 안에서 가장 자주 쓰게 될 명령들.

📖 슬래시 커맨드 핵심 6종
/model: 활성 모델 즉시 교체. ``/model gpt-5`` ``/model ollama:hermes-4`` 식.
/mcp: MCP 서버 관리(목록·추가·제거).
/init: 현재 폴더에 ``CLAUDE.md`` 자동 생성. 오픈클로도 이 파일을 읽음.
/save: 작업 상태 스냅샷 저장. 다음 세션에서 ``/restore`` 로 복구 가능.
/clear: 컨텍스트 초기화. 새 작업 시작 시.
/help: 사용 가능한 모든 명령 목록 표시.

실전 예시:

> /init
✓ CLAUDE.md 생성됨 (123 줄, 프로젝트 구조 자동 감지)

> 이 프로젝트의 테스트를 한번 돌려 줘
[모델이 package.json 읽고 npm test 실행]

> /save
✓ 스냅샷 저장: 2026-04-28-15-30-snapshot.json

> /clear
컨텍스트 초기화 완료

> /restore 2026-04-28-15-30-snapshot.json
✓ 이전 세션 복구

이미지: Ollama for Windows 다운로드 페이지 (출처: ollama.com/download/windows)

Step 7 — Ollama 로컬 모델 추가 (선택, RTX 4090 권장)

24GB GPU 가 있다면 로컬 모델을 띄워 클라우드 비용을 줄일 수 있습니다.

7-1. Ollama 설치 (윈도우)

  1. ollama.com/download/windows 접속 → OllamaSetup.exe 다운
  2. 다운받은 파일 더블 클릭 → 설치 (관리자 권한 필요)
  3. 설치 끝나면 시스템 트레이(우측 하단)에 Ollama 라마 아이콘 등장

7-2. 모델 다운

PowerShell 또는 Git Bash 에서:

# Hermes 4 35B Q4KM (약 20GB)
ollama pull hermes-4:35b-q4_k_m

# 또는 큐웬 3 코더 32B (코딩 특화, 약 19GB)
ollama pull qwen3-coder:32b-q4_k_m

# 다운 확인
ollama list

⚠️ 주의: 35B Q4KM 은 디스크 약 20GB · VRAM 약 22GB. RTX 4090 24GB 한 장이면 컨텍스트 8K~16K 까지 안정적, 그 이상 쓰면 OOM 위험. 컨텍스트 크게 쓸 거면 Q4KS(15GB) 또는 Q3KM(13GB) 같은 더 작은 양자화로.

7-3. 오픈클로에서 Ollama 모델 호출

Ollama 가 http://localhost:11434 에서 자동으로 떠 있으면 오픈클로가 인식합니다.

> /model ollama:hermes-4:35b-q4_k_m
모델 변경: ollama:hermes-4:35b-q4_k_m (로컬 추론)
> 이 함수 리팩터링 해 줘
[로컬 추론 응답... 5~15초]

VRAM 사용량 모니터링은 PowerShell 에서:

nvidia-smi
# Mem-Usage 칸에서 22000MiB / 24576MiB 같이 표시

이미지: Ollama 모델 라이브러리 카탈로그 (출처: ollama.com/library)

결과 확인 — 정상 동작 체크

아래 5가지가 모두 동작하면 세팅 성공입니다.

  • 🟢 버전 출력 — Git Bash 에서 ./openclaude --version 이 버전 문자열 반환
  • 🟢 모델 갈아끼우기 — CLI 안에서 /model 로 두 개 이상 모델 사이 자유 이동
  • 🟢 MCP 상태/mcp 명령이 등록된 MCP 서버 목록 표시
  • 🟢 첫 작업 응답 — "현재 폴더 코드 구조 요약해 줘" 같은 간단 작업 정상 응답
  • 🟡 (옵션) Ollama/model ollama:hermes-4:35b-q4_k_m 로컬 추론 응답 확인 (GPU 보유 시만)
# 한 번에 점검
./openclaude --version
./openclaude --models  # 사용 가능 모델 전체 목록

문제 해결 (FAQ — 윈도우 환경 위주)

Q. ./openclaudepermission denied 로 실행 안 됩니다. A. Git Bash 에서 chmod +x ./openclaude 한 번 실행. 또는 node bin/openclaude.js 로 직접 호출. PowerShell 에서는 .\openclaude 로 슬래시 방향만 바꾸면 됩니다.

Q. npm installEACCES 권한 에러로 실패합니다. A. 관리자 PowerShell 로 실행하지 말고 일반 사용자 권한으로. 그래도 실패하면 Node.js 를 %USERPROFILE%\AppData\Local\nvm 같은 사용자 영역에 다시 설치(nvm-windows 사용).

Q. ./openclaudeAPI key not found 로 종료됩니다. A. .env 파일 위치가 잘못됐을 가능성. 오픈클로는 실행 디렉터리의 .env 만 자동 인식합니다. cd openclaude 후 실행하거나 --env-file C:/path/to/.env 플래그로 절대경로 지정.

Q. Ollama 모델이 Connection refused 로 안 잡힙니다. A. 시스템 트레이의 Ollama 아이콘이 켜져 있는지 확인. 안 보이면 시작 메뉴에서 "Ollama" 검색 후 실행. curl http://localhost:11434 로 응답이 와야 정상.

Q. /mcp 가 클로드 코드용 MCP 를 못 찾습니다. A. cp ~/.claude.json ~/.openclaude.json 이 제대로 실행됐는지 확인. ls -la ~/.openclaude.json 으로 파일 존재 확인. 또는 프로젝트 루트의 .mcp.json 으로 옮겨서 인식시켜도 됩니다.

Q. 윈도우 방화벽이 오픈클로 네트워크 호출을 막습니다. A. 처음 실행 시 윈도우 디펜더 경고가 뜨면 "액세스 허용" 클릭. 사내 망이면 IT 팀에 api.openai.com·api.anthropic.com·api.deepseek.com·generativelanguage.googleapis.com 화이트리스트 요청.

Q. 깃허브 모델스(GitHub Models) 무료 한도를 어떻게 쓰나요? A. gh auth login 으로 깃허브 로그인 후 GITHUB_TOKEN 환경 변수에 토큰 등록. /model gh:gpt-4o 같은 형식으로 깃허브 모델스 라우팅 호출.


한국 개발자가 점검할 것

당장 챙겨야 할 포인트가 셋입니다.

보안 검토가 1순위입니다. 오픈클로는 비공식 포크라 npm audit 한 번은 돌려보고 사내 도입을 결정하는 게 안전합니다. 멀티 프로바이더 어댑터에서 외부 도메인이 늘어난 만큼 회사망 화이트리스트도 다시 봐야 합니다.

비용 추적도 미리 잡아두면 좋습니다. 한 CLI 에서 5~6개 프로바이더를 동시에 쓰다 보면 어디서 토큰을 얼마나 쓴지 가시성이 떨어집니다. 헬리콘(Helicone) · 랭퓨즈(Langfuse) 같은 옵저버빌리티 프록시를 OPENAI_BASE_URL 환경 변수로 끼우는 게 가장 깔끔.

마지막으로 MCP 서버 재활용입니다. 사내에서 클로드 코드용으로 만든 MCP 서버가 있다면 거의 그대로 오픈클로에 붙습니다. 같은 도구 위에 모델만 갈아끼우는 식으로 점진적 마이그레이션 가능.


다음 단계

이 가이드를 마쳤다면 아래 자료로 한 단계 더.


내 생각

저의 경우 오픈클로 깐 첫날 가장 좋았던 게 이미 쓰던 .mcp.json 을 한 줄도 안 고치고 그대로 가져왔다 는 점입니다. 클로드 코드에서 정성스럽게 깔아 둔 컨텍스트7·플레이라이트·필레시스템 MCP 가 그대로 인식됐고, 모델만 /model deepseek-v4 로 바꿨더니 같은 도구 위에서 절반 가격에 작업이 굴러갔습니다.

한 가지 경계할 점은 비공식 프로젝트의 라이프사이클입니다. 깃허브 스타가 빠르게 붙는다고 해서 보안 패치까지 빠른 건 아닙니다. 한국 기업이 도입할 거라면 핵심 의존성 버전은 사내에서 핀(pin)으로 고정하고, 한 달에 한 번씩 업스트림 변경을 검토하는 흐름을 짜두는 게 안전합니다. 그리고 클로드 코드 원본 약관도 사내 법무가 한 번 봐야 합니다 — 사내 상업 코드베이스에 코딩 에이전트로 깊이 들어가는 도구라 라이선스 잘못 해석하면 손해가 큽니다.

오늘 저녁 한번 깔아서 클로드 소넷·딥시크 V4·큐웬 3 코더를 같은 CLI 안에서 비교해 보겠습니다. 그럼 이만~


출처: Gitlawb/openclaude (GitHub README), 클로드 코드 공식 문서, Ollama for Windows, Node.js 공식, Git for Windows