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

> 在 Venice 上部署 NanoClaw —— 一款面向 WhatsApp 和 Telegram 的轻量级个人 AI 助手，实现私有、无审查的聊天和媒体生成。

[NanoClaw](https://github.com/qwibitai/nanoclaw) 是一个轻量级的自托管 AI 助手，运行在 WhatsApp 和 Telegram 上。这个 fork 增加了 Venice AI 支持，使一切都可以私密运行，无需 Anthropic 订阅。

<CardGroup cols={3}>
  <Card title="按 token 付费" icon="coins">
    无订阅。仅按使用量付费
  </Card>

  <Card title="私密推理" icon="shield-halved">
    Venice 服务器零数据保留
  </Card>

  <Card title="Docker 隔离" icon="cube">
    每个聊天都运行在自己的安全容器中
  </Card>
</CardGroup>

***

## 为什么选择 Venice AI？

[Venice](https://venice.ai) 是一个隐私优先的 AI 平台。他们[不存储或记录任何 prompt 或响应](https://venice.ai/privacy) 在其服务器上——您的对话仅存在于您的设备上。请求通过其代理端到端加密到去中心化 GPU 提供商，零数据保留。这意味着您的 AI 助手对话保持私密，即使对 Venice 自身也是如此。

Venice 通过单个 API 提供前沿模型（Claude Opus、Claude Sonnet）的匿名化访问以及开源模型（GLM、Qwen）的完全私密访问——可随时在它们之间切换。

|               | **Venice AI**                                                       | **传统 AI 提供商**                 |
| ------------- | ------------------------------------------------------------------- | ----------------------------- |
| **数据保留**      | 无——零日志                                                              | 是                             |
| **Prompt 隐私** | 加密，永不存储                                                             | 存储在提供商服务器上                    |
| **开源模型**      | 是（GLM、Qwen 等）                                                       | 否                             |
| **前沿模型**      | Claude、GPT 等——匿名化                                                   | 仅通过直接订阅                       |
| **定价**        | 按 token 付费，无订阅。或质押 [DIEM](https://venice.ai/lp/diem) 获取每日刷新的 credit | 每月 \$20–200 订阅或按 token 付费 API |
| **无审查推理**     | 是（开源模型）                                                             | 否                             |

***

## 为什么选择 NanoClaw？

NanoClaw 是 OpenClaw 等大型平台的简洁、最小化替代方案。它专为一个人运行一个机器人而设计。

|            | **NanoClaw（Venice）**   | **OpenClaw**            |
| ---------- | ---------------------- | ----------------------- |
| **代码库**    | \~2,000 行，少量文件         | \~500,000 行，53 个配置文件    |
| **依赖**     | \~15 个包                | 70+ 个包                  |
| **安全模型**   | 操作系统级 Docker 容器隔离      | 应用级允许列表和配对码             |
| **每组隔离**   | 每个群组都有自己的容器、文件系统和内存    | 共享进程，共享内存               |
| **设置**     | 一个向导（`/setup`），约 10 分钟 | 手动多步骤配置                 |
| **AI 提供商** | Venice AI（私密，无订阅）      | Anthropic（需要 API 密钥或订阅） |
| **定制**     | 直接编辑代码——它足够小可以阅读       | 配置文件和插件                 |
| **目标用户**   | 一人一机器人                 | 多用户平台                   |

***

## 您能得到什么

* 在 **Telegram** 和/或 **WhatsApp** 上的个人 AI 助手
* 由 **Venice AI** 提供动力——无需 Anthropic 账户
* 机器人运行在**隔离的 Docker 容器**中（沙盒化，无法访问您的系统）
* **模型切换**——告诉机器人"切换到 zai-org-glm-5"或"使用 opus"
* **计划任务**——设置提醒、循环任务
* **网页搜索和浏览**内置
* Telegram 消息中的 **Markdown 格式**

***

## 前置条件

<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 给您的 token（类似 `123456789:ABCdef...`）

<Warning>
  **WhatsApp——使用虚拟号码，而不是您的个人号码：**

  NanoClaw 作为您 WhatsApp 号码的关联设备连接。这意味着 **agent 可以查看所有进出的消息**——您所有的个人对话、群聊、照片、所有内容。您的手机仍然正常工作，但机器人对您的整个 WhatsApp 账户具有完全的可见性。

  **请改用虚拟电话号码。** 这些应用为您提供一个可以完全专用于机器人的第二号码：

  | 应用                                       | 价格      | 备注                            |
  | ---------------------------------------- | ------- | ----------------------------- |
  | [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 设置期间，使用该第二台设备扫描二维码——不是您的个人手机
</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. **Bootstrap** — 检查 Node.js 和依赖项
    2. **Venice API 密钥** — 验证并保存您的密钥
    3. **通道选择** — 选择 WhatsApp、Telegram 或两者
    4. **构建容器** — 构建 Docker 容器（首次需要几分钟）
    5. **WhatsApp 认证** — 用您的手机扫描二维码（如适用）
    6. **Telegram 设置** — 向您的机器人发送消息以便其检测到您的聊天
    7. **触发词** — 激活机器人的前缀（默认：`@Andy`）
    8. **挂载目录** — 现在选择"No"（稍后可以添加文件访问）
    9. **启动服务** — NanoClaw 和 Venice 代理都作为后台服务启动

    设置向导安装两个后台服务：

    * **NanoClaw** — 机器人本身
    * **Venice 代理** — 一个小型本地服务器（localhost:4001），在 Claude Code 和 Venice AI 之间进行转换

    两者都在启动时自动启动，崩溃时会自动重启。

    <Note>
      如果向导在步骤之间停止，键入 "continue" 或 "next step" 推动其前进。
    </Note>
  </Step>

  <Step title="开始聊天">
    设置完成后，打开您的聊天（Telegram 或 WhatsApp）并发送：

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

    机器人应该在几秒钟内响应。在您的主通道中，您可以正常输入而无需 `@Andy` 前缀。

    **现在您可以关闭终端窗口。** 一切都作为后台服务运行，并在计算机启动时自动启动。
  </Step>
</Steps>

***

## 工作原理

NanoClaw 有两层：

| 层                   | 功能                         |
| ------------------- | -------------------------- |
| **Claude Code CLI** | 用于设置、调试和定制的管理工具            |
| **机器人**             | 您聊天中的 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` 或更改机器人行为。

***

## 模型

| 上下文             | 默认模型                   | 如何切换                                                 |
| --------------- | ---------------------- | ---------------------------------------------------- |
| 机器人（在聊天中）       | `claude-sonnet-4-6`    | 告诉机器人："切换到 opus" 或 "使用 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>

请参阅[模型目录](/models/text)获取所有可用的 Venice 模型。

***

## 故障排查

<AccordionGroup>
  <Accordion title="代理未运行">
    Venice 代理作为后台服务运行，并会自动重启。如果它无法工作：

    **macOS：**

    ```bash theme={"system"}
    # Check if it's running
    launchctl list | grep venice-proxy

    # Restart it
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

    # Check logs
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```

    **Linux：**

    ```bash theme={"system"}
    # Check if it's running
    systemctl --user status nanoclaw-venice-proxy

    # Restart it
    systemctl --user restart nanoclaw-venice-proxy

    # Check logs
    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"}
    # Restart proxy
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

    # Restart bot
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw
    ```

    **Linux：**

    ```bash theme={"system"}
    # Restart proxy
    systemctl --user restart nanoclaw-venice-proxy

    # Restart bot
    systemctl --user restart nanoclaw
    ```

    在[模型目录](/models/text)中查看可用模型。
  </Accordion>

  <Accordion title="机器人不响应消息">
    按顺序进行以下步骤：

    1. **检查您的触发词。** 确保您使用了正确的前缀（例如 `@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 已打开并正在运行。等待 10 秒以让 Docker 完全启动，然后在向导中键入 `continue` 重试。
  </Accordion>

  <Accordion title="WhatsApp 断开连接">
    您的 WhatsApp 会话可能过期。要重新连接：

    ```bash theme={"system"}
    cd nanoclaw-venice
    npm run auth
    ```

    使用 WhatsApp 扫描二维码（设置 → 关联设备 → 关联设备），然后重启机器人：

    * 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：**

    | 操作    | 命令                                                                        |
    | ----- | ------------------------------------------------------------------------- |
    | 启动机器人 | `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：**

    | 操作    | 命令                                               |
    | ----- | ------------------------------------------------ |
    | 启动机器人 | `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` 切换回来。
  </Accordion>

  <Accordion title="运行多个机器人">
    您可以在同一台机器上运行多个 NanoClaw 机器人（例如，一个用于个人使用，一个用于团队）。只需将仓库克隆到不同的文件夹并再次运行设置。注意：它们共享同一个 Docker 镜像，因此重建一个会影响所有机器人。
  </Accordion>

  <Accordion title="开发者命令">
    对于想要修改 NanoClaw 代码的人：

    ```bash theme={"system"}
    npm run dev          # Start proxy + NanoClaw with hot reload
    npm run proxy        # Start just the Venice proxy
    npm run build        # Compile TypeScript
    npm test             # Run tests
    ./container/build.sh # Rebuild agent container
    ```
  </Accordion>
</AccordionGroup>

***

## 架构

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

| 文件                         | 用途                                   |
| -------------------------- | ------------------------------------ |
| `proxy/venice-proxy.ts`    | 为 Venice 将 Anthropic 格式转换为 OpenAI 格式 |
| `src/index.ts`             | 主编排器——消息循环、agent 调用                  |
| `src/channels/whatsapp.ts` | 通过 baileys 的 WhatsApp 连接             |
| `src/channels/telegram.ts` | 通过 grammy 的 Telegram 机器人             |
| `src/container-runner.ts`  | 生成隔离的 agent 容器                       |

***

## 常见问题

<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="它安全吗？">
    Agent 运行在具有真正操作系统级隔离的 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 的上游项目
  </Card>

  <Card title="Venice 模型目录" icon="list" href="/models/text">
    浏览可用模型
  </Card>

  <Card title="Venice 隐私" icon="shield-halved" href="/overview/privacy">
    Venice 如何保护您的数据
  </Card>
</CardGroup>