HappyClaw

개요

HappyClaw는 Anthropic의 Claude Code 에이전트(‘Claude Agent SDK’)를 장기 실행 서비스로 실행할 수 있는 자체 호스팅, 다중 사용자 플랫폼입니다. 공식 Claude Code 런타임을 Node.js/TypeScript 서버로 감싸고 웹 UI와 8개의 인스턴트 메시징 채널(Feishu, Telegram, QQ, DingTalk, WeChat, Enterprise WeChat, Discord, WhatsApp)을 통해 에이전트를 노출합니다. 사용자는 에이전트를 만들고 격리된 워크스페이스에 할당하여 코드 실행, 셸 명령 실행, 웹 브라우징 또는 사용자 지정 Skills/MCP 호출을 수행할 수 있습니다.

핵심 기능

영역	제공 내용
에이전트 중심 워크플로우	Claude 에이전트 생성, 편집, 버전 관리, 복원; 사용자 지정 프롬프트, Skills, MCP, 플러그인 첨부.
워크스페이스	격리된 파일 시스템 디렉터리; 호스트 머신(관리자) 또는 비-root Docker 컨테이너(일반 사용자)에서 실행 가능.
다중 채널 액세스	Feishu, Telegram, QQ, DingTalk, WeChat, Enterprise WeChat, Discord, WhatsApp 및 웹 PWA를 위한 통합 메시징.
프로바이더 관리	여러 Anthropic 또는 호환 가능한 Claude 엔드포인트 구성; 로드 밸런싱(라운드 로빈, 가중치, 페일오버), 상태 확인, 세션 고정 라우팅.
스케줄링	Cron 스타일, 고정 간격 또는 일회성 작업으로 에이전트 또는 셸 스크립트 실행; 멱등성 실행 ID와 재시도 가능한 알림.
메모리 및 파일 처리	워크스페이스 범위 메모리 저장소, 버전 관리 파일 편집, CAS 스타일 업데이트, 검색, 터미널 액세스.
사용량 및 청구	에이전트, 워크스페이스, 모델별 토큰 수준 회계; CSV 내보내기, 할당량, 구독 및 사용 코드 지원.
운영 및 보안	RBAC, 초대 전용 등록, 감사 로그, Docker 이미지 관리, 백업/복원, 비밀번호 암호화 저장.
클라이언트 경험	실시간 스트리밍 출력, 도구 추적 시각화, Markdown/Mermaid/KaTeX 렌더링, 반응형 UI 및 PWA 지원.

사용 대상

공개 채팅 API 대신 비공개하고 제어 가능한 Claude Code 환경을 원하는 팀.
내부 채팅 도구에서 트리거할 수 있는 AI 기반 자동화(코드 리뷰, CI 지원, 데이터 추출)를 실행해야 하는 기업.
Claude 에이전트를 실험하면서 실행을 Docker 컨테이너에 격리하고 싶은 개발자.
세분화된 권한 제어, 사용량 추적, 전체 스택을 온프레미스로 호스팅해야 하는 조직.

시작하기(빠른 단계)

클론 및 시작 – git clone https://github.com/riba2534/happyclaw.git && cd happyclaw && make start.
http://localhost:3000에서 웹 UI를 열고 마법사에 따라 관리자 계정을 생성합니다.
설정 → 모델 및 프로바이더에서 Anthropic(또는 호환 가능한) Claude 프로바이더를 추가합니다.
(선택 사항) 설정 → 메시지 채널에서 하나 이상의 IM 채널을 연결합니다.
워크스페이스를 생성하고 호스트(관리자) 또는 컨테이너(일반 사용자) 실행 모드를 선택합니다.
에이전트(Claude Code)를 구축 – 이름, 아바타, 프롬프트를 지정하고 필요한 Skills나 MCP를 첨부합니다.
세션을 열고(또는 채널 연결) 채팅을 시작 – 에이전트는 파일 읽기/쓰기, 셸 명령 실행, 브라우징 등을 수행할 수 있습니다.

아키텍처 개요

Web/PWA  →  HappyClaw Node 서비스 (Hono, WebSocket, SQLite)
   │                │
   ├─ Auth/RBAC    ├─ Router & Scheduler
   │                │
   └─ Provider pool (Claude endpoints)
        │
        ├─ Host Runner (direct CLI)
        └─ Docker Agent Runner (isolated containers)
                │
                └─ Claude Agent SDK + Claude Code CLI

핵심 서비스는 인증, 메시지 라우팅, 작업 스케줄링, 영속성을 처리합니다. 에이전트 실행은 호스트 머신(관리자가 승인한 디렉터리) 또는 잠긴 버전의 Claude Code 런타임을 실행하는 Docker 컨테이너에 위임됩니다.

라이선스 및 커뮤니티

라이선스: MIT(LICENSE 참조).
스타: ⭐ — 리포지토리에 GitHub 스타 배지가 표시됩니다.
기여: 지침은 README의 기여 섹션에 있습니다; 이슈 또는 풀 리퀘스트를 환영합니다.
문서: API 참조, 런타임 아키텍처, ACL 매트릭스, 배포 가이드는 docs/ 폴더 및 공식 사이트 https://happyclaw.cc/에 제공됩니다.

위 모든 정보는 프로젝트의 README에서 직접 가져온 것입니다. 추가 기능은 추론하지 않았습니다.

riba2534/happyclaw