🐍 CheetahClaws v3.05: Claude Code를 Python으로 재구현한 오픈소스 AI 코딩 어시스턴트 설치 가이드

안녕하세요! 오늘은 오픈소스 AI 코딩 어시스턴트인 CheetahClaws v3.05에 대해 알아보겠습니다. SafeRL-Lab에서 개발한 CheetahClaws는 Claude Code를 Python으로 재구현한 프로젝트로, 8개 이상의 모델 프로바이더를 지원하고 로컬 모델(Ollama, vLLM) 완벽 호환이라는 강력한 장점을 가지고 있습니다. 특히 v3.05에서는 TTS 콘텐츠 팩토리, 모듈형 생태계, CJK 음성 자동 감지 등 혁신적인 기능이 대거 추가되었습니다. 이 블로그에서는 CheetahClaws의 주요 기능, 설치 방법, v3.05의 변경 사항, 그리고 실제 활용법까지 상세히 다루어 보겠습니다. 함께 살펴보시죠!

"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

🤖 CheetahClaws란 무엇인가요?

CheetahClaws는 SafeRL-Lab에서 개발한 Python 기반 오픈소스 AI 코딩 어시스턴트입니다. Anthropic의 Claude Code에서 영감을 받아 처음부터 Python으로 재구현되었으며, Apache 2.0 라이선스로 누구나 자유롭게 사용, 수정, 배포할 수 있습니다.

핵심 철학: Claude Code의 강력한 에이전트 루프를 Python으로 가볍게 재현하되, 어떤 모델이든 사용 가능하게 만드는 것. 핵심 에이전트 루프는 단 174줄의 Python 코드로 작성되어 있어 누구나 쉽게 읽고 수정할 수 있습니다.

전체 프로젝트는 약 12,000줄의 Python 코드(51개 파일)로 구성되어 있어, TypeScript 기반 Claude Code(약 245,000줄, 10,349개 파일)와 비교하면 압도적으로 가볍습니다. 그럼에도 불구하고 코딩에 필요한 핵심 기능은 모두 갖추고 있습니다.

🚀 CheetahClaws v3.05 주요 변경 사항

2026년 4월 7~8일에 연이어 출시된 v3.05 시리즈(v3.05.53 ~ v3.05.55)는 CheetahClaws 역사상 가장 대대적인 업데이트입니다. 주요 변경 사항을 정리해보았습니다.

📦 v3.05.55 (2026년 4월 8일)

기능	설명
모듈형 생태계	`modular/` 폴더에 플러그앤플레이 모듈 구조 도입. 각 서브모듈이 독립적으로 동작하며, 누락된 모듈은 시스템에 영향 없이 우아하게 degraded
TTS 콘텐츠 팩토리	`/tts` 명령으로 AI 기반 텍스트 음성 변환. 내레이터, 뉴스리더, 스토리텔러, ASMR, 동화, 명상 등 9가지 음성 스타일 지원
CJK 음성 자동 감지	한국어/중국어/일본어 텍스트를 감지하면 Edge TTS 음성을 자동으로 `zh-CN-XiaoxiaoNeural`로 전환하여 전체 텍스트 합성 보장
Edge TTS 긴 텍스트 분할	3,000자 이상 텍스트를 2,000자 단위로 문장 경계에서 분할하여 합성 후 ffmpeg로 연결. 긴 스크립트도 완전하게 음성 변환
Readline ANSI 수정	ANSI 색상 코드가 커서 위치를 왜곡하던 문제 수정. REPL 히스토리 스크롤 시 커서 드리프트 해결

🎬 v3.05.54 (2026년 4월 7일)

기능	설명
커스텀 스크립트 모드	`/video` 위저드에서 직접 나레이션 텍스트 입력 가능. AI 스토리 생성 없이 즉시 영상 제작
PIL 자막 렌더링 엔진	Pillow + NotoSansSC 폰트로 자막 렌더링. 한국어, 중국어, 일본어, 아랍어 등 비 라틴 문자가 까만 네모로 표시되던 문제 완전 해결
무료 웹 이미지 검색	Pexels → Wikimedia Commons → Lorem Picsum 순으로 관련 이미지 자동 검색. 소스 이미지 없이도 영상 제작 가능
위저드 UX 대폭 개선	모든 단계에서 `b`=뒤로, `q`=종료 지원. 모든 옵션에 Auto 기본값(Enter=Auto)

📱 v3.05.53 (2026년 4월 7일)

기능	설명
Telegram 사진 비전	Telegram에 사진을 보내면 비전 모델(GPT-4o, Gemini 2.0 Flash 등)이 자동으로 이미지 분석
Telegram 음성 STT	음성 메시지나 오디오 파일 전송 시 Whisper로 자동 전사. ffmpeg로 OGG→PCM 변환 후 처리
프로세스 트리 종료	Bash 명령 타임아웃 시 자식 프로세스 전체 종료. Unix에서 `os.killpg`, Windows에서 `taskkill /F /T`
Windows 쉘 힌트	비 Claude 모델에 Windows 전용 쉘 명령어 치트시트 자동 제공 (`type` vs `cat` 등)

📊 CheetahClaws vs OpenClaw 비교

CheetahClaws는 OpenClaw(이전 Clawdbot)에서 영감을 받았지만, 명확한 차별점이 있습니다.

항목	OpenClaw (TypeScript)	CheetahClaws (Python)
언어	TypeScript + Node.js	Python 3.8+
코드 규모	~245K 줄 / 10,349 파일	~12K 줄 / 51 파일
주요 용도	메시징 채널 개인 비서	AI 코딩 어시스턴트 / 개발 도구
로컬 모델	제한적	완벽 지원 (Ollama, vLLM, LM Studio)
모델 프로바이더	다수 (클라우드 중심)	8+ 프로바이더 (로컬 포함)
설치	데몬 + 페어링 필요	`pip install` 즉시 실행
음성	웨이크워드, PTT, Talk Mode	오프라인 Whisper STT

⚙️ 핵심 기능 살펴보기

🔧 27개 내장 도구

CheetahClaws는 코딩에 필요한 27개의 내장 도구를 기본 제공합니다.

파일 도구: Read · Write · Edit · Glob · Grep
실행 도구: Bash · NotebookEdit · GetDiagnostics
메모리 도구: MemorySave · MemoryDelete · MemorySearch · MemoryList
에이전트 도구: Agent · SendMessage · CheckAgentResult · ListAgentTasks
태스크 도구: TaskCreate · TaskUpdate · TaskGet · TaskList
기타: Skill · SkillList · AskUserQuestion · SleepTimer · EnterPlanMode · ExitPlanMode

🌐 멀티 프로바이더 지원

하나의 --model 플래그로 즉시 모델을 전환할 수 있습니다.

카테고리	지원 모델
클라우드	Anthropic (Claude) · OpenAI (GPT-4o) · Gemini · Kimi · Qwen · Zhipu · DeepSeek · MiniMax
로컬	Ollama · vLLM · LM Studio · 커스텀 엔드포인트
로컬 추천	`qwen2.5-coder`, `llama3.3`, `mistral`, `phi4`
추론 모델	`deepseek-r1`, `qwen3`, `gemma4` (thinking 블록 스트리밍 지원)

🎬 비디오 콘텐츠 팩토리

/video 명령 하나로 AI 영상 제작 파이프라인이 동작합니다.

영상 제작 파이프라인:
스토리 생성 (활성 모델) → TTS 나레이션 (Edge/Gemini/ElevenLabs) → AI 이미지 (Gemini Web 또는 무료 웹 검색) → 자막 삽입 (Whisper 또는 PIL) → FFmpeg 조합 → 최종 .mp4 출력

10가지 바이럴 콘텐츠 니치 제공, 가로/세로 포맷 지원, 완전 무료 경로 사용 가능

🗣️ TTS 콘텐츠 팩토리 (v3.05 신규)

v3.05.55에서 새롭게 추가된 /tts 명령은 AI 기반 텍스트 음성 변환을 제공합니다.

⚠️ 버전 호환성: pip install cheetahclaws로 설치된 v3.05.5는 /tts 명령을 지원하지 않습니다. v3.05.55+의 TTS 기능을 사용하려면 GitHub에서 직접 설치해야 합니다.

지원 음성 스타일 9가지:
내레이터 · 뉴스리더 · 스토리텔러 · ASMR · 동기부여 · 다큐멘터리 · 동화 · 팟캐스트 · 명상

TTS 엔진 우선순위: Gemini → ElevenLabs → Edge (최적 가용 엔진 자동 선택)
출력: .mp3 오디오 + _script.txt 동반 파일

🧠 브레인스톰 & SSJ 개발자 모드

/brainstorm [주제] 명령으로 최대 100명의 전문가 페르소나가 참여하는 AI 토론을 생성할 수 있습니다. 결과는 brainstorm_outputs/에 저장되며, 마스터 플랜과 todo_list.txt를 자동 생성합니다.

/ssj는 지속형 파워 메뉴로, 브레인스톰, TODO 뷰어, 워커, 전문가 토론, 리뷰, 커밋 등 12개 단축 기능을 인터랙티브하게 제공합니다.

🔊 오프라인 음성 입력

/voice 명령으로 완전 오프라인 음성 인식이 가능합니다. faster-whisper를 사용하여 인터넷 연결 없이도 동작하며, 첫 사용 시 base 모델(약 150MB)을 자동 다운로드합니다.

# 음성 입력 최소 설정
pip install sounddevice faster-whisper numpy

# REPL에서 사용
[myproject] ❯ /voice
  🎙 Listening… (speak now, auto-stops on silence, Ctrl+C to cancel)
  🎙 ████
✓ Transcribed: "fix the authentication bug in user.py"
[auto-submitting…]

🌍 지원 모델 상세

CheetahClaws는 클라우드 API 모델과 로컬 모델 모두를 폭넓게 지원합니다.

클라우드 API 모델

프로바이더	대표 모델	특징
Anthropic	Claude Opus, Sonnet, Haiku	툴 콜링, 비전, 200K 컨텍스트
OpenAI	GPT-4o, GPT-4.1	비전, 함수 호출, 128K 컨텍스트
Google	Gemini 2.5 Pro, 2.0 Flash	멀티모달, 1M 토큰 컨텍스트
DeepSeek	DeepSeek-R1, V3	추론 모델, 비용 효율
Qwen	Qwen3, Qwen2.5-Coder	코딩 특화, 다국어
MiniMax	M2.7	코딩·대화 강화, 자기진화
Kimi / Zhipu	GLM-5 시리즈	중국 AI, 강력한 코딩 능력

로컬 모델 (Ollama)

API 키 없이 완전 오프라인으로 실행할 수 있습니다.

# Ollama로 로컬 모델 실행
ollama pull qwen2.5-coder:14b
ollama pull llama3.3:70b

# CheetahClaws에서 로컬 모델 사용
cheetahclaws --model ollama:qwen2.5-coder:14b

# REPL에서 모델 전환
/model ollama:llama3.3:70b

🚀 설치 및 실행 가이드

방법 1: uv로 글로벌 설치 (권장)

uv를 사용하면 격리된 환경에 설치하여 어디서든 cheetahclaws 명령을 사용할 수 있습니다.

# uv 설치 (아직 없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# CheetahClaws 클론 및 설치
git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
uv tool install .

# 실행
cheetahclaws                        # REPL 시작
cheetahclaws --model gpt-4o         # 모델 지정
cheetahclaws -p "explain this"      # 비대화형 모드

# 업데이트
cd cheetahclaws && git pull
uv tool install . --reinstall

curl -LsSf https://astral.sh/uv/install.sh ❘ sh

git clone https://github.com/SafeRL-Lab/cheetahclaws.git

방법 2: 직접 실행

git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws

# 의존성 설치
pip install -r requirements.txt
# 또는 최소 설치
pip install anthropic openai httpx rich

# 음성 입력 (선택사항)
pip install sounddevice faster-whisper numpy

# 실행
python cheetahclaws.py

API 키 설정

클라우드 모델을 사용하려면 해당 프로바이더의 API 키가 필요합니다.

# 환경 변수로 설정
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AI..."
export DEEPSEEK_API_KEY="sk-..."

# 또는 REPL 내에서 설정
/config

# 로컬 모델만 사용하면 API 키 불필요!
cheetahclaws --model ollama:qwen2.5-coder:14b

⌨️ 36개 슬래시 명령어

CheetahClaws는 REPL 내에서 사용할 수 있는 36개의 슬래시 명령어를 제공합니다.

명령어	설명
`/model`	현재 모델 확인 + 사용 가능한 모델 목록
`/model <이름>`	모델 즉시 전환
`/config`	설정 관리
`/voice`	오프라인 음성 입력
`/video`	AI 비디오 팩토리
`/tts`	TTS 콘텐츠 팩토리 (v3.05 신규)
`/brainstorm`	멀티 페르소나 AI 토론
`/ssj`	개발자 파워 메뉴 (12개 단축 기능)
`/worker`	TODO 자동 구현
`/proactive`	백그라운드 자동 모니터링
`/checkpoint`	체크포인트 저장/복원
`/plan`	계획 모드 진입
`/compact`	컨텍스트 압축
`/status`	버전, 모델, 토큰 사용량, 컨텍스트 % 표시
`/doctor`	설치 상태 진단
`/memory`	영구 메모리 관리
`/skills`	스킬 관리
`/telegram`	Telegram 브릿지 시작
`/cloudsave`	GitHub Gist 클라우드 동기화
`/export`	대화를 Markdown/JSON으로 내보내기

CheetahClaws Proactive Mode: Autonomous Agent

🔌 MCP (Model Context Protocol) 지원

CheetahClaws는 MCP 서버를 완벽하게 지원합니다. stdio, SSE, HTTP 방식의 MCP 서버를 연결하면 도구가 자동으로 등록됩니다.

# MCP 서버 설치 및 추가
pip install uv
uvx mcp-server-git --help   # 동작 확인

# REPL에서 MCP 서버 추가
/mcp add git uvx mcp-server-git

# 프로젝트에 .mcp.json 파일 생성 후
/mcp reload

📱 Telegram 브릿지

CheetahClaws를 Telegram 봇으로 연결하면 스마트폰에서 어디서든 AI 어시스턴트를 사용할 수 있습니다.

v3.05.53 신규 기능:
📸 사진 전송: 사진을 보내면 비전 모델이 자동 분석 (GPT-4o, Gemini 2.0 Flash, Claude 등)
🎙 음성 메시지: 음성을 보내면 Whisper가 자동 전사하여 쿼리로 제출
⚡ 슬래시 명령어: Telegram에서도 /model, /ssj 등 인터랙티브 메뉴 사용 가능

📁 프로젝트 구조

경로	설명
`cheetahclaws.py`	메인 진입점
`agent.py`	핵심 에이전트 루프 (174줄)
`tools.py`	27개 내장 도구 구현
`modular/`	플러그앤플레이 모듈 폴더 (v3.05 신규)
`modular/video/`	비디오 팩토리 모듈
`modular/voice/`	음성/TTS 모듈
`brainstorm_outputs/`	브레인스톰 결과 저장소

💡 CheetahClaws가 특별한 이유

CheetahClaws의 핵심 강점:

🐍 Python 네이티브: TypeScript가 아닌 Python으로 작성되어 AI/ML 개발자에게 친숙
🏗️ 읽기 쉬운 코드: 핵심 루프 174줄, 전체 12K줄로 누구나 포크하여 확장 가능
🔌 런타임 확장: register_tool()로 새 도구를 즉시 등록, MCP 서버 자동 연결
🌐 어떤 모델이든: Claude, GPT-4o, Gemini, DeepSeek, 로컬 Ollama까지 한 명령으로 전환
💾 영구 메모리: 세션 간 지속되는 메모리 시스템으로 컨텍스트 유지
📋 태스크 의존성 그래프: blocks/blocked_by 엣지로 구조화된 멀티스텝 계획
🗜️ 2단계 컨텍스트 압축: 규칙 기반 스니핑 + AI 요약으로 긴 대화 관리

🔧 WSL 붙여넣기 문제 해결 (0~/1~ 아티팩트)

WSL(Windows Subsystem for Linux) 환경에서 CheetahClaws 사용 시 Ctrl+V 붙여넣기에서 0~와 1~ 문자가 텍스트 앞뒤에 붙는 현상이 발생할 수 있습니다. 이는 bracketed paste mode ANSI 이스케이프 시퀀스가 WSL 터미널에서 누출되는 문제입니다.

원인

Bracketed paste mode는 터미널이 붙여넣은 텍스트를 \x1b[200~(시작)과 \x1b[201~(종료) 이스케이프 코드로 감싸서 프로그램이 붙여넣기와 직접 입력을 구분할 수 있게 하는 기능입니다. WSL에서는 이 코드가 제대로 처리되지 않고 0~, 1~로 누출됩니다.

해결 방법

다음 설정을 적용하여 bracketed paste mode를 비활성화하세요:

# 1. ~/.zshrc 또는 ~/.bashrc에 추가
printf "\x1b[?2004l"  # zsh 시작 시 bracketed paste 비활성화

# 2. ~/.inputrc에 추가 (readline 설정)
set enable-bracketed-paste off

# 3. ~/.zshenv에 추가 (zsh 초기화 전)
unset zle_bracketed_paste 2>/dev/null

VS Code Terminal 설정

VS Code에서도 bracketed paste를 비활성화해야 합니다:

// settings.json에 추가
{
  "terminal.integrated.enableBracketedPaste": false
}

WSL에서 VS Code 설정 위치: /mnt/c/Users/User/AppData/Roaming/Code/User/settings.json

Windows Terminal 설정

Windows Terminal을 사용하는 경우:

// settings.json의 profiles.defaults에 추가
{
  "profiles": {
    "defaults": {
      "bracketedPasteMode": "none"
    }
  }
}

설정 파일 위치: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json

💡 참고: 위 설정을 모두 적용한 후 터미널과 VS Code를 재시작하세요. CheetahClaws v3.05.5 이상에서는 WSL 환경을 자동 감지하여 bracketed paste mode를 비활성화하고 아티팩트 문자를 자동 제거합니다.

소스 파일 직접 수정 (Python 3.14 호환 문제)

터미널 설정만으로 해결되지 않고 Segmentation fault 에러가 발생하는 경우, CheetahClaws 소스 파일을 직접 수정해야 합니다.

# 파일 위치: ~/.local/share/uv/tools/cheetahclaws/lib/python3.14/site-packages/cheetahclaws.py
# 또는 pip 설치 위치의 cheetahclaws.py

# 1. readline.parse_and_bind() 호출 찾기 (약 78행附近)
# Python 3.14에서 이 호출이 Segmentation fault를 발생시킴
# 다음 코드를 삭제 또는 주석 처리:
# readline.parse_and_bind("set enable-bracketed-paste off")

# 2. WSL 환경에서 아티팩트 문자 제거 코드 추가 (Phase 2 단계)
# 붙여넣기 입력 처리 부분에 추가:
import sys
import platform

def is_wsl():
    return 'microsoft' in platform.release().lower() or \
           'WSL' in platform.release()

# 입력에서 0~/1~ 아티팩트 제거
if is_wsl():
    input_text = input_text.replace('\x1b[200~', '').replace('\x1b[201~', '')
    input_text = input_text.replace('0~', '').replace('1~', '')

⚠️ 주의: 소스 파일 수정은 임시 해결책입니다. CheetahClaws 재설치 시 수정 내용이 사라집니다. 개발자에게 Python 3.14 호환성 문제를 리포트하거나, GitHub에서 최신 버전을 확인하세요.

⚠️ 한계점 및 주의사항

주의사항:

• 로컬 모델의 툴 콜링: 함수 호출(function calling)을 지원하는 모델이 필요합니다. 모든 로컬 모델이 툴 콜링을 지원하지는 않습니다.
• 대규모 시스템 프롬프트: 25개 툴 스키마가 포함된 시스템 프롬프트 때문에, 일부 모델은 thinking 단계를 생략할 수 있습니다.
• 음성 입력 정확도: 기본 base 모델은 코딩 용어 인식이 떨어질 수 있습니다. export NANO_CLAUDE_WHISPER_MODEL=small로 더 큰 모델 사용 권장.
• Windows 환경: 일부 기능(예: 음성 입력)은 추가 설정이 필요할 수 있습니다.
• 비디오 팩토리: FFmpeg 설치가 필수이며, 이미지 품질은 사용 가능한 소스에 따라 다릅니다.

🎯 맺음말

CheetahClaws v3.05는 Python 기반 오픈소스 AI 코딩 어시스턴트로서 완성도를 한 단계 끌어올렸습니다. 특히 모듈형 생태계 도입으로 확장성이 크게 향상되었고, TTS/비디오 콘텐츠 팩토리로 코딩을 넘어 콘텐츠 제작까지 영역을 넓혔습니다. CJK 음성 자동 감지와 PIL 자막 렌더링은 한국어 사용자에게 특히 반가운 기능입니다.

12,000줄의 가벼운 코드베이스로 Claude Code의 핵심 기능을 재현하면서도, 로컬 모델 완벽 지원과 런타임 확장성이라는 차별점을 가집니다. Python 개발자라면 누구나 pip install 한 번으로 시작할 수 있다는 점도 큰 장점입니다.

다만, 여전히 활성 개발 단계이므로 일부 기능은 불안정할 수 있으며, 로컬 모델의 툴 콜링 지원 여부를 사전에 확인해야 합니다. 상용 Claude Code의 안정성이 필요한 경우에는 기존 도구를 병행 사용하는 것을 권장합니다.

여러분도 한번 CheetahClaws를 GitHub에서 직접 체험해보시길 추천드리면서 저는 다음 시간에 더 유익한 정보를 가지고 다시 찾아뵙겠습니다. 감사합니다.

📚 참고 문헌 및 출처

SafeRL-Lab. (2026). CheetahClaws — Claude Code Reimplemented in Python. Retrieved from https://github.com/SafeRL-Lab/cheetahclaws
SkillsLLM. (2026). CheetahClaws Skill Documentation. Retrieved from https://skillsllm.com/skill/cheetahclaws
SafeRL-Lab. (2026). CheetahClaws 한국어 README. Retrieved from https://github.com/SafeRL-Lab/cheetahclaws/blob/main/docs/README.KO.MD

'AI 도구' 카테고리의 다른 글

🤖 Cursor + Claude Code + Codex: 누구도 계획하지 않은 AI 코딩 스택 통합 (1)	2026.04.13
💡 컨텍스트 스트레스 날려주는 Context Mode MCP: Hermes Agent 설치 가이드 (1)	2026.04.12
🤖 32K+ 스타 오픈소스 자가 개선 AI 에이전트: Hermes Agent v2026.4.8 가이드 (0)	2026.04.10
🤖 Claude Mythos Preview: 제로데이 취약점 자율 발견하는 Dual-Use AI (2)	2026.04.08
🔥 GitHub 2시간 만에 50K 스타! Claw Code 설치부터 Ollama 연동까지 완벽 가이드 (0)	2026.04.07