← 전체 가이드로 돌아가기
06. 설치하기
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 공식 MSI, Git for Windows | `node --version`, `git --version` |
| 저장소 | 클리닉 전용 비공개 GitHub 저장소 | `git remote -v` |
| 배포 | 이메일 인증을 마친 Cloudflare 계정, R2 활성화 | `npx.cmd wrangler whoami` |
| 메인 에이전트 | 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와 기본 도구 준비
1. Windows 업데이트를 완료하고 재부팅합니다.
2. Node.js 공식 사이트에서 현재 LTS의 Windows Installer를 설치합니다.
3. Git for Windows를 기본 옵션으로 설치합니다. Claude Code는 네이티브 Windows에서
Git Bash를 내부 명령 셸로 사용할 수 있으므로 Git for Windows 설치가 특히 중요합니다.
4. 새 터미널을 열고 다음을 확인합니다.
```powershell
node --version
npm.cmd --version
git --version
```
프로젝트는 `C:\ClinicOS\내한의원`처럼 로컬 드라이브의 짧고 명확한 폴더에 둡니다.
OneDrive 동기화 폴더, 네트워크 드라이브, 임시 다운로드 폴더는 피합니다. 공백이 포함된
경로는 실기 검증을 통과했지만 첫 설치에서는 단순한 경로가 문제 해결에 유리합니다.
## 2. Git 신원과 GitHub 연결
Git 커밋에 표시할 이름과 이메일을 한 번 설정합니다.
```powershell
git config --global user.name "이름"
git config --global user.email "GitHub 이메일"
```
워크숍에서 만든 비공개 저장소를 내려받거나 지정된 폴더를 엽니다. 에이전트는 작업 전에
현재 폴더, `git status`, `git remote -v`를 확인하고 다른 클리닉 저장소가 아닌지 검증합니다.
## 3. 메인 에이전트 하나 설치
### Claude Code를 선택한 경우
공식 Claude Code Windows 설치 안내에 따라 네이티브 버전을 설치하고 로그인합니다.
Git for Windows가 기본 경로가 아니라면 Claude Code가 Git Bash 위치를 찾지 못할 수 있으므로
공식 설정의 `CLAUDE_CODE_GIT_BASH_PATH` 안내를 따릅니다. 프로젝트 폴더에서 `claude`를
실행하면 `CLAUDE.md`가 진입 문서가 됩니다.
### Codex를 선택한 경우
공식 Codex CLI 또는 ChatGPT Windows 앱 중 하나를 설치하고 ChatGPT 계정으로 로그인합니다.
일반 Windows 터미널에서 CLI를 설치하는 현재 공식 명령은 다음과 같습니다.
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex login
codex login status
```
`codex login`은 브라우저를 열어 각 원장님의 ChatGPT 구독 계정으로 인증합니다. 인증 캐시는
비밀번호와 같은 자격 증명이므로 복사·공유·Git 커밋하지 않습니다. API 키 방식은 사용량 기반
별도 과금이므로 3기 기본 온보딩에서는 선택하지 않습니다.
CLI는 프로젝트 폴더에서 `codex`로 시작하며 `AGENTS.md`를 읽습니다. Windows 앱을 사용할
경우 기본 네이티브 에이전트는 PowerShell에서 실행되며, 통합 터미널 선택과 에이전트 실행
환경은 서로 별도입니다. ClinicOS 때문에 WSL로 변경할 필요는 없습니다.
Codex의 Windows 네이티브 샌드박스는 가능한 경우 `elevated`가 권장됩니다. 전체 접근 모드를
상시 사용하지 말고 프로젝트 폴더 경계와 승인 정책을 유지합니다.
## 4. 프로젝트별 Windows 프로파일 저장
스타터를 받은 뒤 프로젝트 폴더에서 다음을 한 번 실행합니다.
```powershell
npm.cmd run workshop:profile -- windows-native
npm.cmd run workshop:profile -- --show
npm.cmd run academy:windows-canary -- --agent codex
```
Claude Code를 선택했다면 마지막 인자만 `--agent claude-code`로 바꿉니다. 이 검사는 선택한
에이전트 설치, Git, 양쪽 진입 문서, 공통 런타임·스킬 레지스트리, 원격 전용 가드와 첫 미션
호환성을 확인할 뿐 로그인 토큰이나 터미널 로그를 HQ로 전송하지 않습니다.
이 선택은 Git에 올라가지 않는 `.agent/workshop-runtime.local.json`에 프로젝트별로
저장됩니다. 새 터미널이나 에이전트 앱을 다시 열어도 유지되며 같은 PC의 기존 `classic`
클라이언트에는 영향을 주지 않습니다.
`setx CLINIC_WORKSHOP_PROFILE ...`처럼 Windows 사용자 전체에 영구 환경변수를 설정하지
마세요. 긴급한 일회성 시험에서는 환경변수가 프로젝트 설정보다 우선하지만, 정상 설치는
위 프로젝트별 명령을 사용합니다.
## 5. 의존성·계정 사전 점검
```powershell
npm.cmd ci
npm.cmd run doctor -- --step node
npm.cmd run doctor -- --step git
npx.cmd wrangler whoami
```
`npm ci`가 lockfile 문제로 실패할 때만 에이전트가 원인을 확인한 뒤 `npm.cmd install`을
선택합니다. `wrangler whoami`가 미로그인 상태라면 에이전트가 `npx.cmd wrangler login`을
실행하고, 열린 브라우저에서 원장님이 본인 Cloudflare 계정으로 승인합니다.
브라우저 로그인이 불가능한 워크숍 환경에서는 클리닉별 최소권한 토큰을 현재 세션에만
설정할 수 있습니다. 토큰을 채팅, Git, 문서, `.env`에 남기지 않고 다른 클리닉과 공유하지
않습니다.
## 6. 에이전트에게 설치 위임
다음처럼 요청합니다.
```text
네 진입 문서와 .agent/AGENT_RUNTIME.md를 먼저 읽어줘.
이 프로젝트의 windows-native 설정을 유지하고 초기 준비 상태를 진단해줘.
로컬 D1이나 npm run dev는 실행하지 말고, 클리닉 전용 Cloudflare 리소스만 사용해
설치와 배포 안전 체크를 완료한 뒤 pages.dev 주소에서 확인해줘.
커스텀 도메인은 아직 연결하지 마.
```
에이전트는 `.agent/workflows/windows-native-setup.md`를 따라 다음 순서로 진행합니다.
1. 현재 Windows·Node·Git·저장소·프로파일 확인
2. GitHub와 Cloudflare 대상 계정 확인
3. HQ 인증과 스타터 설치/재개
4. 클리닉 전용 Pages/D1/R2 준비와 원격 데이터 초기화
5. 관리자 계정 생성, 빌드, 배포 안전 체크
6. `*.pages.dev` 공개 페이지와 관리자 로그인 확인
7. Git 체크포인트와 설치 상태 기록
관리자 이메일과 초기 비밀번호는 설치 직전에만 전달합니다. 비밀번호를 `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`, HQ 설치 토큰과 Cloudflare 토큰을 Git에 커밋하지 않습니다.
- Production 브랜치 배포는 가능하지만 승인 전 커스텀 도메인은 연결하지 않습니다.
- `core:pull` 전후에 Git 상태와 클리닉 전용 `_local`/`local` 영역 보존을 확인합니다.
- 기존 `classic` 설치본에는 `windows-native` 설정을 추가하지 않습니다.
## 다시 시작할 때
새 터미널이나 재부팅 후에는 프로젝트 폴더에서 선택한 에이전트만 다시 실행하면 됩니다.
프로파일은 프로젝트에 저장되어 있고 GitHub·Cloudflare 로그인은 각각의 도구가 관리합니다.
에이전트는 먼저 아래 상태를 확인한 뒤 중단된 설치를 이어갑니다.
```powershell
npm.cmd run workshop:profile -- --show
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
