NanoClaw 实战：在 Windows 上搭建本地优先的轻量级 AI Agent，并接入 WhatsApp

AI Agent 正在改变人与软件的交互方式。相比在多个应用之间来回切换，Agent 的目标是接受一条自然语言指令，然后自行完成后续步骤，例如设置提醒、处理邮件、协助项目管理，或执行编码与写作任务。

如果场景是个人本地工作流，过于庞杂的 Agent 系统往往带来额外负担：部署重、维护复杂、权限边界不清晰、成本也更高。NanoClaw 走的是另一条路线：本地优先、相对轻量，并借助 Docker 隔离把执行环境限制在容器内，降低直接暴露宿主机环境的风险。

这里演示完整落地流程：

在 Windows 上准备 WSL 2 + Ubuntu 环境
安装 Node.js、Docker、Claude Code
获取并启动 NanoClaw
使用 OneCLI 配置 Claude 访问令牌
将 NanoClaw 接入 WhatsApp
在手机聊天中直接测试 Agent 能力

NanoClaw 的定位与适用范围

NanoClaw 适合以下场景：

希望在本地机器上运行 Agent，而不是完全托管到云端
需要通过聊天渠道触发任务，例如 WhatsApp、Telegram、Slack、Discord、Gmail
希望使用容器隔离来控制运行环境
关注个人使用、实验环境、轻量级自动化，而不是大型企业集成生态

现阶段它覆盖的核心能力包括：

消息通道接入
Web 访问
Memory
定时任务

如果目标是大规模集成生态、多模型支持、复杂企业编排，NanoClaw 并不占优。它更像是一个偏个人化、本地化、强调隔离的 Agent 框架。

系统要求

在 Windows 上运行这套环境，至少需要满足以下条件：

项目	要求
操作系统	Windows 10/11
WSL 版本	WSL 2
虚拟化	硬件虚拟化已开启
内存	至少 4 GB，建议 8 GB 以上
磁盘空间	预留约 20–30 GB
容器环境	Docker Desktop
Linux 发行版	Ubuntu（运行于 WSL 内）

WSL 2 很关键。Claude Code 在 Windows 上依赖 WSL，且其沙箱能力要求 WSL 2，WSL 1 不受支持。

1. 安装 WSL 并准备 Ubuntu 环境

先以管理员身份打开 PowerShell，执行：

wsl --install

安装完成后，如系统要求则重启。随后检查 WSL 状态：

wsl --status

确认当前发行版运行在 WSL 2 上。

接着启动 Ubuntu：

wsl

进入 Ubuntu 后，更新系统并安装基础开发工具：

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git wget

到这一步，Linux 环境已经具备后续安装所需的基础能力。

2. 安装 Node.js、Docker 和 Claude Code

NanoClaw 依赖三类基础组件：

Node.js：用于 JavaScript 生态下的依赖安装与项目运行
Docker：用于容器隔离
Claude Code：用于执行引导式安装与配置流程

使用 NVM 安装 Node.js

在 WSL 的 Ubuntu 终端中执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24
node -v
npm -v

正常情况下会看到类似输出：

v24.14.1
11.11.0

这里使用 NVM 安装 Node.js，而不是直接依赖系统包管理器，原因很直接：后续如果需要切换 Node 版本或重装环境，管理成本更低。

确认 Docker 可在 WSL 中使用

先在 Windows 上安装 Docker Desktop。安装完成后，在 Docker Desktop 中确认以下设置已启用：

Use the WSL 2-based engine
Resources -> WSL Integration 中启用 Ubuntu 发行版的集成

然后回到 Ubuntu 终端，检查 Docker 是否可用：

docker --version
docker ps

预期输出类似：

Docker version 29.1.3, build f52814d
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

如果 docker ps 能正常返回空列表或容器列表，说明 WSL 内已经可以访问 Docker。

在 Ubuntu 中安装 Claude Code

执行：

curl -fsSL https://claude.ai/install.sh | bash

安装完成后，Claude Code 会直接进入 Ubuntu 环境，后续的 NanoClaw 初始化流程将通过它完成。

3. 获取 NanoClaw 源码并打开项目

准备工作完成后，克隆仓库并进入目录：

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw

如果后续需要深度定制，可以先 fork 再克隆自己的仓库。首次安装直接使用主仓库即可。

接着在项目目录中启动 Claude Code：

claude

第一次启动时，会进入 Claude Code 的初始登录与配置流程。可选择两种方式之一：

使用 Claude.ai 账号登录
使用 Anthropic API Key

如果已经具备 Claude Pro 或 Max 订阅，账号登录通常更省事；如果走 API 计费，也可以直接配置 API Key。

完成登录后，Claude Code 会在 nanoclaw 项目中打开，接下来即可执行安装。

4. 运行 NanoClaw 安装流程

在 Claude Code 中执行：

/setup

这会触发 NanoClaw 的引导式安装。

安装阶段会发生什么

/setup 执行后，主要会经历几个阶段：

安装项目依赖
检查本地环境是否满足要求
构建 NanoClaw 的 Docker 容器
验证容器能否正常启动
安装 OneCLI
启动相关服务

完成后，可以在 Docker Desktop 中看到 NanoClaw 相关容器正在运行，通常包括：

NanoClaw 应用容器
PostgreSQL 等支撑服务

OneCLI 的作用

OneCLI 是 NanoClaw 体系中的关键组件，主要负责更安全地管理密钥和容器访问。NanoClaw 不会直接把凭据裸露写入容器环境，而是通过 OneCLI 来注册和传递敏感信息。

5. 为 OneCLI 配置 Claude Token

即使 Claude Code 已经在 WSL 中完成登录，NanoClaw 运行所在的容器仍然需要独立、安全地访问 Claude。这里需要额外生成 token，并把它注册到 OneCLI。

先打开一个新的终端，执行：

claude setup-token

这个命令会生成一个浏览器链接。完成流程如下：

打开链接
登录账号
授权请求
将返回的 code 粘贴回终端
获取 token

得到 token 后，执行下面的命令，将 YOUR_TOKEN 替换为刚生成的值：

onecli secrets create --name Anthropic --type anthropic --value YOUR_TOKEN --host-pattern api.anthropic.com

这一步的目的，是让 NanoClaw 容器在不直接暴露凭据的前提下访问 Claude 接口。

6. 配置 WhatsApp 通道

主安装流程完成后，会进入 channel setup 阶段。这里可以选择 NanoClaw 的交互渠道。支持的渠道包括：

WhatsApp
Discord
Telegram
Slack

这里以 WhatsApp 为例。

生成 WhatsApp 二维码

在通道选择阶段选择 WhatsApp。

浏览器里显示的二维码可能无法正常工作，常见原因是 WSL 与浏览器之间的本地端口访问存在问题。更稳妥的做法是直接使用终端中的二维码。

如果 Claude Code 终端里的二维码显示不完整，打开新终端并执行：

cd nanoclaw
npm run auth

这会在终端中重新生成一个更清晰的二维码。

在手机上绑定 WhatsApp

在手机 WhatsApp 中依次进入：

Settings
Linked Devices
Link a Device

然后扫描终端中的二维码。

绑定成功后，终端会显示成功信息。

完成频道配置

返回最初的 Claude Code 终端，继续完成后续问题。这里可以直接采用默认推荐配置：

trigger word：保持默认
assistant name：保持默认
模式选择 self-chat

self-chat 表示 NanoClaw 只会在自己的 WhatsApp 自聊窗口中响应消息。这个模式很适合测试，因为不会允许其他联系人直接调用 Agent。

完成重建并测试

配置保存后，NanoClaw 会根据新的通道设置重新构建容器。这一步需要等待一段时间。

完成后，可以开始测试。

7. 在 WhatsApp 中测试 NanoClaw

打开手机 WhatsApp，找到自己的号码对应的自聊窗口，发送一条带触发词的消息。例如：

@Andy hello

如果配置正常，NanoClaw 会在聊天中回复。

也可以进一步验证触发词机制。发送一条不带触发词的消息：

How are you?

预期结果是 NanoClaw 不会响应。这是设计使然，用于确保 Agent 只在被显式唤起时执行。

再测试一个复杂任务：

@Andy Tell me the latest gold and silver prices and should i buy it or not

如果相关工具链配置完整，NanoClaw 会执行多步任务并返回结构化结果。这里也需要注意一类典型问题：如果返回的金银价格明显不准确，通常说明它并没有实际进行 Web 搜索，而是退回到了模型内置知识，因此结果带有时效性误差。

常见问题与排查

`/setup` 卡住或失败

最常见的原因有三类：

问题	说明
Docker 未启动	容器运行时不可用
运行时选择错误	Docker 或其他容器后端未正确接入
容器后端尚未就绪	存在启动时序问题

排查顺序建议如下：

docker ps

确认 Docker 在 WSL 内可用后，再重新执行安装流程。

WhatsApp 二维码无法显示或无法绑定

常见原因包括：

WSL 与浏览器之间端口访问异常
终端中的二维码被截断
同一个 WhatsApp 号码已被多个 Agent 占用
容器与本地网络之间存在连接问题

处理方式通常是：

重新在终端生成二维码
使用 npm run auth
检查是否重复绑定同一号码
必要时执行退出重新登录流程

NanoClaw 是否安全

NanoClaw 的安全基础主要来自容器隔离。Agent 运行在 Docker 沙箱环境中，与宿主机操作系统隔开。但这并不意味着可以忽略基础安全原则，仍然需要注意：

API Key 与 token 的管理方式
容器挂载的目录范围
Claude Code / Docker / OneCLI 授予的权限
外部通道接入后的访问控制

如果只在个人设备、本地环境和受限消息通道中运行，风险边界相对清晰。

使用体验与取舍判断

NanoClaw 的方向是成立的：本地优先、容器隔离、轻量 Agent。这类设计对于个人自动化和本地实验环境有现实价值。

但“轻量”更多体现在定位与架构，而不是初次安装体验。放到 Windows + WSL 场景中，整套流程仍然包含不少手工步骤：

Docker Desktop 与 WSL 的联动配置
Claude Code 登录与授权
OneCLI token 注册
通道认证
容器重建与多轮确认

如果对容器、WSL、CLI 工具链不熟悉，安装过程并不轻松。实际使用时还会遇到几个体验问题：

权限确认较多
某些阶段需要切换多个终端
WhatsApp 的交互反馈较粗糙
响应样式与人工消息区分不明显
需要工具调用时，结果质量依赖配置是否真正生效

因此，NanoClaw 更适合两类人：

希望掌控本地运行环境、愿意接受较高配置成本的开发者
需要一个相对安全、可实验、可扩展的个人 Agent 容器化方案的用户

如果目标是“几分钟内就能从手机发消息控制 Agent”，这条路线的上手门槛并不低。

NanoClaw FAQ

NanoClaw 相比更重型的 Agent 框架，能做什么

NanoClaw 覆盖消息通道、Web 访问、记忆、定时任务等核心能力，但在大规模集成生态和多模型支持方面还不算完整，更适合个人化、本地化工作流。

支持哪些平台

可运行于 macOS 和 Linux，也支持 Windows 上的 WSL 2。隔离通常依赖 Docker 或 Apple Containers。前提是操作系统较新，并具备足够的内存和磁盘空间来承载 Docker 镜像与相关服务。

`/setup` 过程中 Docker 阶段失败怎么办

优先检查 Docker Desktop 是否启动、WSL Integration 是否开启、docker ps 是否正常。如果只是后端尚未就绪，重新执行一遍安装流程通常可以恢复。

WhatsApp 和其他消息通道怎么排障

消息通道通常通过二维码或 OAuth 风格流程完成认证。排查重点包括：

二维码是否完整显示
当前号码是否已被其他 Agent 占用
容器和宿主机之间的网络是否正常
浏览器访问本地端口是否成功

适合在个人机器上长期运行吗

从隔离模型看是可行的，但前提是正确管理密钥、挂载目录和权限边界。对于长期运行的个人 Agent，安全问题不在于“是否用了 Docker”，而在于“给了它哪些能力”。

关于

关注我获取更多资讯

📢 公众号

💬 个人号