CG Claude 튜토리얼: Claude Code 로컬 환경 점검, 구성 및 안전한 복원

CG Claude란

CG Claude는 Claude Code 로컬 환경을 위한 구성 및 검사 워크벤치로, Electron 데스크톱 버전과 로컬 브라우저 버전을 제공합니다. 시스템, 터미널, 브라우저, 프록시, TLS, Claude 구성 및 프로젝트 재정의를 검사하고, 미리보기, 백업 및 스냅샷 기능을 통해 구성 복구를 지원합니다.

이 도구에는 31개의 환경 검사가 포함되어 있으며, 기본적으로 연속 세 번 검사합니다. 환경 결과를 바탕으로 계정 상태를 추정하지 않습니다. 계정 세션, 서비스 지역, 할당량, 결제, 웹 개인정보 보호 및 일부 네트워크 상태는 여전히 수동으로 확인해야 합니다.

주요 기능

• 시스템 및 브라우저 시간대, 터미널 TZ, 프록시, DNS, IPv6, TLS, 인증 출처 및 Claude 구성 디렉터리를 검사합니다.
• 13개의 프로세스 노드를 통해 구성을 실행하며, 각 노드는 처음 실패한 후 최대 세 번 재시도하고, 실패하면 건너뛰고 다음 노드를 계속 실행합니다.
• 변경 전에 미리보기를 표시하고 쓰기 전에 백업을 생성합니다. 첫 번째 구성 노드에서는 전체 구성 스냅샷도 저장합니다.
• 프로젝트의 권한, Hooks, MCP, 프록시, TLS, 자격 증명 선언 및 의존성 잠금 파일을 검사합니다.
• 프록시, 게이트웨이, NO_PROXY 및 추가 CA 경로를 포함한 Claude 로컬 연결 설정을 편집합니다.
• 파일 내용, 권한, 파일 누락 상태, 검사 기본 설정 및 기록된 시간대와 TZ를 저장하고 복원합니다.
• OpenAI 호환 Chat Completions 또는 Anthropic Messages를 구성하고, 고정된 예시로 중한 및 한중 양방향 번역을 테스트합니다.
• 중국어 및 영어 인터페이스, 밝은색／눈 보호／어두운색 테마, 애니메이션 줄이기 및 수동 버전 확인을 제공합니다.

CG Claude는 지원되는 구성 파일만 정적으로 분석합니다. 시작 스크립트, 프로젝트 스크립트, Hooks, MCP 또는 의존성 설치를 실행하지 않으며, 키체인, Claude 세션, Skills 또는 Hooks를 자동으로 정리하지도 않습니다.

데스크톱 버전 설치

일반 사용자는 데스크톱 설치 패키지를 우선 사용하세요. 버전 1.2.7 설치 패키지는 Release 첨부 파일의 release/1.2.7/에 있으며, 설치 후 Node.js를 별도로 설치할 필요가 없습니다.

• macOS Apple Silicon:CG-Claude-1.2.7-macos-arm64.dmg
• macOS Intel:CG-Claude-1.2.7-macos-x64.dmg
• Windows x64:CG-Claude-1.2.7-windows-x64-setup.exe
• Linux x64:CG-Claude-1.2.7-linux-x86_64.AppImage 또는 CG-Claude-1.2.7-linux-amd64.deb

다운로드 후 SHA256SUMS.txt를 사용해 파일 무결성을 확인할 수 있습니다. macOS 빌드는 아직 서명되거나 공증되지 않았으며, Windows 및 Linux 데스크톱 상호작용은 아직 실제 기기에서 검증되지 않았습니다.

데스크톱 창을 닫거나 최소화하면 일반적으로 메뉴 막대 또는 시스템 트레이로 숨겨지지만 작업은 계속 실행됩니다. 서비스를 완전히 종료하려면 트레이 메뉴에서 “CG Claude 종료”를 선택하세요. 프로그램은 검사, 구성 또는 복원 트랜잭션이 끝날 때까지 기다린 후 서비스 잠금을 해제합니다.

데스크톱 버전과 브라우저 서비스는 동일한 기록 디렉터리를 동시에 사용할 수 없습니다. 두 버전 중 하나를 시작하기 전에 다른 인스턴스를 종료하여 동시 쓰기를 방지하세요.

소스 코드에서 실행

환경 준비

소스 코드 실행에는 Node.js 22.12 이상이 필요합니다. 프로젝트 디렉터리로 이동한 후 잠금된 의존성을 설치하고 Electron을 시작합니다.

npm ci
npm run desktop

macOS에서는 启动工具.command를 두 번 클릭할 수도 있고, Windows에서는 启动工具.cmd를 두 번 클릭할 수 있습니다. Linux 사용자는 프로젝트 디렉터리에서 npm run desktop을 실행해야 합니다.

준비 스크립트는 잠금된 버전에 따라 Electron을 다운로드하고 이미 설치된 바이너리를 재사용합니다. 다운로드 과정에서는 기존 HTTP／HTTPS 프록시 환경을 사용하지만 사용자 프록시 설정은 변경하지 않습니다.

브라우저 버전 시작

npm run build
npm start

시작 후 http://127.0.0.1:4318에 접속합니다. 서비스는 루프백 주소에서만 수신하며 Ctrl+C로 종료할 수 있습니다. Linux에서는 다음 명령도 실행할 수 있습니다.

./scripts/start.sh

첫 번째 검사: 환경 기준선 설정

1. 검사 기본 설정을 지정합니다. 실제 네트워크 모드, 서비스 방식, 시간대 목표 및 개인정보 보호 기본 설정을 선택합니다. 시간대는 기본적으로 타이베이 기준으로 확인하도록 권장되며, 현재 출구 또는 수동 지정으로 변경할 수도 있습니다.
2. 선택적 네트워크 검사를 확인합니다. 기본 검사는 주로 로컬 구성을 읽습니다. 공용 네트워크 출구를 조회하거나 WebRTC 데이터를 수집하려면 추가로 선택해야 하며, 관련 외부 서비스에는 연결 IP가 표시됩니다.
3. 검사를 시작합니다. “검사 시작”을 클릭하면 도구가 기본적으로 검사를 연속 세 번 실행하여 일시적인 상태로 인한 오판을 줄입니다.
4. 상태별로 필터링합니다. 상단의 “검사 통과”, “주의 필요” 또는 “확인 대기” 항목을 사용합니다. 이 항목을 선택하면 기존 검색 및 분류 조건이 지워지고 첫 번째 결과가 펼쳐져 표시됩니다.
5. 증거와 범위를 확인합니다. 결과는 통과, 주의 필요, 처리 필요, 확인 대기 및 검사되지 않음으로 나뉩니다. 계정, 지역, 결제, 웹 개인정보 보호, 휴대전화 시간대 또는 위치 서비스와 관련된 항목은 안내에 따라 수동으로 확인해야 합니다.

31개 검사는 시스템 및 브라우저 시간대, TZ, 시스템 프록시, 가상 인터페이스, DNS, IPv6, 프로세스 및 시작 파일 프록시, npm 및 Git 프록시, API 주소, Claude 구성 디렉터리, 개인정보 보호, CLI, TLS, 프록시 호환성, 인증 출처, 사용자 지정 CA／mTLS와 선택적 공용 네트워크 출구 및 브라우저 일관성을 다룹니다.

원클릭 구성 실행

검사가 끝난 후 바로 무작정 쓰기를 실행하지 마세요. 먼저 변경 미리보기를 읽고 목표 값, 영향받는 파일 및 시스템 권한이 필요한 작업을 확인합니다.

1. “원클릭 구성”을 클릭하고 네트워크 모드, 서비스 방식 및 개인정보 보호 기본 설정을 항목별로 입력합니다. 사용자 지정 API 주소 정리는 기본적으로 선택되지 않습니다.
2. 기본적으로 선택된 시스템 시간대와 터미널 TZ 두 노드를 확인합니다. 변경하지 않으려면 선택을 해제할 수 있습니다.
3. 쓰기 미리보기를 읽고 변경될 필드, 파일 및 권한을 확인합니다.
4. 구성을 시작합니다. 도구는 13개 노드를 순서대로 실행하며, 쓰기 전에 매번 백업을 저장하고 첫 번째 노드에서 전체 스냅샷을 저장합니다.
5. 구성이 끝나면 한곳에 표시된 남은 작업에 따라 설정 페이지를 열거나 명령을 복사하거나 터미널을 시작하여 자동으로 처리할 수 없는 단계를 완료합니다.
6. 터미널과 Claude 클라이언트를 다시 열고 세 번 재검사합니다. 이미 열려 있는 터미널은 파일 변경으로 환경 변수가 자동 갱신되지 않습니다.

도구는 셸, npm 및 Git 사용자 프록시, 셸 및 Claude 사용자 지정 API 주소, Claude 개인정보 보호 변수와 npm TLS 검증을 처리할 수 있습니다. 또한 원클릭 과정에서 시스템 시간대와 터미널 TZ를 구성할 수 있습니다.

지원되는 구성 위치는 다음과 같습니다.

• .zshrc, .zprofile, .zshenv
• .bashrc, .bash_profile, .bash_login, .profile
• .npmrc, .gitconfig, .config/git/config
• .claude/settings.json

macOS에서 시스템 시간대를 변경하려면 관리자 권한이 필요하고, Windows에서는 UAC를 사용하며, Linux에서는 사용 가능한 polkit 에이전트가 필요합니다. macOS 자동 시간대가 활성화되어 있고 상태를 읽을 수 있는 경우, 원클릭 구성은 권한을 승인한 후 자동 시간대를 끄고 결과를 다시 읽습니다.

Claude 로컬 연결 편집

탐색 메뉴 끝에 있는 “로컬 구성”을 열면 연결 매개변수를 항목별로 유지, 설정 또는 제거할 수 있습니다. 이 기능은 ~/.claude/settings.json의 다음 필드만 기록합니다.

• HTTPS_PROXY
• HTTP_PROXY
• NO_PROXY
• ANTHROPIC_BASE_URL
• NODE_EXTRA_CA_CERTS

저장하기 전에 미리보기를 표시하며, 변경 전 전체 스냅샷과 원본 파일 백업을 기록합니다. 다른 필드, Hooks, 권한 및 자격 증명은 유지되고 JSON은 최종적으로 두 칸 들여쓰기로 통일됩니다. 같은 이름의 소문자 프록시 항목 정규화도 미리보기에 표시됩니다.

추가 CA 파일은 읽을 수 있고 비어 있지 않은 로컬 절대 경로여야 합니다. 도구는 인증서 내용을 읽지 않으며 이를 위해 연결 요청을 실행하지도 않습니다. 사용자 지정 CLAUDE_CONFIG_DIR가 감지되면 잘못된 디렉터리에 쓰는 것을 방지하기 위해 연결 편집 진입점이 비활성화됩니다.

프로젝트 구성 검사

“프로젝트 검사”를 열고 로컬 프로젝트 디렉터리를 선택합니다. 검사 범위에는 구성 재정의, 권한, 명령 샌드박스, Hooks, MCP, 프록시, TLS, 자격 증명 선언, 의존성 잠금 파일 및 로컬 Git 커밋이 포함됩니다.

프로젝트 검사는 고정된 구성 및 메타데이터 파일만 읽으며 프로젝트 스크립트, Hooks, MCP 또는 의존성 설치를 실행하지 않습니다. dotenv 파일의 경우 도구는 존재 여부만 확인하고 내용을 읽지 않습니다. 자격 증명 필드는 안내만 제공하며 값을 표시하지 않습니다.

프로젝트 검사는 소스 코드 취약점, 의존성 취약점 또는 빌드 정확성 검사를 대체할 수 없습니다. 이러한 문제는 해당 보안, 의존성 및 빌드 도구를 사용하여 별도로 확인해야 합니다.

백업 및 전체 스냅샷 복원

“백업 복원”에서 기존 전체 스냅샷을 선택하고 “이전 구성 스냅샷 원클릭 복원”을 클릭합니다. 복원 범위에는 파일 내용, 원래 권한, 파일이 원래 존재하지 않았던 상태, 검사 기본 설정 및 기록된 시스템 시간대와 TZ가 포함될 수 있습니다.

1. 대상 스냅샷을 선택하고 복원 미리보기를 확인합니다.
2. 파일 내용, 권한 및 시간대 상태가 여전히 미리보기 기준선과 일치하는지 확인합니다.
3. 복원을 실행합니다. 도구는 먼저 현재 상태를 추가로 저장한 다음 대상 스냅샷을 복원합니다.
4. 터미널과 클라이언트를 다시 열고 환경 변수 및 Claude 구성을 확인합니다.

미리보기 후 파일 내용, 권한 또는 시간대가 변경되면 새 변경 사항을 덮어쓰지 않도록 복원이 차단됩니다. 스냅샷은 지원되는 11개의 사용자 구성 위치, 검사 기본 설정 및 읽을 수 있는 시간대와 TZ만 덮어씁니다. 번역 구성, 전체 ~/.claude 디렉터리, 키체인 또는 이전 세션은 포함하지 않습니다.

양방향 번역 구성

왼쪽의 “양방향 번역”에서 프로토콜, API 주소, 모델명, 키 및 시간 초과를 설정할 수 있습니다. OpenAI 호환 Chat Completions와 Anthropic Messages를 지원합니다.

“양방향 번역 테스트”를 클릭하면 도구가 고정된 예시 두 개를 실제로 전송하고, 중한 및 한중 결과를 각각 표시합니다. 테스트는 프로젝트 내용이나 Claude 세션을 읽지 않으며 비용이 발생할 수 있는 요청을 자동으로 재시도하지 않습니다.

키는 AES-256-GCM으로 암호화되며 마스터 키는 로컬 개인 기록 디렉터리에 저장됩니다. 그러나 시스템 키체인이 아니므로 해당 디렉터리에 대한 읽기 권한이 있는 사람은 여전히 복호화할 수 있습니다. 저장된 키는 인터페이스로 반환되지 않으며 서비스 주소 또는 프로토콜을 변경한 후에는 다시 입력해야 합니다.

번역 모델 테스트를 통과했다고 해서 Claude Code 기본 터미널이 연결된 것은 아니며, 세션 가로채기가 자동으로 활성화되지도 않습니다.

격리 데모 및 CLI 사용

실제 구성을 변경하기 전에 격리 데모 모드를 사용할 수 있습니다.

npm run demo
npm run desktop:demo

demo는 전용 임시 구성 디렉터리와 4319 포트를 사용하고, desktop:demo는 독립적인 Electron 프로필 디렉터리를 사용합니다. 데모 쓰기는 테스트 디렉터리에만 적용되며 시스템 시간대와 TZ는 격리된 방식으로 시뮬레이션됩니다. 플랫폼 정보와 클라이언트 버전은 여전히 로컬 컴퓨터에서 읽습니다.

검사 결과를 자동으로 읽어야 하는 경우 CLI를 사용할 수 있습니다.

npm run doctor -- --json

CLI는 기본적으로 검사만 수행하고 구성을 변경하지 않습니다. 터미널 공용 네트워크 조회를 활성화하려면 --network를 추가합니다.

npm run doctor -- --json --network

자주 사용하는 실행 변수

• CG_PORT: 브라우저 서비스 포트. 기본값은 4318이며 Electron은 임의의 루프백 포트를 사용합니다.
• CG_HOME: 사용자 구성 루트 디렉터리. 기본값은 현재 사용자의 홈 디렉터리이며 격리 검증에 사용할 수 있습니다.
• CG_DATA_DIR: 기록 디렉터리. 기본적으로 구성 루트 디렉터리 아래의 .claude-guard에 있습니다.
• CG_DEMO=1: 격리 모드를 표시하며, 독립적인 구성 루트 디렉터리를 함께 지정해야 합니다.

고급 사용 권장 사항

오래된 미리 보기 사용 피하기

이전 보고서, 검사 기본 설정 또는 구성 기준이 변경된 경우 다시 검사한 후 수정 사항을 미리 보세요. 이전 보고서는 계속 읽을 수 있지만 새 쓰기 작업의 기준으로 직접 사용해서는 안 됩니다. 도구는 파일 권한과 읽기 상태도 확인하며, 이미 변경된 미리 보기를 그대로 사용하는 것을 거부합니다.

복잡한 구성 파일 올바르게 처리하기

시작 파일은 직접 할당만 정적으로 분석합니다. 복잡한 함수, 조건 블록, 여러 줄 표현식 및 heredoc은 자동으로 편집되지 않습니다. 구성 텍스트는 엄격한 UTF-8이어야 합니다. 잘못된 UTF-8 또는 NUL이 포함된 파일은 스냅샷에서 제외되고 수동 확인 안내가 표시되며, GBK 등의 인코딩으로 추측하지 않습니다.

공용 네트워크 검사에서 개인정보 보호 범위 이해하기

공용 네트워크 검사는 https://ipinfo.io/json, https://api.ipify.org?format=json 및 stun:stun.l.google.com:19302에 접속할 수 있습니다. 이러한 서비스는 연결 IP를 확인할 수 있지만 로컬 구성이나 키를 전달받지는 않습니다. 보고서 내보내기에서는 기본적으로 IP와 호스트 이름을 추가로 숨깁니다.

브라우저 언어와 시간대 구성 구분하기

브라우저 대상 언어의 기본값은 en-US이며, en-CN도 영어이지만 지역이 다릅니다. 이 검사는 프로젝트 확장 항목이며 원문에서 필수로 요구한 사항이 아닙니다. 원클릭 시간대 구성은 외부 브라우저 언어를 변경하지 않으므로 페이지에서 제공하는 Chrome, Edge, Firefox 또는 Safari 안내에 따라 수동으로 설정해야 합니다.

로컬 기록 보호하기

기본 기록 디렉터리는 ~/.claude-guard/이며, 검사 기본 설정, 최근 30개 보고서, 백업, 스냅샷, 수동 검토 및 워크플로 상태가 저장됩니다. 백업이나 스냅샷 원문에는 자격 증명이 포함될 수 있으므로 이 디렉터리를 함부로 복사하거나 커밋하지 마세요.

POSIX 시스템에서 기록 디렉터리 권한은 0700, 기록 파일 권한은 0600이며, Windows에서는 사용자 디렉터리 ACL을 상속합니다. 새 구성 파일은 POSIX에서 0600 권한으로 생성하고, 가능한 한 기존 구성의 권한을 유지합니다.

개발 및 패키징

개발 모드에서는 프런트엔드에 5173 포트, 백엔드에 4318 포트를 사용합니다.

npm run dev

변경 사항을 커밋하기 전에 전체 검사와 형식 검사를 실행할 수 있습니다.

npm run check
npm run format:check

애플리케이션 디렉터리 또는 현재 플랫폼용 설치 패키지를 생성합니다.

npm run pack
npm run dist

pack은 애플리케이션 디렉터리를 생성합니다. dist는 현재 시스템에 따라 macOS dmg／zip, Windows NSIS／portable 또는 Linux AppImage／deb를 생성하며, 현재 시스템 및 CPU 아키텍처에 맞는 Electron 런타임을 사용합니다.

맺음말

CG Claude는 환경 검사, 구성 미리 보기, 필드 수정, 프로젝트 스캔 및 스냅샷 복원을 하나의 로컬 작업 공간에 통합합니다. 먼저 데모 모드에서 흐름을 익힌 다음 실제 환경 기준을 설정하는 것이 좋습니다. 매번 쓰기 전에 미리 보기를 확인하고, 완료 후 터미널을 다시 열어 연속으로 재검사하세요. 계정, 지역, 결제, 휴대전화 시간대 및 브라우저 개인정보 보호처럼 안정적으로 자동 판단할 수 없는 항목은 수동 검토 단계를 유지해야 합니다.

브라우저 환경 구성 플러그인을 확인하려면 LC-time 프로젝트를 방문하세요.