1. Kimi CLI가 뭔가요?
Kimi CLI는 중국 Moonshot AI에서 공개한 터미널 기반 코딩 에이전트입니다. 화면에 띄운 채 대화를 나누는 챗봇이 아니라, 명령 한 줄로 실행해서 코드를 읽고, 고치고, 테스트를 돌리는 일을 대신 처리해 줍니다. 사람이 자리에 없어도 정해진 명령만 던지면 끝까지 알아서 해내는, 이른바 에이전트형 인공지능(Agentic AI)의 대표적인 사례입니다.
왜 "비대화형"일까요?
보통 터미널 도구는 실행 중에 "진행할까요?(y/n)"라고 물어봅니다. 비대화형 모드에서는 이런 입력을 모두 미리 약속해서 사람 없이도 끝까지 자동 실행되게 만듭니다. CI 서버나 예약 작업처럼 한 번 던져 놓고 기다리는 환경에 특히 잘 어울립니다.
이 글에서 다루는 핵심 기능 6가지
- 격리된 Python 3.13 환경에서 CLI 설치
- TOML 파일 기반 Moonshot API 인증
- 다시 쓸 수 있는 Python 래퍼(실행 도우미) 제작
- 소규모 프로젝트에 대한 자동 코드 리뷰와 버그 수정
- 단위 테스트 자동 생성과 검증 실행
- JSONL 이벤트 스트림, 지속 세션, 웹 UI 같은 고급 기능
2. 환경 준비와 CLI 설치
기본 흐름은 간단합니다. uv라는 빠른 파이썬 도구로 깨끗한 가상 환경을 만들고, 그 안에 Kimi CLI를 설치합니다.
uv가 뭔가요?
Rust로 만든 고속 파이썬 패키지·환경 관리자입니다. 기존 pip보다 10~100배 빠르고, 가상환경 생성과 파이썬 버전 설치까지 한 번에 처리해서 최근 표준처럼 자리 잡고 있습니다.
- 필요한 파이썬 모듈을 불러오고, 서브프로세스 실행용 헬퍼 함수를 정의합니다.
uv를 설치한 뒤 환경 변수 경로에 추가합니다.uv로 파이썬 3.13 가상 환경을 만들고, 그 안에 Kimi CLI를 설치합니다.- 설치가 끝나면
kimi --version으로 정상 작동을 확인합니다.
3. Moonshot API 인증 설정
Kimi CLI는 OpenAI 호환 API를 지원합니다. 본문에서는 Moonshot API를 사용하며, API 키는 Google Colab Secrets에 안전하게 보관하거나, 화면에 표시되지 않는 입력창(getpass)으로 받습니다.
설정 파일의 위치
Moonshot 엔드포인트와 모델 이름, 그리고 사용할 컨텍스트 윈도(문맥 창) 크기를 ~/.kimi/config.toml 파일에 적어 둡니다. 컨텍스트 윈도란 모델이 한 번에 기억할 수 있는 입력 크기로, 보통 토큰 수로 나타냅니다. 코드를 길게 다루려면 이 값을 넉넉하게 잡아 주는 게 좋습니다.
TOML이 뭐죠?
TOML은 사람이 읽기 쉽게 만든 설정 파일 형식입니다. key = "value" 형태의 키-값 쌍과 표(table)로 구성되며, 최근 많은 파이썬 프로젝트의 기본 설정 포맷으로 쓰입니다.
4. 비대화형 실행용 Python 래퍼
매번 같은 깃발(--flag)을 반복해서 입력하는 건 비효율적입니다. 본문에서는 다음 깃발을 상황에 따라 자동으로 조합하는 재사용 가능한 파이썬 함수를 만듭니다.
-y/--yolo: 모든 도구 사용을 자동 승인--stream: 결과를 JSONL 형식으로 한 줄씩 흘려보내기--continue: 이전 세션 이어서 시작--work-dir: 작업 폴더를 격리--max-steps: 에이전트가 반복할 최대 횟수 제한
JSONL이 뭐예요?
JSON을 한 줄에 하나씩 기록한 텍스트입니다. 로그나 이벤트 스트림처럼 데이터가 끊임없이 흘러나오는 경우에 아주 잘 어울리며, 파이썬에서는 for line in f: obj = json.loads(line) 같은 한 줄 패턴으로 바로 읽을 수 있습니다.
래퍼는 명령의 출력을 모아 마지막 답변이나 오류 정보를 정리해 반환합니다. 이렇게 한 번 만들어 두면, 이후 단계에서 아주 짧은 호출만으로 Kimi를 돌릴 수 있습니다.
5. 예제 프로젝트 자동 분석
연습용으로 재고 관리(inventory) 토이 프로젝트를 만듭니다. 파이썬 모듈, 실행 스크립트, README까지 갖춘 작은 규모로, 일부러 결함을 심어 둡니다. 그리고 Kimi에게 다음 두 가지를 시킵니다.
- 저장소 디렉터리 구조를 살펴 보기
- 읽기 전용 모드로 프로젝트 분석 보고서를 작성
Kimi는 코드 흐름을 따라가며 "기능상 위험"과 "설계상 위험"을 묶어서 알려 줍니다. 사람이 직접 한 줄 한 줄 살펴보는 시간 없이도 1차 점검 보고서가 자동으로 생성되는 셈입니다.
6. 코드 수정과 테스트 자동화
분석 결과가 마음에 들면 이번에는 에이전트에게 수정 권한을 줍니다. 핵심 단계는 다음과 같습니다.
- 재고 관리 로직의 버그를 스스로 고치도록 지시
- 정상 동작을 검증할 단위 테스트를 직접 작성하게 함
- 테스트 스위트 실행 명령을 돌리게 하고, 실패하면 원인을 진단해 다시 고치게 함
--max-steps값으로 한 번에 반복할 수 있는 최대 횟수를 제한(예: 50회)
실험실 vs 실무
실습 단계에서는 프로젝트 규모가 작아 결과가 빠르게 나옵니다. 실무에 쓸 때는 작업 폴더를 별도 브랜치로 분리하고, 외부 영향이 없는 작은 단위부터 천천히 자동화 범위를 넓히는 편이 안전합니다.
에이전트가 만든 파이썬 파일을 사람이 다시 읽어 보고, 테스트를 외부에서 한 번 더 돌려 봅니다. 이렇게 출력과 실행 결과를 둘 다 확인하는 습관이 워크플로의 신뢰성을 크게 높여 줍니다.
7. 고급 기능 살펴보기
기본 흐름이 안정되면 다음 옵션들을 하나씩 켜 볼 수 있습니다.
- JSONL 스트리밍: 각 이벤트를 파싱해 기계가 읽기 쉬운 형태로 저장
- 지속형 멀티턴 세션: 릴리스 코드명을 저장해 두고 같은 작업 폴더에서 이어서 불러오기
- 계획 모드(plan mode): 코드를 바로 고치기 전에 변경 안을 먼저 제시
- 모델 전환: 작업 난이도에 따라 다른 모델로 교체
- Ralph 루프: 같은 프롬프트를 반복 실행해 오류를 다음 회차에 반영
- MCP 도구: 외부 데이터·도구를 표준 방식으로 연결
- 세션 내보내기 / 웹 UI: 작업 로그 공유, 브라우저 접근
MCP가 뭐예요?
모델 컨텍스트 프로토콜(Model Context Protocol)의 약자로, AI 모델과 외부 시스템(데이터베이스, 파일, API 등)을 연결하는 개방형 표준입니다. 서로 다른 도구를 만들더라도 같은 방식으로 끼워 맞출 수 있어, 에이전트 생태계가 빠르게 커지고 있습니다.
8. 자주 묻는 질문(FAQ)
Kimi CLI는 무료인가요?
CLI 도구 자체는 오픈소스로 무료입니다. 단, 실제로 모델을 호출하려면 Moonshot API 키가 필요하며, API 사용량에 따라 비용이 발생합니다. 소규모 테스트는 무료 크레딧으로 충분합니다.
비대화형 모드일 때 위험한 작업도 자동 승인되나요?
-y 플래그를 켜면 모든 도구 사용에 자동 동의하게 됩니다. 실수할 여지가 큰 스크립트(예: 프로덕션 DB 삭제)에는 이 플래그를 절대 켜지 말고, 사본이나 샌드박스 환경에서만 자동화해야 합니다.
파이썬 외 다른 언어도 되나요?
네. Kimi CLI는 언어에 구애받지 않고 파일을 읽고, 정적 분석 도구와 테스트 러너를 호출할 수 있습니다. 자바스크립트, Go, Rust 프로젝트에도 동일한 워크플로를 그대로 적용할 수 있습니다.
Ralph 루프는 어떤 상황에서 유용한가요?
테스트가 자주 실패하는 리팩터링 작업이나, 같은 버그 클래스를 반복해서 잡아야 할 때 특히 효과적입니다. 한 번의 실행으로 끝나지 않는 경우 반복 개선 패턴을 표준화해 줍니다.
지속형 세션은 어디에 저장되나요?
기본적으로 작업 폴더 안의 .kimi 디렉터리에 세션 파일이 보관됩니다. --continue 옵션으로 같은 폴더에서 다시 시작하면 이전 작업 기억을 그대로 이어받을 수 있습니다.
MCP 도구는 어떻게 추가하나요?
CLI 설정에 MCP 서버 주소를 등록하면 됩니다. 사내 DB, 문서 검색, 이슈 트래커 등 다양한 서비스를 같은 방식으로 연결할 수 있어, 에이전트가 "손이 닿는 범위"가 크게 넓어집니다.