xianyu110/clawbot

Clawdbot完整配置指南：从安装到Claude Code中转

Clawdbot 는 무엇입니까?

Clawdbot 은 오픈소스이며 로컬에서 실행되는 AI 어시스턴트로, 웹 대시보드 또는 Telegram, WhatsApp, Discord 와 같은 인기 있는 메시징 앱을 통해 대규모 언어 모델 백엔드 (Anthropic Claude, OpenAI GPT, Google Gemini 등) 와 대화할 수 있습니다. 모든 대화 데이터는 귀하의 기계에 유지되며, 원격 제공업체로 요청을 리디렉션하는 사용자 정의 "프록시" 서비스를 포함하여, 호환 가능한 API 엔드포인트로 연결할 수 있습니다.

핵심 기능

기능 귀하에게 의미하는 바
다중 플랫폼 채팅 브라우저 UI, 터미널 UI, 또는 Telegram/WhatsApp/Discord 및 기타 12개 이상의 채널의 봇을 통해 상호작용할 수 있습니다.
플러그인 가능한 모델 백엔드 ~/.clawdbot/clawdbot.json 에 제공자 항목을 추가하기만 하면, Claude, GPT‑4o, Gemini 3 Pro 또는 지원되는 OpenAI/Anthropic/Google API를 사용하는 다른 모델 중에서 선택할 수 있습니다.
로컬 데이터 저장 대화, 세션 파일 및 자격 증명은 ~/.clawdbot/ 아래에 저장되며, 제3자 서버로 전송되지 않습니다.
자체 호스팅 게이트웨이 가벼운 Node.js 게이트웨이 (clawdbot gateway) 가 localhost:18789 에서 실행되어 WebSocket 및 HTTP UI를 노출하면서 서비스를 인터넷으로부터 격리합니다.
사용자 정의 보안 게이트웨이는 UI 접근용 토큰을 사용하며, clawdbot security audit 명령어를 통해 위험한 설정을 탐지할 수 있습니다.
CLI/TUI 도구 설정 관리, 서비스 재시작, 로그 보기, clawdbot tui 를 사용해 터미널에서 채팅할 수 있습니다.

누구에게 적합한가요?

  • 클라우드에 코드를 전송하지 않고 개인용 AI 코딩 어시스턴트를 원하는 개발자.
  • 기존 채팅 도구에 연결할 수 있는 공유형 온프레미스 어시스턴트가 필요한 팀.
  • API 키와 대화 기록에 대한 완전한 제어를 원하는 개인정보 보호에 민감한 사용자.

빠른 시작 스냅샷 (README에서)

  1. Node 22 이상 설치 (via nvm).
  2. Clawdbot 설치 – npm install -g clawdbot (또는 원클릭 스크립트 사용).
  3. 온보딩 워즈드 실행 – clawdbot onboard 는 다음을 안내합니다:
    • 보안 면책 조항 수락.
    • Anthropic 모델 선택 및 setup‑token (Claude Max) 또는 API 키 제공.
    • 메시징 채널 추가 (예: Telegram 봇 토큰).
  4. 게이트웨이 시작 – clawdbot gateway restart.
  5. UI 열기 – http://127.0.0.1:18789/ 방문 (토큰을 생성한 경우 ?token=… 추가).
  6. 채팅 시작! 웹 UI 또는 선택한 메신저에서 메시지 전송.

여러 모델로 확장하기 ("프록시" 모드)

README에는 api‑proxy‑gpt, api‑proxy‑claude, api‑proxy‑google 세 개의 제공자를 추가하는 구체적인 JSON 스니펫이 포함되어 있습니다. 각 제공자는 다음을 정의합니다:

  • baseUrl – 지불하는 프록시 엔드포인트.
  • apiKey – 해당 엔드포인트용 비밀 키.
  • api – 사용할 벤더의 요청 형식 (openai‑completions, anthropic‑messages, google‑generative‑ai).
  • models – 각 모델 (ID, 이름, 컨텍스트 창, 토큰 제한 등) 을 설명하는 배열.

~/.clawdbot/clawdbot.json 을 편집한 후, auth‑profiles.json 에도 대응하는 항목을 추가하고 게이트웨이를 재시작해야 변경 사항이 적용됩니다.

일반적인 실수 및 해결책 (요약)

  • Node 버전이 낮음 – Clawdbot 는 Node ≥ 22 를 필요로 합니다. nvm 을 사용해 업그레이드하세요.
  • 환경 변수 무시됨 – 사용자 정의 API URL 은 ANTHROPIC_BASE_URL 가 아닌 JSON 설정 파일에서 설정해야 합니다.
  • models 배열 누락 – 설정 검증기는 models 필드가 없는 제공자를 거부합니다. 아직 모델이 없으면 빈 배열을 추가하세요.
  • Telegram 봇 충돌 – 문제 해결 중에는 채널 비활성화 (clawdbot config set channels.telegram.enabled false) 하세요.
  • User-Agent 필요 – 일부 프록시 서비스는 모델 정의 내부에 User-Agent 헤더를 추가하지 않으면 요청을 거부합니다.
  • 변경 사항 적용 안 됨 – 설정 파일을 편집한 후에는 반드시 clawdbot gateway restart 를 실행하세요.

자주 사용하는 명령어

# 서비스 제어
clawdbot gateway restart          # 설정 변경 적용
clawdbot channels status          # 상태 확인

# 설정
clawdbot configure                # 인터랙티브 에디터
clawdbot config set gateway.mode local
clawdbot config set channels.telegram.enabled false

# 진단 및 로그
clawdbot doctor                   # 자동 검사 실행
clawdbot doctor --fix            # 자동 수정 시도
tail -f ~/.clawdbot/logs/gateway.log

# UI 단축키
clawdbot dashboard                # 브라우저 UI 열기
clawdbot tui                      # 터미널 채팅 UI

파일 위치

~/.clawdbot/
├─ clawdbot.json          # 주 설정
├─ credentials/           # API 키 (Git에 커밋하지 않음)
├─ sessions/              # 대화 기록
├─ logs/
│  ├─ gateway.log
│  └─ gateway.err.log
└─ agents/main/...        # 에이전트별 워크스페이스

보안 최적 실천 (가이드에서)

  • API 키를 버전 관리에 포함하지 마세요.
  • 정기적으로 키를 교체하세요.
  • UI 접근에는 게이트웨이 토큰을 사용하고 주기적으로 변경하세요.
  • VPN/Tailscale를 명시적으로 사용하지 않는 한 게이트웨이를 localhost 에 바인딩하여 실행하세요.
  • tar -czf backup‑$(date +%F).tar.gz ~/.clawdbot/ 로 ~/.clawdbot/ (설정 + 세션)을 백업하세요.

결론

Clawdbot 은 일관된 로컬 저장 설정을 통해 Claude, GPT, Gemini 등의 주요 LLM 제공업체에 연결할 수 있는 완전 기능의 자체 호스팅 AI 어시스턴트 플랫폼입니다. README에는 단계별 설치 방법, 상세한 JSON 기반 모델 프록시 설정, 철저한 문제 해결 가이드가 포함되어 있어, 개인적이고 확장 가능한 AI 채팅 인터페이스를 원하는 개발자에게 실용적인 도구입니다.

관련

  • 프로젝트
    crabwise-ai/crabwalk

    Crabwalk은 WhatsApp, Telegram, Discord 및 Slack에서 OpenClaw AI 에이전트의 활동을 시각화하는 실시간 웹 UI입니다. OpenClaw 게이트웨이에서 WebSocket을 통해 이벤트를 스트리밍하고, 실시간 세션 노드 그래프를 표시하며, 도구 호출을 검사할 수 있고 Docker, CLI 또는 소스 설치 배포를 지원합니다.

  • 프로젝트
    Spr-Aachen/Easy-Voice-Toolkit

    Easy Voice Toolkit은 오픈소스 음성 모델(Whisper, GPT-SoVITS)을 GUI/Colab 워크플로우에 통합하여 오디오 정리, 전사, 음성 변환 데이터셋 구축, 맞춤 음성 모델 학습, 변환 음성 생성을 수행합니다. 즉시 실행 가능한 Windows 휴대용 패키지와 Colab 노트북을 제공하며, 개발자 친화적인 설치 가이드를 포함합니다. 이 프로젝트는 학술용으로만 사용되며 향후 LLM 챗봇 통합 및 Linux 지원을 계획하고 있습니다.

  • 프로젝트
    Aethena-Lab/Z3r0

    Z3r0는 React UI, FastAPI 제어 플레인, LightRAG 검색을 갖춘 다중 에이전트 런타임, 그리고 Docker 기반 사전 환경 실행을 통합한 AI 기반 레드팀 워크벤치입니다. 모든 작업은 변경 불가능한 증거로 기록되며, 재생 가능한 타임라인을 제공하여 승인된 펜테스트를 감사 가능하고 공동 작업이 가능한 환경으로 만듭니다.

  • 프로젝트
    Deng-m1/MaliangAINovalWriter

    Maliang AI Novel Writer (AINoval)는 중국 웹소설 작가가 AI 지원을 받아 장편 소설을 쓸 수 있도록 도와주는 오픈소스 웹 플랫폼입니다. Flutter-Web 기반의 풍부한 텍스트 편집기, 계층적 콘텐츠 관리, AI 기반 개요/장면 생성, 구조화된 세계관 트리, 프롬프트/프리셋 관리, 사용자, 모델, 비용, 콘텐츠 모니터링을 위한 완전한 관리 콘솔을 통합하고 있습니다. 백엔드는 LangChain4j를 사용한 LLM 오케스트레이션을 위한 Spring Boot 3 (Java 21), MongoDB를 통한 스토리지, Chroma를 통한 벡터 임베딩을 사용합니다. 단일 Docker-Compose 파일로 배포 가능하며, 제공된 스크립트로 관리자 계정을 생성합니다. 개인 작가, 작가 팀, 플랫폼 운영자에게 AI 강화된 소설 작성과 견고한 운영 도구가 필요한 분들에게 이상적입니다.