NanoClaw with Venice | Venice API Docs

NanoClaw는 WhatsApp과 Telegram에서 동작하는 경량 셀프 호스팅 AI 비서입니다. 이 포크는 Venice AI 지원을 추가해, Anthropic 구독 없이도 모든 것이 프라이빗하게 동작합니다.

토큰 단위 결제

구독 없이 사용한 만큼만 지불

프라이빗 추론

Venice 서버의 데이터 보존 제로

Docker 격리

각 채팅이 자체 보안 컨테이너에서 실행

왜 Venice AI인가요?

Venice는 프라이버시 우선 AI 플랫폼입니다. Venice는 서버에 어떤 prompt나 응답도 저장하거나 로그하지 않습니다 — 대화는 사용자의 기기에만 존재합니다. 요청은 Venice의 프록시를 통해 탈중앙화 GPU 공급자로 종단간 암호화되어 전송되며, 데이터 보존은 제로입니다. 즉, AI 비서 대화가 Venice조차 알 수 없도록 프라이빗하게 유지됩니다. Venice는 하나의 API를 통해 프런티어 모델(Claude Opus, Claude Sonnet)에 익명화된 접근을, 오픈소스 모델(GLM, Qwen)에 완전 프라이빗 접근을 제공합니다 — 언제든지 전환할 수 있습니다.

	Venice AI	기존 AI 공급자
데이터 보존	없음 — 로그 제로	있음
Prompt 프라이버시	암호화, 절대 저장 안 함	공급자 서버에 저장
오픈소스 모델	예 (GLM, Qwen 등)	아니오
프런티어 모델	Claude, GPT 등 — 익명으로	직접 구독을 통해서만
가격	토큰 단위 결제, 구독 없음. 또는 DIEM을 스테이킹해 매일 갱신되는 크레딧 사용	월 $20–200 구독 또는 토큰 단위 API
비검열 추론	예 (오픈소스 모델)	아니오

왜 NanoClaw인가요?

NanoClaw는 OpenClaw 같은 더 큰 플랫폼의 깔끔하고 미니멀한 대안입니다. 한 명이 한 개의 봇을 운영하도록 설계되었습니다.

	NanoClaw (Venice)	OpenClaw
코드베이스	약 2,000줄, 적은 파일 수	약 500,000줄, 53개 설정 파일
의존성	약 15개 패키지	70개 이상 패키지
보안 모델	OS 수준 Docker 컨테이너 격리	애플리케이션 수준 allowlist 및 페어링 코드
그룹별 격리	각 그룹이 고유 컨테이너, 파일시스템, 메모리 보유	공유 프로세스, 공유 메모리
설정	하나의 마법사(`/setup`), 약 10분	다단계 수동 설정
AI 공급자	Venice AI (프라이빗, 구독 불필요)	Anthropic (API 키 또는 구독 필요)
커스터마이즈	코드 직접 편집 — 충분히 작아 가독성 좋음	설정 파일과 플러그인
대상 사용자	한 명, 한 봇	멀티 사용자 플랫폼

무엇을 얻나요

Telegram 및/또는 WhatsApp에서 동작하는 개인 AI 비서
Venice AI 구동 — Anthropic 계정 불필요
봇이 격리된 Docker 컨테이너에서 실행됨(샌드박스, 시스템 접근 불가)
모델 전환 — 언제든지 봇에게 “switch to zai-org-glm-5” 또는 “use opus” 라고 요청
예약 작업 — 알림, 반복 작업 설정
웹 검색 및 브라우징 내장
Telegram 메시지의 마크다운 포매팅

사전 요구사항

Node.js 20+

node --version으로 확인

Docker

설치 후 한 번 실행해 동작 상태로 둠

Claude Code CLI

claude --version으로 확인

Venice API 키

Venice 계정에서 생성

Telegram의 경우(첫 사용자에게 권장):

Telegram을 열고 @BotFather를 검색
/newbot을 보내고 안내를 따라가기
BotFather가 준 토큰을 저장(123456789:ABCdef... 형태)

WhatsApp의 경우 — 본인 번호가 아닌 가상 번호를 사용하세요:NanoClaw는 WhatsApp 번호의 연결된 디바이스로 접속합니다. 즉, 에이전트가 들어오고 나가는 모든 메시지 — 개인 대화, 그룹 채팅, 사진 등 모든 것을 볼 수 있습니다. 폰은 정상적으로 동작하지만 봇은 전체 WhatsApp 계정에 대한 가시성을 가집니다.가상 전화번호를 사용하세요. 다음 앱들은 봇 전용으로 쓸 수 있는 두 번째 번호를 제공합니다:

App	Price	Notes
Hushed	월 약 $5	안정적, WhatsApp 인증에도 잘 동작
Burner	월 약 $5	Hushed와 유사, 일회용 번호
Google Voice	무료	미국 전용, WhatsApp 인증이 안 될 수 있음

설정 방법:

위 앱 중 하나에서 가상 번호를 받기
해당 가상 번호로 두 번째 기기(구형 폰, 태블릿, 에뮬레이터)에 WhatsApp 설치
NanoClaw 설정 중 본인 폰이 아니라 그 두 번째 기기로 QR 코드 스캔

설정

설정은 약 10분 걸립니다. 터미널 창 하나만 있으면 됩니다.

클론 및 설치

터미널을 열고 실행하세요:

git clone https://github.com/lorenzovenice/nanoclaw-venice.git
cd nanoclaw-venice
npm install

npm install이 에러 없이 완료될 때까지 기다리세요.

Venice로 Claude Code 실행

your-key를 Venice API 키로 바꾸고 실행하세요:

VENICE_API_KEY=your-key npm run venice

이 명령은 Venice 프록시를 시작하고 그것을 통해 Claude Code를 한 번에 실행합니다.

Claude Code는 설정 비용을 낮게 유지하기 위해 기본 모델로 GLM 5(zai-org-glm-5)를 사용합니다. 설정이 끝난 뒤 Claude Code 안에서 /model을 입력해 최고 성능을 위해 claude-sonnet-4-6 또는 claude-opus-4-6으로 전환하세요.

“Do you want to use this API key?”라는 질문이 나오면 Yes를 선택하세요.

설정 마법사 실행

Claude Code 터미널에 다음을 입력하세요:

/setup

마법사가 다음 과정을 안내합니다:

부트스트랩 — Node.js와 의존성 확인
Venice API 키 — 키를 검증하고 저장
채널 선택 — WhatsApp, Telegram, 또는 둘 다 선택
컨테이너 빌드 — Docker 컨테이너 빌드(처음에는 몇 분 소요)
WhatsApp 인증 — 폰으로 QR 코드 스캔(해당 시)
Telegram 설정 — 봇에 메시지를 보내 채팅을 감지하게 함
트리거 단어 — 봇을 활성화하는 prefix(기본값: @Andy)
마운트 디렉터리 — 지금은 “No” 선택(나중에 파일 접근 추가 가능)
서비스 시작 — NanoClaw와 Venice 프록시가 백그라운드 서비스로 시작

설정 마법사는 두 개의 백그라운드 서비스를 설치합니다:

NanoClaw — 봇 자체
Venice 프록시 — Claude Code와 Venice AI 사이를 번역하는 작은 로컬 서버(localhost:4001)

둘 다 부팅 시 자동 시작되며, 충돌하면 스스로 재시작합니다.

마법사가 단계 사이에서 멈춘다면 “continue” 또는 “next step”이라고 입력해 다음 단계로 넘기세요.

채팅 시작

설정이 완료되면 채팅(Telegram 또는 WhatsApp)을 열고 다음을 보내세요:

@Andy hello, are you there?

봇은 몇 초 안에 응답해야 합니다. 메인 채널에서는 @Andy prefix 없이도 평소처럼 입력할 수 있습니다.이제 터미널 창을 닫아도 됩니다. 모든 것이 백그라운드 서비스로 실행되며 컴퓨터 부팅 시 자동으로 시작됩니다.

동작 방식

NanoClaw에는 두 개의 레이어가 있습니다:

Layer	What It Does
Claude Code CLI	설정, 디버깅, 커스터마이즈를 위한 관리 도구
봇(The Bot)	채팅 안의 AI, 격리된 Docker 컨테이너에서 실행

언제든지 Claude Code를 열려면:

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

이를 사용해 /setup, /debug, /customize를 실행하거나 봇의 동작을 변경하세요.

모델

Context	Default Model	How to Switch
봇(채팅 내)	`claude-sonnet-4-6`	봇에게 “switch to opus” 또는 “use zai-org-glm-5”라고 말함
Claude Code CLI	`zai-org-glm-5` (GLM 5)	Claude Code에서 `/model` 또는 `claude --model <name>` 사용

CLI는 설정 비용을 낮게 유지하기 위해 기본값으로 GLM 5를 사용합니다. 설정 후 최고 성능을 위해 claude-sonnet-4-6 또는 claude-opus-4-6으로 전환하세요.

사용 가능한 모든 Venice 모델은 모델 카탈로그를 참고하세요.

문제 해결

프록시가 실행되지 않습니다

Venice 프록시는 백그라운드 서비스로 실행되며 자동 재시작합니다. 동작하지 않는다면:macOS:

# 실행 중인지 확인
launchctl list | grep venice-proxy

# 재시작
launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

# 로그 확인
tail -f ~/nanoclaw-venice/logs/venice-proxy.log

Linux:

# 실행 중인지 확인
systemctl --user status nanoclaw-venice-proxy

# 재시작
systemctl --user restart nanoclaw-venice-proxy

# 로그 확인
tail -f ~/nanoclaw-venice/logs/venice-proxy.log

Claude Code가 Venice 프록시에 연결할 수 없다는 의미입니다.

프록시가 실행 중인지 확인. 위 문제 해결 단계를 참고하세요.
올바른 폴더에 있는지 확인. 항상 먼저 cd nanoclaw-venice를 실행하세요.

새로 시작: 모든 터미널을 닫고 다음을 실행하세요:

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

모델 에러('model does not exist')

프록시와 봇을 재시작하세요:macOS:

# 프록시 재시작
launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

# 봇 재시작
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Linux:

# 프록시 재시작
systemctl --user restart nanoclaw-venice-proxy

# 봇 재시작
systemctl --user restart nanoclaw

사용 가능한 모델은 모델 카탈로그에서 확인하세요.

봇이 메시지에 응답하지 않습니다

다음 순서대로 진행하세요:

트리거 단어 확인. 올바른 prefix(예: @Andy hello)를 사용하는지 확인.
Docker 실행 확인. docker info를 실행, 에러가 나면 Docker Desktop을 여세요.
프록시 실행 확인. 위 “프록시가 실행되지 않습니다”를 참고.
로그 확인: 프로젝트 폴더에서 tail -f logs/nanoclaw.log.
컨테이너 로그 확인. nanoclaw-venice/groups/main/logs/ 폴더를 열고 container-로 시작하는 가장 최근 파일을 여세요.
모두 재시작: 프록시와 봇을 모두 재시작(위 참고).

설정 중 컨테이너 빌드 실패

Docker Desktop이 열려 동작 중인지 확인하세요. Docker가 완전히 시작되도록 10초 정도 기다린 뒤 마법사에 continue라고 입력해 재시도하세요.

WhatsApp 연결 끊김

WhatsApp 세션이 만료될 수 있습니다. 재연결하려면:

cd nanoclaw-venice
npm run auth

WhatsApp으로 QR 코드를 스캔하고(Settings → Linked Devices → Link a Device), 봇을 재시작하세요:

macOS: launchctl kickstart -k gui/$(id -u)/com.nanoclaw
Linux: systemctl --user restart nanoclaw

고급

봇에 컴퓨터의 파일 접근 권한 주기

기본적으로 봇은 컴퓨터로부터 완전히 차단되어 있어 자체 메모리와 대화 기록만 볼 수 있습니다.

설정 중: 디렉터리 접근을 물을 때 “Yes” 선택
설정 후: Claude Code에서 /customize 실행

봇 수동 시작/정지

NanoClaw는 부팅 시 자동 시작되는 두 개의 백그라운드 서비스로 실행됩니다.macOS:

Action	Command
봇 시작	`launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`
봇 정지	`launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`
봇 재시작	`launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
프록시 시작	`launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`
프록시 정지	`launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`
프록시 재시작	`launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`

Linux:

Action	Command
봇 시작	`systemctl --user start nanoclaw`
봇 정지	`systemctl --user stop nanoclaw`
봇 재시작	`systemctl --user restart nanoclaw`
프록시 시작	`systemctl --user start nanoclaw-venice-proxy`
프록시 정지	`systemctl --user stop nanoclaw-venice-proxy`
프록시 재시작	`systemctl --user restart nanoclaw-venice-proxy`

봇 없이 Venice를 통한 Claude Code 사용

Venice로 Claude Code만 쓰고 WhatsApp/Telegram이 필요 없다면 프록시 서비스가 실행되어 있어야 합니다. 이미 /setup을 실행했다면 백그라운드 서비스로 실행 중입니다.

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

팁: ~/.zshrc(또는 ~/.bashrc)에 다음을 추가하면 어떤 터미널에서든 Venice로 빠르게 전환할 수 있습니다:

alias venice='export ANTHROPIC_BASE_URL=http://localhost:4001 && export ANTHROPIC_API_KEY=venice-proxy && echo "Using Venice API"'
alias anthropic='unset ANTHROPIC_BASE_URL && unset ANTHROPIC_API_KEY && echo "Using Anthropic API"'

claude 실행 전에 어떤 터미널에서든 venice를 입력하면 Venice를 사용하고, anthropic을 입력하면 Anthropic으로 되돌아갑니다.

여러 봇 실행

같은 머신에서 여러 NanoClaw 봇을 실행할 수 있습니다(예: 개인용 1개, 팀용 1개). 다른 폴더에 레포를 클론하고 다시 설정을 실행하면 됩니다. 참고: 같은 Docker 이미지를 공유하므로 하나를 재빌드하면 모두에게 영향이 갑니다.

개발자 명령

NanoClaw 코드를 수정하고 싶은 사람을 위한 명령:

npm run dev          # 핫 리로드와 함께 프록시 + NanoClaw 시작
npm run proxy        # Venice 프록시만 시작
npm run build        # TypeScript 컴파일
npm test             # 테스트 실행
./container/build.sh # 에이전트 컨테이너 재빌드

아키텍처

You (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   Docker Container (isolated sandbox)
        ↓
   Venice Proxy (localhost:4001)
        ↓
   api.venice.ai (private inference)

File	Purpose
`proxy/venice-proxy.ts`	Anthropic 포맷을 Venice를 위한 OpenAI 포맷으로 변환
`src/index.ts`	메인 오케스트레이터 — 메시지 루프, 에이전트 호출
`src/channels/whatsapp.ts`	baileys를 통한 WhatsApp 연결
`src/channels/telegram.ts`	grammy를 통한 Telegram 봇
`src/container-runner.ts`	격리된 에이전트 컨테이너 spawn

FAQ

왜 프록시가 필요한가요?

Claude Agent SDK는 Anthropic의 메시지 포맷을 사용합니다. Venice는 OpenAI 포맷을 사용합니다. 프록시는 둘 사이를 번역해, SDK를 수정하지 않고도 모든 것이 동작하게 합니다.

오픈소스 모델을 쓸 수 있나요?

예. Venice는 다양한 모델을 호스팅합니다. 봇에게 “switch to zai-org-glm-5”나 다른 Venice 모델 ID를 말하면 됩니다. 모델 카탈로그 참고.

안전한가요?

에이전트는 실제 OS 수준 격리를 갖춘 Docker 컨테이너에서 실행됩니다. Venice API 키는 stdin을 통해 전달되며 컨테이너 내부 디스크에 절대 기록되지 않습니다. 각 그룹은 자체 격리 환경을 가집니다.

Anthropic 구독이 필요한가요?

아니오. 모든 것이 Venice AI를 통해 동작합니다. Venice API 키만 있으면 됩니다.

서버에서도 쓸 수 있나요?

예. Docker가 설치된 모든 Linux 머신에서 동작합니다. 부팅 시 자동 시작은 systemd 서비스를 사용하세요.

리소스

NanoClaw Venice 레포

소스 코드와 전체 README

원본 NanoClaw

qwibitai의 upstream 프로젝트

Venice 모델 카탈로그

사용 가능한 모델 둘러보기

Venice 프라이버시

Venice가 데이터를 보호하는 방법

Guides

Getting Started

Text & Chat

Image & Video

Agents & Integrations

Agent Tooling

Coding Tools

SDKs & Frameworks

Projects

NanoClaw

토큰 단위 결제

프라이빗 추론

Docker 격리

왜 Venice AI인가요?

왜 NanoClaw인가요?

무엇을 얻나요

사전 요구사항

Node.js 20+

Docker

Claude Code CLI

Venice API 키

설정

동작 방식

모델

문제 해결

고급

아키텍처

FAQ

리소스

NanoClaw Venice 레포

원본 NanoClaw

Venice 모델 카탈로그

Venice 프라이버시

토큰 단위 결제

프라이빗 추론

Docker 격리

​왜 Venice AI인가요?

​왜 NanoClaw인가요?

​무엇을 얻나요

​사전 요구사항

Node.js 20+

Docker

Claude Code CLI

Venice API 키

​설정

​동작 방식

​모델

​문제 해결

​고급

​아키텍처

​FAQ

​리소스

NanoClaw Venice 레포

원본 NanoClaw

Venice 모델 카탈로그

Venice 프라이버시

왜 Venice AI인가요?

왜 NanoClaw인가요?

무엇을 얻나요

사전 요구사항

설정

동작 방식

모델

문제 해결

고급

아키텍처

FAQ

리소스