Claude Code용 AgentKit(ak CLI)를 처음부터 설치하는 방법 (2026)

이 가이드의 모든 명령은 agentkit.best/docs와 docs.agentkit.best에 있는 공식 문서(2026년 8월 확인)에서 가져왔어요. ak CLI는 현재 베타 채널로 제공되고 있어서 명령과 플래그가 바뀔 수 있으니, 실행하기 전에 문서에서 최신 명령을 다시 확인하세요.

어떤 AgentKit? OpenAI의 AgentKit가 아니라 Claude Code용 ak CLI예요

명령 하나를 복사하기 전에, 30초만 들여 올바른 것을 설치하고 있는지 확인하세요. 지금 "agentkit"라는 단어는 서로 관계없는 여러 제품에 퍼져 있어요: OpenAI AgentKit(2025년 10월 출시), BCG-X의 agentkit(Next.js/FastAPI/LangChain 스타터 킷), Google의 agents-cli, 그리고 이름만 같은 사이트 몇 개가 더 있어요. 그중 하나를 실수로 설치하면 명령이 Claude Code에서 절대 동작하지 않아요.

이 글에서 다루는 것은 agentkit.best에 있는 Claude Code용 키트이고, ak라는 CLI로 조작해요. 이전 Claude Kit의 후속작이에요(ck가 ak로 이름이 바뀌었어요). skill과 agent를 통해 Claude Code(그리고 Codex와 Copilot까지)를 "AI 개발·마케팅 팀"으로 바꿔줘요. OpenAI나 BCG의 제품을 찾고 있다면, 이건 그게 아니에요.

이름 변경의 전체 배경과 ak가 ck를 대체한 이유는 Claude Kit가 AgentKit로 이름이 바뀐 과정(ck에서 ak로)을 읽어보세요.

설치하기 전에 (사전 준비)

AgentKit는 Claude Code 위에서 동작하며, Claude Code를 대체하지 않아요. 시작하기 전에 두 가지가 필요해요:

• ① Claude Code가 설치되어 정상 동작할 것. claude --version으로 확인하세요. "command not found" 오류가 나면, 먼저 이 Claude Code 설치 가이드(사전 준비)로 Claude Code를 설치하세요. Claude Code에는 Node 18+가 필요하고, 모델을 돌리려면 Claude 요금제(Pro, Max 또는 API)도 필요해요.
• ② AgentKit 계정. CLI에는 이메일 또는 API 키로 로그인해요. 실제로 키트(Engineer 또는 Marketing)를 다운로드하려면 그 계정에 연결된 이용 권한(entitlement)이 필요해요 — 즉, 이미 키트를 보유하고 있어야 해요.

사람들이 자주 헷갈리는 점: ak 바이너리 자체는 네이티브 바이너리라서 실행에 Node.js나 Bun이 필요 없어요. 하지만 대상 키트가 Claude Code일 때는 Claude Code 환경에 여전히 Node 18+가 필요해요. 이 둘은 별개예요.

아직 키트가 없나요? 그래도 CLI 설치와 로그인은 할 수 있지만, ak kit init을 실행하면 이용 권한이 없다고 나와요. 제대로 쓰고 싶다면 AgentKit 요금제를 확인하고 라이선스를 받으세요(링크로 20% 할인) — Engineer 키트와 Marketing 키트는 각각 한 번만 결제하면 되고, Bundle은 둘을 합친 거예요.

1단계 - ak CLI 설치하기 (macOS / Linux / Windows)

설치 프로그램은 OS와 아키텍처를 자동으로 감지해 안정 빌드를 내려받고, SHA-256 체크섬을 검증한 뒤 ~/.local/bin에 설치해요. 사용하는 운영체제에 맞는 명령을 고르세요:

macOS / Linux:

curl -fsSL https://agentkit.best/install.sh | sh

Windows (PowerShell):

irm https://agentkit.best/install.ps1 | iex

회사 네트워크가 기본 도메인을 차단한다면 백업 도메인 releases.agentkit.best/install.sh(또는 .ps1)를 사용하세요. 알아두면 편한 선택적 환경 변수가 몇 가지 있어요:

• AK_INSTALL_DIR - 기본값을 쓰고 싶지 않을 때 설치 디렉터리를 바꿔요.
• AK_CHANNEL=beta - 베타 채널을 설치해요(가장 최신이지만 덜 안정적일 수 있어요).
• AK_VERSION=x.y.z - 특정 버전으로 고정해요.

설치가 끝나면 두 명령으로 바로 검증하세요:

ak --version
ak doctor

ak --version은 버전 번호를 출력해요. ak doctor는 환경을 검사해 PATH, 권한, 충돌을 보고해요 — 전부 초록색이면 문제없어요. 작은 팁: ak doctor가 PATH 문제를 지적하면 로그인과 키트 설치로 서둘러 넘어가지 말고 PATH부터 고치세요. 이후의 오류는 거의 다 여기서 비롯되니까요. macOS/Linux에서는 바이너리가 ~/.local/bin/ak에 있으니, PATH를 신경 쓰기 전에 전체 경로로 실행해 빠르게 확인할 수 있어요.

2단계 - 로그인하고 인증하기 (ak login)

여기가 가장 많이 헷갈리는 부분이니 꼼꼼히 읽으세요.

라이선스 키는 CLI를 활성화하지 않아요. 라이선스 키는 AgentKit 데스크톱 앱만 활성화해요. ak CLI는 계정에 로그인하는 것으로 인증(권한 부여)돼요. 터미널에서 "라이선스 키를 붙여넣으세요"라는 프롬프트를 계속 찾아도 절대 나오지 않아요 — 그런 건 없거든요.

개인 컴퓨터라면(브라우저가 열리거나 이메일로 OTP가 와요):

ak login --email [email protected]

CI나 비대화형 환경이라면 API 키를 쓰세요:

ak login --api-key ak_live_... --no-interactive

올바른 계정으로 로그인했는지, 무엇에 접근할 수 있는지 확인하세요:

ak whoami
ak licenses

ak whoami는 어떤 계정으로 로그인했는지 알려줘요. ak licenses는 다운로드가 허용된 이용 권한(키트) 목록을 보여줘요. 키트를 분명히 샀는데도 ak licenses가 비어 있게 나오면, 엉뚱한 이메일로 로그인한 건 아닌지 다시 확인하세요.

보안: API 키는 절대 커밋하거나 공유하지 마세요(ak_live_ 접두사가 붙어 있고, 봇이 GitHub에서 이걸 스캔해요). 공유 컴퓨터에서는 작업이 끝나면 ak logout을 실행하는 걸 잊지 마세요.

3단계 - Claude Code에 키트 설치하기 (ak kit init)

이제 skill과 agent를 Claude Code에 불러오는 부분이에요. Engineer 키트의 표준 명령은 이거예요:

ak kit init engineer --target claude-code --global

Marketing 키트를 설치하려면 engineer를 marketing으로 바꾸세요. --global 플래그는 모든 프로젝트에 설치해요. 현재 디렉터리에만 넣고 싶다면 빼세요.

모든 skill을 설치할 필요는 없어요 — 컨텍스트를 가볍게 유지하려면 골라서 설치할 수 있어요:

ak kit init engineer --target claude-code --global --skills ak-cook,ak-plan
ak kit init engineer --target claude-code --global --exclude-skills ak-deep-swe

설치하기 전에 어떤 키트와 skill을 쓸 수 있는지 보려면:

ak kit list-kits
ak versions

아직 Engineer/Marketing 키트가 없나요? 이 단계에는 이용 권한이 필요해요. 어떤 skill과 워크플로가 들어 있는지는 Engineer 키트에 담긴 것을 확인하세요. 이미 결정했다면 Engineer 또는 Marketing 키트를 받으세요 — 20% 할인, 지금 키트당 $79.20.

4단계 - Claude Code에서 실행해 보기 (/ak:)

프로젝트에서 Claude Code를 열고 /를 입력한 다음 ak:를 입력하면, 방금 불러온 키트의 슬래시 명령이 추천으로 떠요:

/ak:cook # implement a feature within scope
/ak:plan # plan the work, break it into phases
/ak:fix # fix bugs, failing tests, CI
/ak:ask # quick questions about the codebase

설치 과정 전체가 제대로 연결됐는지 확인하려면 작은 실제 작업(예: 엔드포인트 추가)에서 /ak:cook을 실행해 보세요. Claude Code가 명령을 받아들여 키트의 워크플로를 진행하기 시작하면 설치에 성공한 거예요. /ak:를 입력해도 명령이 뜨지 않으면, 보통 키트가 올바른 대상에 로드되지 않은 거예요 — ak kit init으로 돌아가 올바른 --target claude-code 플래그를 붙여 실행하거나, Claude Code를 재시작해 명령 목록을 다시 불러오게 하세요. 여기까지 왔다면 다층 검증 체인을 전부 거친 거예요: ak --version(바이너리 실행), ak doctor(깨끗한 환경), ak whoami(로그인됨), ak licenses(이용 권한 있음), 그리고 마지막으로 Claude Code에 /ak:가 뜨는 것(키트가 살아 있음)이에요.

이전 Claude Kit에서 이전하기 (ck에서 ak로)

예전에 Claude Kit(ck)를 썼다면 ak가 바로 그 후속작이에요. 두 바이너리를 함께 두지 마세요 — 예전 ck가 PATH를 가로채거나 충돌하는 shim을 남길 수 있어요. ak를 설치한 뒤 실행하세요:

ak doctor --check ck_shim_collision

이 명령은 ck에서 남은 shim 충돌을 감지해요. 경고가 나오면 예전 ck 바이너리를 PATH에서 제거하세요. 문서도 docs.claudekit.cc에서 docs.agentkit.best로 옮겨졌으니, 예전 ck 명령을 따르는 건 그만두세요. 이름 변경에 관한 전체 맥락은 Claude Kit가 AgentKit로 이름 변경에 있어요.

자주 나는 오류 해결하기

ak 설치에서 생기는 대부분의 문제는 아래 경우 중 하나예요:

자주 묻는 질문 (FAQ)

ak CLI를 설치하는 데 Node.js가 필요한가요?

아니요. ak 바이너리는 네이티브(macOS/Linux/Windows)라서 Node.js나 Bun 없이 단독으로 실행돼요. Node 18+가 필요한 건 키트를 불러오는 대상인 Claude Code 환경뿐이에요.

라이선스 키는 어디에 입력하나요? 그리고 CLI에는 왜 필요 없나요?

라이선스 키는 CLI가 아니라 AgentKit 데스크톱 앱을 활성화해요. ak CLI는 계정 로그인(이메일이나 API 키로 ak login)으로 인증돼요. 이게 가장 흔한 혼동 지점이에요.

Windows에도 설치할 수 있나요?

네. PowerShell에서 irm https://agentkit.best/install.ps1 | iex를 사용하세요. 설치 후 ak를 입력했는데 "not recognized"라고 나오면, 새 터미널 창을 열기만 하면 돼요.

Claude Code Pro가 필요한가요?

모델이 돌아가려면 Claude Code에서 동작하는 Claude 요금제(Pro, Max 또는 종량제 API)가 필요해요. AgentKit는 그 요금제를 대체하지 않고, Claude Code 위에 skill과 agent를 더해줄 뿐이에요.

ak는 어떻게 제거하나요?

ak uninstall을 실행하세요. 공유 컴퓨터에서는 먼저 ak logout을 실행해 세션을 지우세요.

라이선스 하나로 몇 대의 컴퓨터를 쓸 수 있나요?

라이선스당 기기 수는 agentkit.best의 현재 약관에 따라 달라져요.

마무리와 라이선스 받기

5단계를 다시 정리해요: Claude Code 설치(사전 준비), ak 바이너리 설치, ak login으로 인증, ak kit init engineer --target claude-code --global 실행, 그다음 Claude Code에서 /ak: 입력. 가장 큰 함정을 기억하세요: 라이선스 = 데스크톱 앱, CLI = 계정 로그인. CLI는 베타라서, 실행하기 전에 문서에서 최신 명령을 확인하세요.

AgentKit가 실제로 얼마나 가치 있는지 알아보려면 AgentKit 전체 리뷰를 읽고, AgentKit 가격 분석으로 비용을 따져보세요.