문제 해결

설치 시 게시자 경고가 떠요

베타 빌드는 코드 서명 전이라 SmartScreen/Defender 경고가 정상적으로 표시됩니다. 다운로드 페이지의 “최초 실행 안내”를 따라 한 번만 허용하면 이후에는 표시되지 않습니다. 설치 파일이 커서 첫 검사에 시간이 걸릴 수 있습니다 — 창이 바로 안 뜨면 잠시 기다린 뒤 다시 실행해 보세요.

VNC 원격 화면

접속 방법

새 탭 메뉴 → VNC 접속… 또는 저장된 연결. 입력 항목:

항목	기본값	설명
호스트	—	VNC 서버 IP 또는 도메인
포트	5900	VNC 기본 포트
비밀번호	—	VNC 인증 비밀번호
저장 이름	—	입력 시 저장된 연결에 등록

SSH 터널로 내부망 VNC 접근

접속 다이얼로그의 SSH 터널 옵션을 켜면 bastion 서버를 경유해 내부망 VNC에 접근할 수 있습니다. 방화벽 외부에서 직접 5900 포트를 열지 않아도 됩니다.

헤더 버튼

버튼	동작
클립보드 전송	로컬 클립보드를 원격으로 보냄
`Ctrl+Alt+Del`	원격 PC에 Ctrl+Alt+Del 전송
📁 FT	파일 전송 패널 토글

클립보드 단축키

Ctrl+Shift+V — 로컬 클립보드를 원격으로 전송만 (붙여넣기 키 전송 없음)
Ctrl+V — 전송 + 원격에 붙여넣기 키까지 전송

파일 전송 (TightVNC 2.x FT)

파일 전송 패널 기능:

기능	방법
폴더 탐색	목록 클릭, ↑ 상위 폴더
새로고침	↻ 버튼
새 폴더	➕ 버튼
업로드	⬆ 버튼 (복수 파일 선택 가능)
다운로드	더블클릭 / 우클릭 / 체크박스 선택 후 다운로드
이름 변경 / 삭제	우클릭 메뉴

동일 이름 파일 업로드 시 덮어쓰기 확인 메시지가 표시됩니다.

파일명이 깨지면 패널 상단 인코딩 드롭다운을 변경하세요(기본 UTF-8). 변경 시 자동 재연결합니다.

VNC 문제 해결

증상	원인	조치
접속 실패	호스트·포트·비밀번호 오류	접속 정보 재확인, 서버 VNC 실행 여부 확인
내부망 접근 불가	방화벽 차단	SSH 터널 옵션 켜기
파일 전송 패널이 없거나 오류	TightVNC 2.x 아닌 서버	TightVNC 2.x 서버로 교체
파일명 깨짐	서버 인코딩 불일치	인코딩 드롭다운에서 서버 인코딩 선택 (예: EUC-KR)
화면은 보이나 클립보드 안 됨	서버 클립보드 비활성	VNC 서버 설정에서 클립보드 공유 활성화

WinRM — 원격 Windows PowerShell

접속 방법

새 탭 메뉴 → WinRM (원격 Windows)…. 입력 항목:

항목	기본값	설명
호스트	—	원격 Windows PC IP 또는 도메인
사용자	—	Windows 로컬 또는 도메인 계정
비밀번호	—	계정 비밀번호
포트	5985 (HTTP) / 5986 (HTTPS)	HTTPS 사용 토글로 선택
HTTPS 사용	꺼짐	켜면 5986, 끄면 5985
저장 이름	—	입력 시 저장된 연결에 등록

원격 PC 사전 조건

원격 PC에서 PowerShell을 관리자로 열고 아래 명령을 실행하세요:

Enable-PSRemoting -Force

도메인 환경이 아닌 작업그룹 또는 IP 직접 접속의 경우, 클라이언트 PC에서 TrustedHosts를 설정해야 합니다. 접속 다이얼로그의 “이 호스트 신뢰 추가” 버튼을 클릭하면 자동으로 처리됩니다.

수동으로 설정하려면:

# 관리자 PowerShell에서 실행
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "대상IP또는호스트명" -Force

동작 방식 및 제한

콘솔에 PowerShell 명령을 입력하고 Enter로 실행합니다.
↑ / ↓ 키로 명령 기록을 탐색할 수 있습니다.
매 명령마다 새 연결을 맺는 명령형 방식입니다(세션 상태는 유지되지 않음).
Read-Host 같은 인터랙티브 프롬프트는 지원하지 않습니다.

WinRM 문제 해결

증상	원인	조치
”액세스 거부” 오류	계정 권한 부족	관리자 계정 사용 또는 원격 관리 허용 그룹 추가
연결 안 됨 (작업그룹)	TrustedHosts 미설정	다이얼로그 “이 호스트 신뢰 추가” 클릭
연결 안 됨 (방화벽)	5985/5986 포트 차단	원격 PC 방화벽에서 WinRM 포트 허용
WinRM 서비스 없음	PSRemoting 미활성	원격 PC에서 `Enable-PSRemoting -Force` 실행
HTTPS 인증서 오류	자체서명 인증서	HTTP(5985)로 접속하거나 인증서 신뢰 설정
메뉴에 WinRM 없음	macOS에서 실행 중	Windows 전용 기능, Windows PC에서 사용

데스크탑 캡처

화면 영역 캡처 (📷)

탭 바의 📷 버튼을 클릭하면 화면 위에 투명 오버레이가 덮입니다.

마우스로 드래그해 캡처할 영역을 선택합니다 (외부 모니터 포함).
캡처된 이미지가 마크업 편집기에서 열립니다 — 화살표·텍스트·형광펜으로 주석을 달 수 있습니다.
“AI로 전송” 버튼을 클릭하면 열려 있는 AI 채팅에 이미지가 첨부됩니다.

데스크탑 미러 (라이브 스트리밍)

새 탭 메뉴 → 🖥️ 데스크탑 캡처… → 창 목록에서 앱을 선택하면 해당 창이 패널에 라이브 스트리밍됩니다(보기 전용).

AI는 desktop_screenshot 도구로 미러 화면을 볼 수 있습니다.
웹 미리보기 패널은 ✏️ 버튼으로 캡처해 AI에 전송할 수 있습니다.

전체 문제 해결

앱 크래시·화면이 하얗게 되는 경우

증상	원인	조치
화면이 하얗게 되며 자동 재로드	렌더러 프로세스 크래시	자동 복구됨 — 정상 동작
30초 안에 3회 이상 반복 크래시	GPU 드라이버 또는 메모리 문제	GPU 드라이버 업데이트 후 재실행
재로드해도 계속 하얀 화면	심각한 렌더러 오류	`crash.log` 확인 후 문의

크래시 로그 위치: %APPDATA%\Blyck\crash.log

크래시 발생 시:

crash.log를 열어 마지막 오류 내용을 확인합니다.
F12로 개발자 도구를 열어 콘솔 탭에서 에러를 확인합니다.
해결이 안 되면 crash.log와 logs\blyck.log를 문의 페이지에 첨부해 주세요.

멈춤·키 입력 지연

증상	원인	조치
5~10초 멈춤 후 자동 복구	RAG 재인덱싱 또는 LSP 초기화 중 메인스레드 블록	잠시 대기
반복적으로 멈춤	리소스 경합	`blyck.log` 첨부 후 문의
AI 작업 중 긴 멈춤	턴 백스톱(60분) 또는 2분 무응답 처리	■ 정지 버튼으로 강제 중단

업데이트 관련

Blyck은 앱 시작 시와 4시간 간격으로 update.blyck.dev에서 업데이트를 확인합니다. 새 버전은 백그라운드 다운로드 후 앱 종료 시 자동 설치됩니다.

증상	원인	조치
업데이트가 적용 안 됨	앱이 완전히 종료되지 않음	트레이 아이콘까지 완전 종료 후 재실행
다운로드 실패	회사 네트워크 CDN 차단	IT팀에 `update.blyck.dev` 허용 요청 또는 수동 설치
업데이트 확인 안 됨	오프라인 환경	인터넷 연결 후 재시작

라이선스 관련

증상	원인	조치
전체 화면 잠금 표시	14일 체험 종료	라이선스 키 붙여넣어 인증
”구독이 만료되었습니다”	구독 만료 또는 취소	Lemon Squeezy 포털에서 구독 상태 확인
인증 실패	오프라인 상태	네트워크 연결 후 재시도
”다른 기기에 등록됨”	기기 등록 초과	Lemon Squeezy 포털에서 기기 관리
인증 후 7일 지나 잠김	오프라인 grace period 초과	인터넷 연결 후 앱 재시작으로 재검증

DB 연결 관련

증상	원인	조치
연결 타임아웃	네트워크·방화벽 차단	호스트·포트·방화벽 규칙 확인. PG/MySQL 10초, MSSQL 15초
Oracle `ORA-xxxxx`	서버 측 오류(서비스명·계정 잠김 등)	서버 접속 정보 재확인
Oracle `NJS-116`	Thin 모드 미지원 환경	Thick 강제 체크 + 64비트 Instant Client 경로 설정
Oracle `NJS-118`	Thick 초기화 오류	앱 재시작 후 재시도
MySQL BIGINT 문자열 표시	2^53 초과 정밀도 보호	정상 동작 — 버그 아님
연결 풀 세션 폭증	—	풀(최대 4개)로 자동 관리됨, 문제 없음

자세한 DB 관련 문제는 DB 클라이언트 페이지를 참고하세요.

웹 미리보기 관련

증상	원인	조치
페이지 로드 안 됨	개발 서버 미실행	로컬 개발 서버를 먼저 실행 후 URL 입력
`preview_eval` 즉시 실패	페이지 아직 로드 중	`preview_wait` 도구 후 재시도
화면이 빈 채로 멈춤	URL 오류 또는 서버 오류	URL과 서버 상태 확인

자세한 내용은 실행 · 미리보기 페이지를 참고하세요.

RAG 검색 관련

증상	원인	조치
결과가 없거나 오래된 파일 표시	인덱스 미갱신	채팅 설정 → RAG 인덱스 상태 확인
삭제한 파일이 검색됨	Orphan 항목	Orphan Scan 청소 도구 실행
결과가 너무 노이즈	불필요 파일 인덱싱	`.termeditignore`로 제외 패턴 추가
임베딩 모델 변경 후 결과 이상	재인덱싱 진행 중	재인덱싱 완료까지 대기

RAG 인덱스 관리는 RAG 검색 페이지를 참고하세요.

SSH 접속 관련

증상	원인	조치
비밀번호 입력에서 멈춤	비표준 프롬프트 (감지 대기 최대 30초)	직접 입력하거나 비밀번호 저장 사용
자동 재연결 실패	비밀번호 전용 서버 (재연결 시 비번 미재사용)	키/agent 인증 설정 또는 수동 재접속
SFTP만 실패	SFTP 서브시스템 비활성	파일 패널에서 수동으로 다시 연결
한글 깨짐	서버 로케일	서버 `locale`로 `*.UTF-8` 확인

자세한 내용은 터미널 · SSH · SFTP 페이지를 참고하세요.

AI 기능 관련

증상	원인	조치
AI 채팅 비활성	CLI 미설치 또는 미로그인	준비 마법사에서 CLI 설치·로그인
401/403 오류	API 키 만료 또는 잘못됨	키 재등록 또는 `claude login` 재실행
응답 안 옴 / 멈춤	네트워크 또는 인증 만료	자동 재시도 3회 후 재로그인, 새 채팅 시작
승인 카드 없이 파일 변경됨	🚀 자동 모드 활성	`Ctrl+3`으로 ⚡ 실행+검토 모드로 전환

자세한 내용은 AI 채팅 페이지를 참고하세요.

LSP 자동완성 관련

증상	원인	조치
Python 자동완성 안 됨	Pyright 미설치	첫 Python 파일 열 때 “다운로드?” 모달 승인
Go 자동완성 안 됨	Go 툴체인 없음	Go 설치 후 `go install golang.org/x/tools/gopls@latest`
Rust 자동완성 안 됨	rust-analyzer 다운로드 실패	GitHub 접근 가능 환경에서 앱 재시작 또는 수동 설치 후 PATH 등록
회사 네트워크에서 다운로드 실패	GitHub 차단	해당 서버를 직접 설치해 PATH에 등록

터미널 표시 관련

증상	원인	조치
글자 흐릿함	WebGL 폴백(Canvas/DOM)	설정에서 Canvas 렌더러 명시 지정
전각 문자 정렬 깨짐	DOM 렌더러 사용 중	설정에서 Canvas 렌더러 지정
한글 깨짐 (로컬)	—	Windows는 UTF-8 자동 적용, `ipconfig` 등 네이티브 exe는 PowerShell cmdlet으로 대체

잘못된 변경을 되돌리고 싶어요

Ctrl+Shift+H로 변경 이력을 열면 파일·DB·SSH 변경이 모두 기록되어 있습니다. 항목을 선택해 되돌리기하세요. DML은 실행 직전 데이터가 자동 백업되므로 WHERE 없는 UPDATE도 복구할 수 있습니다.

자세한 동작은 Git · ChangeSet 페이지를 참고하세요.

로그·데이터 위치 (Windows)

항목	위치
앱 로그	`%APPDATA%\Blyck\logs\blyck.log` (2MB 회전)
크래시 로그	`%APPDATA%\Blyck\crash.log`
접속 정보 (비밀번호 제외)	`%APPDATA%\Blyck\connections.json`
레이아웃 (탭·분할)	`%APPDATA%\Blyck\layout.json`
AI 채팅 기록	`%APPDATA%\Blyck\chats\`
변경 이력 (ChangeSet)	`%APPDATA%\Blyck\blyck-history.db`
RAG 인덱스	워크스페이스별 SQLite 파일

비밀번호와 토큰은 파일이 아니라 OS 자격증명 저장소에 암호화 보관됩니다. 로그에는 비밀번호·토큰·API 키·사용자 경로가 자동 마스킹되며, 로컬에만 저장되고 외부로 전송되지 않습니다.

그 밖의 문제

해결되지 않는 문제는 문의 페이지로 보내주세요. 환경 정보(OS·버전)와 재현 절차를 함께 적어주시면 빠르게 도와드릴 수 있습니다. Blyck이 내부적으로 여는 보조 서버(MCP·VNC 프록시 등)는 모두 localhost 동적 포트 + 토큰 인증으로만 열리므로 방화벽 예외나 포트 개방이 필요 없습니다.