설치와 시작 가이드

Clinic-OS는 Claude Code 또는 Codex 중 선택한 메인 에이전트가 설치를 진행합니다. 사용자는 환경을 열고, 선택한 에이전트에게 "설치해줘"라고 요청하면 됩니다. 두 에이전트는 같은 스킬과 안전 규칙을 사용합니다.

총 소요 시간: 처음부터 기본 홈페이지 확인까지 약 7~10분

시작하기 전에

설치를 시작하기 전에 아래 5가지를 준비하세요.

준비물	설명	주소
GitHub 계정	스타터킷 다운로드, Codespaces 사용 (무료)	github.com
Cloudflare 계정	사이트 배포용 (무료 티어)	dash.cloudflare.com/sign-up
메인 에이전트 계정	Claude Code 또는 Codex 중 하나를 선택해 코딩·운영	claude.ai / chatgpt.com
ChatGPT/Codex 이미지 기능	이미지 작업 시 실제 생성 검증 필수. Codex 메인은 네이티브 기능, Claude Code 메인은 Codex 어댑터 사용	chatgpt.com
한의원 기본 정보	상호, 주소, 전화, 진료시간, 의료진 프로필	,

설치 시간: Codespaces 7~10분 / macOS 로컬 약 20분 / Windows 네이티브·WSL은 환경 준비 시간에 따라 달라집니다. 전체 지원 범위와 Windows 셸별 주의사항은 지원 환경과 Windows 설치를 기준으로 합니다.

개발 환경 선택하기

추천: 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분)

에이전트에게 이렇게 말하세요:

스타터킷 받아서 설치해줘

에이전트가 다음 명령을 실행합니다 (원장님이 직접 입력해도 동일):

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. 인증 완료 → 자동 다운로드

브라우저 인증을 마치면 스크립트가 자동으로 진행:

인증 완료 메시지 표시 (예: ✓ 인증 완료! (백록담한의원))
내 한의원 전용 스타터킷 zip 다운로드 (개별 clinic.json + 라이선스 키 포함, Bearer 토큰 인증)
압축 해제 → clinic-os/ 폴더 생성

##### 4-3. 의존성 설치 + 초기 셋업

에이전트가 이어서:

cd clinic-os
npm install
npm run setup:agent

완료되면 개발 서버가 실행되고 포트 4321이 자동 포워딩되어 브라우저에서 한의원 기본 홈페이지를 확인할 수 있습니다.

Cloudflare 연결은 별도 단계입니다. 워크숍 후반(보통 3주차)에 진행합니다. Codespaces 환경에서는 wrangler login OAuth가 불안정하므로 API Token 방식을 사용합니다. 자세한 발급/적용 방법: Cloudflare 셋업 가이드 참조.

macOS 로컬 (20분)

Mac은 Unix 기반이라 별도 설정이 거의 없습니다. 로컬 환경은 과금이 없는 장점이 있습니다.

필요한 것:

macOS 12 이상
Homebrew (없으면 에이전트가 설치 안내)
Node.js 20+ (없으면 에이전트가 설치 안내)

시작 방법:

터미널에서 스타터킷 다운로드 스크립트 실행:

   curl -fsSL https://clinic-os.moden.marketing/cos-setup.sh | bash

터미널에 표시되는 인증 코드(예: ABCD-1234)를 자동으로 열린 브라우저에서 입력 + HQ 계정 로그인.
인증 완료 시 스타터킷 zip이 자동 다운로드 → clinic-os/ 폴더 생성.
cd clinic-os 후 선택한 메인 에이전트 실행 → "설치 상태 진단하고 설치 진행해줘" 요청

에이전트가 환경을 진단하고 의존성 설치부터 초기 설정까지 진행합니다.

브랜드·콘텐츠 이미지 온보딩 전에는 같은 환경에서 현재 메인 에이전트에 맞는 Codex 이미지 기능으로 테스트 이미지가 실제 생성·저장되는지 확인합니다.

Cloudflare 연결: macOS 로컬에서는 wrangler login OAuth도 정상 작동하므로, API Token 방식과 OAuth 둘 다 가능합니다. 자세한 내용: Cloudflare 셋업 가이드 참조.

스타터킷을 수동으로 받고 싶다면 HQ 대시보드에서 zip 파일을 다운로드할 수도 있습니다.

Windows 로컬

Windows 로컬은 네이티브 Windows와 WSL Ubuntu를 모두 지원합니다. 상세 절차와 최신 제약은 지원 환경과 Windows 설치에서 확인하세요.

Windows 네이티브

Node.js LTS와 Git for Windows를 설치합니다.

   winget install --id OpenJS.NodeJS.LTS
   winget install --id Git.Git

Claude Code 또는 Codex 중 하나를 설치하고 로그인 상태를 확인합니다.

   # 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

Git 커밋 신원을 먼저 설정합니다.

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

HQ에서 발급된 내 클리닉용 서명 Starter ZIP을 내려받아 로컬 드라이브의 전용 폴더에

풉니다. 일반 Core ZIP이나 다른 클리닉의 설정 파일을 복사하지 않습니다.

PowerShell에서는 실행 정책을 바꾸지 말고 npm 스크립트를 npm.cmd run <script>로 실행합니다.

cmd.exe에서는 npm run <script>를 사용할 수 있습니다.

프로젝트 폴더에서 선택한 에이전트를 열고 **"Windows 네이티브 설치 상태를 진단하고,

Core Pull부터 pages.dev 배포 검증까지 진행해줘"**라고 요청합니다.

에이전트는 의존성 설치와 숨김 Cloudflare 인증, HQ 활성화, Git/Core upstream 연결을 마친 뒤 다음 순서를 모두 통과시켜야 합니다.

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 다운" 공지. 강사가 대응합니다.