설정 확인 (Windows)
모든 항목을 자동으로 설치 또는 복구합니다(무인 실행, 재실행 안전, 성공 시 .setup-ok 파일 생성):
powershell -NoProfile -ExecutionPolicy Bypass -File tools/setup.ps1
자동으로 처리할 수 없는 경우 SETUP FAILED: <이유>와 함께 해결 방법을 출력합니다.
알려진 정상 설정:
| 도구 | 위치 |
|---|---|
| Node.js 22+ | winget OpenJS.NodeJS.LTS → C:\Program Files\nodejs |
| FFmpeg / FFprobe | winget Gyan.FFmpeg |
| 트랜스크립션 / AI 음성 | tools/transcribe-deepgram.ps1을 통한 Deepgram API, 사용자 환경 변수 DEEPGRAM_API_KEY에 키 저장 |
| Chrome | 시스템 설치 또는 npx --yes hyperframes browser ensure을 통한 개인 복사본 |
| HyperFrames 스킬 | %USERPROFILE%\.agents\skills (+ .claude\skills) |
whisper.cpp를 설치하거나 로컬 트랜스크립션 모델을 실행하지 마십시오(일반 PC에서 느리고 시끄럽습니다).
확인
npx -y hyperframes doctor
Docker, Kokoro(TTS), MusicGen 및 whisper-cpp는 여기서 필요하지 않으므로 무시하십시오.
일반적인 문제 해결
- Deepgram 키: 사용자가 직접
powershell -NoProfile -ExecutionPolicy Bypass -File tools/set-deepgram-key.ps1을 실행합니다(채팅에 키를 절대 붙여넣지 마십시오). 스크립트는 이전 터미널에서도 사용자 범위 값을 읽습니다. - 설정 직후
node/ffmpeg를 찾을 수 없는 경우: 터미널에서 PATH를 새로 고칩니다 ($env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User')) 또는 편집기를 다시 시작합니다. - "실행 스크립트 사용 안 함" 오류: 항상
powershell -NoProfile -ExecutionPolicy Bypass -File ...을 사용하여 스크립트를 호출합니다. - Deepgram 401 오류: 키가 잘못되었거나 만료되었습니다. 사용자에게 다시 설정하도록 요청하십시오. 402/429: 크레딧 부족 / 속도 제한.
- 스킬 / CLI 업데이트:
npx -y hyperframes skills update,npx -y hyperframes upgrade. - 관리자 권한이 필요한 모든 작업: 사용자에게 정확한 명령을 관리자 터미널에서 실행하도록 안내합니다.