설치와 시작 가이드

# 설치와 시작 가이드 Clinic-OS는 **Claude Code 또는 Codex 중 선택한 메인 에이전트가 설치를 진행**합니다. 사용자는 환경을 열고, 선택한 에이전트에게 "설치해줘"라고 요청하면 됩니다. 두 에이전트는 같은 스킬과 안전 규칙을 사용합니다. > **총 소요 시간**: 처음부터 기본 홈페이지 확인까지 **약 7~10분** --- ## 시작하기 전에 설치를 시작하기 전에 아래 5가지를 준비하세요. | 준비물 | 설명 | 주소 | |--------|------|------| | **GitHub 계정** | 스타터킷 다운로드, Codespaces 사용 (무료) | [github.com](https://github.com) | | **Cloudflare 계정** | 사이트 배포용 (무료 티어) | [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) | | **메인 에이전트 계정** | Claude Code 또는 Codex 중 하나를 선택해 코딩·운영 | [claude.ai](https://claude.ai) / [chatgpt.com](https://chatgpt.com) | | **ChatGPT/Codex 이미지 기능** | 이미지 작업 시 실제 생성 검증 필수. Codex 메인은 네이티브 기능, Claude Code 메인은 Codex 어댑터 사용 | [chatgpt.com](https://chatgpt.com) | | **한의원 기본 정보** | 상호, 주소, 전화, 진료시간, 의료진 프로필 | , | > 설치 시간: **Codespaces 7~10분** / macOS 로컬 약 20분 / Windows 네이티브·WSL은 환경 준비 시간에 따라 달라집니다. > > 전체 지원 범위와 Windows 셸별 주의사항은 **[지원 환경과 Windows 설치](/guides/supported-environments)**를 기준으로 합니다. --- ## 개발 환경 선택하기 ### 추천: GitHub Codespaces **설치할 것이 없습니다.** 브라우저만 있으면 됩니다. 클라우드에 Node.js와 개발 도구가 이미 준비된 환경이 2~3분 안에 만들어집니다. 설치 없이 가장 빨리 시작하려는 경우 Codespaces를 권장합니다. Windows에서도 아래의 네이티브 Windows 또는 WSL Ubuntu 경로를 선택할 수 있습니다. #### 1단계 · 내 레포 만들기 (30초) 브라우저에서 워크숍 템플릿 저장소에 접속: **`github.com/xulfereht/clinic-os-workshop`** 상단의 초록색 **"Use this template"** 버튼 → **"Create a new repository"** 선택 → 본인 GitHub 계정에 새 레포 생성: - Repository name: `clinic-os-{내한의원이름}` (예: `clinic-os-baekrokdam`) - **Public / Private**: **Private 권장** (한의원 데이터 보호) > ⚠️ **워크샵 템플릿 레포에서 직접 Codespace를 만들지 마세요.** 그러면 작업을 `git push`로 백업할 수 없습니다. 반드시 위 단계로 **내 레포**를 먼저 만들고 거기서 Codespace를 여세요. #### 2단계 · 내 레포에서 Codespace 열기 (2~3분) 방금 만든 **내 레포**로 이동 → 초록색 **`< > Code`** 버튼 → **Codespaces** 탭 → **Create codespace on main** 클릭. 2~3분 대기. 자동 설치: - Node.js 22 - Cloudflare Wrangler CLI - 선택한 AI 에이전트(Claude Code 또는 Codex) - Astro Codespace가 열린 뒤 선택한 메인 에이전트의 설치·인증을 확인합니다. 이미지 작업을 시작할 때는 한의원 소유 ChatGPT/Codex 기능으로 실제 이미지 생성까지 검증합니다. #### 3단계 · 메인 에이전트 실행 + 로그인 (1분) Claude Code를 선택했다면: ``` claude ``` Codex를 선택했다면: ``` codex ``` 첫 실행 시 선택한 서비스의 로그인 화면이 뜹니다. 터미널의 링크를 열어 본인 계정으로 인증하고 돌아오면 준비가 끝납니다. 일반 코딩 작업을 위해 두 에이전트를 모두 설치하거나 서로 호출할 필요는 없습니다. #### 4단계 · 스타터킷 다운로드 + HQ 인증 (3~5분) 에이전트에게 이렇게 말하세요: ``` 스타터킷 받아서 설치해줘 ``` 에이전트가 다음 명령을 실행합니다 (원장님이 직접 입력해도 동일): ```bash curl -fsSL https://clinic-os.moden.marketing/cos-setup.sh | bash ``` ##### 4-1. 인증 코드 입력 (브라우저) 스크립트가 실행되면 터미널에 **인증 코드 박스**가 표시됩니다: ``` ╔══════════════════════════════════════╗ ║ 브라우저에서 아래 코드를 입력하세요: ║ ║ ║ ║ ABCD-1234 ║ ╚══════════════════════════════════════╝ URL: https://clinic-os.moden.marketing/auth/device ``` 동시에 **브라우저가 자동으로 열립니다.** 박스에 표시된 코드(`ABCD-1234`)를 브라우저 화면에 입력하고 **HQ 계정으로 로그인**하세요. > HQ 계정이 없으면 강사가 사전에 발급해드린 계정 정보를 사용하세요. > > 브라우저가 자동으로 열리지 않으면 터미널에 표시된 URL을 직접 방문하면 됩니다. > > 인증 시간은 최대 15분입니다. 그 안에 브라우저 인증을 완료하세요. ##### 4-2. 인증 완료 → 자동 다운로드 브라우저 인증을 마치면 스크립트가 자동으로 진행: 1. **인증 완료 메시지** 표시 (예: `✓ 인증 완료! (백록담한의원)`) 2. **내 한의원 전용 스타터킷** zip 다운로드 (개별 `clinic.json` + 라이선스 키 포함, Bearer 토큰 인증) 3. 압축 해제 → `clinic-os/` 폴더 생성 ##### 4-3. 의존성 설치 + 초기 셋업 에이전트가 이어서: ```bash cd clinic-os npm install npm run setup:agent ``` 완료되면 개발 서버가 실행되고 포트 4321이 자동 포워딩되어 브라우저에서 한의원 기본 홈페이지를 확인할 수 있습니다. > **Cloudflare 연결은 별도 단계입니다.** 워크숍 후반(보통 3주차)에 진행합니다. Codespaces 환경에서는 `wrangler login` OAuth가 불안정하므로 **API Token 방식**을 사용합니다. 자세한 발급/적용 방법: **[Cloudflare 셋업 가이드](/guides/cloudflare-setup)** 참조. --- ### macOS 로컬 (20분) Mac은 Unix 기반이라 별도 설정이 거의 없습니다. **로컬 환경은 과금이 없는 장점이 있습니다.** **필요한 것:** - macOS 12 이상 - Homebrew (없으면 에이전트가 설치 안내) - Node.js 20+ (없으면 에이전트가 설치 안내) 시작 방법: 1. 터미널에서 스타터킷 다운로드 스크립트 실행: ```bash curl -fsSL https://clinic-os.moden.marketing/cos-setup.sh | bash ``` 2. 터미널에 표시되는 **인증 코드**(예: `ABCD-1234`)를 자동으로 열린 브라우저에서 입력 + HQ 계정 로그인. 3. 인증 완료 시 스타터킷 zip이 자동 다운로드 → `clinic-os/` 폴더 생성. 4. `cd clinic-os` 후 선택한 메인 에이전트 실행 → **"설치 상태 진단하고 설치 진행해줘"** 요청 에이전트가 환경을 진단하고 의존성 설치부터 초기 설정까지 진행합니다. 브랜드·콘텐츠 이미지 온보딩 전에는 같은 환경에서 현재 메인 에이전트에 맞는 Codex 이미지 기능으로 테스트 이미지가 실제 생성·저장되는지 확인합니다. > **Cloudflare 연결**: macOS 로컬에서는 `wrangler login` OAuth도 정상 작동하므로, API Token 방식과 OAuth 둘 다 가능합니다. 자세한 내용: **[Cloudflare 셋업 가이드](/guides/cloudflare-setup)** 참조. > 스타터킷을 수동으로 받고 싶다면 HQ 대시보드에서 zip 파일을 다운로드할 수도 있습니다. --- ### Windows 로컬 Windows 로컬은 **네이티브 Windows와 WSL Ubuntu를 모두 지원**합니다. 상세 절차와 최신 제약은 **[지원 환경과 Windows 설치](/guides/supported-environments)**에서 확인하세요. #### Windows 네이티브 1. Node.js LTS와 Git for Windows를 설치합니다. ```powershell winget install --id OpenJS.NodeJS.LTS winget install --id Git.Git ``` 2. Claude Code 또는 Codex 중 하나를 설치하고 로그인 상태를 확인합니다. ```powershell # Claude Code 선택 시 winget install Anthropic.ClaudeCode claude auth login claude auth status # Codex/ChatGPT Windows 앱 선택 시 winget install --id 9PLM9XGG6VKS -s msstore codex login codex login status ``` 3. Git 커밋 신원을 먼저 설정합니다. ```powershell git config --global user.name "이름" git config --global user.email "이메일" ``` 4. HQ에서 발급된 **내 클리닉용 서명 Starter ZIP**을 내려받아 로컬 드라이브의 전용 폴더에 풉니다. 일반 Core ZIP이나 다른 클리닉의 설정 파일을 복사하지 않습니다. 5. PowerShell에서는 실행 정책을 바꾸지 말고 npm 스크립트를 `npm.cmd run <script>`로 실행합니다. cmd.exe에서는 `npm run <script>`를 사용할 수 있습니다. 6. 프로젝트 폴더에서 선택한 에이전트를 열고 **"Windows 네이티브 설치 상태를 진단하고, Core Pull부터 pages.dev 배포 검증까지 진행해줘"**라고 요청합니다. 에이전트는 의존성 설치와 숨김 Cloudflare 인증, HQ 활성화, Git/Core upstream 연결을 마친 뒤 다음 순서를 모두 통과시켜야 합니다. ```powershell 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 ``` Claude Code를 선택했다면 canary 인자만 `claude-code`로 바꿉니다. 두 에이전트를 모두 설치할 필요는 없습니다. 위 Core 명령은 stable Starter 기준이며, 발급된 `clinic.json`의 channel이 `beta`라면 두 Core 명령을 `core:pull:beta`로 바꿉니다. #### WSL Ubuntu Linux 환경을 선호하거나 기존 WSL 설치본을 이어갈 때 선택합니다. 프로젝트는 `/mnt/c/...` 대신 `~/clinic-os` 또는 `~/projects/clinic-os`처럼 WSL 파일 시스템 안에 두는 것을 권장합니다. > 2026-08-03 실제 검증에서 Windows 네이티브의 업데이트, 빌드, Cloudflare 배포와 실서빙까지 > 확인했습니다. 최초 빌드의 `npx` ENOENT 문제는 Clinic-OS v1.65.x에서 수정되었습니다. --- ## ⚠️ Codespace 관리 규칙 (필독) ### 핵심: Codespace를 **삭제하지 마세요** , 프로덕션 배포 전에는 치명적 Codespace를 삭제하면 `.gitignore`에 포함된 파일(= GitHub에 푸시되지 않는 것)이 **전부 소실**됩니다. | 항목 | GitHub에 푸시되나? | Codespace 삭제 시 | |------|--------------------|-------------------| | 소스 코드, 설정 파일 | ✅ | 복구 가능 (`git clone`) | | 업로드한 이미지 (`public/local/images/`) | ✅ | 푸시했으면 복구 | | **로컬 D1 DB** (환자 데모, 포스트 초안, 설정) | ❌ `.gitignore` | **완전 증발** | | API 키, 비밀번호 (`.env.local`) | ❌ `.gitignore` | **재발급 필요** | | `node_modules` | ❌ `.gitignore` | 재설치 3~5분 | 워크숍 초반 1~2주 동안 원장님이 에이전트와 대화하며 입력한 **한의원 소개, 환자 데모, 블로그 초안, 프로그램 정보**는 모두 **로컬 D1 파일에만** 있다가 Cloudflare 배포 시점에 원격으로 복사됩니다. 배포 전 삭제하면 처음부터 다시 입력해야 합니다. ### ✅ 해야 할 것 - **매일 작업 끝날 때 `git push`** , 커밋 가능한 모든 변경사항 백업 - 에이전트에게 "오늘 작업 커밋하고 푸시해줘"라고 하면 자동 처리 - **작업 중단 시 그냥 브라우저 닫기** , 30분 idle 후 자동 정지 (VM 과금 멈춤, 스토리지 유지) ### ❌ 절대 하지 말 것 - **Codespace 삭제** , 프로덕션 배포(보통 3주차) 전까지 치명적 - 워크숍 전 기간(약 5주) 동일 Codespace 유지 ### 📅 재접속 방법 언제든 내 레포 → Code → Codespaces → 기존 Codespace 클릭 → 다시 열림 (정지 상태였으면 30초 내 부팅). ### 🛡️ 프로덕션 배포 후 Cloudflare D1에 데이터가 원격 저장되므로 Codespace를 삭제해도 실제 한의원 데이터는 안전합니다. 다만 로컬 개발환경 복구에 시간이 걸리므로 여전히 삭제 비추천. --- ## 과금 예상 (4주 워크숍 기준) | 항목 | 비용 | |------|------| | 메인 에이전트 구독 | Claude Code 또는 Codex 중 선택한 서비스의 현재 요금제 | | 이미지 기능 | 선택한 ChatGPT/Codex 계정의 현재 제공 범위 확인 | | GitHub Codespaces | **무료** (2코어 60시간/월 한도 내) | | Codespace 스토리지 | ~$2/월 ($0.07/GB × 30GB) | | Cloudflare | **무료** (Pages + D1 기본 플랜) | --- ## 설치 진행하기 환경이 준비되면 에이전트에게 이렇게 요청하세요: > **"이 프로젝트를 읽고 설치 상태를 진단한 다음, 설치를 진행해줘."** 에이전트가 자동으로 처리하는 것: - 현재 상태 진단 (신규/재개/업데이트 판별) - 의존성 설치 - 데이터베이스 초기화 - 빌드 검증 - 설치 완료 시 health 점수 표시 사용자가 설치 중에 하는 일: - **HQ 인증** , 터미널에 표시된 device-code(예: `ABCD-1234`)를 자동으로 열린 브라우저에 입력 + HQ 계정 로그인 - **Cloudflare 토큰 적용** , 배포 단계(보통 워크숍 3주차)에 발급한 API Token을 환경변수로 등록 (Codespaces 환경 필수, macOS 로컬은 OAuth 가능) - **기본 정보 제공** , 한의원 이름 등 에이전트가 물어보는 항목에 답변 - **위험한 작업 승인** , 에이전트가 이유를 설명하고 제안하면 확인 --- ## 문제 해결 ### 메인 에이전트가 오래된 버전일 때 ``` npm install -g @anthropic-ai/claude-code@latest ``` Claude Code를 선택한 경우 위 명령 후 `claude`를 다시 실행합니다. Codex를 선택한 경우에는 Codex의 공식 업데이트 절차로 갱신한 뒤 `codex`를 다시 실행합니다. ### Codespace 부팅이 너무 느릴 때 네트워크 재시도. 안 되면 Codespaces → 해당 Codespace → **"Rebuild container"** (삭제 아님, 재빌드). ### 작업 내용이 사라진 것 같을 때 - 에이전트에게 "`git status`, `git log`, `git reflog` 보여줘" 요청 - 로컬 DB 내용이 증발했으면 → 안타깝게도 재입력 필요 (이래서 삭제 금지) ### 설치가 꼬였을 때 무작정 다시 설치하지 마세요. 에이전트에게 이렇게 요청하세요: > **"설치가 꼬인 것 같아. 현재 상태를 진단하고 이어서 갈지 새로 할지 판단해줘."** 에이전트가 상태를 진단하고 가장 안전한 복구 경로를 제안합니다. ### HQ 응답이 없을 때 워크숍 단톡방에 "HQ 다운" 공지. 강사가 대응합니다. --- ## 관련 콘텐츠 - 📹 **관련 영상**: 커리큘럼 0-3b. [Mac] 로컬 환경에서 시작하기 - 📋 **워크숍**: W1 M0에서 다룸 - 🎯 **직원 투어**: 관리자 패널에서 **설정** 투어를 시작하세요 설치가 완료되면 에이전트에게 **"온보딩 시작해"**라고 요청하세요. 한의원 정보 입력부터 홈페이지 구성까지 에이전트가 안내합니다. - [에이전트와 처음 만나기](/guides/agent-start) , 에이전트 사용법 안내 - [에이전트에게 효과적으로 요청하기](/guides/ai-effective-requests) , 좋은 요청 패턴 - [Cloudflare 셋업 가이드](/guides/cloudflare-setup) , 도메인 연결, 추가 설정

설치와 시작 가이드

이 페이지에서 확인할 내용