Longterm Copilot
설치 가이드 · 비개발자용

5분 만에 시작하기 (베타)

인증서 1쌍과 5분이면 됩니다. 운영체제별 zip 다운로드 → 환경변수 설정 → ltc setup → ltc whoami 검증 → ltc check 9 룰 점검.

처음이라 부담스러우시면 📘 비개발자 친화 A-Z 가이드를 참조하세요. 운영체제 확인부터 자연어 호출까지 단계별로 안내해드립니다.

v0.0.10.2 · prerelease (베타)
1

운영체제별 zip 다운로드

본 페이지는 접속한 OS를 자동으로 감지하여 추천 버튼에 강조 표시를 합니다. JavaScript가 비활성화된 환경에서도 4 OS 모두 동등하게 표시됩니다.

macOS Apple Silicon
arm64
2.9 MB SHA256: 3f17bc3b…
다운로드 추천
macOS Intel
x86_64
3.1 MB SHA256: de05ea9c…
다운로드 추천
Linux
x86_64
3.1 MB SHA256: 6ce78b9d…
다운로드 추천
Windows
x64
3.1 MB SHA256: fbb6da79…
다운로드 추천
SHA256 검증 (선택)

파일 무결성 확인을 원하시면 SHA256SUMS.txt 다운로드 후 다음 명령으로 검증하세요: 

shasum -a 256 -c SHA256SUMS.txt

Windows PowerShell: Get-FileHash ltc-windows-amd64.zip -Algorithm SHA256

2

6단계로 끝내는 설치

zip 압축 해제 후 5분 안에 완료되는 단계별 안내입니다. macOS / Linux / Windows 각 운영체제별 명령을 함께 표기했습니다.

  1. ①

    압축 해제

    다운로드한 zip을 원하는 디렉토리에 풉니다.

    # macOS Apple Silicon 예시
unzip ltc-darwin-arm64.zip -d ~/ltc-bridge
chmod +x ~/ltc-bridge/auth-bridge-darwin-arm64
    # Linux
unzip ltc-linux-amd64.zip -d ~/ltc-bridge
chmod +x ~/ltc-bridge/auth-bridge-linux-amd64

    Windows: 탐색기에서 다운로드한 zip을 우클릭 → "압축 풀기" → C:\ltc-bridge 같은 경로에 풉니다. 실행 권한은 자동입니다.

  2. ②

    npm 패키지 글로벌 설치 — ltc 명령 등록

    zip 내부에 동봉된 4개 tarball(ltc-types/ltc-core/ltc-mcp/ltc-cli)을 글로벌 설치하면 ltc 명령어가 PATH에 등록됩니다. Node.js 22 LTS가 사전에 설치되어 있어야 합니다 (node --version 확인). 

    # macOS / Linux (~/ltc-bridge로 이동 후 한 줄)
cd ~/ltc-bridge
npm install -g ./ltc-types-*.tgz ./ltc-core-*.tgz ./ltc-mcp-*.tgz ./ltc-cli-*.tgz
    # Windows PowerShell
cd C:\ltc-bridge
npm install -g .\ltc-types-0.0.7.tgz .\ltc-core-0.0.7.tgz .\ltc-mcp-0.0.7.tgz .\ltc-cli-0.0.7.tgz

    권한 에러 시 macOS/Linux는 sudo npm install -g ..., Windows는 PowerShell을 "관리자 권한으로 실행"하세요. 설치 후 ltc --version 으로 정상 등록 여부를 확인할 수 있습니다.

  3. ③

    환경변수 설정 — LTC_AUTH_BRIDGE_BIN

    auth-bridge 바이너리 경로를 환경변수로 알려줍니다.

    # macOS / Linux (bash, zsh)
export LTC_AUTH_BRIDGE_BIN="$HOME/ltc-bridge/auth-bridge-darwin-arm64"
# 영구 적용: ~/.zshrc 또는 ~/.bashrc 에 위 라인 추가
    # Windows PowerShell (현재 세션)
$env:LTC_AUTH_BRIDGE_BIN = "C:\ltc-bridge\auth-bridge-windows-amd64.exe"

# 영구 적용 (재시작 후에도 유지)
[Environment]::SetEnvironmentVariable(
  "LTC_AUTH_BRIDGE_BIN",
  "C:\ltc-bridge\auth-bridge-windows-amd64.exe",
  "User"
)

    Linux x86_64는 auth-bridge-linux-amd64, Intel Mac은 auth-bridge-darwin-amd64로 파일명을 바꿔서 적용하세요.

  4. ④

    ltc setup — 인증서·기관기호 등록 (대화형)

    인증서 디렉토리, 비밀번호(Keychain 저장), 기관기호를 한 번 등록합니다. 명령을 인자 없이 실행하면 4개 질문이 순서대로 표시됩니다. 기본값이 미리 입력되어 있으며, Enter로 채택하거나 Backspace로 지우고 새 경로 입력도 가능합니다.

    ltc setup
? 인증서 디렉토리 경로 (Enter=기본값 사용, 수정 시 Backspace): ~/ltc-bridge/테스트재가복지센터
? 인증서 비밀번호: ************   (입력 시 * 마스킹)
? 기관기호 (10~11자리 숫자): 21165000216
? 기관 유형 코드: B01   (방문요양 = B01)
✓ ~/.ltc/config.json 저장
✓ Keychain에 비밀번호 안전 저장
✓ 로그인 테스트 성공

    📁 경로 입력 방식 — 두 가지 모두 가능

    표기 ① ~/ 단축 (모든 OS 권장):

    ~/ltc-bridge/테스트재가복지센터

    본인 홈 디렉터리로 자동 확장되어 저장됩니다 (운영체제별 실제 절대경로):

    • macOS: /Users/<사용자>/ltc-bridge/테스트재가복지센터
    • Linux: /home/<사용자>/ltc-bridge/테스트재가복지센터
    • Windows: C:\Users\<사용자>\ltc-bridge\테스트재가복지센터

    표기 ② Windows 절대경로 (드라이브 루트):

    C:\ltc-bridge\테스트재가복지센터

    이 경우 C:\ltc-bridge\ 와 C:\Users\<사용자>\ltc-bridge\ 는 서로 다른 위치입니다. zip을 푼 실제 위치와 일치시키세요.

    비밀번호는 macOS Keychain · Windows Credential Manager · Linux Secret Service에만 저장되며 파일에 절대 기록되지 않습니다.

    비대화형 모드(flag 전달)는 현재 미지원 — 다음 사이클에서 추가 예정입니다.

  5. ⑤

    ltc whoami — 인증 검증

    등록된 인증서로 NPBS에 즉시 로그인하여 기관 정보를 회신합니다.

    ltc whoami
→ 햇살재가복지센터 · 인증 OK · 0.6s

    실패 시 FAQ "ltc whoami가 인증 실패로 끝나요" 항목을 참조하세요.

  6. ⑥

    ltc check — 9 룰 자동 점검

    누락 청구·계약 만료·평가 자료 결격 등 9개 룰을 일괄 점검합니다.

    ltc check
✓ 청구 누락 점검 — 2건 발견
✓ 계약 만료 임박 — 3명
✓ 재가 정기평가 자료 — 결격 0
…

    여기까지 끝났다면 정상 가동입니다. MCP 등록(§6)은 선택이며, 자연어로 호출하고 싶을 때만 진행하세요.

3

인증서 준비 (NPBS)

국민건강보험공단(NPBS) 포털에서 발급받으신 signCert.der + signPri.key 한 쌍이 필요합니다. 본 도구는 인증서 파일을 외부 서버로 송신하지 않습니다 — NPBS API 호출에만 로컬에서 사용합니다.

필요한 파일

  • signCert.der — 공개 인증서
  • signPri.key — 개인 키

두 파일은 같은 디렉토리에 있어야 합니다.

경로 예시

~/ltc-bridge/<기관명>/
├── signCert.der
└── signPri.key

권한 (macOS / Linux)

chmod 0700 ~/ltc-bridge/<기관명>
chmod 0600 ~/ltc-bridge/<기관명>/signCert.der
chmod 0600 ~/ltc-bridge/<기관명>/signPri.key

디렉토리 0700, 파일 0600 — 본인만 읽기/쓰기 가능 권한.

외부 송신 0건 약속

인증서 파일은 본 PC에만 보관되며, NPBS 호출에만 로컬에서 사용됩니다. Anthropic·OpenAI 등 LLM 서버로도, 본 도구 개발자 측 서버로도 송신되지 않습니다.

인증서 발급 절차는 공단 포털 longtermcare.or.kr 의 인증서 발급 안내를 참조하세요.

4

macOS Gatekeeper 우회

본 베타 단계에서는 Apple Developer ID 코드사이닝이 미실행 상태입니다. macOS에서 처음 실행 시 "확인되지 않은 개발자" 또는 "열 수 없음" 경고가 나타날 수 있습니다. 아래 명령으로 1회만 격리 속성을 제거하면 이후 정상 실행됩니다. 

# 격리 속성 제거 (1회만)
xattr -d com.apple.quarantine ~/ltc-bridge/auth-bridge-darwin-arm64

# 실행 확인
~/ltc-bridge/auth-bridge-darwin-arm64 --version
# → ltc-auth-bridge v0.0.10.2 (정상 실행)

정식 출시 시점에는 Apple Developer ID 코드사이닝 인증서로 자동 해소될 예정입니다.

5

Windows SmartScreen 우회

Windows에서 처음 실행 시 SmartScreen이 "Windows에서 PC를 보호했습니다" 경고를 표시할 수 있습니다. 아래 절차로 우회하시면 됩니다 (1회만).

  1. 경고창에서 "추가 정보" 텍스트 클릭
  2. 표시된 "실행" 버튼 클릭
  3. 이후 동일 파일은 경고 없이 자동 실행됩니다

정식 출시 시점에는 Microsoft Authenticode 코드사이닝 인증서로 자동 해소될 예정입니다.

6

MCP 등록 (선택, 자연어로 호출)

Claude Desktop · Claude Code · Codex CLI · Cursor 4 클라이언트에 1줄로 등록할 수 있습니다. 등록하면 "이번 달 미승인 RFID 보여줘" 같은 자연어로 ltc 명령을 호출할 수 있습니다. 

ltc mcp install --target claude-desktop
# 또는: --target claude-code | codex-cli | cursor | manual

Windows Claude Desktop (MS Store) 사용자: ltc mcp install --target claude-desktop 명령이 MS Store 경로 (%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\)와 일반 경로 (%APPDATA%\Claude\) 양쪽을 자동 탐지합니다. MS Store 경로가 우선 선택됩니다.

env.LTC_AUTH_BRIDGE_BIN 자동 주입: 등록 시 생성되는 claude_desktop_config.json에 env.LTC_AUTH_BRIDGE_BIN 필드가 자동으로 추가됩니다. MS Store sandbox 환경에서도 auth-bridge 바이너리 경로를 직접 전달하므로 MCP가 정상 작동합니다.

PowerShell BOM 주의: config 파일을 직접 편집 시 BOM 없는 UTF-8(UTF-8 without BOM)로 저장하세요. PowerShell 5.x: [IO.File]::WriteAllLines($path, $content, [Text.UTF8Encoding]::new($false))
PowerShell 7+: Set-Content -Path $path -Value $content -Encoding UTF8NoBOM

claude-desktopAnthropic Claude Desktop 앱
claude-codeAnthropic Claude Code CLI
codex-cliOpenAI Codex CLI
cursorCursor 에디터
manual 베타 zip 사용자 권고 — 수동 등록 안내 출력 (BETA-TESTER-GUIDE §3 참조)

자연어 호출 시나리오

  • "이번 달 미승인 RFID 보여줘" → check-rfid --month 2026-05 자동 호출
  • "4월 청구 요약해줘" → claim-summary --month 2026-04 자동 호출
  • "계약 만료 임박 명단 뽑아줘" → contract-expiring --within 30d 자동 호출
⚠️ 개인정보 처리 안내

MCP 등록 시 사용자가 사용하는 LLM 클라이언트(Claude Desktop · Cursor · Codex 등)를 통해 조회 결과 데이터가 LLM 서버(Anthropic · OpenAI 등 LLM 제공자)로 송신될 수 있습니다. 귀 센터가 개인정보보호법상 위탁처리·국외이전 고지 주체가 됩니다.

MCP를 등록하지 않으면 본 도구는 LLM 서버로 데이터를 송신하지 않으며, NPBS와의 로컬 통신만 발생합니다. (선택 기능)

7

버전 확인 및 업데이트

현재 설치된 버전과 최신 버전을 비교하고 새 버전이 있으면 안내해 드립니다. 자동 다운로드/설치는 보안상 제외했습니다. 사용자가 직접 새 zip을 받아 교체하시면 됩니다.

📌 현재 버전 확인

ltc --version
# → ltc 0.0.10.2 (auth-bridge 0.0.10.2-darwin-arm64)

ltc-cli 패키지 버전과 auth-bridge 바이너리 버전이 함께 표시됩니다. 두 버전이 다르면 ZIP 재설치를 권장합니다.

🔍 최신 버전 체크

ltc update
# → 현재 버전: 0.0.10.2 (최신)
#   마지막 확인: 2026-05-13T06:04:03.970Z

# (구버전이 설치된 경우)
# → 현재 버전: 0.0.3
#   최신 버전: v0.0.10.2 (prerelease, 2026-05-13)
#   변경사항: 자세한 내용은 GitHub Releases 참조
#   다운로드: https://longterm-copilot.pages.dev/install/#download

longterm-copilot.pages.dev/downloads/version.json에서 최신 버전을 조회합니다. 네트워크 차단 시 버전 확인 실패: 네트워크 오류, 다음에 다시 시도 메시지가 표시됩니다.

JSON 출력이 필요한 경우 ltc update --format json, 타임아웃 조정은 ltc update --timeout 10000 (ms)을 사용하세요.

🔄 업데이트 방법 (전체 절차, ~1분)

v0.0.8 같은 신규 버전에는 auth-bridge 바이너리 변경(NPBS 호출 수정 등)과 ltc CLI 변경(setup 동작 개선 등) 두 가지가 함께 들어갈 수 있습니다. 완전한 적용을 위해 zip 덮어쓰기 + npm 재설치를 모두 진행하는 것을 권장합니다.

macOS / Linux

# 1. 최신 zip 다운로드 (예: macOS Apple Silicon)
curl -LO https://longterm-copilot.pages.dev/downloads/latest/ltc-darwin-arm64.zip

# 2. 기존 폴더에 덮어쓰기 (-o = overwrite without prompt)
unzip -o ltc-darwin-arm64.zip -d ~/ltc-bridge

# 3. macOS만: Gatekeeper 격리 속성 재제거 (1회)
xattr -d com.apple.quarantine ~/ltc-bridge/auth-bridge-darwin-arm64

# 4. npm 글로벌 재설치 (ltc CLI 갱신)
cd ~/ltc-bridge
npm install -g ./ltc-types-*.tgz ./ltc-core-*.tgz ./ltc-mcp-*.tgz ./ltc-cli-*.tgz

# 5. 검증
ltc --version
# → ltc 0.0.7 (auth-bridge 0.0.7-darwin-arm64)

Windows (PowerShell)

# 1. 다운로드 페이지에서 최신 ltc-windows-amd64.zip 받기
#    (브라우저로 https://longterm-copilot.pages.dev/install/#download 접속)

# 2. 탐색기에서 zip 우클릭 → "압축 풀기" → 기존 C:\ltc-bridge 위에 덮어쓰기

# 3. npm 글로벌 재설치 (관리자 권한 PowerShell 권장)
cd C:\ltc-bridge
ls *.tgz   # 동봉된 tarball 실제 파일명 확인
npm install -g .\ltc-types-0.0.7.tgz .\ltc-core-0.0.7.tgz .\ltc-mcp-0.0.7.tgz .\ltc-cli-0.0.7.tgz

# 4. 검증
ltc --version
# → ltc 0.0.7 (auth-bridge 0.0.7-windows-amd64)

마지막 단계 — MCP 사용자만 Claude Desktop 재시작: Claude Desktop이 auth-bridge 바이너리를 잡고 있을 수 있으므로 재시작하면 새 버전이 적용됩니다.

간단 시나리오 (auth-bridge 바이너리만 교체): ltc --version 의 괄호 안 값(예: auth-bridge 0.0.7-...)만 갱신하면 충분한 경우, 위 절차에서 1·2·3·5만 수행해도 됩니다. 단, ltc setup 기본값 등 CLI 변경사항은 적용되지 않습니다.

8

자주 묻는 질문 (트러블슈팅)

다운로드한 zip이 macOS에서 "열 수 없음"으로 거부됩니다

베타 단계에서 코드사이닝이 미실행이라 macOS Gatekeeper가 격리 속성을 부여합니다. §4 macOS Gatekeeper 우회 참조 — xattr -d com.apple.quarantine 명령으로 1회 해소됩니다.

Windows에서 SmartScreen 경고가 떠요

§5 SmartScreen 우회 참조 — 경고창에서 "추가 정보 → 실행" 절차로 진행하시면 이후 동일 파일은 경고 없이 실행됩니다.

ltc 명령어를 찾을 수 없다고 나와요 (command not found)

zip 압축 해제만 한 상태에서는 ltc 명령이 등록되지 않습니다. zip 내부의 4개 tarball(ltc-types/ltc-core/ltc-mcp/ltc-cli)을 npm 글로벌 설치해야 PATH에 등록됩니다. (설치 안내 §2 step ② 참조) 

# macOS / Linux
cd ~/ltc-bridge
npm install -g ./ltc-types-*.tgz ./ltc-core-*.tgz ./ltc-mcp-*.tgz ./ltc-cli-*.tgz

# Windows PowerShell
cd C:\ltc-bridge
npm install -g .\ltc-types-0.0.7.tgz .\ltc-core-0.0.7.tgz .\ltc-mcp-0.0.7.tgz .\ltc-cli-0.0.7.tgz

설치 후 ltc --version 으로 확인하세요.

  • 권한 에러: macOS/Linux는 sudo 추가, Windows는 PowerShell을 관리자 권한으로 실행
  • Node 미설치 에러: nodejs.org 에서 LTS 22.x 설치 (필수)
  • npm prefix 변경 시 macOS/Linux: $(npm prefix -g)/bin 가 PATH에 있는지 확인
ltc whoami가 인증 실패로 끝나요

cert 디렉토리 권한과 파일명을 확인하세요. signCert.der + signPri.key 파일이 정확한 이름으로 같은 디렉토리에 있어야 하며, 권한은 디렉토리 0700, 파일 0600입니다. 

ls -la ~/ltc-bridge/<기관명>/
# signCert.der  -rw-------
# signPri.key   -rw-------

chmod 0700 ~/ltc-bridge/<기관명>
chmod 0600 ~/ltc-bridge/<기관명>/*

비밀번호도 Keychain에 정상 저장됐는지 확인 — ltc setup을 다시 실행하시면 갱신됩니다.

MCP 등록 후 Claude Desktop에서 안 보여요

Claude Desktop을 완전히 종료한 후 재시작하세요. 등록 직후에는 설정 파일이 아직 로드되지 않았을 수 있습니다. 

# macOS — 설정 파일 위치 확인
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows — 설정 파일 위치 확인
type %APPDATA%\Claude\claude_desktop_config.json

파일에 "longterm-copilot" 항목이 추가됐는지 확인 후, Claude Desktop 재시작.

Windows에서 한글이 깨져 보여요 (□□□ 또는 ?)

PowerShell의 기본 코드페이지가 UTF-8이 아니어서 발생합니다. 다음 중 하나로 해결하세요: 

# 방법 1: 현재 세션만 UTF-8로 (PowerShell)
chcp 65001
ltc whoami

# 방법 2: Windows Terminal 사용 (권장)
# 시작 메뉴 → "Terminal" 검색 → 실행

Windows Terminal은 UTF-8을 기본 지원하며 한글 폭도 정확하게 렌더링합니다.

9

105 서식 — Standard 플랜 안내

공단 공식 105 서식 자동 채움은 Standard 플랜 전용 기능입니다. 베타 단계(Lite)에서는 비활성이며, ltc draft 등 4 명령은 진입 시 Standard 안내 후 종료됩니다.

정식 Standard 출시 시점에 RAG 기반 좌표 자동 매핑과 분기별 갱신 SLA로 활성화됩니다. 베타 검증 단일 가치축은 22종 조회 + 9 룰 자동 점검 + MCP 26 자연어입니다.