> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NanoClaw

> WhatsApp과 Telegram용 경량 개인 AI 비서인 NanoClaw를 Venice에 배포해 비공개·무검열 채팅과 미디어 생성을 활용하세요.

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

<CardGroup cols={3}>
  <Card title="토큰 단위 결제" icon="coins">
    구독 없이 사용한 만큼만 지불
  </Card>

  <Card title="프라이빗 추론" icon="shield-halved">
    Venice 서버의 데이터 보존 제로
  </Card>

  <Card title="Docker 격리" icon="cube">
    각 채팅이 자체 보안 컨테이너에서 실행
  </Card>
</CardGroup>

***

## 왜 Venice AI인가요?

[Venice](https://venice.ai)는 프라이버시 우선 AI 플랫폼입니다. Venice는 [서버에 어떤 prompt나 응답도 저장하거나 로그하지 않습니다](https://venice.ai/privacy) — 대화는 사용자의 기기에만 존재합니다. 요청은 Venice의 프록시를 통해 탈중앙화 GPU 공급자로 종단간 암호화되어 전송되며, 데이터 보존은 제로입니다. 즉, AI 비서 대화가 Venice조차 알 수 없도록 프라이빗하게 유지됩니다.

Venice는 하나의 API를 통해 프런티어 모델(Claude Opus, Claude Sonnet)에 익명화된 접근을, 오픈소스 모델(GLM, Qwen)에 완전 프라이빗 접근을 제공합니다 — 언제든지 전환할 수 있습니다.

|                  | **Venice AI**                                                               | **기존 AI 공급자**              |
| ---------------- | --------------------------------------------------------------------------- | -------------------------- |
| **데이터 보존**       | 없음 — 로그 제로                                                                  | 있음                         |
| **Prompt 프라이버시** | 암호화, 절대 저장 안 함                                                              | 공급자 서버에 저장                 |
| **오픈소스 모델**      | 예 (GLM, Qwen 등)                                                             | 아니오                        |
| **프런티어 모델**      | Claude, GPT 등 — 익명으로                                                        | 직접 구독을 통해서만                |
| **가격**           | 토큰 단위 결제, 구독 없음. 또는 [DIEM](https://venice.ai/lp/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 메시지의 **마크다운 포매팅**

***

## 사전 요구사항

<CardGroup cols={2}>
  <Card title="Node.js 20+" icon="node-js" href="https://nodejs.org/">
    `node --version`으로 확인
  </Card>

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    설치 후 한 번 실행해 동작 상태로 둠
  </Card>

  <Card title="Claude Code CLI" icon="terminal" href="https://claude.ai/download">
    `claude --version`으로 확인
  </Card>

  <Card title="Venice API 키" icon="key" href="https://venice.ai/settings/api">
    Venice 계정에서 생성
  </Card>
</CardGroup>

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

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

<Warning>
  **WhatsApp의 경우 — 본인 번호가 아닌 가상 번호를 사용하세요:**

  NanoClaw는 WhatsApp 번호의 연결된 디바이스로 접속합니다. 즉, **에이전트가 들어오고 나가는 모든 메시지** — 개인 대화, 그룹 채팅, 사진 등 모든 것을 볼 수 있습니다. 폰은 정상적으로 동작하지만 봇은 전체 WhatsApp 계정에 대한 가시성을 가집니다.

  **가상 전화번호를 사용하세요.** 다음 앱들은 봇 전용으로 쓸 수 있는 두 번째 번호를 제공합니다:

  | App                                      | Price   | Notes                        |
  | ---------------------------------------- | ------- | ---------------------------- |
  | [Hushed](https://hushed.com)             | 월 약 \$5 | 안정적, WhatsApp 인증에도 잘 동작      |
  | [Burner](https://www.burnerapp.com)      | 월 약 \$5 | Hushed와 유사, 일회용 번호           |
  | [Google Voice](https://voice.google.com) | 무료      | 미국 전용, WhatsApp 인증이 안 될 수 있음 |

  **설정 방법:**

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

***

## 설정

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

<Steps>
  <Step title="클론 및 설치">
    터미널을 열고 실행하세요:

    ```bash theme={"system"}
    git clone https://github.com/lorenzovenice/nanoclaw-venice.git
    cd nanoclaw-venice
    npm install
    ```

    `npm install`이 에러 없이 완료될 때까지 기다리세요.
  </Step>

  <Step title="Venice로 Claude Code 실행">
    `your-key`를 Venice API 키로 바꾸고 실행하세요:

    ```bash theme={"system"}
    VENICE_API_KEY=your-key npm run venice
    ```

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

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

    "Do you want to use this API key?"라는 질문이 나오면 **Yes**를 선택하세요.
  </Step>

  <Step title="설정 마법사 실행">
    Claude Code 터미널에 다음을 입력하세요:

    ```
    /setup
    ```

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

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

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

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

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

    <Note>
      마법사가 단계 사이에서 멈춘다면 "continue" 또는 "next step"이라고 입력해 다음 단계로 넘기세요.
    </Note>
  </Step>

  <Step title="채팅 시작">
    설정이 완료되면 채팅(Telegram 또는 WhatsApp)을 열고 다음을 보내세요:

    ```
    @Andy hello, are you there?
    ```

    봇은 몇 초 안에 응답해야 합니다. 메인 채널에서는 `@Andy` prefix 없이도 평소처럼 입력할 수 있습니다.

    **이제 터미널 창을 닫아도 됩니다.** 모든 것이 백그라운드 서비스로 실행되며 컴퓨터 부팅 시 자동으로 시작됩니다.
  </Step>
</Steps>

***

## 동작 방식

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

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

언제든지 Claude Code를 열려면:

```bash theme={"system"}
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>` 사용 |

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

사용 가능한 모든 Venice 모델은 [모델 카탈로그](/models/text)를 참고하세요.

***

## 문제 해결

<AccordionGroup>
  <Accordion title="프록시가 실행되지 않습니다">
    Venice 프록시는 백그라운드 서비스로 실행되며 자동 재시작합니다. 동작하지 않는다면:

    **macOS:**

    ```bash theme={"system"}
    # 실행 중인지 확인
    launchctl list | grep venice-proxy

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

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

    **Linux:**

    ```bash theme={"system"}
    # 실행 중인지 확인
    systemctl --user status nanoclaw-venice-proxy

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

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

  <Accordion title="Claude Code에 403 에러 또는 'Please run /login'이 표시됩니다">
    Claude Code가 Venice 프록시에 연결할 수 없다는 의미입니다.

    1. **프록시가 실행 중인지 확인.** 위 문제 해결 단계를 참고하세요.
    2. **올바른 폴더에 있는지 확인.** 항상 먼저 `cd nanoclaw-venice`를 실행하세요.
    3. **새로 시작:** 모든 터미널을 닫고 다음을 실행하세요:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="모델 에러('model does not exist')">
    프록시와 봇을 재시작하세요:

    **macOS:**

    ```bash theme={"system"}
    # 프록시 재시작
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

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

    **Linux:**

    ```bash theme={"system"}
    # 프록시 재시작
    systemctl --user restart nanoclaw-venice-proxy

    # 봇 재시작
    systemctl --user restart nanoclaw
    ```

    사용 가능한 모델은 [모델 카탈로그](/models/text)에서 확인하세요.
  </Accordion>

  <Accordion title="봇이 메시지에 응답하지 않습니다">
    다음 순서대로 진행하세요:

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

  <Accordion title="설정 중 컨테이너 빌드 실패">
    Docker Desktop이 열려 동작 중인지 확인하세요. Docker가 완전히 시작되도록 10초 정도 기다린 뒤 마법사에 `continue`라고 입력해 재시도하세요.
  </Accordion>

  <Accordion title="WhatsApp 연결 끊김">
    WhatsApp 세션이 만료될 수 있습니다. 재연결하려면:

    ```bash theme={"system"}
    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`
  </Accordion>
</AccordionGroup>

***

## 고급

<AccordionGroup>
  <Accordion title="봇에 컴퓨터의 파일 접근 권한 주기">
    기본적으로 봇은 컴퓨터로부터 완전히 차단되어 있어 자체 메모리와 대화 기록만 볼 수 있습니다.

    * **설정 중:** 디렉터리 접근을 물을 때 "Yes" 선택
    * **설정 후:** Claude Code에서 `/customize` 실행
  </Accordion>

  <Accordion title="봇 수동 시작/정지">
    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` |
  </Accordion>

  <Accordion title="봇 없이 Venice를 통한 Claude Code 사용">
    Venice로 Claude Code만 쓰고 WhatsApp/Telegram이 필요 없다면 프록시 서비스가 실행되어 있어야 합니다. 이미 `/setup`을 실행했다면 백그라운드 서비스로 실행 중입니다.

    ```bash theme={"system"}
    cd nanoclaw-venice
    ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
    ```

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

    ```bash theme={"system"}
    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으로 되돌아갑니다.
  </Accordion>

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

  <Accordion title="개발자 명령">
    NanoClaw 코드를 수정하고 싶은 사람을 위한 명령:

    ```bash theme={"system"}
    npm run dev          # 핫 리로드와 함께 프록시 + NanoClaw 시작
    npm run proxy        # Venice 프록시만 시작
    npm run build        # TypeScript 컴파일
    npm test             # 테스트 실행
    ./container/build.sh # 에이전트 컨테이너 재빌드
    ```
  </Accordion>
</AccordionGroup>

***

## 아키텍처

```
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

<AccordionGroup>
  <Accordion title="왜 프록시가 필요한가요?">
    Claude Agent SDK는 Anthropic의 메시지 포맷을 사용합니다. Venice는 OpenAI 포맷을 사용합니다. 프록시는 둘 사이를 번역해, SDK를 수정하지 않고도 모든 것이 동작하게 합니다.
  </Accordion>

  <Accordion title="오픈소스 모델을 쓸 수 있나요?">
    예. Venice는 다양한 모델을 호스팅합니다. 봇에게 "switch to zai-org-glm-5"나 다른 Venice 모델 ID를 말하면 됩니다. [모델 카탈로그](/models/text) 참고.
  </Accordion>

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

  <Accordion title="Anthropic 구독이 필요한가요?">
    아니오. 모든 것이 Venice AI를 통해 동작합니다. Venice API 키만 있으면 됩니다.
  </Accordion>

  <Accordion title="서버에서도 쓸 수 있나요?">
    예. Docker가 설치된 모든 Linux 머신에서 동작합니다. 부팅 시 자동 시작은 systemd 서비스를 사용하세요.
  </Accordion>
</AccordionGroup>

***

## 리소스

<CardGroup cols={2}>
  <Card title="NanoClaw Venice 레포" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    소스 코드와 전체 README
  </Card>

  <Card title="원본 NanoClaw" icon="github" href="https://github.com/qwibitai/nanoclaw">
    qwibitai의 upstream 프로젝트
  </Card>

  <Card title="Venice 모델 카탈로그" icon="list" href="/models/text">
    사용 가능한 모델 둘러보기
  </Card>

  <Card title="Venice 프라이버시" icon="shield-halved" href="/overview/privacy">
    Venice가 데이터를 보호하는 방법
  </Card>
</CardGroup>