클로드코드 필수 Helper 프로그램 CCKit 사용법 > CCKIT 소식

본문 바로가기

클로드코드 필수 Helper 프로그램 CCKit 사용법

필기자
17시간 18분전 130 0

본문

CCKit(Claude Code Kit) 을 처음 설치하는 법부터 세션 관리, 세션별 API 키 · 모델 설정까지 한 글로 정리했습니다.

클로드코드 필수 Helper 프로그램 CCKit 사용법

최신 버전 받기: Windows · Mac

1부. 설치와 기본 사용 - Windows · Mac

CCKit(Claude Code Kit)은 Claude Code 를 쓰는 데 필요한 Node.js · Git · Python · Claude Code 를 설치 파일 하나로 깔고, 여러 Claude Code 세션을 패널에서 관리하는 무료 프로그램입니다.

하나씩 깔면 사이트 네 곳을 돌며 설치 옵션을 고르고, command not found가 뜨면 PATH 를 직접 찾아야 합니다. CCKit 은 이 과정을 체크 몇 번으로 끝냅니다.

#카드 비교
#머리 하나씩 깔기 vs ^^CCKit 한 번^^
## 직접 설치
#작게 사이트 4곳 돌아다니기
- Node.js · Git · Python 따로 받기
- 설치 옵션 하나하나 고르기
- PATH 꼬이면 command not found
#끝 "어디서 막힌 거지?"
## ★ Claude Code Kit
#작게 설치 마법사 한 번
- 4가지를 체크만 하면 자동 설치
- 공식 사이트 최신판으로 받기
- PATH 등록 · 복구 버튼까지
#끝 "체크하고 다음만 누르면 끝"

📌 Windows의 터미널에는 명령 프롬프트(CMD)와 PowerShell 두 가지가 있습니다. 이 공지는 PowerShell 기준으로 설명합니다. Windows 11에서 「터미널」을 열면 나오는 창이 PowerShell이고, 프롬프트가 PS C:\Users\이름>처럼 PS로 시작합니다. CMD는 C:\Users\이름>처럼 PS가 없으니, 창을 열었을 때 PS가 보이는지 먼저 확인하세요. (Mac은 「터미널」 앱 하나입니다)

1. Claude Code Kit은 무엇인가요?

Claude Code Kit은 Claude Code를 편하게 쓰도록 돕는 무료 프로그램입니다. Windows판과 Mac판이 따로 있고, 소개와 사용 설명서는 각각의 GitHub 저장소에 있습니다(외부 서비스).

크게 두 가지 일을 합니다.

#카드 격자
## 처음 세팅
Node.js · Git · Python · Claude Code를 한 번에 확인하고 깔아 줍니다.
## 매일 쓰기
터미널에서 명령어로 하던 세션 관리, 원격 조종, 이미지 붙여넣기를 패널 버튼으로 할 수 있게 해 줍니다. 재부팅해도 열어 둔 세션을 자동으로 다시 엽니다.
항목 내용
Windows판 Windows 10 / 11 · 설치 파일(.exe)
Mac판 macOS 12 이상 · Apple Silicon·Intel · 터미널 한 줄 설치
가격 무료 (Freeware)
함께 설치 Node.js · Git · Python · Claude Code
받는 곳 GitHub - hull-kr/Claude-Code-Kit · Claude-Code-Kit-Mac

2. Windows에서 설치하기

① 설치 파일 받기

아래 주소에서 CCKitSetup.exe를 내려받습니다. 항상 최신판으로 연결됩니다.

https://github.com/hull-kr/Claude-Code-Kit/releases/latest/download/CCKitSetup.exe

💡 백신 프로그램(또는 크롬)이 .exe 다운로드를 막으면 같은 설치 파일을 압축한 CCKitSetup.zip을 받으세요. 압축을 푼 뒤 안에 든 CCKitSetup.exe를 실행하면 됩니다.

https://github.com/hull-kr/Claude-Code-Kit/releases/latest/download/CCKitSetup.zip

② "Windows의 PC를 보호했습니다" 경고가 뜨면

내려받은 파일을 실행하면 파란 경고 창이 뜰 수 있습니다. 무료 프로그램이라 유료 코드 서명 인증서를 붙이지 않아서, Windows가 습관처럼 띄우는 경고입니다.

03_smartscreen_b_m_k

💡 추가 정보를 누른 뒤 실행 버튼을 누르면 설치가 이어집니다.

③ 설치할 프로그램 체크하기

설치 마법사 중간에 Node.js · Git · Python · Claude Code를 고르는 화면이 나옵니다.

setup-tasks_97b
  • 새 PC라면 네 가지가 모두 체크된 채로 나옵니다. 그대로 다음만 누르면 됩니다.
  • 이미 깔려 있는 것은 버전과 함께 "설치됨"으로 표시되고 체크가 꺼져 있습니다. 체크하면 최신판으로 다시 설치합니다.
  • 설치 파일은 공식 사이트에서 직접 받습니다 - nodejs.org · git-scm.com · python.org
  • PATH(명령어 위치) 등록도 각 설치 프로그램이 알아서 해 줍니다.

설치가 끝나면 작업 표시줄 오른쪽 트레이나 바탕화면의 아이콘을 더블클릭해 패널을 엽니다.

3. Mac에서 설치하기

Mac판은 메뉴바에 머무는 앱입니다. 설치 파일을 내려받는 대신 터미널에 한 줄을 붙여 넣으면 됩니다.

① 터미널에 설치 명령 넣기

⌘ + Space를 누르고 "터미널"을 검색해 엽니다. 창에 ~ % 같은 표시와 깜빡이는 커서가 보이면, 거기가 명령을 넣는 자리입니다.

02_open_mac_m_k

아래 칸의 복사 버튼을 누르고, 터미널 창을 한 번 클릭한 뒤 ⌘ + V로 붙여 넣고 Enter를 누릅니다. Apple Silicon(M1~)과 Intel 중 맞는 것을 알아서 받습니다.

~ % curl -fsSL https://github.com/hull-kr/Claude-Code-Kit-Mac/releases/latest/download/install.sh | bash
▶ 내려받는 중 (arm64)
▶ 압축 푸는 중
▶ 설치: /Applications/Claude Code Kit.app
▶ 실행

✅ 설치 완료 - 화면 오른쪽 위 메뉴바의 ✦ 아이콘을 누르세요.

"설치 완료"가 나오면 화면 오른쪽 위 메뉴바의 ✦ 아이콘 → 컨트롤 패널을 엽니다. 앱은 응용 프로그램 폴더에 Claude Code Kit으로 설치됩니다.

💡 무료 프로그램이라 Apple 유료 서명을 하지 않았습니다. 브라우저로 받으면 macOS가 "확인할 수 없는 개발자"라며 막지만, 터미널 한 줄로 설치하면 이 경고 없이 깔립니다.

② 터미널 제어 허용하기

처음 세션을 열 때 "Claude Code Kit"이(가) "터미널"을(를) 제어하려고 합니다 창이 뜨면 허용을 누릅니다. 세션 열기·닫기·리모트를 터미널에 명령을 넣는 방식으로 하기 때문에 꼭 필요합니다.

01_mac_terminal_allow

③ 선행 프로그램 설치하기

Mac 은 명령 한 줄로 CCKit 을 깐 뒤, 나머지는 화면에서 진행합니다. 메뉴바 ✦ → 컨트롤 패널 → 설정 → 선행 프로그램을 엽니다. 처음 쓰는 Mac 이면 이렇게 보입니다.

mac-prereq-not-installed_b
  • 그림의 1번 - 「미설치」 줄의 설치를 누릅니다. Node.js · Python · Git은 Homebrew로, Claude Code는 Anthropic 공식 설치 스크립트로 깝니다. Python · Git 은 Mac 에 기본으로 설치되어 있을 수 있어서, 처음부터 「설치됨」으로 보이기도 합니다.
  • 그림의 2번 - Homebrew가 없으면 Homebrew부터 깝니다. 끝나면 설치를 한 번 더 누릅니다.

설치를 누르면 확인 창이 뜹니다. 예를 누르면 터미널 창이 열려 그 하나만 설치합니다. 암호를 물으면 Mac 로그인 암호를 넣습니다.

02_mac_install_confirm

터미널에서 설치가 끝나면 그림의 3번 - 다시 확인을 누릅니다. 네 가지가 모두 「설치됨」이 되면 끝입니다(4절 화면).

4. 잘 깔렸는지 확인하고, 나중에도 여기서 관리하기

Windows 는 2절 ③ 설치할 프로그램 체크하기에서 설치 마법사가, Mac 은 3절 ③ 선행 프로그램 설치하기에서 설치 버튼으로 선행 프로그램을 깔았습니다. 패널 왼쪽 메뉴의 설정 → 선행 프로그램에서 네 가지 모두 버전이 나오면 성공입니다. Mac 도 같은 화면입니다.

v118_선행표시

다 깔린 뒤에도 이 화면은 계속 씁니다.

  • 최신판으로 바꾸기 - 「최신 … 있음」이 보이면 재설치를 눌러 최신판으로 바꿉니다.
  • 명령을 못 찾을 때 - 터미널에서 claude · node 를 못 찾는다고 나오면 환경변수 등록/복구를 누릅니다. 설치 위치를 찾아 PATH 에 다시 등록해 줍니다. 그 뒤 열어 둔 터미널은 닫고 새로 엽니다.

5. 패널로 Claude Code 다루기

세팅이 끝나면 CCKit은 트레이(Mac은 메뉴바)에 머물면서 Claude Code 세션 관리 패널이 됩니다. 터미널에서 명령어로 하던 일을 버튼으로 할 수 있습니다.

panel_c_s
터미널에서 치던 것 CCKit 패널에서
claude + 새 세션 버튼 (폴더·이름 선택)
claude --resume 닫힌 세션 열기 / 전체 이어서 열기
/remote-control 리모트 켜기 - 폰·웹에서 이 PC 세션 조종
/bg bg 전환 - 창은 닫고 작업은 계속
/rename 제목 칸 더블클릭

세션을 그룹으로 나누기

세션이 많아지면 패널 위쪽 그룹 탭으로 나눠 봅니다. 「세미나」, 「개발」, 「자동화」처럼 일의 종류별로 묶어 두면 지금 필요한 세션만 골라 볼 수 있습니다.

cckit-groups_c_s

그룹 만들기는 이렇게 합니다. 예를 들어 블로그 글을 쓰는 세션들을 「블로그」 그룹으로 묶어 봅니다.

탭 줄 맨 오른쪽 + 그룹을 누르면 「새 그룹」 창이 뜹니다. 그룹 이름을 넣고 확인을 누릅니다.

group-1_b

탭 줄에 새 그룹 탭이 바로 생깁니다.

group-3_b_s

그룹 탭은 마우스로 끌어서(드래그) 순서를 바꿀 수 있습니다. 자주 쓰는 그룹을 앞으로 옮겨 두세요.

이제 세션을 그 그룹으로 옮깁니다. 세션 줄의 그룹 칸(「개발 ▾」처럼 생긴 칸)을 누르면 메뉴가 뜹니다. 옮길 그룹을 고르면 끝입니다. 메뉴 맨 아래 + 새 그룹...으로 여기서 바로 새 그룹을 만들 수도 있습니다.

group-2_b_s
#카드 격자
#머리 그룹으로 ^^세션 정리하기^^
## + 그룹
#작게 탭 줄 맨 오른쪽 버튼
새 그룹(카테고리)을 만듭니다
## ★ 그룹 탭
#작게 전체 · 미분류 · 세미나 · 개발 …
누르면 그 그룹의 세션만 목록에 보입니다. 끌어서 순서를 바꿉니다
## 그룹 칸
#작게 세션 줄의 「개발 ▾」 같은 칸
눌러서 그 세션을 다른 그룹으로 옮깁니다
## 미분류
#작게 그룹을 정하지 않은 세션
아직 묶지 않은 세션이 여기에 모입니다

트레이 아이콘으로 다루기

CCKit은 작업 표시줄 오른쪽 아래 트레이에 머뭅니다. 아이콘이 안 보이면 ^(숨겨진 아이콘 표시)를 누르세요. Mac은 화면 위 메뉴바 아이콘을 누릅니다.

#카드 격자
## 더블클릭
패널이 열립니다.
## 오른쪽 클릭
아래 메뉴가 뜹니다. 패널을 열지 않고도 세션을 바로 다시 열 수 있습니다.
tray_menu_b
메뉴 하는 일
컨트롤 패널 패널 창을 엽니다
세션 이어서 열기 ▸ 관리(★)에 담아 둔 세션 목록이 나옵니다. 하나를 누르면 그 세션을 이어서 엽니다. 관리 세션 이어서 열기는 담아 둔 세션을 한꺼번에 엽니다
열린 세션 ▸ 지금 열려 있는 세션 목록입니다
설정 · 사용법 설정 화면과 사용 설명서를 엽니다
다시 시작 · 종료 CCKit을 다시 띄우거나 끕니다

💡 패널 창을 닫아도 CCKit은 트레이에 남아 있습니다. 완전히 끄려면 트레이 메뉴에서 종료를 누르세요.

6. 처음부터 쓰면 좋은 기능 2가지

① 이미지 붙여넣기 - Ctrl + Shift + V (Mac은 ⌃ + ⇧ + V)

Claude Code에 화면 캡처를 보여주고 싶을 때 쓰는 기능입니다. Win + Shift + S로 화면을 캡처한 뒤 터미널에서 Ctrl + Shift + V를 누르면, 이미지가 지금 폴더에 저장되고 그 경로가 입력창에 자동으로 들어갑니다. Mac에서는 ⌘ + ⇧ + 4로 캡처한 뒤 ⌃ + ⇧ + V를 누르면 됩니다.

01_image_paste_e

"이 화면에서 버튼이 안 보여"처럼 말로 설명하기 어려운 문제를 캡처 한 장으로 바로 전달할 수 있습니다.

② 리모트 - 폰에서 PC 작업 이어가기

세션의 리모트를 켜면 claude.ai/code 웹이나 Claude 모바일 앱에서 PC(또는 Mac)에서 돌던 그 세션을 그대로 보고 이어서 시킬 수 있습니다. 긴 작업을 걸어 두고 자리를 비울 때 유용합니다.

리모트를 켠 뒤 폰에서는 Claude 모바일 앱, 노트북에서는 claude.ai/code 웹으로 그 세션을 이어서 시킵니다.

7. 세션 열기 - 패널에서 바로, 또는 ccd 명령으로

CCKit을 쓰면 터미널을 열고 폴더를 찾아 들어가 명령을 칠 필요가 없습니다. 패널에서 세션을 만들거나, 만들어 둔 세션의 「열기」만 누르면 그 폴더에서 Claude Code가 바로 열립니다.

① 처음 시작할 때 - + 새 세션

패널 아래 + 새 세션을 누르고 세션 위치(작업 폴더)를 고른 뒤 만들기를 누릅니다. 그룹을 고르고 세션명에 알아보기 쉬운 이름(예: 테스트 세션)을 쓰면 나중에 목록에서 찾기 쉽습니다. 둘 다 비워 둬도 됩니다. 터미널 창이 열리면서 그 폴더에서 Claude Code가 시작되고, 새 폴더에서 묻는 "이 폴더를 믿을까요?"도 자동으로 넘어갑니다.

cckit-new-session_f

💡 폴더마다 다른 API 키 · 모델로 Claude Code 를 열고 싶다면, CCKit 에 API 프로필을 등록해 두고 새 세션을 만들 때 고르면 됩니다. 등록하는 법은 아래 2부에 있습니다.

② 이어서 할 때 - 열기

한 번 만든 세션은 창을 닫아도 목록에 남습니다. 모든 세션(또는 닫힌 세션) 탭에서 이어서 할 세션의 열기를 누르면 그 폴더에서, 하던 대화 그대로 다시 열립니다. 여러 개를 체크하고 선택 열기로 한꺼번에 열 수도 있습니다.

cckit-all-sessions_e_s

「열기」를 누르면 터미널 창이 새로 열리고, 그 세션의 지난 대화가 그대로 보입니다. CCKit 이 터미널에 claude --resume(지난 대화 이어서 열기)을 대신 넣어 주는 것입니다.

#화면 Claude Code 테스트 세션
^^ ▐▛███▛█^^   Claude Code v2.1.310
^^▝▜██████▀^^  Opus 5.5 · Claude Max
^^ ▝▝   ▝▝^^   C:\Users\user\claude-test [1]
❯ 오늘 할 일을 정리하는 웹페이지를 index.html 로 만들어 줘. [2]
● Write(index.html)
  ⎿  Wrote 86 lines to index.html
● index.html 을 만들었습니다. 더블클릭하면 브라우저로 열립니다.
>>{테스트 세션} [3]
#설명 1 「테스트 세션」의 작업 폴더에서 열립니다. 창 탭에도 세션 이름이 보입니다
#설명 2 지난번에 나눈 대화가 그대로 다시 보입니다
#설명 3 입력창 위 오른쪽의 「테스트 세션」으로 이어 연 세션이 맞는지 확인하고, 이어서 말하면 됩니다

💡 처음엔 새 세션 → 만들기, 다음부터는 열기. 이것만 알면 터미널 명령 없이 Claude Code를 쓸 수 있습니다.

③ 명령으로 열고 싶다면 - ccd

터미널이 편하다면 ccd 단축 명령을 씁니다. ccd는 claude --dangerously-skip-permissions의 줄임말로, 파일을 고치거나 명령을 실행할 때마다 묻던 승인 확인을 건너뛰는 모드로 Claude Code를 엽니다. 그래서 입력창 아래에 빨간 글씨로 ⏵⏵ bypass permissions on이 표시됩니다.

평소처럼 claude로 열면 같은 자리에 회색 글씨로 ⏸ manual mode on(하나씩 묻는 기본 모드)이 보이고, 파일을 고치거나 명령을 실행할 때마다 먼저 물어봅니다.

CCKit 설정 → 세션 복원 → ccd 명령 사용에 체크하면 켜집니다.

v118_ccd표시

Claude Code는 터미널이 열린 폴더에서 일합니다. 그래서 먼저 작업할 폴더로 들어간 뒤 명령을 칩니다.

#카드 격자
## 가장 쉬운 방법 (Windows)
파일 탐색기에서 작업 폴더를 열고, 빈 곳을 **마우스 오른쪽**으로 눌러 **터미널에서 열기**를 고릅니다. 그 폴더에서 PowerShell 터미널이 바로 열립니다.
## 명령으로 들어가기
터미널에서 `cd 폴더이름`을 치면 그 폴더로 들어갑니다. 프롬프트의 폴더 이름이 바뀌면 들어간 것입니다.
04_folder_windows_t_k
05_folder_mac_t_k

폴더에 들어갔으면 처음 시작하는지, 이어서 하는지에 따라 명령을 고릅니다.

상황 명령 하는 일
처음 시작 ccd 새 대화로 시작합니다
바로 이어서 ccd -c 이 폴더에서 마지막으로 하던 대화를 그대로 이어서 엽니다
골라서 이어서 ccd -r 이 폴더의 지난 대화 목록이 뜨고, 방향키로 골라 Enter

처음 시작할 때

PS C:\Users\user> cd claude-test
PS C:\Users\user\claude-test> ccd
#화면 Claude Code
PS C:\Users\user\claude-test> ccd
^^ ▐▛███▛█^^   Claude Code v2.1.310
^^▝▜██████▀^^  Opus 5.5 · Claude Max
^^ ▝▝   ▝▝^^   C:\Users\user\claude-test
>>
#빨강   ⏵⏵ bypass permissions on (shift+tab to cycle) [1]
#설명 1 **ccd** 로 열면 입력창 아래에 이 빨간 표시가 뜹니다. 파일 수정·명령 실행을 묻지 않고 바로 합니다

바로 이어서 할 때 - 어제 하던 대화가 그대로 다시 표시되고, 이어서 말하면 됩니다.

PS C:\Users\user\claude-test> ccd -c
#화면 Claude Code
PS C:\Users\user\claude-test> ccd -c
^^ ▐▛███▛█^^   Claude Code v2.1.310
^^▝▜██████▀^^  Opus 5.5 · Claude Max
^^ ▝▝   ▝▝^^   C:\Users\user\claude-test
❯ 오늘 할 일을 정리하는 웹페이지를 index.html 로 만들어 줘. [1]
● Write(index.html)
  ⎿  Wrote 86 lines to index.html
● index.html 을 만들었습니다. 더블클릭하면 브라우저로 열립니다.
>> [2]
#빨강   ⏵⏵ bypass permissions on (shift+tab to cycle)
#설명 1 지난 대화가 그대로 다시 보입니다
#설명 2 맨 아래 입력창에 이어서 말하면 됩니다

골라서 이어서 할 때 - 이 폴더에서 했던 대화 목록이 뜹니다.

PS C:\Users\user\claude-test> ccd -r
#화면 Claude Code
PS C:\Users\user\claude-test> ccd -r
#굵게  Resume session
#흐림  ⌕ Search…
@ 오늘 할 일 웹페이지 만들기 [1]
#흐림      2 hours ago · 24.1KB
  매출 엑셀 합치기
#흐림      yesterday · 88.0KB
  회의록 요약
#흐림      3 days ago · 12.4KB
#흐림  Ctrl+A to show all projects · Space to preview · Type to search · Esc to cancel
#설명 1 ↑↓로 고르고 Enter. 대화마다 제목이 자동으로 붙고, 글자를 치면 검색됩니다

Mac도 명령은 똑같습니다. Finder의 폴더를 터미널 창으로 끌어다 놓으면 경로가 입력되니, 앞에 cd 를 붙여 Enter를 누른 뒤 같은 명령을 칩니다.

~ % cd claude-test
~/claude-test % ccd -c

💡 ccd 대신 claude를 써도 같습니다 - claude(처음) · claude -c(바로 이어서) · claude -r(골라서 이어서). 차이는 승인 확인을 건너뛰느냐뿐입니다.

8. CCKit 설정 확인하기

패널 왼쪽 메뉴의 설정을 누르면 CCKit의 동작을 정하는 화면이 나옵니다. 처음 한 번만 훑어보고, 바꾼 뒤에는 맨 아래 저장을 누릅니다. 저장하지 않고 다른 화면으로 가려 하면 「설정이 변경됐습니다. 저장하시겠습니까?」라고 한 번 더 물어봅니다.

v118_설정1
v118_설정2
#카드 격자
#머리 처음 한 번 ^^확인할 설정^^
## ★ 세션 보관 기간
#작게 Claude Code 기본값 30일 - 지나면 대화 자동 삭제
오래 이어 갈 세션이 있으면 365(1년)처럼 늘려 둡니다
## ★ 선행 프로그램 · 환경변수
#작게 Node.js · Python · Git · Claude Code 최신판 유지
버전과 최신 여부가 보입니다. **재설치**로 최신판으로 바꾸고, 명령을 못 찾으면 **환경변수 등록/복구**로 PATH를 다시 등록합니다
## ★ 로그인 시 자동 복원
#작게 재부팅해도 세션 그대로(9절)
재부팅 전 열려 있던 세션을 자동으로 복원합니다
## 단일 창에 탭으로 열기
#작게 창 하나에 탭으로 모으기
세션을 한 창의 탭으로 엽니다. 끄면 세션마다 창이 따로 열립니다
## ccd 명령 사용
#작게 승인 확인을 건너뛰는 모드(7절)
체크하면 터미널 어디서나 `ccd` 로 Claude Code를 엽니다
## 절전 방지
#작게 폰으로 원격 조종할 때
PC가 잠들지 않게 해서 폰 연결이 끊기지 않습니다. 모니터는 꺼집니다
## 이미지 붙여넣기
#작게 Ctrl + Shift + V
붙여 넣은 그림을 미리 보여 주는 시간과 크기, 저장 알림을 정합니다
## 언어 / Language
#작게 한국어 · English · 日本語 · 中文
패널에 보이는 글자 언어를 바꿉니다

대화가 사라졌다면 - 세션 보관 기간과 「기간만료」

Claude Code는 기본으로 30일이 지난 대화를 자동으로 지웁니다. 한 달 전에 만든 세션을 열었는데 대화가 비어 있다면 CCKit이나 백신이 지운 것이 아니라 Claude Code의 이 규칙 때문입니다.

CCKit은 이렇게 사라진 세션 옆에 빨간 기간만료를 붙여 원인을 알려 줍니다. 기간만료를 누르면 보관 기간 설정으로 바로 갑니다.

v118_기간만료표시

설정의 세션 보관 기간 (Claude Code)에서 일수를 늘리면 그날부터는 더 오래 남습니다. 이 값은 Claude Code의 설정 파일(settings.json)의 cleanupPeriodDays에 저장됩니다. 이미 지워진 대화는 되살릴 수 없으니 처음 설치할 때 미리 늘려 두세요.

v118_보관표시

9. 재부팅해도 세션 그대로 - 로그인 시 자동 복원

재부팅한 뒤에도 하던 작업을 그대로 잇게 해 주는 기능입니다.

Claude Code에 익숙해지면 일마다 세션을 따로 열어 두게 됩니다. 블로그 글쓰기, 엑셀 보고서, 홈페이지… 금방 열 개가 넘습니다.

그런데 Windows 업데이트나 정전으로 컴퓨터가 재부팅되면 이 창들이 한 번에 전부 닫힙니다. CCKit의 로그인 시 자동 복원을 켜 두면 재부팅 전에 열려 있던 세션을 폴더와 대화 그대로 자동으로 복원합니다.

#카드 비교
#머리 재부팅 뒤 세션 10개 ^^다시 열기^^
## 손으로 하나씩 열기
#작게 세션 하나에 4단계, 이걸 10번
- 터미널 열기
- `cd` 로 작업 폴더 찾아 들어가기
- `claude -r` 로 지난 대화 목록 열기
- 하던 대화를 찾아 고르기
#끝 "이 세션 폴더가 어디였더라?"
## ★ CCKit 자동 복원
#작게 켜 두기만 하면 끝
- 재부팅 전 열려 있던 세션을 모두 복원
- 작업 폴더와 하던 대화 그대로
- 직접 닫은 세션은 빼고 엶
#끝 "켜자마자 바로 이어서"
01_restore_flow_d_k

켜는 법 - 패널 설정 → 세션 복원 → 로그인 시 자동 복원에 체크하고 맨 아래 저장을 누릅니다.

v118_복원표시

💡 자동 복원은 재부팅 직전에 열려 있던 세션만 다시 엽니다. 일부러 닫아 둔 세션까지 한꺼번에 열고 싶으면 그 세션들을 관리(★)에 담아 두고, 트레이 메뉴의 관리 세션 이어서 열기를 누르세요.

1부 확인 목록 - 설치와 기본 사용

#카드 체크
#머리 아래 다섯 가지가 되면 ^^세팅 끝^^입니다
- Windows는 CCKitSetup.exe 로, Mac은 설치 한 줄로 CCKit을 깔았다
- Node.js · Git · Python · Claude Code 네 가지를 설치했다
- 패널 **설정**에서 네 가지 모두 버전이 보인다
- 패널의 **+ 새 세션**으로 첫 대화를 시작했고, 다음부터는 **열기**로 이어서 연다
- 설정에서 **로그인 시 자동 복원**을 켜고 **세션 보관 기간**을 늘린 뒤 저장했다

Mac판 소개와 설명서는 github.com/hull-kr/Claude-Code-Kit-Mac에서 볼 수 있습니다.

CCKit 에 새로 생긴 세션별 API 설정(폴더마다 다른 API 키 · 모델)은 아래 2부에서 이어서 다룹니다.


2부. 세션별 API 설정 - 폴더마다 다른 API 키 · 모델

Claude Code 비용은 API 키 · 구독 · 팀 세 가지로 냅니다. API 키를 쓰는 흔한 방법은 환경 변수나 설정 파일에 넣는 것입니다. 그 방법은 PC 전체에 키가 들어갑니다. 모든 폴더 · 모든 창이 키로 바뀌고, 구독으로 돌아가려면 키를 다시 지워야 합니다.

CCKit Windows v1.3.0 부터 세션별 API 설정을 쓸 수 있습니다. 고른 세션 폴더 하나에만 다른 API 키와 모델을 넣고, 나머지 폴더는 구독 그대로 둡니다. Anthropic API 키로 Claude 모델을 쓰는 것은 물론, OpenRouter 키로 다른 회사 모델(GPT 등)도 Claude Code 안에서 쓸 수 있습니다.

1. 세션별 API 설정 - 폴더 하나에만 다른 키 · 모델

CCKit 에서 세션은 작업 폴더 하나입니다. 세션별 API 설정은 그 폴더의 Claude Code 설정 파일에만 키와 모델을 적습니다. Windows 환경 변수나 전역 설정 파일(C:\Users\user\.claude\settings.json)은 건드리지 않습니다.

#카드 비교
#머리 API 키를 ^^어디에^^ 넣나
## PC 전체에 넣기
#작게 환경 변수 · 전역 설정 파일
- 모든 폴더 · 모든 창이 키로 바뀜
- 구독으로 돌아가려면 키를 지워야 함
## ★ 세션별 API 설정
#작게 CCKit v1.3.0 - 고른 세션 폴더에만
- 그 폴더만 키 · 모델로 열림
- 나머지 폴더는 구독 그대로
- 되돌릴 때는 「사용 안 함」 한 번

넣을 수 있는 키는 두 가지입니다.

#카드 비교
#머리 지원하는 키 ^^두 가지^^
## OpenRouter 키
#작게 sk-or-v1-… · openrouter.ai
다른 회사 모델(예: openai/gpt-5.6-luna)을 **Claude Code 안에서** 씁니다. 충전한 크레딧에서 나갑니다
## Anthropic API 키
#작게 sk-ant-… · Claude Console
Claude 모델을 **구독 대신 API 종량제**로 씁니다. Claude Console 에서 청구됩니다

OpenRouter(오픈라우터)는 여러 회사의 AI 모델을 키 하나로 쓰게 이어 주는 서비스입니다. OpenAI · 구글 키는 CCKit 에 바로 넣을 수 없습니다. 그 회사 모델은 OpenRouter 를 거쳐 씁니다.

쓰는 때 - 세미나 실습 · 프로젝트별 키 · 다른 회사 모델

#카드 격자
#머리 세션별 API 설정이 ^^필요한 때^^
## 세미나 실습 폴더
#작게 실습용 키와 정한 모델
참가자가 자기 구독과 상관없이 같은 키 · 같은 모델로 따라 합니다. 모델이 잠겨 `/model` 로 바꿀 수 없습니다
## 프로젝트마다 다른 키
#작게 비용을 따로 계산
회사 일 폴더는 회사 키, 개인 폴더는 구독처럼 나눕니다
## 다른 회사 모델 시험
#작게 OpenRouter 로 한 폴더만
GPT 같은 모델을 Claude Code 의 도구 · 스킬 그대로 시험해 봅니다

전체 흐름은 여섯 단계입니다. 키를 받아 CCKit 에 프로필로 등록하고, 세션에 적용하고, 시작 화면에서 확인합니다.

02_session_api_flow

2. CCKit 업데이트하기 - Windows v1.3.0 · Mac v0.3.1 부터

세션별 API 설정은 Windows CCKit v1.3.0, Mac CCKit v0.3.1 부터 들어 있습니다. 이미 CCKit 을 쓰고 있으면 트레이 알림의 업데이트로 받습니다. 패널 왼쪽 메뉴에 「세션별 API 설정」 탭이 보이면 된 것입니다.

v1.3.0 을 일찍 깐 분은 같은 번호로 다시 올라온 설치 파일이라 앱 안 업데이트 알림이 뜨지 않습니다. 탭이 안 보이면 아래 주소에서 CCKitSetup.exe 를 다시 받아 설치하세요. 크롬이 .exe 를 막으면 CCKitSetup.zip 을 받아 압축을 풀고 실행합니다.

https://github.com/hull-kr/Claude-Code-Kit/releases/latest

Mac 은 Claude-Code-Kit-Mac v0.3.1 에 같은 기능이 있습니다. 이 공지의 화면은 Windows 판입니다.

3. API 키 받기 - OpenRouter 또는 Claude Console

키는 쓸 쪽 하나만 받으면 됩니다. 키로 여는 세션은 구독 사용량이 아니라 그 키의 종량제로 요금이 나갑니다. 구독을 쓰고 있어도 그 폴더에서는 API 요금이 나갑니다.

#카드 비교
#머리 키 받는 곳과 ^^비용 상한^^
## OpenRouter
#작게 openrouter.ai
- 키(sk-or-v1-…)를 받고 크레딧을 충전
- 키마다 크레딧 상한을 걸 수 있음
## Anthropic
#작게 platform.claude.com (Claude Console)
- 키(sk-ant-…)를 받음
- 키 자체에는 모델 제한이 없음
- 워크스페이스를 따로 만들어 **지출 한도**를 검

Claude Console 의 Default 워크스페이스에는 지출 한도를 걸 수 없습니다. 세미나 실습처럼 여럿이 쓸 키는 실습용 워크스페이스를 새로 만들고 그 안에서 키를 받은 뒤 한도를 거세요.

4. 프로필 등록하기 - 「세션별 API 설정」 탭

키 하나와 모델 하나를 묶어 프로필로 등록합니다. 작업 표시줄 오른쪽 트레이의 CCKit 아이콘을 더블클릭해 패널을 열고 왼쪽 메뉴의 「세션별 API 설정」 탭을 엽니다. 위에 등록 칸 두 개, 아래에 프로필 목록이 있습니다. 아래는 프로필 두 개를 등록한 뒤의 패널 전체 화면입니다.

09_panel_full
#설명 1 왼쪽 메뉴의 **세션별 API 설정** - 누르면 오른쪽에 아래 칸들이 열립니다
#설명 2 **오픈라우터 API 키 프로필** 등록 칸 - 아래 ① 에서 확대합니다
#설명 3 **앤트로픽 API 키 프로필** 등록 칸 - 아래 ② 에서 확대합니다
#설명 4 **프로필 목록** - 등록한 프로필이 한 줄씩 쌓입니다(아래 ③ 에서 확대)

① 오픈라우터 API 키 프로필

03_openrouter_profile_b
#설명 1 **이름** - 목록과 메뉴에 보일 이름입니다. 무엇인지 알아보게 짓습니다(예: 오픈라우터_루나)
#설명 2 **모델** - 글자 일부만 쳐도 목록에서 찾아 줍니다. luna 를 치고 ↑↓ 로 고른 뒤 Enter
#설명 3 **API 키** - OpenRouter 에서 받은 sk-or-v1- 로 시작하는 키를 붙여 넣습니다
#설명 4 **추가** - 아래 프로필 목록에 한 줄이 생깁니다

② 앤트로픽 API 키 프로필

Claude 모델은 아래 칸에 넣습니다. 모델 칸에 son · opus 처럼 일부만 치면 Claude 모델 목록(claude-opus-5-5 · claude-sonnet-5-5 · claude-haiku-5-5 · claude-fable-5-2)에서 찾아 줍니다. 모델은 꼭 골라야 합니다.

04_anthropic_profile_b
#설명 1 **이름** - 예: 클로드소넷
#설명 2 **모델** - son 을 치면 claude-sonnet-5-5 가 나옵니다. 고르고 Enter
#설명 3 **API 키** - Claude Console 에서 받은 sk-ant- 로 시작하는 키
#설명 4 **추가**

키에 공백이나 ; $ & " 같은 특수문자가 섞여 있으면 CCKit 이 등록을 거부합니다. 복사할 때 앞뒤에 공백이 붙지 않았는지 봅니다.

③ 프로필 목록

두 종류가 한 목록에 모입니다. 실제 화면에는 모델 오른쪽에 엔드포인트(키를 보내는 주소) 칸도 있습니다.

05_profile_list_b
#설명 1 행을 고르면 그 프로필을 쓰는 세션이 아래 표에 나옵니다
#설명 2 **수정** - 위 등록 칸으로 불러와 키 · 모델을 바꿉니다. 그 프로필을 쓰던 폴더도 함께 새 값으로 바뀝니다. **삭제** 전에는 세션에서 먼저 「사용 안 함」으로 풀어 둡니다
#설명 3 이 프로필이 적용된 세션과 폴더입니다(예: 루나테스트 · D:\luna_test)
#설명 4 **선택 세션에서 해제** - 고른 세션에서 프로필을 뺍니다

5. 세션에 적용하기 - 우클릭 한 번, 또는 새 세션 창

① 이미 있는 세션에 적용하기

패널 왼쪽의 열린 세션(또는 관리 세션 · 모든 세션) 탭을 열고, 키를 넣을 세션 줄을 마우스 오른쪽 단추로 클릭합니다. 아래는 루나테스트 세션 줄을 우클릭한 화면입니다.

06_session_list
#설명 1 키를 넣을 세션 줄 - 이 줄 아무 곳에서나 오른쪽 단추를 누릅니다
#설명 2 우클릭 메뉴가 열립니다. 「세션별 API 설정」에 마우스를 올리면 오른쪽에 프로필 목록이 펼쳐집니다(아래에서 확대)

열린 메뉴를 확대하면 이렇습니다.

06_session_menu_b
#설명 1 **세션별 API 설정** - 괄호 안에 지금 적용된 프로필 이름이 보입니다
#설명 2 **사용 안 함** - 되돌릴 때 고릅니다. 괄호 안은 PC 의 로그인 방식에 따라 「클로드 구독제」 또는 「클로드 API」로 나옵니다
#설명 3 프로필을 고르면 지금 적용된 것에 ✓ 가 붙습니다

그 폴더에 열려 있는 세션이 있으면 지금 다시 열지 묻습니다.

07_restart
#설명 1 **예** - 세션을 닫고 다시 엽니다. 대화는 이어지고 모델만 새 설정으로 바뀝니다. 아니요를 고르면 다음에 그 세션을 새로 열 때부터 적용됩니다

② 새 세션 만들 때 고르기

패널 아래 「+ 새 세션」 창에도 프로필 칸이 생겼습니다. 여기서 고르면 처음부터 그 키 · 모델로 열립니다.

08_new_session_b
#설명 1 **세션별 API 프로필** - 비워 두면(사용 안 함) 지금처럼 구독으로 열립니다
#설명 2 등록한 프로필 목록입니다. 하나를 고릅니다
#설명 3 프로필을 고르면 **원격 연결** 체크가 자동으로 꺼집니다. 키로 여는 세션은 리모트 컨트롤을 쓸 수 없습니다(8절)

6. 적용됐는지 확인하기 - 시작 화면의 모델 이름과 API Usage Billing

세션을 열면 맨 위 시작 화면 둘째 줄에 등록한 모델 이름과 API Usage Billing(API 요금으로 계산)이 보입니다. 구독으로 열린 세션은 이 자리에 구독 이름(Claude Max 등)이 나옵니다.

#화면 Claude Code 루나테스트
^^ ▐▛███▛█^^   Claude Code v2.1.322
^^▝▜██████▀^^  openai/gpt-5.6-luna[1m] with medium effort · API Usage Billing [1]
^^ ▝▝   ▝▝^^   D:\luna_test
>>{루나테스트}
#설명 1 OpenRouter 프로필로 연 세션입니다. 앤트로픽 프로필이면 등록한 Claude 모델 이름이 나옵니다

이 폴더는 등록한 모델로 잠깁니다. /model 로 다른 모델로 바꿀 수 없고, 명령에 다른 모델을 붙여 열어도 등록한 모델로 열립니다. 다른 모델을 쓰려면 프로필의 모델을 바꾸거나 다른 프로필을 적용합니다.

세션 위쪽에 「claude.ai connectors are disabled …」 경고가 뜨는 것은 정상입니다. 키로 동작하고 있어서 claude.ai 계정에 연결된 기능이 꺼졌다는 뜻입니다.

CCKit 쪽에서는 세션 줄 우클릭 메뉴의 ✓, 또는 「프로필 목록」에서 행을 골랐을 때 아래 「선택한 프로필이 적용된 세션」 표로 확인합니다(4절 ③ 프로필 목록).

7. 키가 저장되는 곳 - 평문이니 PC 를 같이 쓰면 조심

세션에 적용하면 그 세션 폴더의 .claude\settings.local.json 에 키와 모델이 적힙니다.

#폴더 키를 적용한 세션 폴더
luna_test/
  .claude/
    settings.local.json   # CCKit 이 키 · 모델을 적음
  .gitignore   # git 저장소면 자동으로 한 줄 더함

이 파일은 암호화하지 않은 평문입니다. PC 를 다른 사람과 같이 쓰면 그 사람도 파일을 열어 키를 볼 수 있습니다. 같이 쓰는 PC 에는 지출 한도를 걸어 둔 키만 넣으세요(3절).

#카드 격자
#머리 CCKit 이 ^^알아서 하는 것^^
## 커밋 막기
#작게 .gitignore 에 자동 추가
세션 폴더가 git 저장소면 settings.local.json 이 커밋되지 않게 막습니다(.gitignore 에 한 줄 추가)
## 해제하면 그 값만
#작게 다른 설정은 그대로
「사용 안 함」을 고르면 CCKit 이 넣은 줄만 지우고, 그 파일의 다른 설정(권한 허용 등)은 남깁니다
## 키 확인 질문 없음
#작게 앤트로픽 키도 바로 적용
환경 변수로 넣을 때처럼 처음 열 때 「이 키를 쓸까요?」를 묻지 않고 바로 적용됩니다
## PC 전체는 그대로
#작게 환경 변수 · 전역 설정 안 건드림
다른 폴더를 열면 지금 PC 의 로그인 방식(구독 또는 API) 그대로입니다

8. 키로 연 세션에서 되는 것과 안 되는 것

키로 연 세션도 Claude Code 의 일은 똑같이 합니다. claude.ai 계정으로 로그인해야 쓰는 기능만 빠집니다.

기능 키로 연 세션
코드 읽기 · 수정, 명령 실행, 파일 만들기, 내 PC 의 스킬 ✅ 됨
Artifact · Docs · 리모트 컨트롤 · claude.ai 커넥터 ❌ 안 됨 (claude.ai 계정 로그인 필요)

리모트 컨트롤로 폰에서 이어 쓰던 세션이라면 그 폴더는 구독으로 두세요.

#카드 격자
#머리 쓰기 전에 ^^알아 둘 것^^
## 요금
#작게 그 키의 종량제
구독 사용량에서 빠지지 않고 Claude Console 청구 또는 OpenRouter 크레딧에서 나갑니다
## 비용 상한
#작게 키를 받는 곳에서
Anthropic 은 워크스페이스 지출 한도, OpenRouter 는 키별 크레딧 상한을 겁니다
## 모델 잠금
#작게 내 PC 설정 파일에 거는 잠금
설정 파일을 직접 고치면 풀 수 있습니다. 서버에서 막는 것은 아닙니다
## 지우는 순서
#작게 「사용 안 함」 먼저
세션에서 프로필을 풀고 나서 프로필 목록에서 삭제합니다

더 자세한 설명은 CCKit 저장소의 README - 세션별 API 설정에 있습니다.

2부 확인 목록 - 세션별 API 설정

#카드 체크
#머리 아래 여섯 가지가 되면 ^^세션별 API 설정^^은 끝입니다
- CCKit 패널 왼쪽에 「세션별 API 설정」 탭이 보인다
- OpenRouter 나 Claude Console 에서 키를 받고 비용 상한을 걸었다
- 이름 · 모델 · API 키를 넣고 「추가」로 프로필을 만들었다
- 세션 줄 우클릭 → 「세션별 API 설정」에서 프로필을 고르고 「예」로 다시 열었다
- 시작 화면에 등록한 모델 이름과 API Usage Billing 이 보인다
- 되돌릴 때는 같은 메뉴의 「사용 안 함」을 고른다

구독은 그대로 두고 필요한 폴더 하나에만 키를 넣는 기능입니다. 세미나 실습 폴더, 비용을 따로 계산할 프로젝트, 다른 회사 모델을 시험할 폴더부터 하나씩 나눠 보세요.

클로드 코드 기초 강좌는 한국클로드코드랩에서

궁금한 점은 댓글로 남겨 주세요. 🙂

댓글목록0

등록된 댓글이 없습니다.
게시판 전체검색