OpenAI Codex에서 AgentKit 사용하는 방법 (2026 단계별 가이드)

- 아래 명령어와 가격은 작성 시점(2026-08)에 공식 문서(docs.agentkit.best, 베타 채널)와 대조해 확인했어요. 베타 채널은 정식(GA) 릴리스보다 변경이 빠르니, 의존하기 전에 최신 문서에서 다시 확인하세요.

'AgentKit'/'Codex'라고 불리는 세 가지 - 먼저 읽어 주세요

명령어를 하나라도 입력하기 전에, 자꾸 혼동되는 세 이름을 구분해 두세요. 이걸 섞어 버리면 단순한 표현 실수가 아니라, 엉뚱한 제품을 엉뚱한 가격에 사게 돼요.

그래서 'use AgentKit with Codex'나 'AgentKit pricing'으로 검색하면 OpenAI 자체 Agent Builder 결과가 뜨는 거예요 - 잘못된 제품, 잘못된 가격, 잘못된 설치 경로죠. 이 글은 오직 위의 두 번째 행, 즉 agentkit.best만 다뤄요. 엉뚱한 걸 사지 않도록 전체 정리를 보려면 OpenAI AgentKit vs AgentKit(agentkit.best) 완전 비교를 확인하세요.

시작하기 전에 필요한 것

5분이면 되는 체크리스트예요 - 첫 명령어를 입력하기 전에 전부 읽어 보세요.

• OpenAI 계정으로 이미 설치·로그인된 Codex CLI, 또는 Codex를 포함한 ChatGPT 요금제.
• 이미 구매한 AgentKit 라이선스 - Engineer $99 또는 Bundle $149이며, 무료 등급이 아니에요.
• 키트를 설치하려는 바로 그 프로젝트 디렉터리에서 연 터미널.
• 방해받지 않는 약 5분.

사람들이 놓치는 부분: AgentKit에 로그인해도 Codex에 로그인되지 않고, 그 반대도 마찬가지예요 - 이 둘은 완전히 별개인 두 개의 인증 시스템이라, 서로 다른 두 가지에 두 번 로그인하게 되고, 기기를 바꾸면 각각 따로 다시 인증해야 해요. ak kit init까지 진행한 뒤에야 Codex에 로그인이 안 돼 있었다(또는 그 반대)는 걸 발견하지 마세요 - 먼저 둘 다 확인해 두면 쓸데없는 디버깅 반복을 아낄 수 있어요. 아직 Codex를 설치하지 않았나요? 먼저 Codex CLI 설치 방법을 읽어 보세요. Codex가 무엇인지, Claude Code와 어떻게 다른지 잘 모르겠다면 OpenAI Codex란 무엇인가를 참고하세요.

1단계 - ak CLI 설치하기

AgentKit은 ak이라는 단일 네이티브 CLI 바이너리를 통해 실행돼요 - Node도, Bun도, 먼저 설치할 추가 런타임도 필요 없어요. 여러분의 OS를 고르세요.

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

# Windows (PowerShell)
irm https://agentkit.best/install.ps1 | iex

설치 프로그램이 OS와 아키텍처를 자동으로 감지해요. 끝나면 두 가지 명령어로 확인하세요.

ak --version
ak doctor --json

ak doctor --json은 설치 상태를 JSON으로 출력해요 - 이후 단계를 포함해 뭔가 이상하다 싶을 때 언제든 실행하세요. 네이티브 바이너리이기 때문에, 이 설치 경로는 Node가 없는 샌드박스/CI 환경에서도 깔끔하게 동작해요 - npm 패키지로 배포되는 키트와의 진짜 차이점이죠.

2단계 - 로그인하고 라이선스 확인하기

이메일이나 API 키 중 편한 방법으로 로그인하세요.

ak login --email [email protected]
# or
ak login --api-key ak_live_...

그런 다음 무언가를 설치하기 전에, 올바른 라이선스를 가진 올바른 계정인지 확인하세요 - 대부분이 건너뛰는 단계인데, 나중에 라이선스가 실제로는 활성화되지 않았거나 결제할 때 쓴 것과 다른 이메일로 로그인돼 있다는 걸 발견하게 돼요.

ak whoami
ak licenses

ak licenses는 여러분이 소유한 것(Engineer, Marketing 또는 Bundle)을 정확히 나열해요. 결제한 게 분명한데도 목록이 비어서 돌아온다면, 계속하기 전에 주문 확인 이메일이나 agentkit.best 계정 페이지를 확인하세요 - 아무것도 확인하지 않고 설치한 뒤 권한이 없다는 오류가 왜 나는지 고민하지 마세요.

3단계 - Codex에 키트 설치하기

이게 글 전체의 핵심 명령어예요 - 현재 어떤 페이지도 전체를 그대로 적어 두지 않은 그 명령어죠.

ak kit init engineer --target codex

기본값은 프로젝트 스코프로 설치돼요 - 키트가 현재 프로젝트 디렉터리 안에서만 적용되고, 어디서나 되는 건 아니에요. 매번 다시 설치하지 않고 모든 프로젝트에서 쓰고 싶다면 글로벌 플래그를 추가하세요.

ak kit init engineer --target codex --global

디스크에 무언가를 쓰기 전에 ak은 확인/미리 보기 화면을 보여줘요: 키트 이름, 출력 위치, 설치 모드(프로젝트 또는 글로벌), 스코프, 그리고 곧 쓸 파일들의 정확한 목록이요. 'y'를 입력하기 전에 이 화면을 읽으세요 - 나중에 짐작하며 쓰인 내용을 뒤지는 대신, 키트가 무엇을 건드릴지 정확히 아는 순간이에요.

직접 해 본 메모: 처음 이걸 실행했을 때, 확인 화면이 모든 걸 명확히 보여줬어요 - Engineer 키트, .agents/skills에 쓰기, 프로젝트 스코프, 그리고 곧 만들어질 파일들의 구체적인 목록이요. 뒤에 숨겨진 건 없어요. 확인을 누르면 무엇이 건드려졌는지 정확히 알 수 있어요.

아직 키트가 없나요? 위 명령어가 실제로 실행되려면 Engineer 또는 Bundle 라이선스가 필요해요. 현재 가격과 진행 중인 할인을 확인한 다음 이 단계로 돌아오세요.

AgentKit Engineer 키트 받기 →

4단계 - $ak:cook으로 첫 스킬 실행하기

Codex는 방금 설치한 바로 그 프로젝트에서 새 Codex 세션을 연 뒤에야 스킬을 인식해요 - 스킬을 탐색하려면 다시 스캔하는 리로드가 필요하거든요. 예전 세션에서 계속 입력하면서 왜 아무 일도 없는지 고민하지 마세요.

새 세션에서 Codex의 $ak: 구문으로 스킬을 호출하세요.

$ak:cook Add a health-check endpoint

예시 작업은 여러분의 것으로 바꾸세요 - 이건 호출 구문을 보여 주는 예시일 뿐, 정해진 공식이 아니에요. 기억해 둘 만한 건 두 런타임 사이의 구문 차이예요: Codex는 $ak:를 쓰고, Claude Code는 /ak:를 써요 - 같은 키트, 같은 스킬이고, 실행되는 곳에 따라 호출 문자만 달라요. Codex 안에서 /ak:cook을 입력해 놓고 키트가 고장 났다고 넘겨짚지 마세요. 그건 거의 항상 설치 실패가 아니라 구문 불일치예요.

직접 해 본 메모: 새 Codex 세션에서 $ak:cook을 호출하니, 추가 설정 없이 곧바로 스킬이 인식됐어요 - 설치 후 탐색에는 새 세션이 필요하다는 문서 설명과 일치해요.

Codex와 Claude Code에서 AgentKit이 다르게 동작하는 지점

여기가 정말 새로운 정보예요 - 현재 어떤 페이지도 이걸 적어 두지 않았어요. AgentKit은 모든 런타임에서 똑같이 실행되지 않고, Codex에는 Claude Code와 비교해 특정한 제약이 있어요. 런타임 어댑터 문서(docs.agentkit.best/en/beta/concepts/runtime-adapters, 2026-08 접속)에 명시돼 있어요.

짧게 말하면: 스킬, 규칙, 에이전트 디스패치는 Codex에서 완전히 동작해요 - $ak:cook 호출 뒤에 있는 전체 메커니즘이 바로 그거예요. Hooks는 부분적이고, Kit 명령어(스킬과는 다른, 키트 자체의 슬래시 형식 명령어)와 상태 표시줄은 Codex에는 아예 존재하지 않아요. 여러분이 의존하는 워크플로가 Kit 명령어나 지원 그룹 밖의 hook에 크게 기대고 있다면, 그 부분은 Claude Code에서는 잘 되더라도 Codex에서는 조용히 실행되지 않는다고 생각하세요 - 이건 버그가 아니라, 어댑터가 자신의 경계를 미리 선언하는 것이고, 의존한 뒤에 호되게 겪으며 알게 되는 그런 게 아니에요.

Claude Code에 익숙하고 Codex가 처음이라면, 몇 가지가 '사라진' 것처럼 보여도 놀라지 마세요 - 그것들은 애초에 Codex에서 지원된 적이 없는 것이지, 여러분의 설치로 고장 난 게 아니에요.

구체적인 예를 들게요: Claude Code에서 익숙한 워크플로에 Kit 명령어를 통해 실행되는 단계나, 지원 그룹 밖의 hook에 의존하는 단계가 들어 있다면, 그 특정 단계는 Codex에서 조용히 실행되지 않고, 반면 핵심 스킬 레이어($ak:cook 등)는 문제없이 계속 동작한다고 보세요. 안전한 방법은 같은 키트라는 이유로 동일한 동작을 가정하지 말고, 설치 직후에 바로 테스트해 보는 거예요.

무료 Codex vs 유료 AgentKit - 솔직한 경계선

먼저 분명히 말할게요: 여러분은 'Codex를 쓰려고' 돈을 내는 게 아니에요. Codex CLI, Codex 클라우드, 심지어 goal 모드 /goal까지 무료이거나, 여러분이 이미 내고 있는 ChatGPT 요금제(Free/Go/Plus/Pro/Business)에 포함돼 있어요. AgentKit은 그 같은 무료 Codex 엔진 위에 설치하는 미리 만들어진 스킬, 에이전트, 워크플로의 레이어예요 - 스킬을 직접 작성하는 수고를 건너뛰려고 돈을 내는 것이지, Codex 내부의 무언가를 잠금 해제하려는 게 아니에요.

위 가격은 작성 시점(2026-08)의 가격 페이지를 반영해요. 이 사이트는 ref 링크를 통해 -20% 할인을 자주 진행하고(Engineer 약 $79.20) - 할인은 바뀔 수 있으니 어떤 숫자도 고정으로 여기지 말고, 결제 전에 현재 배너를 확인하세요. 환불 보장이 있지만 사이트가 구체적인 기간을 공개하진 않아요 - '14일'이나 '30일'이라고 넘겨짚지 말고 결제 시 정확한 조건을 확인하세요. 구매 전 제품 전체 그림과 시간당 ROI 분석은 AgentKit 전체 리뷰나 AgentKit 가격, 그만한 가치가 있을까의 상세 가격 정보를 읽어 보세요 - 이 둘은 가치 평가를 깊이 파고들어요. 이 글은 설치 전에 판단할 수 있을 만큼만 무료 대 유료의 경계를 분명히 다뤄요.

문제 해결

• 설치가 깨진 것 같을 때: 처음부터 다시 설치하기 전에 ak doctor --json을 실행하고 JSON의 오류 섹션을 읽어 보세요.
• 키트/스킬 버전을 확인하고 싶을 때: ak versions는 최신 릴리스와 비교해 줘요. 키트가 오래됐다고 의심될 때 유용해요.
• $ak:cook이 인식되지 않을 때: 거의 항상 키트를 설치한 바로 그 프로젝트 디렉터리에서 새 Codex 세션을 열지 않았다는 뜻이에요 - 예전 세션을 닫고, 올바른 디렉터리에서 다시 열어 다시 시도하세요.
• 프로젝트 스코프로 설치했는데 다른 곳에서도 필요할 때: 이건 버그가 아니라 예상된 동작이에요 - 프로젝트 스코프는 설치한 곳에서만 적용돼요. 어디서나 쓰고 싶다면 --global을 붙여 명령어를 다시 실행하세요.
• 라이선스가 아직 유효한지 모를 때: ak whoami와 ak licenses로 계정과 실제로 소유한 키트를 확인할 수 있어요.
• 확인 화면에 예상치 못한 게 나올 때(잘못된 스코프, 잘못된 출력 경로): 일단 취소하고, --global을 붙이려던 게 맞는지 다시 확인한 뒤 재실행하세요 - 잘못된 곳에 쓰인 파일을 치우는 것보다 미리 보기를 취소하는 편이 비용이 적어요.

자주 묻는 질문(FAQ)

Codex와 함께 쓸 때 AgentKit은 무료인가요?

아니요. Codex(CLI/클라우드/ChatGPT)는 무료이거나 이미 여러분이 내는 요금제에 포함돼 있어요. AgentKit은 그 위에 설치하는 유료 키트예요 - Engineer $99, Bundle $149이고, Codex를 포함한 어떤 타깃이든 같은 가격이에요.

/ak:와 $ak:의 차이는 뭔가요?

같은 키트, 같은 스킬이고, 런타임마다 호출 구문만 달라요. Claude Code는 /ak:cook, Codex는 $ak:cook을 써요. 잘못된 문자를 입력하는 게 스킬이 '실행되지 않는' 가장 흔한 이유예요.

Claude Code도 필요한가요, 아니면 Codex 전용으로만 AgentKit을 설치할 수 있나요?

Codex만으로 충분해요. ak kit init engineer --target codex는 Codex용으로 단독 설치돼요 - 옆에 Claude Code가 함께 필요하지 않아요.

이건 OpenAI 자체 AgentKit과 같은 건가요?

아니요. 이 글의 AgentKit은 agentkit.best로, ak CLI로 구동되는 서드파티 제품이에요. OpenAI AgentKit은 OpenAI 자체 Agent Builder/ChatKit으로, 이름만 같은 완전히 다른 제품이에요.

AgentKit은 Claude Code보다 Codex에서 더 비싼가요?

차이 없어요. 같은 라이선스가 같은 가격(키트당 $99 또는 Bundle $149)으로, 어떤 --target을 설치하든 적용돼요 - Codex가 별도로 또는 더 비싸게 책정되지 않아요.

라이선스 하나를 Claude Code와 Codex에 걸쳐 쓸 수 있나요?

라이선스 하나로 여러 타깃을 무제한 동시에 쓸 수 있다는 공식 확인은 없어요 - 라이선스는 기기 활성화로 관리되고, --target은 키트가 놓일 위치를 정하는 설치 시점 매개변수일 뿐이에요. 같은 라이선스로 두 런타임을 돌릴 계획이라면, 넘겨짚지 말고 결제 시 활성화 한도를 확인하세요.

아직 Codex를 설치하지 않았어요 - AgentKit을 먼저 설치할 수 있나요?

그다지 의미 없어요. ak kit init … --target codex는 Codex가 읽는 디렉터리(.agents/skills)에 스킬을 쓰기만 해요. Codex가 설치돼 있지 않으면 아직 그걸 실행할 게 없어요. 먼저 Codex CLI 설치 가이드로 Codex를 설치하고 로그인한 다음, 위 단계로 돌아오세요.

확인 화면에서 정말 아무것도 쓰이기 전에 취소할 수 있나요?

네 - 그게 바로 그 화면의 목적이에요. ak kit init은 무언가를 쓰기 전에 키트 이름, 출력 위치, 설치 모드, 스코프, 파일 목록을 보여줘요. 스코프나 저장 위치가 이상해 보이면, 나중에 알아차리는 대신 그 화면에서 빠져나올 수 있어요.

결론

진짜 경로 전체는 네 단계로 정리돼요: ak 설치, ak login, ak kit init engineer --target codex, 새 Codex 세션 열기, 그다음 $ak:cook 호출. Codex는 계속 무료이거나 여러분이 내는 ChatGPT 요금제에 이미 포함돼 있어요. AgentKit은 미리 만들어진 스킬/에이전트 레이어에 대한 추가 비용이지, Codex를 '잠금 해제'하는 요금이 아니에요. 이미 매일 Codex를 쓰고 스킬을 처음부터 짜고 싶지 않다면 살 만해요. 아직 순수한 Codex에 적응하는 중이라면 급하진 않아요.