자주 묻는 질문 (FAQ)
이 장에서는 가장 자주 묻는 질문과 문제 해결 방법을 정리합니다.
원하는 답을 찾지 못하셨다면 GitHub Issues에 알려 주세요.
설치 및 시작
macOS에서 「응용 프로그램이 손상되었습니다」라고 표시됨
원인: 현재 버전은 코드 서명이 적용되지 않음 (v1.0.1부터는 서명 후 이 조작이 불필요).
다음 방법 중 하나를 선택해 우회합니다.
「응용 프로그램」에서 PinSlip 우클릭 → 열기
터미널에서 실행:
xattr -cr /Applications/PinSlip.app
Linux에서 전역 단축키가 반응하지 않음
원인: Wayland 세션에서는 네이티브 창에 대한 전역 단축키가 반응하지 않습니다.
해결 방법: X11 세션으로 로그인; X11에서는 정상적으로 동작합니다.
GNOME 데스크톱에서 트레이 아이콘이 보이지 않음
원인: GNOME은 기본적으로 애플리케이션 인디케이터를 표시하지 않습니다.
해결 방법: AppIndicator and KStatusNotifierItem Support 확장을 설치하면 됩니다.
Windows 설치형의 「자동 시작」이 회색으로 표시됨
원인: dev 모드 (pnpm dev)는 레지스트리 쓰기를 지원하지 않습니다.
해결 방법: 설치형 (PinSlip-Setup-*.exe)으로 설치한 경우에만 이 스위치가 표시됩니다.
첫 실행이 느림
원인: Go 서비스의 최초 컴파일 + 인덱스 전체 재구성.
설명: 두 번째 실행부터는 즉시 열립니다. 빈 vault는 보통 몇 초, 수천 개의 메모가 있으면 1~2분 정도 걸릴 수 있습니다.
메모를 찾을 수 없음 / 화면 밖으로 나감
메모가 화면 밖으로 나감
원인: 외부 디스플레이 분리 / 디스플레이 해상도 변경.
해결 방법: 애플리케이션을 다시 열면 → PinSlip이 자동으로 표시 영역으로 복귀.
메인 인터페이스가 보이지 않음
해결 방법:
시스템 트레이에서 좌클릭으로 PinSlip 아이콘 클릭 → 표시 전환
단축키
Ctrl+Shift+N으로 퀵 캡처 다시 호출애플리케이션 재시작
Windows 작업 표시줄에서도 찾을 수 없음
해결 방법: 각 메모는 작업 표시줄에 아이콘이 표시됩니다. 표시되지 않는다면 트레이에 「숨김」으로 되어 있지 않은지 확인하세요.
삭제 및 복구
실수로 삭제한 경우
해결 방법: .trash/에서 파일을 notes/로 드래그하면; PinSlip watcher가 자동으로 인식하고 인덱스를 재구성합니다.
폴더 전체가 삭제된 경우
해결 방법: .trash/폴더 트리/에서 폴더 전체를 notes/로 드래그합니다.
휴지통을 거치지 않고 특정 메모를 물리적으로 삭제하고 싶음
해결 방법: .trash/에서 직접 파일을 삭제 (PinSlip의 삭제 로직 우회).
일반적으로 권장하지 않습니다. 휴지통이 존재하는 의미가 바로 보험이기 때문입니다.
검색
일부 키워드를 검색할 수 없음
문제 해결:
순수 기호 문자열은 누락될 가능성이 높음
태그 또는 제목 단어를 시도 (가중치가 가장 높음)
키워드가 본문에 있을 때는 가중치가 비교적 낮아 첫 번째로 표시되지 않을 수 있음
검색 결과가 너무 많음
해결 방법: 더 많은 수식어를 추가하거나 태그 검색을 사용하세요.
Markdown 및 이미지
붙여넣은 이미지가 표시되지 않음
문제 해결:
<vault>/attachments/디렉터리의 권한 확인외부 편집기(Obsidian / VS Code)가 상대 경로
../attachments/를 지원하는지 확인<img>태그의 경로에 지원되지 않는 문자(공백, 일부 비 ASCII 문자 등)가 포함되어 있지 않은지 확인합니다.
작업 상자를 클릭할 수 없음
문제 해결:
마우스 커서가 작업 상자의 네모 칸 위에 있어야 함
현재 메모가 접힘 상태가 아닌지 확인 (접힘 상태에서는 작업 상자를 클릭할 수 있으나, 스크롤 영역이 대상으로 지정됨)
글자 크기 조절 버튼이 사라짐
원인: 창이 너무 좁아 우선순위에 따라 접힘.
해결 방법:
창 너비를 넓힘
⋯ 메뉴에서 「글자 크기 조절」 찾기
Git 동기화
인증 실패
문제 해결:
token이 만료되었는지?
리포지토리 주소에
.git접미사가 포함되어 있는지?쓰기 권한이 있는지?
사용자명을 잘못 입력했는지?
동기화가 멈춤
원인: 네트워크 / 원격 문제.
해결 방법:
상태 패널에
lastError표시지수 백오프 1분→5분→15분은 정상 동작
동기화가 반복적으로 실패
문제 해결:
GitHub / GitLab / cnb에 네트워크로 접근할 수 있는지?
DNS 오염? hosts 파일 수정을 시도
국내 네트워크에서 가져오지 못함? cnb 또는 자체 호스팅 Gitea 사용 고려
「충돌 대기」 표시가 나타남
해결 방법: 충돌이 있는 메모 열기 → 「모두 로컬 사용 / 모두 원격 사용 / 수동 편집」 선택 → 해결 후 저장.
MCP
클라이언트가 MCP에 연결할 수 없음
문제 해결:
<vault>/.pinslip/mcp.json이 존재하는지 확인pid가 살아 있는지 (PinSlip 프로세스와 일치) 확인
설정의 MCP 스위치가 켜져 있는지 확인
클라이언트 URL이
localhost가 아닌127.0.0.1을 사용하는지 확인
도구 호출 404
원인: MCP 스위치가 꺼져 있거나 서비스가 시작되지 않음.
해결 방법:
설정 → MCP 서비스 → 스위치 켜기
PinSlip 재시작
도구 호출 시간 초과
해결 방법:
Go 서비스가 멈추지 않았는지 확인 (PinSlip 재시작)
대량의 메모가 인덱스 재구성 중인지 확인
브라우저 확장
확장이 데스크톱에 연결할 수 없음
문제 해결:
데스크톱 측 PinSlip이 실행 중인지 확인
옵션 페이지의 포트가
mcp.json의port와 일치하는지 확인 (기본 17639이나 일치하지 않을 수 있음)「재연결 탐지」 버튼 시도
우클릭 메뉴에 PinSlip 항목이 없음
문제 해결:
확장에서 「컨텍스트 메뉴」 권한이 활성화되어 있는지 확인
삽입이 허용되지 않는 페이지(Chrome Web Store / 설정 페이지 등)에 있는지 확인
성능
대용량 vault가 열리는 데 오래 걸림
해결 방법:
.pinslip/pinslip.db가 외부 프로그램에 의해 점유되고 있는지 확인 (점유되지 않아야 함)메모가 수천 개 이내는 대체로 무리 없음
불필요한 메모는 제때 휴지통으로 비우기
편집이 끊김
문제 해결:
단일 메모가 너무 긴가? 분할하거나 외부 파일로 보관
브라우저 확장이 지속적으로 디스크를 읽고 쓰는 중인지 확인
기타
macOS 트레이 아이콘 크기 이상
설명: v1.0.0 초기 버전에서 「큰 아이콘이 메뉴 바를 가득 채움」 문제가 있었음; v1.0.1에서 수정됨. 최신 버전으로 업그레이드하세요.
완전히 제거하는 방법
macOS: 휴지통으로 드래그
Windows: 설정 → 앱 → 제거
Linux:
sudo apt remove pinslip또는 AppImage 직접 삭제vault 디렉터리 삭제 (사전에 백업)
데이터는 누구의 것인가
사용자 본인입니다. PinSlip은 그저 단순한 인터페이스일 뿐이며, 메모는 항상 사용자의 디스크에 Markdown 파일로 존재합니다.
PinSlip이 더 이상 운영되지 않더라도, Obsidian / VS Code / Typora 같은 어떤 편집기로도 열 수 있습니다.
이것이 바로 PinSlip이 태어나면서부터 가진 설계 철학입니다.