Clinic-OS 지원 환경
이 문서는 Clinic-OS 클라이언트 설치·운영 환경의 기준입니다. 다른 문서에서 지원 범위를 설명할 때는 별도 목록을 만들지 말고 이 문서를 참조하세요.
Claude Code와 Codex는 지원 환경 모두에서 동등한 메인 에이전트입니다. 둘 중 하나만 인증해 코딩·운영을 진행할 수 있으며, 이미지 작업에는 현재 런타임에 맞는 클리닉 소유 ChatGPT/Codex 이미지 기능을 추가로 확인합니다.
| 환경 | 상태 | Node.js 설치 | 셸 안내 | 알려진 제약 |
|---|---|---|---|---|
| GitHub Codespaces | 지원 | devcontainer가 준비 | 기본 터미널 사용 | Codespace 준비가 끝난 뒤 진행 |
| macOS | 지원 | Homebrew 또는 nvm | 기본 셸 사용 | 없음 |
| WSL Ubuntu | 지원 | apt 또는 nvm | Ubuntu 터미널 사용 | 프로젝트를 WSL 파일 시스템에 두는 것을 권장 |
| Windows 네이티브 + 원격 Cloudflare | 3기 파일럿 권장 | Node.js LTS + Git for Windows | PowerShell은 npm.cmd/npx.cmd; cmd.exe와 Git Bash도 지원 | 프로젝트별 windows-native; Claude Code 또는 Codex 사용; 로컬 D1/workerd 미사용 |
| Codex Cloud | 선택적 원격 대체 | Windows에는 Git과 앱만 준비; 실행은 원격 Linux | 앱에서 Cloud 환경 선택 | 프로젝트별 codex-cloud; Cloudflare Pages URL로 확인 |
| Codex Windows 앱 | 선택적 Windows UI | Node.js LTS + Git for Windows | 네이티브 에이전트는 PowerShell, WSL 전환 가능 | 앱은 필수가 아니며 일반 Codex CLI와 같은 ClinicOS 런타임 계약 사용 |
Windows 네이티브 지원 범위는 cmd.exe와 PowerShell 양쪽에서 업데이트, 빌드, Cloudflare 배포와 실제 사이트 응답까지 확인한 결과를 바탕으로 정했습니다.
Windows 인증서(CA) 오류 자동 처리 (v1.66.1~)
Windows의 Node.js는 기본적으로 OS 인증서 저장소를 신뢰하지 않아, 사내망/방화벽/프록시가 자체 인증서(self-signed 또는 사설 CA)를 끼워 넣는 환경에서 npm run update:starter가 UNABLE_TO_VERIFY_LEAF_SIGNATURE 오류로 실패할 수 있습니다.
v1.66.1부터 update:starter(및 update-starter-standalone.cjs)가 실행 시점에 자동으로 감지·우회를 시도합니다:
- Windows이고 실행 중인 Node가 시스템 인증서 저장소 사용 기능(
--use-system-ca, Node
23.8.0 이상에서만 지원 , Node.js 23.8.0 릴리스 노트)을 지원하면, 스크립트가 자동으로 그 옵션을 켠 채 자기 자신을 한 번 재실행합니다 , 사용자가 수동으로 환경 변수를 설정할 필요가 없습니다.
- 실행 중인 Node가 그보다 오래된 버전(예: 이 프로젝트가 실측 검증한 v22.13.1)이면, 이
자동우회 기능 자체가 Node에 없어 적용할 수 없습니다 , 인증서 오류가 계속되면 Node.js를 최신 버전으로 업그레이드하거나, 사내망 관리자에게 문의해 NODE_EXTRA_CA_CERTS 환경변수로 사설 CA 인증서 경로를 직접 지정하세요.
- macOS/Linux는 이 문제와 무관합니다(OS 인증서 저장소를 기본적으로 신뢰) , 이 절은 Windows
네이티브 환경에만 해당합니다.
Windows 네이티브 시작 전 확인
- Windows 업데이트를 완료합니다. Windows 11을 권장하며 최신 Windows 10은 파일럿
범위로 유지합니다.
- Node.js LTS와 Git for Windows를 설치합니다.
winget install --id OpenJS.NodeJS.LTS
winget install --id Git.Git- Git 커밋 신원 정보를 설정합니다.
git config --global user.name "이름"
git config --global user.email "이메일"- 클리닉별 비공개 GitHub 저장소와 이메일 인증·R2 활성화를 마친 Cloudflare 계정을
준비합니다.
- Claude Code 또는 Codex 중 메인 에이전트 하나를 설치하고 인증합니다. 둘 다 설치할
필요는 없습니다. 버전 확인만으로 끝내지 않고 claude auth status 또는 codex login status가 성공해야 합니다.
- HQ에서 클리닉용으로 발급된 서명 Starter ZIP을 내려받습니다. 일반 Core ZIP이나 다른
클리닉의 clinic.json은 사용할 수 없습니다.
- 스타터를 받은 프로젝트에서 아래 선택을 한 번 저장합니다.
npm.cmd run workshop:profile -- windows-native
npm.cmd run workshop:profile -- --show- PowerShell에서는
npm.cmd run <script>형태를 사용합니다. 시스템 실행 정책을 바꿀
필요가 없습니다. cmd.exe에서는 일반적인 npm run <script>가 동작합니다.
설치를 마쳤다고 판단하려면 windows:canary → 채널에 맞는 Core Pull 사전 확인 (dry-run) → 실제 Pull → build → deploy 순서입니다. clinic.json의 channel이 stable이면 core:pull, beta이면 core:pull:beta를 사용합니다. canary는 Git 초기화 전 ZIP 상태에서 실행하는 사전검사가 아니라, 로그인·Git 체크포인트까지 준비된 뒤 실행하는 마지막 확인 절차입니다.
프로파일은 프로젝트별 로컬 파일에 저장되며 Git과 core:pull 대상에서 보호됩니다. Windows 사용자 전체에 setx로 설정하지 않으므로 같은 PC의 기존 classic 설치본은 영향받지 않습니다.
환경별 상세 절차는 Windows에서 Claude Code 또는 Codex로 시작하기, 설치와 시작 가이드, Cloudflare 연결 가이드를 참고하세요.
Windows 헤드리스 SSH에서 wrangler d1 --local 크래시
실제 클라이언트 설치·운영에는 영향이 없습니다. 이 절은 SSH 기반 원격 Windows 점검 도구를 사용할 때만 참고합니다.
wrangler d1 execute --local(Miniflare/workerd 기반 로컬 D1)을 pty가 없는 비대화형 SSH 세션(ssh host "cmd.exe /c ...")에서 실행하면 libuv 레벨 크래시가 발생합니다: Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76, 종료코드 0xC0000409. ssh -tt(강제 pty 할당)로도 동일하게 재현됨(2026-08-04 실측, wincom13) , 실제 클라이언트가 겪는 정상 콘솔 세션에서는 발생하지 않는, 헤드리스 SSH 특유의 제약으로 판단됩니다. 로컬 D1이 필요한 Windows 원격 점검은 RDP/실제 콘솔 세션을 사용하거나, 이 단계만 건너뛰고 유닛 테스트와 별도로 확인한 프로세스 실행 방식으로 대체하세요.