Windows에서 Claude Code 또는 Codex로 시작하기

Windows에서 Claude Code 또는 Codex로 ClinicOS 시작하기

이 문서는 3기 워크숍의 권장 Windows 네이티브 경로입니다. 일반 Windows 터미널에서 ClinicOS를 편집·빌드하고 Cloudflare Pages/D1/R2에 바로 배포합니다. Codex 앱, Codex Cloud, WSL은 선택 사항이며 필수 준비물이 아닙니다.

기존 Claude Code + macOS/WSL/Codespaces 설치본은 classic 경로를 그대로 사용합니다. 기존 설치본의 프로파일을 임의로 바꾸지 마세요.

준비물

구분	필요한 것	확인 방법
Windows	Windows 11 권장, 최신 Windows 10은 파일럿 범위	Windows 업데이트 확인
개발 도구	Node.js LTS, Git for Windows	`node --version`, `npm.cmd --version`, `git --version`
저장소	클리닉 전용 비공개 GitHub 저장소	`git remote -v`
배포	이메일 인증을 마친 Cloudflare 계정, R2 활성화, 최소권한 API Token	`npm.cmd run cloudflare:status`
메인 에이전트	Claude Code 또는 Codex 중 하나	`claude --version` 또는 `codex --version`
이미지 작업	클리닉 소유 ChatGPT/Codex 이미지 기능	이미지 온보딩 때 별도 확인

Claude Code와 Codex를 둘 다 설치할 필요는 없습니다. Claude Code는 CLAUDE.md, Codex는 AGENTS.md에서 시작하지만 두 문서는 .agent/AGENT_RUNTIME.md와 같은 작업 도구, 워크플로, 상태 및 보호 규칙으로 연결됩니다.

1. Windows와 기본 도구 준비

Windows 업데이트를 완료하고 재부팅합니다.
Node.js LTS와 Git for Windows를 설치합니다. 공식 Windows 패키지 관리자를 사용하면

winget install --id OpenJS.NodeJS.LTS, winget install --id Git.Git입니다.

Git for Windows를 기본 옵션으로 설치합니다. Claude Code는 네이티브 Windows에서

Git Bash를 내부 명령 셸로 사용할 수 있으므로 Git for Windows 설치가 특히 중요합니다.

새 터미널을 열고 다음을 확인합니다.

   node --version
   npm.cmd --version
   git --version

프로젝트는 C:\ClinicOS\내한의원처럼 로컬 드라이브의 짧고 명확한 폴더에 둡니다. OneDrive 동기화 폴더, 네트워크 드라이브, 임시 다운로드 폴더는 피합니다. 공백이 포함된 경로는 실기 검증을 통과했지만 첫 설치에서는 단순한 경로가 문제 해결에 유리합니다.

2. Git 신원과 GitHub 연결

Git 커밋에 표시할 이름과 이메일을 한 번 설정합니다.

git config --global user.name "이름"
git config --global user.email "GitHub 이메일"

워크숍에서 만든 비공개 저장소를 내려받거나 지정된 폴더를 엽니다. 에이전트는 작업 전에 현재 폴더, git status, git remote -v를 확인하고 다른 클리닉 저장소가 아닌지 검증합니다.

3. 메인 에이전트 하나 설치

Claude Code를 선택한 경우

공식 Claude Code Windows 설치 안내에 따라 네이티브 버전을 설치하고 로그인합니다.

winget install Anthropic.ClaudeCode
claude auth login
claude auth status

Git for Windows가 기본 경로가 아니라면 Claude Code가 Git Bash 위치를 찾지 못할 수 있으므로 공식 설정의 CLAUDE_CODE_GIT_BASH_PATH 안내를 따릅니다. 프로젝트 폴더에서 claude를 실행하면 CLAUDE.md가 진입 문서가 됩니다.

Codex를 선택한 경우

공식 Codex CLI 또는 ChatGPT Windows 앱 중 하나를 설치하고 ChatGPT 계정으로 로그인합니다. Windows 앱의 현재 공식 명령줄 설치 경로는 다음과 같습니다.

winget install --id 9PLM9XGG6VKS -s msstore
codex login
codex login status

codex login은 브라우저를 열어 각 원장님의 ChatGPT 구독 계정으로 인증합니다. 인증 캐시는 비밀번호와 같은 자격 증명이므로 복사·공유·Git 커밋하지 않습니다. API 키 방식은 사용량 기반 별도 과금이므로 3기 기본 온보딩에서는 선택하지 않습니다.

CLI는 프로젝트 폴더에서 codex로 시작하며 AGENTS.md를 읽습니다. Windows 앱을 사용할 경우 기본 네이티브 에이전트는 PowerShell에서 실행되며, 통합 터미널 선택과 에이전트 실행 환경은 서로 별도입니다. ClinicOS 때문에 WSL로 변경할 필요는 없습니다.

Codex의 Windows 네이티브 샌드박스는 가능한 경우 elevated가 권장됩니다. 전체 접근 모드를 상시 사용하지 말고 프로젝트 폴더 경계와 승인 정책을 유지합니다.

4. 프로젝트별 Windows 프로파일 저장

HQ에서 내려받은 서명된 Starter ZIP을 로컬 드라이브의 전용 폴더에 풉니다. 일반 공개 Core ZIP이나 다른 클리닉의 clinic.json을 복사한 폴더는 신규 설치 입력물이 아닙니다. 프로젝트 폴더에서 프로파일만 먼저 저장합니다.

npm.cmd run workshop:profile -- windows-native
npm.cmd run workshop:profile -- --show

windows:canary는 Git 초기화와 로그인까지 확인하는 마지막 설치 확인입니다. ZIP을 막 푼 시점에는 Git 저장소가 아직 없으므로 먼저 실행하지 않습니다. Academy 학습 상태는 이 검사를 막지 않습니다.

이전 자동화용 academy:windows-canary 명령도 같은 독립 검사로 계속 동작하지만, 새 문서와 설치에서는 windows:canary를 사용합니다.

이 선택은 Git에 올라가지 않는 .agent/workshop-runtime.local.json에 프로젝트별로 저장됩니다. 새 터미널이나 에이전트 앱을 다시 열어도 유지되며 같은 PC의 기존 classic 클라이언트에는 영향을 주지 않습니다.

setx CLINIC_WORKSHOP_PROFILE ...처럼 Windows 사용자 전체에 영구 환경변수를 설정하지 마세요. 긴급한 일회성 시험에서는 환경변수가 프로젝트 설정보다 우선하지만, 정상 설치는 위 프로젝트별 명령을 사용합니다.

5. 의존성·계정 사전 점검

npm.cmd install
npm.cmd run doctor -- --step node
npm.cmd run doctor -- --step git
npm.cmd run workshop:profile -- windows-native
npm.cmd run cloudflare:setup
npm.cmd run cloudflare:status -- --verify

현재 발급 Starter에는 루트 lockfile이 없으므로 첫 설치는 npm.cmd install을 사용합니다. npm.cmd ci로 시작하지 않습니다. cloudflare:setup이 연 숨김 입력란에 원장님이 토큰을 직접 붙여 넣습니다. 입력한 문자는 화면과 터미널 기록에 표시되지 않으며, 도구는 실제 Cloudflare API로 토큰과 계정을 확인한 뒤 이 프로젝트의 Git 제외 .env에만 저장합니다. 토큰을 에이전트 채팅이나 명령 인자에 붙여 넣지 마세요.

이 로컬 저장은 재부팅 뒤에도 같은 클리닉의 설치·배포를 이어가기 위한 것입니다. .env는 Git에 올라가지 않으며 setup/deploy는 그중 CLOUDFLARE_API_TOKEN과 CLOUDFLARE_ACCOUNT_ID와 클리닉별 Preview 검증 시크릿만 읽습니다. Preview 검증 시크릿은 setup이 별도 랜덤 값으로 만들며 Cloudflare API Token을 재사용하지 않습니다. setx나 Windows 사용자 전체 환경변수에는 저장하지 않고, 다른 클리닉 폴더로 복사하지 않습니다. 확인 명령은 다음과 같습니다.

git check-ignore .env
git ls-files .env

이 두 Git 명령은 setup이 Git 저장소를 만든 뒤 실행합니다. 첫 명령은 .env를 출력해야 하고 두 번째 명령은 아무것도 출력하지 않아야 합니다. 기존 classic 설치에서 정상 작동하는 wrangler login OAuth는 그대로 유지할 수 있습니다.

6. 에이전트에게 설치 위임

다음처럼 요청합니다.

네 진입 문서와 .agent/AGENT_RUNTIME.md를 먼저 읽어줘.
이 프로젝트의 windows-native 설정을 유지하고 초기 준비 상태를 진단해줘.
로컬 D1이나 npm run dev는 실행하지 말고, 클리닉 전용 Cloudflare 리소스만 사용해
설치와 배포 안전 체크를 완료한 뒤 pages.dev 주소에서 확인해줘.
커스텀 도메인은 아직 연결하지 마.

에이전트는 .agent/workflows/windows-native-setup.md를 따라 다음 순서로 진행합니다.

현재 Windows·Node·Git·저장소·프로파일 확인
GitHub와 Cloudflare 대상 계정 확인
서명된 Starter의 HQ 인증과 설치/재개
클리닉 전용 Pages/D1/R2 준비와 원격 데이터 초기화
관리자 계정 생성, 빌드, 배포 안전 체크
*.pages.dev 공개 페이지와 관리자 로그인 확인
Git 체크포인트와 설치 상태 기록

설치 단계가 Git과 Core upstream을 연결한 뒤 아래 최종 확인을 수행합니다. 선택한 에이전트 하나만 사용하며, Claude Code라면 --agent claude-code로 바꿉니다. 아래는 stable Starter 기준입니다. clinic.json의 channel이 beta라면 두 Core 명령을 core:pull:beta로 바꿉니다.

npm.cmd run windows:canary -- --agent codex
npm.cmd run core:pull -- --dry-run
npm.cmd run core:pull
npm.cmd run build
npm.cmd run deploy

canary는 에이전트 실행 파일뿐 아니라 실제 로그인, Node/npm/Git, Git 저장소, 깨끗한 체크포인트를 모두 확인합니다. 실패 항목을 우회한 채 Core Pull이나 배포로 넘어가지 않습니다.

관리자 이메일과 초기 비밀번호는 설치 직전에만 전달합니다. 비밀번호를 setx로 저장하거나 Git에 기록하지 않으며 첫 로그인 후 변경합니다.

7. Windows 네이티브 운영 규칙

PowerShell에서는 npm 대신 npm.cmd, npx 대신 npx.cmd를 우선 사용합니다.
npm run dev, 로컬 D1, wrangler dev, workerd는 실행하지 않습니다.
확인은 배포 안전 체크를 통과한 Cloudflare Pages URL에서 합니다.
wrangler.toml, clinic.json, .env, HQ 설치 토큰과 Cloudflare 토큰을 Git에 커밋하지 않습니다.
Production 브랜치 배포는 가능하지만 승인 전 커스텀 도메인은 연결하지 않습니다.
core:pull 전후에 Git 상태와 클리닉 전용 _local/local 영역 보존을 확인합니다.
기존 classic 설치본에는 windows-native 설정을 추가하지 않습니다.

다시 시작할 때

새 터미널이나 재부팅 후에는 프로젝트 폴더에서 선택한 에이전트만 다시 실행하면 됩니다. 프로파일은 프로젝트에 저장되어 있고 GitHub·Cloudflare 로그인은 각각의 도구가 관리합니다. 에이전트는 먼저 아래 상태를 확인한 뒤 중단된 설치를 이어갑니다.

npm.cmd run workshop:profile -- --show
npm.cmd run windows:canary -- --agent codex
npm.cmd run agent:doctor -- --json
npm.cmd run setup:step -- --status

선택 경로

WSL2: 기존 Linux 로컬 개발이 필요하면 classic 프로파일로 계속 지원합니다.
Codespaces: 기존 워크숍 참가자와 운영 클라이언트를 위해 계속 지원합니다.
Codex Cloud: 로컬 PC에서 에이전트 실행이 곤란할 때 codex-cloud 원격 전용 프로파일을

선택할 수 있습니다.

공식 참고

Codex CLI: https://learn.chatgpt.com/docs/codex/cli
ChatGPT Windows 앱: https://learn.chatgpt.com/docs/windows/windows-app
Codex Windows 샌드박스: https://learn.chatgpt.com/docs/windows/windows-sandbox
Claude Code Windows 설치: https://code.claude.com/docs/en/setup