SafeRL-Lab/cheetahclaws

English | 中文 | 한국어 | 日本語 | Français | Deutsch | Español | Português

CheetahClaws: OpenClaw와 Claude Code에서 영감을 받아 제작되었으며, 어떤 모델이든 사용할 수 있고 빠르고, 사용하기 쉬우며, 프로덕션 환경에 적합한(Production-Ready), Python 네이티브 개인용 AI 어시스턴트입니다. 사용자를 위해 24/7 자율적으로 작동하도록 설계되었습니다.

CheetahClaws

Website · Brief Intro · Issue · Claude Code의 최신 소스

curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash

설치 후:

source ~/.zshrc # macOS
# 또는: source ~/.bashrc # Linux
cheetahclaws # 채팅 시작!

기타 설치 방법: pip install | uv install | 소스에서 실행 | 상세 정보

• 2026년 5월 12일 (최신):
  보안 강화 작업 — 환경 변수를 통한 봇 토큰(bot tokens), 웹 CSRF, 터미널 세션 소유자 바인딩, 플러그인/MCP/fs 샌드박싱(sandboxing). 동일한 브랜치에 두 차례의 수정 사항(CRITICAL + HIGH)이 적용되었습니다: (1)$TELEGRAM_BOT_TOKEN / $SLACK_BOT_TOKEN이 이제 봇 토큰을 제공하는 권장 방식입니다. 환경 변수로 제공된 토큰은 readline 히스토리나 ~/.cheetahclaws/config.json에 절대 저장되지 않습니다. 기존의 /telegram <token> <chat_id> 구문은 여전히 작동하지만, 지원 중단 경고(deprecation warning)를 출력하며 메모리 내 히스토리에서 토큰을 자동으로 삭제합니다. (2) 웹 UI에 이중 제출 CSRF 쿠키(ccsrf)가 추가되었습니다. 모든 POST/PUT/PATCH/DELETE 요청은 X-CSRF-Token을 통해 이를 에코(echo)해야 합니다. 번들로 포함된 프론트엔드(web/static/js/csrf.js)가 window.fetch를 패치하여 이 과정이 자동으로 처리됩니다. (3) /api/session 터미널 세션이 이제 JWT 소유자에게 바인딩됩니다. 따라서 다른 인증된 사용자가 우연히 알게 된 sid를 탈취할 수 없습니다. (4) Bash 도구의 하드 디나일리스트(hard-denylist) (rm -rf /, fork bomb, mkfs, dd of=/dev/sd…)는 permission_mode=accept-all 설정으로도 우회할 수 없습니다. (5) Read / Write / Edit 기능에 기본적으로 자격 증명 경로 디나일리스트(~/.ssh/id_*, ~/.aws, /etc/shadow, …)가 적용됩니다. (6) 플러그인 로더에 CHEETAHCLAWS_DISABLE_PLUGINS 및 CHEETAHCLAWS_PLUGIN_ALLOWLIST 기능이 추가되었습니다. 모듈 경로는 install_dir로 제한됩니다. (7) MCP 서버 설정에서 더 이상 LD_PRELOAD / PYTHONPATH / DYLD_*를 주입할 수 없습니다.

/NODE_OPTIONS 등을 서브프로세스 환경 변수(subprocess env)로 주입합니다. (8) macOS 데몬이 Unix 소켓 피어 인증(peer-cred auth)을 위한 getpeereid(2) 권한을 획득했습니다 (이전에는 Linux의 SO_PEERCRED만 지원했습니다). (9) permission_mode=accept-all 설정이 더 이상 디스크에 저장되지 않으며, 세션 범위(session-scoped)로 유지됩니다. (10) 터미널 일회용 비밀번호(one-time password)가 6자에서 32자로 확장되었습니다 (~190 비트의 엔트로피). 총 2347개의 테스트가 모두 통과(green)되었으며, 회귀(regression)는 없습니다. 전체 참조: docs/guides/security.md. - 2026년 5월 12일:
데몬 기반 로드맵 — 9개의 F-1…F-9 항목이 모두 완료되었습니다. RFC 0002의 남은 4개 범위 항목을 종료합니다:
F-4 #2 서브프로세스 러너(subprocess runner)의 notify IPC를 새로운 bridge_supervisor.notify(kind, text) 메일박스(mailbox)에 연결합니다;
F-4 #3 지수 백오프(exponential backoff)와 지터(jitter)를 포함한 on-crash 재시작 정책을 추가하며, 이는 agent.start(restart_policy=…, max_restarts=…, backoff_*)를 통해 설정 가능합니다;
F-6/F-7/F-8 Phase 1 Telegram / Slack / WeChat 폴링 루프를 기능 플래그(feature-flagged)가 적용된 데몬 워커(CHEETAHCLAWS_ENABLE_F6/7/8)로 격상시키며, bridges SQLite 영속성(persistence)과 bridge.{start,stop,list,send,status} RPC를 제공합니다;
F-6 Phase 2 인바운드 리팩토링을 추가합니다 — session.send / session.reply / session.list_recent RPC가 SSE 버스(SSE bus)에 게시되며, REPL 형태의 슈퍼바이저(supervisor)를 슬림한 데몬 기반 워커(daemon_phase2=True)로 대체합니다;
F-9 cheetahclaws serve 하의 4가지 보수적인 예산(budget) 기본값을 변경하고, system.status 및 agent.resume(budget_overrides, name?) RPC를 추가하며, 진정한 러너별 할당량 일시 중지(per-runner quota-pause) 훅을 연결합니다 (일시 중지된 예산 IPC → quota_warn 이벤트 → _resume_event에서 차단 → 재개 IPC가 러너의 차단을 해제함).
감사(Audit)를 통해 새 코드에서 발견된 5개의 실제 버그(WeChat 필드 이름, Slack 커서 시딩, Telegram 롱 폴링(long-poll) 응답성, _unregister 내의 stop()/restart 타이머 레이스 컨디션, 더 광범위한 비밀 정보 삭제(secret redaction))도 수정되었습니다. 전체 테스트 결과: 2347개 통과, 3개 건너뜀 (환경 제한이 있는 라이브 LLM 테스트), 0개 실패. 상세 내용: RFC 0002 + docs/architecture.md §Daemon + docs/news.md. - 2026년 5월 12일:
PR #119에서 어댑터 클래스(adapter class)를 배포했으나 접근할 수 없는 상태로 남겨두었습니다: litellm/

PR #119에 대한 프로바이더(provider) 후속 조치 — litellm을 실제 선택적 의존성(optional dep)으로 만들고, ledger / 스트리밍(streaming)을 수정하며, CLI / Web UI 경로에 연결합니다. litellm

코어 의존성(core deps)에 포함되어 있었으나(설명에는 선택적이라고 되어 있었음), 최상위 providers.PROVIDERS에 항목이 없었습니다.

(따라서 --model litellm/... 명령이 CLI / Web UI를 통해 해결되지 않았습니다.) cost_micro가 0으로 하드코딩되어 있었고, 스트리밍 시 토큰 수(token counts)와 도구 호출(tool_calls)이 누락되었습니다. 후속 브랜치(fix/litellm-provider-followup)는 해당 의존성을 pip install ".[litellm]"로 이동시키고, SDK를 지연 임포트(lazy-imports)하며, 레지스트리 항목과 stream_litellm 제너레이터(generator)를 추가합니다. 또한, litellm.completion_cost를 통해 비용을 계산하되, 누락 시 cost_unknown=True 메타데이터 플래그를 사용하며, stream_chunk_builder(stream_options={"include_usage": True} 포함)를 통해 스트리밍된 청크(chunks)를 재조립합니다. litellm.exceptions.*를 ProviderInvalidRequest와 ProviderUnavailable로 올바르게 매핑하고, 방어적인 도구 호출(tool_call) 파싱을 추가했습니다. 이제 AWS Bedrock (SigV4), Azure (배포 라우팅), Vertex AI (서비스 계정 JWT)에서 사용 가능합니다. 유닛 테스트 17개 추가, E2E 테스트 3개 추가 (CC_LITELLM_E2E=1 설정 시 실행). 전체 테스트 스위트: 2222개 통과, 회귀(regressions) 없음. 상세 내용: docs/news.md.

• 2026년 5월 11일:
  Daemon F-4 스켈레톤(skeleton) — 각 agent_runner는 cc_daemon의 감독(supervision) 하에 서브프로세스(subprocess)로 실행됩니다 (기본값은 off). /agent 러너는 이제 프로세스 내 스레드(in-process thread) 대신 python -m agent_runner --pipe 자식 프로세스가 될 수 있으므로, 하나의 러너에서 발생하는 누수(leak) / 행(hang) / OOM(메모리 부족)이 더 이상 스케줄러나 브릿지(bridges)를 중단시키지 않습니다. 신규 항목: cc_daemon/runner_supervisor.py (생명주기 + 3단계 중지 ≤ 5초 + 충돌 감지), cc_daemon/runner_ipc.py (JsonLineChannel 커널 재내보내기), cc_daemon/agent_methods.py (agent.start / agent.stop / agent.list / agent.status RPC), agent_runner.py에 --pipe 엔트리 포인트 추가. 반복(Iteration) 및 실행(run) 행이 agent_runs / agent_iterations에 기록됩니다 (이전 F-2 테이블은 비어 있었음). POSIX 전용; CHEETAHCLAWS_ENABLE_F4=1 또는 agent_runner_subprocess=true로 토글 가능합니다.

. +27개 테스트, 104/104 통과. 상세 내용: RFC 0002 + docs/news.md. - 2026년 5월 10일 (
v3.05.79):Web Chat UI 세션 관리 기능 (폴더, 드래그 앤 드롭, ChatGPT 스타일의 활성 폴더 컨텍스트, 일괄 선택 및 내보내기, 크기 조절 가능한 사이드바) + headless-bridges 슬래시 핸들러 ( #84 후속 조치: Telegram/Slack/WeChat의 /help/monitor/model/status 명령이 이제 Docker/--web 환경에서 응답함) + stale-session reaper 크래시 수정 + #111 슬래시 중복 수정 + --web --model 지속성(persistence). 상세 내용: docs/news.md. - 2026년 5월 10일:
Web Chat UI 수정 — 슬래시 명령어가 더 이상 두 번 응답하지 않음; 상세 내용: docs/news.md.--web --model X 명령이 실제로 모델을 적용함 (#111). - 2026년 5월 10일:
소규모 컨텍스트 로컬 모델이 대규모 워크로드에서도 생존 — 4단계 수정: 컨텍스트 용량(ctx cap), 자동 팬아웃(auto-fanout), 정체 중단(stagnation-stop), ~/.cheetahclaws/ 하위 출력 경로. 상세 내용: docs/news.md. - 2026년 5월 9일:
상세 내용: docs/news.md.fix/agentic-on-every-model 브랜치 — 모든 모델이 유용한 작업을 생성하도록 개선 + /brainstorm 명령을 실제 적대적 토론(adversarial debate)으로 구현 (9개 커밋, 269개 신규 테스트). - 2026년 5월 8일:
Agent-OS 레이어 (cc_kernel/) v1.0 도달 — 27개의 RFC 배포, 1771개 테스트 통과, 기존 REPL/bridges 경로에서 회귀(regression) 발생 제로. - 2026년 5월 8일:
F-2/F-3 후속 조치 + CI 차단 해제 (feature/fix-f2**). - 2026년 5월 8일 (v3.05.78):**Research lab Phase A — 자율적인 다일(multi-day) 연구; WeChat 스마트 답장 + /draft 반자동 답장; 연구소 파이프라인 전반의 신뢰성 및 UX 강화. - 2026년 5월 7일 (v3.05.77):**MCP HTTP/SSE 전송 + OAuth 2.0 PKCE, .env 로더, ANTHROPIC_ENDPOINT 기업용 프록시 오버라이드, AskUserQuestion UI 개선 (#88, #89) - 2026년 5월 5일:
Telegram 브리지 파일 라운드트립(round-trip) + 채널 간 선택 가능한 권한 프롬프트 (#84) - 2026년 5월 3일:
Research Lab — 샌드박스 실험을 동반한 자율적 멀티 에이전트 논문 작성 + 웹 UI. - 2026년 5월 2일:
데몬(Daemon) 기반 구축 완료 (#80) — cheetahclaws serve 및 cheetahclaws daemon {status, stop, logs, rotate-token} 명령이 실제로 작동함.

• 2026년 5월 2일:
  Docker chat UI 에셋 404 후속 조치 (#73) — 상세 내용: docs/news.md. _WEB_DIR 문제를 importlib.resources.files("web")를 통해 해결함.

따라서 편집 가능(editable) 및 비편집 가능(non-editable) 설치 방식 모두에서 정적 파일(static files)을 찾을 수 있음; web/static/ 하위 트리 전체를 배포할 수 있도록 package-data 범위를 확장함.

• 2026년 4월 30일:
  Docker / 홈 서버(home-server) 지원 (#73)

• 2026년 4월 24일:
  DeepSeek V4 모델 지원, 멀티 모델 프롬프트 적응(multi-model prompt adaptation)

• 2026년 4월 20일 (v3.05.76):
  연구 파이프라인 (Research pipeline) — 학계/기술/금융/사회/웹 전반의 20개 소스 + 교차 플랫폼 어텐션 히트 테이블(cross-platform attention heat table), 출판 트렌드 스파크라인(publication trend sparkline), 주요 인용자 분석(notable-citer analysis), 엔티티 추출(entity extraction), 멀티 쿼리 확장(multi-query expansion), 병렬 비교(side-by-side compare), 저장된 보고서, /monitor를 통한 주간 트렌드 추적, 원클릭 /ssj 마법사 포함. 또한 중국 플랫폼 포함: Zhihu (知乎) · Bilibili (B站) · Weibo (微博) · Rednote (小红书).

• 2026년 4월 18일 (v3.05.75):
  CHEETAHCLAWS_PLUGIN_PATH를 통한 외부 플러그인 탐색 + 더 안전한 의존성 관리(dependency management); OpenAI 호환 제공자(DeepSeek 등)를 위한 도구 이력(tool-history) 무결성 수정; 전체 체크포인트 왕복(checkpoint round-trip)을 포함한 제공자 간 엔드 투 엔드 프롬프트 캐시 토큰 추적.

• 2026년 4월 16일 (v3.05.74):
  Web UI 프로덕션 강화 — 지속성(persistence), 다중 사용자 인증(multi-user auth), 운영 엔드포인트(ops endpoints), JS 모듈 분할, pytest 스위트

더 많은 소식은 여기를 참조하세요.

CheetahClaws: Claude Code를 가볍고 사용하기 쉽게 Python으로 재구현한 것으로, Claude, GPT, Gemini, Kimi, Qwen, Zhipu, DeepSeek, MiniMax 및 Ollama 또는 모든 OpenAI 호환 엔드포인트를 통한 로컬 오픈 소스 모델 등 모든 모델을 지원합니다.

• CheetahClaws를 사용하는 이유
• CheetahClaws vs OpenClaw
• 주요 기능 (Features)
• 지원 모델 (Supported Models)
• 설치 (Installation)
• 사용법: 폐쇄형 소스 API 모델 (Closed-Source API Models)
• 사용법: 오픈 소스 모델 (로컬) (Open-Source Models (Local))
• 모델 이름 형식 (Model Name Format)
• 트레이딩 에이전트 (Trading Agent) (멀티 에이전트 분석, 백테스팅, 메모리)
• Web UI (채팅 인터페이스, 설정, API 엔드포인트)
• 문서 (Documentation) (모든 기능에 대한 가이드)
• 보안 및 환경 변수 (Security & environment variables) (샌드박싱, CSRF, 토큰 처리)
• 기여하기 (Contributing)
• 자주 묻는 질문 (FAQ)
• 인용 (Citation)

코드 리뷰: 느린 Python 함수 프로파일링, 로컬 Ollama로 전환, 수정 사항 적용 — 11배 더 빨라짐 Claude Code는 강력한 프로덕션급 (production-grade) AI 코딩 어시스턴트이지만, 그 소스 코드는 컴파일된 12 MB 크기의 TypeScript/Node.js 번들(~1,300개 파일, ~283K개 라인)입니다. 이는 Anthropic API와 밀접하게 결합되어 있어 수정하기 어렵고, 로컬 모델이나 대체 모델을 대상으로 실행하는 것이 불가능합니다.

CheetahClaws는 필요한 모든 기능은 유지하고 불필요한 기능은 제거하여, 동일한 핵심 루프 (core loop)를 약 40K 라인의 읽기 쉬운 Python으로 재구현했습니다. 더 자세한 분석(CheetahClaws v3.03)은 여기에서 영어 버전 및 중국어 버전으로 확인하세요.

차원 (Dimension)	Claude Code (TypeScript)	CheetahClaws (Python)
언어 (Language)	TypeScript + React/Ink	Python 3.8+
...
UI 품질 (UI quality)— 스트리밍 렌더링 (streaming rendering), 세밀한 차이 시각화 (fine-grained diff visualization) 및 대화 시스템 (dialog systems)을 갖춘 React/Ink 컴포넌트 트리.
도구 범위 (Tool breadth)— RemoteTrigger, EnterWorktree 및 기타 UI 통합 도구를 포함한 44개의 도구.
엔터프라이즈 기능 (Enterprise features)— MDM 관리 구성, 팀 권한 동기화, OAuth, 키체인 저장소 (keychain storage), GrowthBook 기능 플래그 (feature flags).
AI 기반 메모리 추출 (AI-driven memory extraction)— extractMemories 서비스가 명시적인 도구 호출 없이 대화에서 지식을 선제적으로 추출합니다.
프로덕션 신뢰성 (Production reliability)— 단일 배포 가능한 cli.js, 포괄적인 테스트 커버리지, 버전 고정 릴리스.

멀티 프로바이더 (Multi-provider)— --model 또는 /model을 사용하여 Claude, GPT-4o, Gemini 2.5 Pro, DeepSeek, Qwen, MiniMax 또는 로컬 Llama 모델 간에 재컴파일 없이 전환할 수 있습니다.
로컬 모델 지원 (Local model support)— Ollama, LM Studio 또는 vLLM으로 호스팅되는 모든 모델을 사용하여 완전히 오프라인으로 실행할 수 있습니다.
읽기 쉬운 소스 (Readable source)— 전체 에이전트 루프 (agent loop)는 174 라인(agent.py)입니다. 어떤 Python 개발자라도 몇 분 안에 이를 읽고, 포크(fork)하고, 확장할 수 있습니다.
빌드 불필요 (Zero build)— pip install -r requirements.txt만 하면 바로 실행됩니다. 변경 사항은 즉시 적용됩니다.
동적 확장성 (Dynamic extensibility)— register_tool(ToolDef(...))를 사용하여 런타임에 새로운 도구를 등록할 수 있습니다.

, git URL에서 스킬 팩 (skill packs)을 설치하거나, 임의의 MCP 서버를 연결할 수 있습니다.작업 의존성 그래프 (Task dependency graph)— TaskCreate / TaskUpdate는 구조화된 다단계 계획 (structured multi-step planning)을 위해 blocks / blocked_by 엣지 (edges)를 지원합니다 (Claude Code에서는 지원되지 않음).2계층 컨텍스트 압축 (Two-layer context compression)— 규칙 기반 스니핑 (rule-based snip)과 AI 요약 (AI summarization)을 결합하며, preserve_last_n_turns를 통해 설정할 수 있습니다.노트북 편집 (Notebook editing)— NotebookEdit는 커널 (kernel) 없이도 .ipynb JSON 파일을 직접 조작 (셀 교체/삽입/삭제)합니다.LSP 서버 없는 진단 (Diagnostics without LSP server)— GetDiagnostics는 Python의 경우 pyright → mypy → flake8 → py_compile를, 기타 언어의 경우 tsc/shellcheck를 체이닝 (chaining)하며 별도의 설정이 필요 없습니다.오프라인 음성 입력 (Offline voice input)— /voice는 sounddevice / arecord / SoX를 통해 녹음하고, 로컬 faster-whisper로 전사 (transcribe)합니다.