NanoClaw on MacBook M3 Pro

Complete Deployment Guide From Setup to AI Company

NanoClaw MacBook M3 Pro 部署與實戰完全指南

從安裝到 AI 公司

"Any sufficiently advanced technology is indistinguishable from a competent assistant." — Arthur C. Clarke (adapted)

「任何足夠先進的技術，都與一位稱職的助手無異。」—— Arthur C. Clarke（改編）

Who This Guide Is For

You have a MacBook M3 Pro. You want a personal AI assistant that:

Lives in WhatsApp or Telegram — the apps you already use
Runs entirely on your machine — no cloud hosting fees
Can browse the web, compare prices, manage your email, organize your notes
Operates inside secure containers so a rogue prompt can't nuke your filesystem
Scales into a multi-agent team when you need more than one brain

This guide walks through every step: from git clone to running an AI company with Agent Swarm. No steps skipped. No "left as an exercise for the reader."

What you'll build by the end:

NanoClaw running in Docker Sandboxes on Apple Silicon
WhatsApp as your primary chat interface (free, via Baileys)
Telegram as your fallback channel (also free)
Gmail integration with a daily top-10 email digest
Product price comparison via Agent Browser
Obsidian knowledge base integration for persistent notes
A multi-agent "AI company" using Agent Swarm

這份指南適合誰

你有一台 MacBook M3 Pro。你想要一個個人 AI 助手，它：

住在 WhatsApp 或 Telegram 裡——你本來就在用的 app
完全跑在你的機器上——不需要雲端託管費用
能瀏覽網頁、比價、管理 email、整理筆記
在安全容器中運行，讓惡意 prompt 無法炸掉你的檔案系統
需要時能擴展成多 agent 團隊

本指南走過每一個步驟：從 git clone 到用 Agent Swarm 經營一間 AI 公司。沒有跳過任何步驟，沒有「留給讀者當練習」。

讀完後你會建好：

NanoClaw 在 Apple Silicon 上的 Docker Sandboxes 中運行
WhatsApp 作為主要聊天介面（免費，透過 Baileys）
Telegram 作為備用頻道（也免費）
Gmail 整合，每天早上寄出 top 10 重要信件摘要
透過 Agent Browser 的商品比價功能
Obsidian 知識庫整合，持久化筆記
使用 Agent Swarm 的多 agent「AI 公司」

Part 1: Prerequisites and Installation

Prerequisites

Before you begin, make sure you have these installed:

Prerequisite	Minimum Version	Check Command	Notes
Node.js	20.0+	`node --version`	LTS recommended; install via `brew install node`
Docker Desktop	4.57+	`docker --version`	Must be running; allocate at least 8 GB RAM
Claude Code	2.1.32+	`claude --version`	`npm install -g @anthropic-ai/claude-code`
Xcode CLI Tools	Any	`xcode-select -p`	`xcode-select --install` if missing
GitHub CLI	2.0+	`gh --version`	`brew install gh` then `gh auth login`
Anthropic API Key	—	—	From console.anthropic.com

The M3 Pro's 18 GB (or 36 GB) unified memory is ideal. NanoClaw's orchestrator uses under 200 MB. Each Docker Sandbox container takes 256–512 MB. You can comfortably run 4–6 concurrent agent containers on the base 18 GB model.

Fork and Clone

bash

gh repo fork qwibitai/nanoclaw --clone
cd nanoclaw

This creates your own fork (so you can customize freely) and clones it locally.

Launch Claude Code and Run Setup

bash

claude

Inside the Claude Code REPL:

/setup

This triggers NanoClaw's 8-step setup wizard. Here's what each step does:

Step 1: API Key Configuration The wizard prompts for your Anthropic API key. It stores this in .env as CLAUDE_API_KEY. Never commit this file — it's already in .gitignore.

Step 2: Assistant Identity Choose your assistant's name. This is the ASSISTANT_NAME variable — the name users @-mention in group chats. Default: Andy.

Step 3: Container Runtime Selection Choose between Docker Sandboxes (recommended) and Apple Containers. More on this below.

Step 4: Channel Configuration Select which messaging channels to enable. You can add more later with /add-whatsapp, /add-telegram, /add-slack, etc.

Step 5: Admin Configuration Set your admin phone number or Telegram ID. The admin channel (your self-chat) is your control center for managing the assistant.

Step 6: Security Defaults Configure mount allowlists, blocked patterns, and privilege tiers. The defaults are secure — accept them unless you have specific needs.

Step 7: Skill Installation Choose optional skills: Gmail, Agent Browser, Obsidian, Agent Swarm, etc. Each skill adds a set of tools to the agent.

Step 8: Verification The wizard runs a health check: starts a container, sends a test message, verifies the response loop, and tears down the container.

Docker Sandboxes for Apple Silicon

Docker Sandboxes are NanoClaw's recommended container runtime. Each agent session gets a hypervisor-backed MicroVM with its own kernel — not just a namespace-isolated container, but a genuine virtual machine.

Install with:

bash

curl -fsSL https://nanoclaw.dev/install-docker-sandboxes.sh | bash

This script detects Apple Silicon, installs the ARM64 runtime, and configures the Docker Desktop integration.

Core commands:

bash

# Create a new sandbox
docker sandbox create --name agent-01

# Run a command inside
docker sandbox run agent-01 -- claude --print "Hello from the sandbox"

# List all sandboxes
docker sandbox ls

# Stop a running sandbox
docker sandbox stop agent-01

# Start a stopped sandbox
docker sandbox start agent-01

# Remove a sandbox
docker sandbox rm agent-01

Apple Containers Alternative

Apple Containers (introduced in macOS 26) are lighter-weight — they use Apple's native Virtualization.framework without the Docker daemon overhead. But they're less battle-tested with NanoClaw.

To use Apple Containers instead:

bash

# In .env
CONTAINER_RUNTIME=apple

Stick with Docker Sandboxes unless you have a specific reason to switch. The rest of this guide assumes Docker Sandboxes.

Key Environment Variables

After setup, your .env file will contain:

bash

# Required
CLAUDE_API_KEY=sk-ant-...your-key...

# Container runtime
CONTAINER_RUNTIME=docker-sandbox   # or "apple" or "docker"

# Assistant identity
ASSISTANT_NAME=Andy

# Performance tuning
IDLE_TIMEOUT=300000               # 5 min — container sleeps after this
MAX_CONCURRENT_CONTAINERS=4       # Increase if you have 36 GB RAM
IPC_POLL_INTERVAL=500             # ms — how often orchestrator checks containers
SCHEDULER_POLL_INTERVAL=60000     # ms — how often cron scheduler ticks

Variable	Default	What It Does
`CLAUDE_API_KEY`	(none)	Your Anthropic API key
`CONTAINER_RUNTIME`	`docker-sandbox`	Which container backend to use
`ASSISTANT_NAME`	`Andy`	Name the assistant responds to
`IDLE_TIMEOUT`	`300000`	Container sleep timeout in ms (5 min)
`MAX_CONCURRENT_CONTAINERS`	`4`	Max simultaneous agent containers
`IPC_POLL_INTERVAL`	`500`	Orchestrator polling interval in ms
`SCHEDULER_POLL_INTERVAL`	`60000`	Cron scheduler tick interval in ms

Directory Structure After Setup

nanoclaw/
├── .env                          # API keys and config (gitignored)
├── CLAUDE.md                     # Agent persistent memory
├── package.json                  # Dependencies
├── src/
│   ├── orchestrator.ts           # Main polling loop (~800 lines)
│   ├── channels/
│   │   ├── whatsapp.ts           # Baileys integration
│   │   ├── telegram.ts           # Telegram Bot API
│   │   ├── slack.ts              # Slack integration
│   │   └── discord.ts            # Discord integration
│   ├── containers/
│   │   ├── docker-sandbox.ts     # Docker Sandboxes runtime
│   │   ├── apple-container.ts    # Apple Container runtime
│   │   └── mount-validator.ts    # Mount allowlist enforcement
│   ├── scheduler/
│   │   └── cron.ts               # Scheduled task engine
│   └── skills/
│       ├── gmail/                # Gmail MCP skill
│       ├── browser/              # Agent Browser skill
│       └── obsidian/             # Obsidian vault skill
├── store/
│   ├── auth/
│   │   └── whatsapp/             # WhatsApp session credentials
│   ├── messages.db               # SQLite message store
│   └── scheduler.db              # SQLite scheduled tasks
└── docker/
    └── Dockerfile.sandbox        # Base container image

Verification

Run the health check:

bash

npm run verify

Expected output:

✓ Node.js 20.14.0
✓ Docker Desktop 4.57.1
✓ Docker Sandboxes runtime detected
✓ Claude Code 2.1.34
✓ API key valid (claude-opus-4-20250514 accessible)
✓ Container lifecycle: create → run → stop → rm
✓ IPC round-trip: 23ms
✓ All checks passed

If any check fails, see Part 11 (Troubleshooting) at the end of this guide.

Part 1：前置需求與安裝

前置需求

開始之前，確認你已經安裝：

前置需求	最低版本	確認指令	備註
Node.js	20.0+	`node --version`	建議 LTS 版；用 `brew install node` 安裝
Docker Desktop	4.57+	`docker --version`	必須正在運行；至少分配 8 GB RAM
Claude Code	2.1.32+	`claude --version`	`npm install -g @anthropic-ai/claude-code`
Xcode CLI Tools	任意	`xcode-select -p`	沒有的話 `xcode-select --install`
GitHub CLI	2.0+	`gh --version`	`brew install gh` 然後 `gh auth login`
Anthropic API Key	—	—	從 console.anthropic.com 取得

M3 Pro 的 18 GB（或 36 GB）統一記憶體非常理想。NanoClaw 的 orchestrator 使用不到 200 MB。每個 Docker Sandbox 容器佔 256–512 MB。在基本的 18 GB 機型上，你可以輕鬆同時跑 4–6 個 agent 容器。

Fork 並 Clone

bash

gh repo fork qwibitai/nanoclaw --clone
cd nanoclaw

這會建立你自己的 fork（讓你可以自由客製化）並 clone 到本地。

啟動 Claude Code 並執行 Setup

bash

claude

在 Claude Code REPL 裡：

/setup

這會觸發 NanoClaw 的 8 步驟設定精靈。以下是每一步的說明：

步驟 1：API Key 設定 精靈會要求你的 Anthropic API key。它會存在 .env 中的 CLAUDE_API_KEY。絕對不要 commit 這個檔案——它已經在 .gitignore 裡了。

步驟 2：助手身份 選擇助手的名字。這是 ASSISTANT_NAME 變數——使用者在群組聊天中 @mention 的名字。預設：Andy。

步驟 3：容器 Runtime 選擇 選擇 Docker Sandboxes（推薦）或 Apple Containers。下方有更多說明。

步驟 4：頻道設定 選擇要啟用哪些通訊頻道。之後可以用 /add-whatsapp、/add-telegram、/add-slack 等指令新增。

步驟 5：管理員設定 設定你的管理員電話號碼或 Telegram ID。管理員頻道（你的自聊天）是管理助手的控制中心。

步驟 6：安全預設 設定 mount allowlist、阻擋模式和權限層級。預設值是安全的——除非你有特殊需求，否則接受它們。

步驟 7：Skill 安裝 選擇可選 skill：Gmail、Agent Browser、Obsidian、Agent Swarm 等。每個 skill 會為 agent 增加一組工具。

步驟 8：驗證 精靈執行健康檢查：啟動一個容器、傳送測試訊息、驗證回應迴圈、然後拆掉容器。

Apple Silicon 的 Docker Sandboxes

Docker Sandboxes 是 NanoClaw 推薦的容器 runtime。每個 agent session 都會得到一個 hypervisor 支援的 MicroVM，擁有自己的 kernel——不只是 namespace 隔離的容器，而是一個真正的虛擬機。

安裝方式：

bash

curl -fsSL https://nanoclaw.dev/install-docker-sandboxes.sh | bash

這個 script 會偵測 Apple Silicon、安裝 ARM64 runtime，並設定 Docker Desktop 整合。

核心指令：

bash

# 建立新的 sandbox
docker sandbox create --name agent-01

# 在裡面執行指令
docker sandbox run agent-01 -- claude --print "Hello from the sandbox"

# 列出所有 sandbox
docker sandbox ls

# 停止運行中的 sandbox
docker sandbox stop agent-01

# 啟動已停止的 sandbox
docker sandbox start agent-01

# 移除 sandbox
docker sandbox rm agent-01

Apple Containers 替代方案

Apple Containers（macOS 26 引入）更輕量——它使用 Apple 原生的 Virtualization.framework，不需要 Docker daemon 的開銷。但它與 NanoClaw 的整合還不夠成熟。

要使用 Apple Containers：

bash

# 在 .env 中
CONTAINER_RUNTIME=apple

除非有特殊理由，否則繼續使用 Docker Sandboxes。本指南後續都假設使用 Docker Sandboxes。

關鍵環境變數

設定完成後，你的 .env 檔案會包含：

bash

# 必要
CLAUDE_API_KEY=sk-ant-...your-key...

# 容器 runtime
CONTAINER_RUNTIME=docker-sandbox   # 或 "apple" 或 "docker"

# 助手身份
ASSISTANT_NAME=Andy

# 效能調校
IDLE_TIMEOUT=300000               # 5 分鐘——容器在此後進入休眠
MAX_CONCURRENT_CONTAINERS=4       # 如果有 36 GB RAM 可以調高
IPC_POLL_INTERVAL=500             # ms——orchestrator 檢查容器的頻率
SCHEDULER_POLL_INTERVAL=60000     # ms——cron 排程器的 tick 頻率

變數	預設值	功能
`CLAUDE_API_KEY`	（無）	你的 Anthropic API key
`CONTAINER_RUNTIME`	`docker-sandbox`	使用哪個容器後端
`ASSISTANT_NAME`	`Andy`	助手回應的名字
`IDLE_TIMEOUT`	`300000`	容器休眠超時（ms，5 分鐘）
`MAX_CONCURRENT_CONTAINERS`	`4`	同時運行的最大 agent 容器數
`IPC_POLL_INTERVAL`	`500`	Orchestrator 輪詢間隔（ms）
`SCHEDULER_POLL_INTERVAL`	`60000`	Cron 排程器 tick 間隔（ms）

設定完成後的目錄結構

nanoclaw/
├── .env                          # API key 和設定（gitignored）
├── CLAUDE.md                     # Agent 持久記憶
├── package.json                  # 相依套件
├── src/
│   ├── orchestrator.ts           # 主要 polling 迴圈（約 800 行）
│   ├── channels/
│   │   ├── whatsapp.ts           # Baileys 整合
│   │   ├── telegram.ts           # Telegram Bot API
│   │   ├── slack.ts              # Slack 整合
│   │   └── discord.ts            # Discord 整合
│   ├── containers/
│   │   ├── docker-sandbox.ts     # Docker Sandboxes runtime
│   │   ├── apple-container.ts    # Apple Container runtime
│   │   └── mount-validator.ts    # Mount allowlist 驗證
│   ├── scheduler/
│   │   └── cron.ts               # 排程任務引擎
│   └── skills/
│       ├── gmail/                # Gmail MCP skill
│       ├── browser/              # Agent Browser skill
│       └── obsidian/             # Obsidian vault skill
├── store/
│   ├── auth/
│   │   └── whatsapp/             # WhatsApp session 憑證
│   ├── messages.db               # SQLite 訊息存儲
│   └── scheduler.db              # SQLite 排程任務
└── docker/
    └── Dockerfile.sandbox        # 基礎容器映像

驗證

執行健康檢查：

bash

npm run verify

預期輸出：

✓ Node.js 20.14.0
✓ Docker Desktop 4.57.1
✓ Docker Sandboxes runtime detected
✓ Claude Code 2.1.34
✓ API key valid (claude-opus-4-20250514 accessible)
✓ Container lifecycle: create → run → stop → rm
✓ IPC round-trip: 23ms
✓ All checks passed

如果任何檢查失敗，請參閱文末的 Part 11（疑難排解）。

Part 2: WhatsApp Setup (Free)

Why It's Free

NanoClaw uses the Baileys library — an open-source, reverse-engineered WhatsApp Web client. It connects to WhatsApp's servers the same way WhatsApp Web does in your browser. There is:

No WhatsApp Business API — no Meta approval process
No monthly fees — zero cost
No phone number purchase — uses your existing number
No Business Manager — no Facebook/Meta account required

You're essentially running another "WhatsApp Web" session from your MacBook. WhatsApp allows up to 4 linked devices per phone number.

Setup

During /setup (Step 4), select WhatsApp. Or add it later:

/add-whatsapp

Authentication Methods

NanoClaw supports three ways to link your WhatsApp:

Method 1: QR Code (Browser) The wizard opens a local web page at http://localhost:3847 showing the QR code. Scan it with your phone.

Method 2: QR Code (Terminal/ASCII) If you're running headless or over SSH, the QR code renders directly in your terminal as ASCII art. Works in any terminal that supports Unicode block characters.

Method 3: Pairing Code For situations where QR scanning isn't practical. The wizard generates a 6-digit pairing code that you enter manually in WhatsApp.

Step-by-Step Linking

Open WhatsApp on your phone
Go to Settings (gear icon, bottom right on iOS)
Tap Linked Devices
Tap Link a Device
Authenticate with Face ID / fingerprint
Scan the QR code shown by NanoClaw (or enter the pairing code)

The connection establishes within 2–5 seconds. You'll see:

✓ WhatsApp connected as +1-555-xxx-xxxx
✓ Session credentials saved to store/auth/whatsapp/creds.json
✓ Listening for messages...

Session Persistence

Baileys saves session credentials to store/auth/whatsapp/creds.json. On restart, NanoClaw reuses these credentials — no re-scanning needed. The session persists until:

You explicitly unlink the device from your phone
WhatsApp invalidates the session (rare, usually after 14+ days of inactivity)
You delete creds.json

Auto-reconnect is built in. If the connection drops (Wi-Fi blip, laptop sleep), NanoClaw retries with exponential backoff: 1s, 2s, 4s, 8s, up to 60s max.

Media Support

Media Type	Supported	Notes
Text messages	Yes	Full Unicode, emoji, formatting
Images	Yes	Lazy download — fetched only when agent needs them
Documents	Yes	PDF, DOCX, XLSX parsed via container tools
Voice notes	Yes	Transcribed via Whisper skill if installed
Replies with context	Yes	Agent sees the quoted message
Location sharing	Yes	Parsed as latitude/longitude
Contacts	Partial	vCard parsed, but limited utility
Stickers	No	Ignored
Video calls	No	Not applicable

Limitations

One linked session only — if you already have 4 linked devices, you must unlink one
Stricter rate limits — WhatsApp may temporarily block accounts that send too many messages too fast. NanoClaw's built-in rate limiter sends max 1 message per second
QR expires in 60 seconds — scan quickly, or refresh
No outbound initiation — the agent can only reply, not start new conversations (WhatsApp policy)
Session may drop after extended laptop sleep — auto-reconnect handles this, but there's a brief gap

Admin Channel

Your self-chat (sending a message to yourself) becomes the admin control channel. From here you can:

Check agent status: @Andy status
List active containers: @Andy containers
View scheduled tasks: @Andy schedules
Force-stop a runaway agent: @Andy stop all
View cost usage: @Andy cost today

Part 2：WhatsApp 設定（免費）

為什麼是免費的

NanoClaw 使用 Baileys 函式庫——一個開源的、逆向工程的 WhatsApp Web 客戶端。它用和你瀏覽器中 WhatsApp Web 相同的方式連接 WhatsApp 伺服器。也就是說：

不用 WhatsApp Business API——不需要 Meta 審核流程
不用月費——零成本
不用購買電話號碼——使用你現有的號碼
不用 Business Manager——不需要 Facebook/Meta 帳號

你本質上是從 MacBook 跑了另一個「WhatsApp Web」session。WhatsApp 允許每個電話號碼最多 4 個連結裝置。

設定方式

在 /setup（步驟 4）中選擇 WhatsApp。或之後再新增：

/add-whatsapp

驗證方式

NanoClaw 支援三種連結 WhatsApp 的方式：

方式 1：QR Code（瀏覽器） 精靈會在 http://localhost:3847 開一個本地網頁顯示 QR code。用手機掃描即可。

方式 2：QR Code（終端機/ASCII） 如果你在 headless 環境或透過 SSH 連線，QR code 會直接在終端機中以 ASCII art 呈現。任何支援 Unicode block characters 的終端機都可以。

方式 3：Pairing Code 在不方便掃描 QR 的情況下使用。精靈會產生一個 6 位數配對碼，你在 WhatsApp 中手動輸入。

逐步連結

打開手機上的 WhatsApp
前往設定（iOS 右下角的齒輪圖示）
點擊已連結的裝置
點擊連結裝置
使用 Face ID / 指紋驗證
掃描 NanoClaw 顯示的 QR code（或輸入配對碼）

連線會在 2–5 秒內建立。你會看到：

✓ WhatsApp connected as +1-555-xxx-xxxx
✓ Session credentials saved to store/auth/whatsapp/creds.json
✓ Listening for messages...

Session 持久化

Baileys 將 session 憑證儲存在 store/auth/whatsapp/creds.json。重啟時，NanoClaw 會重用這些憑證——不需要重新掃描。Session 會持續到：

你從手機明確取消連結該裝置
WhatsApp 使 session 失效（罕見，通常超過 14 天不活動才會發生）
你刪除 creds.json

自動重連是內建的。如果連線中斷（Wi-Fi 閃斷、筆電休眠），NanoClaw 會用指數退避重試：1s、2s、4s、8s，最多到 60s。

媒體支援

媒體類型	支援	備註
文字訊息	是	完整 Unicode、emoji、格式化
圖片	是	延遲下載——agent 需要時才取得
文件	是	PDF、DOCX、XLSX 透過容器工具解析
語音訊息	是	如有安裝 Whisper skill 會自動轉文字
引用回覆	是	Agent 可以看到被引用的訊息
位置分享	是	解析為經緯度
聯絡人	部分	vCard 可解析，但效用有限
貼圖	否	忽略
視訊通話	否	不適用

限制

只能佔一個連結 session——如果你已經有 4 個連結裝置，必須先取消一個
較嚴格的速率限制——WhatsApp 可能暫時封鎖傳訊太快的帳號。NanoClaw 內建速率限制器，每秒最多 1 則訊息
QR 在 60 秒後過期——快速掃描，或刷新
無法主動發起對話——agent 只能回覆，不能開新對話（WhatsApp 政策）
筆電長時間休眠後 session 可能中斷——自動重連會處理，但會有短暫空窗

管理員頻道

你的自聊天（傳訊息給自己）會成為管理員控制頻道。在這裡你可以：

檢查 agent 狀態：@Andy status
列出活躍容器：@Andy containers
查看排程任務：@Andy schedules
強制停止失控的 agent：@Andy stop all
查看費用使用：@Andy cost today

Part 3: Telegram as Fallback (Also Free)

Why Telegram as a Second Channel

WhatsApp works great as your daily driver, but Telegram has structural advantages that make it an excellent fallback — or even your primary channel if you prefer:

More generous rate limits — 30 messages per second vs WhatsApp's ~1/second
Native Bot API — official, documented, and stable (no reverse engineering)
No session conflicts — bots don't count toward linked device limits
Unlimited bots — create as many as you want, each with its own identity
Up to 2 GB file uploads — vs WhatsApp's 100 MB limit
Rich formatting — Markdown, HTML, inline keyboards, custom commands

And like WhatsApp via Baileys: completely free.

Create a Bot via @BotFather

Open Telegram and search for @BotFather
Send /newbot
Choose a display name (e.g., "Andy AI")
Choose a username (must end in bot, e.g., andy_nanoclaw_bot)
BotFather replies with your bot token: 7891234567:AAH...

Save this token. You'll need it in the next step.

Setup in NanoClaw

/add-telegram

The wizard prompts for:

Bot token (from BotFather)
Your Telegram user ID (send /start to @userinfobot to find it)
Admin-only mode (recommended: yes — only you can talk to the bot initially)

Telegram Swarm Skill

This is where Telegram really shines over WhatsApp. The Telegram Swarm skill lets you create multiple bots — each representing a different "employee" in your AI company:

@Andy create telegram swarm:
- @researcher_bot: "You are a research analyst. Search the web and compile reports."
- @writer_bot: "You are a content writer. Draft articles from provided research."
- @reviewer_bot: "You are an editor. Proofread, fact-check, and improve drafts."

Each bot runs in its own Docker Sandbox container with its own system prompt and memory. More on this in Part 8.

Telegram vs WhatsApp Quick Comparison

Feature	WhatsApp (Baileys)	Telegram (Bot API)
Cost	Free	Free
Rate limit	~1 msg/sec	30 msg/sec
Max file size	100 MB	2 GB
API type	Reverse-engineered	Official
Session stability	Good (occasional drops)	Excellent
Multi-bot	Not possible	Unlimited
Group support	Yes	Yes
Rich formatting	Limited	Full Markdown/HTML
Inline keyboards	No	Yes

Part 3：Telegram 作為備用（也免費）

為什麼要有第二頻道

WhatsApp 作為日常使用很棒，但 Telegram 有結構性優勢，使它成為出色的備用——或者如果你偏好的話，甚至可以當主要頻道：

更寬鬆的速率限制——每秒 30 則訊息 vs WhatsApp 的約 1 則/秒
原生 Bot API——官方的、有文件的、穩定的（不是逆向工程）
沒有 session 衝突——bot 不計入連結裝置限制
無限 bot——想建多少就建多少，每個都有自己的身份
最大 2 GB 檔案上傳——vs WhatsApp 的 100 MB 限制
豐富格式化——Markdown、HTML、inline keyboard、自訂指令

和透過 Baileys 的 WhatsApp 一樣：完全免費。

透過 @BotFather 建立 Bot

打開 Telegram 搜尋 @BotFather
傳送 /newbot
選擇顯示名稱（例如「Andy AI」）
選擇使用者名稱（必須以 bot 結尾，例如 andy_nanoclaw_bot）
BotFather 回覆你的 bot token：7891234567:AAH...

保存這個 token。下一步會用到。

在 NanoClaw 中設定

/add-telegram

精靈會要求：

Bot token（從 BotFather 取得）
你的 Telegram 使用者 ID（傳 /start 給 @userinfobot 取得）
僅限管理員模式（建議：是——一開始只有你能和 bot 對話）

Telegram Swarm Skill

這是 Telegram 真正比 WhatsApp 閃耀的地方。Telegram Swarm skill 讓你建立多個 bot——每個代表你 AI 公司中不同的「員工」：

@Andy create telegram swarm:
- @researcher_bot: "You are a research analyst. Search the web and compile reports."
- @writer_bot: "You are a content writer. Draft articles from provided research."
- @reviewer_bot: "You are an editor. Proofread, fact-check, and improve drafts."

每個 bot 跑在自己的 Docker Sandbox 容器中，有自己的 system prompt 和記憶。更多細節在 Part 8。

Telegram vs WhatsApp 快速比較

功能	WhatsApp（Baileys）	Telegram（Bot API）
費用	免費	免費
速率限制	約 1 則/秒	30 則/秒
最大檔案大小	100 MB	2 GB
API 類型	逆向工程	官方
Session 穩定性	良好（偶爾中斷）	極佳
多 bot	不可能	無限
群組支援	是	是
豐富格式化	有限	完整 Markdown/HTML
Inline keyboard	否	是

Part 4: Security Deep Dive

NanoClaw's entire philosophy is trust no agent. Every agent runs in a container. Every file access goes through a validation pipeline. Here's how it works.

Mount Allowlist

The mount allowlist controls which host directories a container can access. It lives at:

~/.config/nanoclaw/mount-allowlist.json

Example configuration:

json

{
  "allowedRoots": [
    {
      "path": "~/Documents/GitHub/my-project",
      "allowReadWrite": true,
      "description": "Main project repo"
    },
    {
      "path": "~/Documents/GitHub/my_note",
      "allowReadWrite": true,
      "description": "Obsidian vault"
    },
    {
      "path": "~/Downloads",
      "allowReadWrite": false,
      "description": "Read-only access to downloads"
    }
  ]
}

7-Step Validation Process

Every mount request goes through this pipeline:

Path expansion — ~ is expanded to $HOME, environment variables resolved
Absolute path conversion — relative paths are rejected
Blocked pattern check — matches against the default blocked list
Allowlist matching — path must be a child of an allowedRoots entry
Read/write permission check — write operations require allowReadWrite: true
Non-main group override — non-admin groups get read-only or no access
Container normalization — host path is mapped to a stable container path (e.g., /workspace/extra/notes/)

If any step fails, the mount is denied. No exceptions, no overrides from the agent.

Default Blocked Patterns

These paths are always blocked, regardless of allowlist entries:

.ssh — SSH keys
.gnupg — GPG keys
.aws — AWS credentials
.env — Environment files
private_key — Any file with this in the name
credentials — Any file with this in the name
.config/nanoclaw/ — NanoClaw's own config (prevents self-modification)

Three-Tier Privilege Model

Tier	Who	Mount Access	Container Behavior
Main group	Your self-chat / admin channel	Full allowlist (read + write)	`--dangerously-skip-permissions` enabled
Non-main group	Other chats / group chats you add	Read-only mounts only	Standard permission checks
No mounts	Unknown / untrusted sources	No host filesystem access	Fully isolated container

Docker Sandboxes on M3 Pro

Docker Sandboxes provide hypervisor-level isolation on Apple Silicon:

MicroVM — each container is a lightweight virtual machine, not just a namespace
Own kernel — the container runs its own Linux kernel, not the host's
Isolated Docker daemon — each sandbox has its own Docker daemon; a compromised daemon can't affect others
Credential proxy — API keys are injected via a proxy, not environment variables; the agent process can use them but can't read them directly

On the M3 Pro, each MicroVM adds roughly 256 MB memory overhead and 1–2 seconds startup time. The hardware virtualization support in Apple Silicon (Hypervisor.framework) makes this nearly native speed.

Why `--dangerously-skip-permissions` Is Safe Here

In normal Claude Code usage, --dangerously-skip-permissions is dangerous — it lets the agent execute any command without asking. But inside a Docker Sandbox:

The agent can only access files mounted via the allowlist
Network access is controlled by container networking rules
The agent can't escape the VM boundary
Even if the agent runs rm -rf /, it only destroys the container — your host is untouched

NanoClaw enables this flag by default for the main admin group because the speed benefit is enormous (no permission prompts for every file read/write) and the risk is contained.

The "Lethal Trifecta" Limitation

Container isolation is necessary but not sufficient. The "lethal trifecta" for AI assistant security:

Prompt injection — a malicious email, webpage, or document tricks the agent into executing harmful instructions
Credential access — the agent has your API keys, OAuth tokens, or credentials
External communication — the agent can send emails, post to APIs, or message other people

NanoClaw mitigates #1 with container isolation (damage is contained) and #2 with the credential proxy (keys can be used but not read). But #3 is inherent to the use case — you want the agent to send emails and messages.

This means: if a prompt injection tricks the agent while it has Gmail access, it could send emails on your behalf. Container isolation won't stop this because sending email is an intended capability.

Mitigation: Use Tool Mode (not Channel Mode) for sensitive integrations. Review the agent's actions in the admin channel. Set up alerts for unusual activity patterns.

Part 4：安全深入剖析

NanoClaw 的整體哲學是不信任任何 agent。每個 agent 都跑在容器中。每次檔案存取都經過驗證管道。以下是運作方式。

Mount Allowlist

Mount allowlist 控制容器可以存取哪些主機目錄。它位於：

~/.config/nanoclaw/mount-allowlist.json

範例設定：

json

{
  "allowedRoots": [
    {
      "path": "~/Documents/GitHub/my-project",
      "allowReadWrite": true,
      "description": "主要專案 repo"
    },
    {
      "path": "~/Documents/GitHub/my_note",
      "allowReadWrite": true,
      "description": "Obsidian vault"
    },
    {
      "path": "~/Downloads",
      "allowReadWrite": false,
      "description": "下載資料夾唯讀存取"
    }
  ]
}

7 步驟驗證流程

每個 mount 請求都會經過這個管道：

路徑展開——~ 展開為 $HOME，環境變數被解析
絕對路徑轉換——相對路徑被拒絕
阻擋模式檢查——與預設阻擋清單比對
Allowlist 匹配——路徑必須是 allowedRoots 條目的子路徑
讀寫權限檢查——寫入操作需要 allowReadWrite: true
非主群組覆寫——非管理員群組只能唯讀或無存取權限
容器正規化——主機路徑被對應到穩定的容器路徑（例如 /workspace/extra/notes/）

任何步驟失敗，mount 就會被拒絕。沒有例外，沒有來自 agent 的覆寫。

預設阻擋模式

不管 allowlist 怎麼設定，這些路徑永遠被阻擋：

.ssh——SSH 金鑰
.gnupg——GPG 金鑰
.aws——AWS 憑證
.env——環境變數檔案
private_key——任何名稱中包含這個的檔案
credentials——任何名稱中包含這個的檔案
.config/nanoclaw/——NanoClaw 自身的設定（防止自我修改）

三層權限模型

層級	誰	Mount 存取	容器行為
主群組	你的自聊天 / 管理員頻道	完整 allowlist（讀 + 寫）	啟用 `--dangerously-skip-permissions`
非主群組	你加入的其他聊天 / 群組	僅唯讀 mount	標準權限檢查
無 mount	未知 / 不受信任的來源	無主機檔案系統存取	完全隔離容器

M3 Pro 上的 Docker Sandboxes

Docker Sandboxes 在 Apple Silicon 上提供 hypervisor 層級的隔離：

MicroVM——每個容器是一個輕量級虛擬機，不只是 namespace
獨立 kernel——容器運行自己的 Linux kernel，不是主機的
隔離的 Docker daemon——每個 sandbox 有自己的 Docker daemon；被入侵的 daemon 無法影響其他的
Credential proxy——API key 透過代理注入，不是環境變數；agent 程序可以使用但無法直接讀取

在 M3 Pro 上，每個 MicroVM 增加大約 256 MB 記憶體開銷和 1–2 秒啟動時間。Apple Silicon 的硬體虛擬化支援（Hypervisor.framework）使其幾乎是原生速度。

為什麼 `--dangerously-skip-permissions` 在這裡是安全的

在一般 Claude Code 使用中，--dangerously-skip-permissions 是危險的——它讓 agent 不經詢問就能執行任何指令。但在 Docker Sandbox 裡：

Agent 只能存取透過 allowlist mount 的檔案
網路存取由容器網路規則控制
Agent 無法逃脫 VM 邊界
即使 agent 執行 rm -rf /，它也只會摧毀容器——你的主機不受影響

NanoClaw 預設為主管理員群組啟用這個 flag，因為速度提升巨大（每次檔案讀寫不需要權限提示），而且風險是被控制住的。

「致命三連」限制

容器隔離是必要但不充分的。AI 助手安全的「致命三連」：

Prompt injection——惡意 email、網頁或文件欺騙 agent 執行有害指令
Credential 存取——agent 有你的 API key、OAuth token 或憑證
外部通訊——agent 可以傳 email、呼叫 API、或發訊息給其他人

NanoClaw 用容器隔離緩解 #1（損害被控制），用 credential proxy 緩解 #2（key 可以使用但不能讀取）。但 #3 是使用場景本身固有的——你就是想要 agent 傳 email 和訊息。

這意味著：如果 prompt injection 在 agent 有 Gmail 存取權時欺騙了它，它可能以你的名義傳 email。容器隔離不會阻止這個，因為傳 email 是預期的功能。

緩解方式： 對敏感整合使用 Tool Mode（而非 Channel Mode）。在管理員頻道中審查 agent 的行為。對異常活動模式設定警報。

Part 5: Gmail Integration — Daily Top 10 Email Digest

Setup

Add the Gmail skill:

/add-gmail

Or install it manually:

bash

npx -y @lobehub/market-cli skills install gavrielc-nanoclaw-add-gmail

Google Cloud Console OAuth Setup

This is the most tedious part of the entire guide, but you only do it once:

Go to Google Cloud Console
Create a new project (e.g., "NanoClaw Gmail")
Navigate to APIs & Services > Library
Search for "Gmail API" and click Enable
Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Application type: Desktop app
Name: "NanoClaw" (or anything you like)
Click Create
Download the JSON file
Place it at ~/.gmail-mcp/credentials.json

First run will open a browser for OAuth consent. Click through:

"This app isn't verified" warning — click Advanced > Go to NanoClaw Gmail (unsafe)
This is normal for personal-use OAuth apps — Google shows this warning for any app not published to the marketplace
Grant the requested Gmail permissions
The refresh token is saved locally at ~/.gmail-mcp/token.json

Two Modes: Tool Mode vs Channel Mode

Mode	How It Works	When to Use
Tool Mode	Agent calls Gmail tools on-demand when you ask	Default. Safer. Agent only accesses email when you explicitly request it.
Channel Mode	NanoClaw polls your inbox and auto-processes new emails	Advanced. Enables auto-reply, auto-categorization. Higher prompt injection risk from malicious emails.

Start with Tool Mode. Switch to Channel Mode only if you want autonomous email processing.

Capabilities

Read — fetch individual emails, search by query, list threads
Send — compose and send emails (with your actual Gmail address as sender)
Search — full Gmail search syntax (from:boss@company.com after:2026/03/01 is:unread)
Draft — create drafts without sending
Thread context — agent understands email threads and can reply in-thread

Setting Up the Daily Digest

This is the killer use case. Send this to your admin channel:

@Andy every weekday at 7am, check my inbox, pick the 10 most important
emails, and send me a summary with sender, subject, and one-line synopsis.
Flag anything that needs urgent response.

NanoClaw creates a scheduled task (see Part 9) that:

Fires at 7:00 AM Monday–Friday
Spins up a container with Gmail tools
Runs a Gmail search for unread messages from the last 24 hours
Uses Claude to rank by importance (sender reputation, urgency keywords, your past interaction patterns)
Formats a clean summary
Sends it to your WhatsApp or Telegram

Example output you'd receive:

📧 Daily Email Digest — March 18, 2026

🔴 URGENT
1. Sarah Chen (CTO) — "Q1 Board Deck Review Needed"
   Needs your feedback by EOD. Deck attached.

2. AWS Billing — "Your March bill is $2,847"
   47% increase from last month. Unusual spike.

🟡 IMPORTANT
3. Legal Team — "Contract renewal for Acme Corp"
   New terms attached. Review deadline: March 22.

4. David Park — "Engineering hiring update"
   3 offers extended, 1 accepted. Pipeline review Thursday.

5. GitHub — "[my-repo] Security advisory: CVE-2026-1234"
   High severity. Affects dependencies.

🟢 FYI
6. Product Team — "Sprint retro notes"
7. HR — "Updated PTO policy effective April 1"
8. Conference — "Your talk proposal accepted"
9. Newsletter — "This Week in AI: March 18"
10. LinkedIn — "5 new connection requests"

Reply with a number to see the full email or take action.

Privacy Considerations

OAuth tokens are stored locally at ~/.gmail-mcp/token.json
Email content passes through the Claude API — Anthropic's API is stateless (no training on your data), but the content does leave your machine
Tool Mode minimizes exposure — the agent only reads emails you explicitly ask about
Channel Mode reads everything — every incoming email is sent to the Claude API for processing
Restrict to Tool Mode if email privacy is a concern

Part 5：Gmail 整合——每日 Top 10 重要信件摘要

設定

新增 Gmail skill：

/add-gmail

或手動安裝：

bash

npx -y @lobehub/market-cli skills install gavrielc-nanoclaw-add-gmail

Google Cloud Console OAuth 設定

這是整份指南中最繁瑣的部分，但只需要做一次：

前往 Google Cloud Console
建立新專案（例如「NanoClaw Gmail」）
導航至 APIs & Services > Library
搜尋「Gmail API」並點擊 Enable
前往 APIs & Services > Credentials
點擊 Create Credentials > OAuth client ID
Application type：Desktop app
Name：「NanoClaw」（或任何你喜歡的名字）
點擊 Create
下載 JSON 檔案
放在 ~/.gmail-mcp/credentials.json

第一次執行會開啟瀏覽器進行 OAuth 同意。一路點擊：

「This app isn't verified」警告——點擊 Advanced > Go to NanoClaw Gmail (unsafe)
這對個人使用的 OAuth app 是正常的——Google 對任何未發布到 marketplace 的 app 都會顯示此警告
授予要求的 Gmail 權限
Refresh token 會儲存在本地 ~/.gmail-mcp/token.json

兩種模式：Tool Mode vs Channel Mode

模式	運作方式	適用時機
Tool Mode	Agent 在你要求時按需呼叫 Gmail 工具	預設。較安全。Agent 只在你明確要求時存取 email。
Channel Mode	NanoClaw 輪詢你的收件匣並自動處理新 email	進階。支援自動回覆、自動分類。惡意 email 的 prompt injection 風險較高。

從 Tool Mode 開始。只有在你想要自主 email 處理時才切換到 Channel Mode。

功能

讀取——取得個別 email、依查詢搜尋、列出對話串
傳送——撰寫並傳送 email（使用你的實際 Gmail 地址作為寄件人）
搜尋——完整 Gmail 搜尋語法（from:boss@company.com after:2026/03/01 is:unread）
草稿——建立草稿但不傳送
對話串 context——agent 理解 email 對話串，可以在串內回覆

設定每日摘要

這是殺手級用例。在管理員頻道傳送：

@Andy every weekday at 7am, check my inbox, pick the 10 most important
emails, and send me a summary with sender, subject, and one-line synopsis.
Flag anything that needs urgent response.

NanoClaw 會建立一個排程任務（見 Part 9），它會：

週一到週五 7:00 AM 觸發
啟動一個有 Gmail 工具的容器
執行 Gmail 搜尋過去 24 小時的未讀訊息
使用 Claude 依重要性排名（寄件人信譽、緊急關鍵字、你過去的互動模式）
格式化一份簡潔摘要
傳送到你的 WhatsApp 或 Telegram

你會收到的範例輸出：

📧 每日信件摘要——2026 年 3 月 18 日

🔴 緊急
1. Sarah Chen（CTO）——「Q1 Board Deck Review Needed」
   需要你今天內回饋。簡報已附上。

2. AWS Billing——「Your March bill is $2,847」
   比上月增加 47%。異常飆升。

🟡 重要
3. 法務團隊——「Acme Corp 合約續約」
   新條款已附上。審查截止日：3 月 22 日。

4. David Park——「Engineering hiring update」
   已發 3 份 offer，1 人接受。週四 pipeline 審查。

5. GitHub——「[my-repo] Security advisory: CVE-2026-1234」
   高嚴重性。影響相依套件。

🟢 知會
6. 產品團隊——「Sprint retro 筆記」
7. HR——「更新的 PTO 政策，4 月 1 日生效」
8. 研討會——「你的演講提案已獲接受」
9. Newsletter——「This Week in AI: March 18」
10. LinkedIn——「5 個新連線請求」

回覆數字可查看完整 email 或採取行動。

隱私考量

OAuth token 儲存在本地 ~/.gmail-mcp/token.json
Email 內容會通過 Claude API——Anthropic 的 API 是無狀態的（不會用你的資料訓練），但內容確實會離開你的機器
Tool Mode 最小化曝露——agent 只讀取你明確要求的 email
Channel Mode 讀取所有——每封新進 email 都會傳送到 Claude API 處理
如果 email 隱私是顧慮，請限制使用 Tool Mode

Part 6: Product Price Comparison

Agent Browser Skill

NanoClaw containers come with the Agent Browser skill — a Chromium-based web automation toolkit. Unlike simple API calls, Agent Browser actually navigates web pages, reads content, clicks buttons, and extracts structured data.

Setup

Inside your NanoClaw project:

bash

npm install -g playwright && npx playwright install chromium

The Chromium binary is installed inside the container image. On M3 Pro, the ARM64 Chromium build runs natively — no Rosetta overhead.

Capabilities

Headless navigation — browse any website without a visible browser window
Page snapshots — capture the full DOM as structured text (not screenshots) for Claude to analyze
Semantic locators — find elements by visible text, ARIA labels, or role rather than brittle CSS selectors
Wait strategies — intelligent waiting for dynamic content (SPAs, lazy-loaded data)
Multi-tab support — open multiple pages simultaneously for comparison
Cookie/session management — maintain login sessions across requests

Example: Price Comparison

Send this to your admin channel:

@Andy compare prices for "Sony WH-1000XM5" across Amazon, Best Buy,
and B&H Photo. Table with price, shipping, availability.

The agent will:

Spawn a Chromium instance inside its Docker Sandbox
Navigate to each retailer's search page
Search for the product
Extract price, shipping info, and availability
Compile a comparison table

Example response:

Sony WH-1000XM5 — Price Comparison (March 18, 2026)

| Retailer   | Price    | Shipping          | Availability |
|------------|----------|-------------------|--------------|
| Amazon     | $278.00  | Free (Prime)      | In stock     |
| Best Buy   | $279.99  | Free (2-day)      | In stock     |
| B&H Photo  | $278.00  | Free (expedited)  | In stock     |

Lowest: Amazon and B&H Photo tied at $278.00.
Best Buy is $1.99 more but offers price-match guarantee.

Note: Amazon price was from a third-party seller (4.8★, 2,341 ratings).
B&H price is direct. Best Buy price is in-store and online.

Recurring Price Alerts

Set up automatic monitoring:

@Andy every day at 6pm, check the price of this product on Amazon:
https://amazon.com/dp/B0C8PSQWBJ
Message me if it drops below $200.

The agent creates a scheduled task that:

Navigates to the URL daily at 6 PM
Extracts the current price
Compares against your threshold ($200)
Only messages you if the condition is met
Optionally tracks price history in a local SQLite table

Limitations

CAPTCHAs — some sites serve CAPTCHAs to automated browsers. The agent cannot solve them (by design — this keeps you on the right side of ToS)
Bot detection — aggressive anti-bot measures (Cloudflare, PerimeterX) may block requests. Residential proxy support is not built in
JavaScript-heavy SPAs — some sites require complex interaction flows that time out
IP rate limiting — repeated requests from the same IP may trigger blocks. NanoClaw adds random delays between requests
Login-required pricing — member-only prices or cart-based pricing can't be accessed without credentials (and storing retailer credentials is a security risk)

Part 6：商品比價

Agent Browser Skill

NanoClaw 容器內建 Agent Browser skill——一個基於 Chromium 的網頁自動化工具包。與簡單的 API 呼叫不同，Agent Browser 實際上會瀏覽網頁、讀取內容、點擊按鈕、提取結構化資料。

設定

在你的 NanoClaw 專案中：

bash

npm install -g playwright && npx playwright install chromium

Chromium 二進位檔安裝在容器映像裡。在 M3 Pro 上，ARM64 Chromium build 原生執行——沒有 Rosetta 開銷。

功能

Headless 瀏覽——在沒有可見瀏覽器視窗的情況下瀏覽任何網站
頁面快照——將完整 DOM 擷取為結構化文字（不是截圖）供 Claude 分析
語意定位器——透過可見文字、ARIA 標籤或角色尋找元素，而非脆弱的 CSS 選擇器
等待策略——智慧等待動態內容（SPA、延遲載入資料）
多分頁支援——同時開啟多個頁面進行比較
Cookie/session 管理——跨請求維持登入 session

範例：比價

在管理員頻道傳送：

@Andy compare prices for "Sony WH-1000XM5" across Amazon, Best Buy,
and B&H Photo. Table with price, shipping, availability.

Agent 會：

在 Docker Sandbox 內啟動一個 Chromium 實例
導航到每個零售商的搜尋頁面
搜尋產品
提取價格、運費資訊和庫存狀態
彙整成比較表格

範例回應：

Sony WH-1000XM5——比價結果（2026 年 3 月 18 日）

| 零售商     | 價格     | 運費              | 庫存狀態   |
|------------|----------|-------------------|------------|
| Amazon     | $278.00  | 免費（Prime）     | 有貨       |
| Best Buy   | $279.99  | 免費（2 天）      | 有貨       |
| B&H Photo  | $278.00  | 免費（快速）      | 有貨       |

最低價：Amazon 和 B&H Photo 並列 $278.00。
Best Buy 貴 $1.99 但提供價格保證。

備註：Amazon 價格來自第三方賣家（4.8★，2,341 則評價）。
B&H 價格為直營。Best Buy 價格線上線下同價。

定期價格提醒

設定自動監控：

@Andy every day at 6pm, check the price of this product on Amazon:
https://amazon.com/dp/B0C8PSQWBJ
Message me if it drops below $200.

Agent 會建立一個排程任務：

每天下午 6 點導航到該 URL
提取當前價格
與你的門檻（$200）比較
只有在條件符合時才傳訊息給你
可選擇性地在本地 SQLite 表格中追蹤價格歷史

限制

CAPTCHA——某些網站會對自動化瀏覽器出 CAPTCHA。Agent 無法解決它們（這是設計如此——讓你不違反 ToS）
反 bot 偵測——激進的反 bot 措施（Cloudflare、PerimeterX）可能阻擋請求。不內建住宅代理支援
JavaScript 密集的 SPA——某些網站需要複雜的互動流程，可能超時
IP 速率限制——同一 IP 的重複請求可能觸發阻擋。NanoClaw 在請求之間加入隨機延遲
需登入才能看的價格——會員專屬價或購物車定價無法在沒有憑證的情況下存取（而儲存零售商憑證是安全風險）

Part 7: Knowledge Base with Obsidian

CLAUDE.md — Per-Group Persistent Memory

Every NanoClaw chat group gets its own CLAUDE.md file. This is the agent's persistent memory — preferences, context, and instructions that survive across sessions. Think of it as the agent's personal notebook for each conversation.

The main admin group's CLAUDE.md is at the project root (nanoclaw/CLAUDE.md). Non-main groups get theirs in store/groups/{group-id}/CLAUDE.md.

The agent reads CLAUDE.md at the start of every session and can update it when you tell it to remember something:

@Andy remember that I prefer responses in Traditional Chinese
@Andy remember my Obsidian vault is for investment research

Mount Allowlist for Obsidian

To give the agent access to your Obsidian vault, add it to the mount allowlist:

json

{
  "allowedRoots": [
    {
      "path": "~/Documents/GitHub/my_note",
      "allowReadWrite": true,
      "description": "Obsidian vault"
    }
  ]
}

Container Mount Configuration

In your NanoClaw config, map the host vault to a container path:

json

{
  "additionalMounts": [
    {
      "hostPath": "~/Documents/GitHub/my_note",
      "containerPath": "/workspace/extra/notes",
      "readWrite": true
    }
  ]
}

Inside the container, the agent accesses your Obsidian vault at /workspace/extra/notes/. Any changes it makes are reflected immediately on your host filesystem (and vice versa, since it's a bind mount).

Example Commands

Save conversation summaries:

@Andy summarize today's conversations and save to my Obsidian vault
under daily-notes/2026-03-18.md

The agent creates or appends to the file at ~/Documents/GitHub/my_note/daily-notes/2026-03-18.md with a structured summary of the day's interactions.

Search and synthesize:

@Andy search my notes for everything about "investment strategy" and
give me a synthesis

The agent uses grep and file traversal inside the container to find all matching notes, reads them, and produces a coherent synthesis — not just a list of matches, but a connected narrative.

Create structured notes from research:

@Andy research the current state of Taiwan semiconductor industry,
then save a structured note to my vault under research/semiconductors/
taiwan-2026-q1.md with sections for market overview, key players,
risks, and opportunities

Cross-reference and link:

@Andy find all notes in my vault that mention "TSMC" and add a
backlink section to each one pointing to research/semiconductors/
taiwan-2026-q1.md

Best Practices

CLAUDE.md for agent preferences — store the agent's personality, language preferences, and vault structure conventions here, not in the vault itself
Global folder for shared knowledge — create a _global/ folder in your vault for information all agents should know (investment thesis, company directory, project list)
Read-only mounts for non-main groups — if you share the bot with family or a team, give their groups read-only vault access so they can query but not modify your notes
Daily notes as an inbox — use daily-notes/ as a capture folder, then periodically ask the agent to organize and file items into the proper vault locations
Obsidian compatibility — the agent writes standard Markdown with [[wikilinks]] for internal links, which Obsidian recognizes natively. Front matter (YAML) is preserved when editing existing notes

Part 7：Obsidian 知識庫整合

CLAUDE.md——逐群組持久記憶

每個 NanoClaw 聊天群組都有自己的 CLAUDE.md 檔案。這是 agent 的持久記憶——偏好設定、context 和跨 session 存活的指示。把它想成 agent 針對每個對話的個人筆記本。

主管理員群組的 CLAUDE.md 在專案根目錄（nanoclaw/CLAUDE.md）。非主群組的在 store/groups/{group-id}/CLAUDE.md。

Agent 在每個 session 開始時讀取 CLAUDE.md，在你告訴它記住某事時可以更新它：

@Andy remember that I prefer responses in Traditional Chinese
@Andy remember my Obsidian vault is for investment research

Obsidian 的 Mount Allowlist

要讓 agent 存取你的 Obsidian vault，將它加入 mount allowlist：

json

{
  "allowedRoots": [
    {
      "path": "~/Documents/GitHub/my_note",
      "allowReadWrite": true,
      "description": "Obsidian vault"
    }
  ]
}

容器 Mount 設定

在你的 NanoClaw config 中，將主機 vault 對應到容器路徑：

json

{
  "additionalMounts": [
    {
      "hostPath": "~/Documents/GitHub/my_note",
      "containerPath": "/workspace/extra/notes",
      "readWrite": true
    }
  ]
}

在容器內部，agent 透過 /workspace/extra/notes/ 存取你的 Obsidian vault。它做的任何變更都會立即反映在你的主機檔案系統上（反之亦然，因為是 bind mount）。

指令範例

儲存對話摘要：

@Andy summarize today's conversations and save to my Obsidian vault
under daily-notes/2026-03-18.md

Agent 會在 ~/Documents/GitHub/my_note/daily-notes/2026-03-18.md 建立或附加一份當天互動的結構化摘要。

搜尋並綜合：

@Andy search my notes for everything about "investment strategy" and
give me a synthesis

Agent 使用容器內的 grep 和檔案走訪來找到所有匹配的筆記，讀取它們，並產生一份連貫的綜合報告——不只是匹配清單，而是有脈絡的敘述。

從研究建立結構化筆記：

@Andy research the current state of Taiwan semiconductor industry,
then save a structured note to my vault under research/semiconductors/
taiwan-2026-q1.md with sections for market overview, key players,
risks, and opportunities

交叉引用和連結：

@Andy find all notes in my vault that mention "TSMC" and add a
backlink section to each one pointing to research/semiconductors/
taiwan-2026-q1.md

最佳實踐

CLAUDE.md 存 agent 偏好——把 agent 的個性、語言偏好和 vault 結構慣例存在這裡，不要存在 vault 本身
Global 資料夾存共享知識——在 vault 中建立一個 _global/ 資料夾，存放所有 agent 都應該知道的資訊（投資論點、公司名錄、專案清單）
非主群組用唯讀 mount——如果你和家人或團隊共用 bot，給他們的群組唯讀 vault 存取權，讓他們可以查詢但不能修改你的筆記
Daily notes 作為收件匣——使用 daily-notes/ 作為暫存資料夾，然後定期請 agent 整理並歸檔到 vault 的適當位置
Obsidian 相容性——agent 寫入標準 Markdown 並使用 [[wikilinks]] 作為內部連結，Obsidian 原生支援。編輯既有筆記時會保留 front matter（YAML）

Part 8: Running an AI Company with Agent Swarm

The Vision

Instead of one assistant doing everything, imagine a team of specialized agents — each with its own identity, expertise, container, and memory. A "Researcher" that searches the web. A "Writer" that drafts content. A "Reviewer" that fact-checks. A "Scheduler" that manages deadlines. All coordinated through your messaging app.

NanoClaw makes this possible through Agent Swarm.

NanoClaw Agent Swarm

Agent Swarm is NanoClaw's built-in multi-agent framework. It works at three levels:

Level 1: Telegram Swarm Each Telegram bot becomes a separate "employee." Each bot has:

Its own BotFather token and identity
Its own system prompt defining its role
Its own Docker Sandbox container
Its own CLAUDE.md persistent memory
Access to shared mount points for collaboration

Level 2: Claude Code Agent Teams (built-in since v2.1.32) Within a single container, the main Claude Code process can spawn sub-agents:

A team lead decomposes the task into subtasks
Teammates work independently on their assigned subtasks
The team lead collects results and synthesizes the final output
This is faster than Telegram Swarm but less persistent

Level 3: NanoClaw Orchestration Layer NanoClaw adds on top of both levels:

Persistent memory — each agent remembers past interactions via CLAUDE.md
Scheduled triggers — agents can be awakened on a schedule, not just by messages
Message routing — the orchestrator routes messages to the right agent based on @-mentions or group context
Container isolation — each agent's container is firewalled from others
Shared mounts — agents collaborate through shared filesystem directories

Comparison: NanoClaw Agent Swarm vs Paperclip

Dimension	NanoClaw Agent Swarm	Paperclip
Focus	Personal assistant teams	Zero-human software companies
Architecture	Messaging-first (WhatsApp/Telegram)	Git-first (worktrees + PRs)
Agent types	General-purpose (research, writing, email, browsing)	Software-specific (PM, architect, dev, QA)
Governance	Admin channel approval	Automated PR review + CI gates
Cost control	Per-container usage tracking	Per-agent budget limits
Setup complexity	Low (NanoClaw does it)	Medium (requires repo structure)
Best for	Daily life automation, knowledge work	Software development at scale

Practical Setup

Send this to your admin channel:

@Andy create a swarm with these agents:
- Researcher: searches web, compiles reports
- Writer: drafts content from research
- Reviewer: proofreads and fact-checks
- Scheduler: manages deadlines and sends reminders

NanoClaw will:

Create 4 Telegram bots via BotFather (or use existing ones you provide)
Configure each with a specialized system prompt
Spin up 4 Docker Sandbox containers
Create a shared mount at /workspace/shared/ for file exchange
Add all bots to a Telegram group for inter-agent communication

Task Delegation

From your admin channel:

@Researcher research the top 5 AI assistant frameworks released in 2026.
Save your findings to the shared folder.

@Writer use the research in the shared folder to draft a blog post
comparing the top 5 frameworks. Target: 2000 words, technical audience.

@Reviewer review the draft at shared/blog-draft.md. Check all facts
against the research. Fix any errors and improve readability.

@Scheduler remind me in 3 days to review the final draft. Then remind
me again in 5 days to publish.

Each agent works in its own container. Files are exchanged through the shared mount. The admin channel gives you full visibility into what each agent is doing.

Claude Code Sub-Agent Architecture

When a single NanoClaw agent spawns Claude Code sub-agents, the architecture looks like this:

NanoClaw Container (agent-researcher)
├── Main Claude Code process (team lead)
│   ├── Sub-agent 1: "Search Google Scholar for papers on topic X"
│   ├── Sub-agent 2: "Search arXiv for recent preprints on topic X"
│   └── Sub-agent 3: "Search industry blogs for practical applications"
└── Results synthesized by team lead → response sent to chat

Each sub-agent runs as a separate Claude Code process within the same container. They share the filesystem but have independent context windows. The team lead manages coordination.

For Heavier Orchestration

If you need more structured workflows — approval gates, budget limits, audit trails — layer Paperclip on top:

bash

# Install Paperclip as a NanoClaw skill
npx -y @lobehub/market-cli skills install paperclip-orchestrator

Paperclip provides:

Role-based access control (RBAC) for agents
Budget caps per agent per day
Automated code review via PR-based workflows
Deterministic task graphs (DAGs) instead of free-form delegation

This is overkill for personal use but valuable for team settings.

Part 8：用 Agent Swarm 經營一間 AI 公司

願景

與其一個助手做所有事，想像一個專業化 agent 團隊——每個都有自己的身份、專長、容器和記憶。一個搜尋網路的「研究員」。一個撰寫內容的「寫手」。一個事實查核的「審查員」。一個管理截止日期的「排程師」。全部透過你的通訊 app 協調。

NanoClaw 透過 Agent Swarm 實現這一切。

NanoClaw Agent Swarm

Agent Swarm 是 NanoClaw 內建的多 agent 框架。它在三個層級運作：

層級 1：Telegram Swarm 每個 Telegram bot 成為一個獨立的「員工」。每個 bot 有：

自己的 BotFather token 和身份
自己的 system prompt 定義角色
自己的 Docker Sandbox 容器
自己的 CLAUDE.md 持久記憶
存取共享 mount 點以進行協作

層級 2：Claude Code Agent Teams（v2.1.32 起內建） 在單一容器內，主要的 Claude Code 程序可以產生子 agent：

Team lead 將任務分解為子任務
Teammate 獨立工作於各自分配的子任務
Team lead 收集結果並綜合最終輸出
這比 Telegram Swarm 更快，但較不持久

層級 3：NanoClaw 編排層 NanoClaw 在兩個層級之上增加：

持久記憶——每個 agent 透過 CLAUDE.md 記住過去的互動
排程觸發——agent 可以按排程被喚醒，不只是被訊息觸發
訊息路由——orchestrator 根據 @mention 或群組 context 將訊息路由到正確的 agent
容器隔離——每個 agent 的容器與其他的隔離
共享 mount——agent 透過共享的檔案系統目錄協作

比較：NanoClaw Agent Swarm vs Paperclip

面向	NanoClaw Agent Swarm	Paperclip
聚焦	個人助手團隊	零人軟體公司
架構	訊息優先（WhatsApp/Telegram）	Git 優先（worktree + PR）
Agent 類型	通用（研究、寫作、email、瀏覽）	軟體專用（PM、架構師、開發、QA）
治理	管理員頻道審批	自動化 PR review + CI 閘門
成本控制	逐容器使用量追蹤	逐 agent 預算限制
設定複雜度	低（NanoClaw 代勞）	中等（需要 repo 結構）
最適合	日常生活自動化、知識工作	大規模軟體開發

實戰設定

在管理員頻道傳送：

@Andy create a swarm with these agents:
- Researcher: searches web, compiles reports
- Writer: drafts content from research
- Reviewer: proofreads and fact-checks
- Scheduler: manages deadlines and sends reminders

NanoClaw 會：

透過 BotFather 建立 4 個 Telegram bot（或使用你提供的既有 bot）
為每個設定專門的 system prompt
啟動 4 個 Docker Sandbox 容器
建立共享 mount 在 /workspace/shared/ 用於檔案交換
將所有 bot 加入一個 Telegram 群組進行 agent 間通訊

任務委派

從你的管理員頻道：

@Researcher research the top 5 AI assistant frameworks released in 2026.
Save your findings to the shared folder.

@Writer use the research in the shared folder to draft a blog post
comparing the top 5 frameworks. Target: 2000 words, technical audience.

@Reviewer review the draft at shared/blog-draft.md. Check all facts
against the research. Fix any errors and improve readability.

@Scheduler remind me in 3 days to review the final draft. Then remind
me again in 5 days to publish.

每個 agent 在自己的容器中工作。檔案透過共享 mount 交換。管理員頻道讓你完全掌握每個 agent 正在做什麼。

Claude Code 子 Agent 架構

當單個 NanoClaw agent 產生 Claude Code 子 agent 時，架構如下：

NanoClaw Container (agent-researcher)
├── 主要 Claude Code 程序（team lead）
│   ├── 子 agent 1：「在 Google Scholar 搜尋主題 X 的論文」
│   ├── 子 agent 2：「在 arXiv 搜尋主題 X 的最新 preprint」
│   └── 子 agent 3：「搜尋業界部落格找主題 X 的實務應用」
└── Team lead 綜合結果 → 回應傳送到聊天

每個子 agent 作為同一容器內的獨立 Claude Code 程序運行。它們共享檔案系統但有獨立的 context window。Team lead 負責協調。

需要更重的編排時

如果你需要更結構化的工作流程——審批閘門、預算限制、稽核軌跡——在上面疊加 Paperclip：

bash

# 安裝 Paperclip 作為 NanoClaw skill
npx -y @lobehub/market-cli skills install paperclip-orchestrator

Paperclip 提供：

Agent 的角色存取控制（RBAC）
每個 agent 每天的預算上限
透過 PR 工作流程的自動化程式碼審查
確定性任務圖（DAG）取代自由形式的委派

對個人使用來說這過度了，但在團隊環境中很有價值。

Part 9: Scheduled Tasks Reference

Three Scheduling Types

NanoClaw supports three ways to schedule tasks:

1. Cron Expressions Standard cron syntax for recurring tasks:

@Andy schedule cron "0 7 * * 1-5" — check my inbox and send daily digest

This fires at 7:00 AM Monday through Friday.

2. Interval-Based Run a task every N minutes/hours:

@Andy schedule every 4 hours — check for new GitHub issues in my repos

3. One-Shot Run a task once at a specific time:

@Andy schedule at 2026-03-20 14:00 — remind me about the board meeting

Example Scheduled Tasks

Task	Schedule	Command
Daily email digest	Weekday 7 AM	`@Andy schedule cron "0 7 * * 1-5" — inbox digest top 10`
Price monitoring	Daily 6 PM	`@Andy schedule cron "0 18 * * *" — check Amazon price for [URL]`
Weekly KB review	Sunday 10 AM	`@Andy schedule cron "0 10 * * 0" — review my Obsidian vault, find orphan notes, suggest organization`
Sales pipeline	Weekday 9 AM	`@Andy schedule cron "0 9 * * 1-5" — check CRM dashboard, summarize pipeline changes`
Weekly report	Friday 5 PM	`@Andy schedule cron "0 17 * * 5" — compile weekly accomplishments from my daily notes`

Task Management Commands

@Andy list schedules          — show all scheduled tasks with IDs
@Andy pause schedule #3       — pause task #3 (keeps config, stops execution)
@Andy resume schedule #3      — resume a paused task
@Andy delete schedule #3      — permanently remove task #3
@Andy run schedule #3 now     — trigger task #3 immediately (doesn't affect schedule)
@Andy edit schedule #3 cron "0 8 * * 1-5"  — change the schedule

Configuration

The scheduler uses SCHEDULER_POLL_INTERVAL to determine how often it checks for due tasks:

bash

# In .env
SCHEDULER_POLL_INTERVAL=60000   # Check every 60 seconds (default)

Lower values = more responsive but higher CPU usage. For most use cases, the 60-second default is fine. If you need sub-minute precision (rare), set it to 10000 (10 seconds).

Scheduled tasks are stored in store/scheduler.db (SQLite). They survive restarts. The scheduler checks on every tick whether any task's next execution time has passed, and if so, spins up a container to execute it.

Part 9：排程任務參考

三種排程類型

NanoClaw 支援三種排程任務的方式：

1. Cron 表達式 標準 cron 語法，用於重複任務：

@Andy schedule cron "0 7 * * 1-5" — check my inbox and send daily digest

這會在週一到週五的 7:00 AM 觸發。

2. 間隔型 每 N 分鐘/小時執行一次任務：

@Andy schedule every 4 hours — check for new GitHub issues in my repos

3. 一次性 在特定時間執行一次任務：

@Andy schedule at 2026-03-20 14:00 — remind me about the board meeting

排程任務範例

任務	排程	指令
每日信件摘要	週間 7 AM	`@Andy schedule cron "0 7 * * 1-5" — inbox digest top 10`
價格監控	每天 6 PM	`@Andy schedule cron "0 18 * * *" — check Amazon price for [URL]`
每週知識庫審查	週日 10 AM	`@Andy schedule cron "0 10 * * 0" — review my Obsidian vault, find orphan notes, suggest organization`
銷售管線	週間 9 AM	`@Andy schedule cron "0 9 * * 1-5" — check CRM dashboard, summarize pipeline changes`
每週報告	週五 5 PM	`@Andy schedule cron "0 17 * * 5" — compile weekly accomplishments from my daily notes`

任務管理指令

@Andy list schedules          — 顯示所有排程任務及其 ID
@Andy pause schedule #3       — 暫停任務 #3（保留設定，停止執行）
@Andy resume schedule #3      — 恢復已暫停的任務
@Andy delete schedule #3      — 永久移除任務 #3
@Andy run schedule #3 now     — 立即觸發任務 #3（不影響排程）
@Andy edit schedule #3 cron "0 8 * * 1-5"  — 修改排程

設定

Scheduler 使用 SCHEDULER_POLL_INTERVAL 決定多久檢查一次到期任務：

bash

# 在 .env 中
SCHEDULER_POLL_INTERVAL=60000   # 每 60 秒檢查一次（預設）

數值越低 = 回應越快但 CPU 使用越高。大多數場景下，60 秒的預設值就夠了。如果你需要低於一分鐘的精確度（罕見），設為 10000（10 秒）。

排程任務儲存在 store/scheduler.db（SQLite）。它們在重啟後存活。Scheduler 在每次 tick 時檢查是否有任務的下次執行時間已過，如果是，就啟動一個容器來執行它。

Part 10: Cost Breakdown

Complete Cost Table

Component	Cost	Notes
NanoClaw	Free (MIT license)	Open source, self-hosted
WhatsApp	Free (Baileys library)	No Business API fees
Telegram	Free (Bot API)	Unlimited bots
Docker Desktop	Free for personal use	Paid for companies with 250+ employees or $10M+ revenue
Claude Code CLI	Free	Included with API access
Node.js	Free	Open source
Chromium (Playwright)	Free	Open source
Gmail OAuth	Free	Google Cloud free tier

The only variable cost is the Claude API usage.

Claude API Pricing (as of March 2026)

Model	Input (per MTok)	Output (per MTok)	Best For
Claude Opus 4.6	$5.00	$25.00	Complex reasoning, research synthesis
Claude Sonnet 4.6	$3.00	$15.00	General-purpose tasks (default)
Claude Haiku 4.5	$1.00	$5.00	Simple tasks, high-volume operations

MTok = million tokens. 1 million tokens is roughly 750,000 words.

Estimated Monthly Costs

Usage Level	Description	Estimated Cost
Light	5–10 messages/day, simple tasks	$5–15/month
Moderate	20–50 messages/day, email digest, occasional research	$20–50/month
Heavy	100+ messages/day, multi-agent swarm, constant browsing	$50–150+/month

Cost Optimization Strategies

1. Use Haiku for simple tasks Configure NanoClaw to route simple queries (reminders, lookups, formatting) to Haiku instead of Sonnet:

@Andy set model haiku for simple tasks

2. Enable prompt caching NanoClaw supports Anthropic's prompt caching. Repeated system prompts and CLAUDE.md content are cached, reducing input token costs by up to 90% for the cached portion.

bash

# In .env
ENABLE_PROMPT_CACHING=true

3. Use Ollama for free local inference For tasks that don't need Claude's reasoning power, run a local model:

bash

# Install Ollama
brew install ollama

# Pull a model
ollama pull llama3.3:70b

# Configure NanoClaw fallback
# In .env
LOCAL_MODEL_PROVIDER=ollama
LOCAL_MODEL_NAME=llama3.3:70b

Route low-stakes tasks (formatting, simple summaries, reminders) to the local model. Reserve Claude for complex reasoning, research, and multi-step tasks.

4. Set idle timeout aggressively Containers that stay alive consume API tokens for context maintenance. Set a short idle timeout:

bash

IDLE_TIMEOUT=120000   # 2 minutes instead of default 5

5. Monitor usage Check your costs regularly:

@Andy cost today
@Andy cost this week
@Andy cost breakdown by agent

Part 10：成本分析

完整費用表

組件	費用	備註
NanoClaw	免費（MIT 授權）	開源、自架
WhatsApp	免費（Baileys 函式庫）	無 Business API 費用
Telegram	免費（Bot API）	無限 bot
Docker Desktop	個人使用免費	250+ 員工或 $10M+ 營收的公司需付費
Claude Code CLI	免費	隨 API 存取附帶
Node.js	免費	開源
Chromium（Playwright）	免費	開源
Gmail OAuth	免費	Google Cloud 免費額度

唯一的變動成本是 Claude API 使用量。

Claude API 定價（截至 2026 年 3 月）

模型	輸入（每 MTok）	輸出（每 MTok）	最適合
Claude Opus 4.6	$5.00	$25.00	複雜推理、研究綜合
Claude Sonnet 4.6	$3.00	$15.00	通用任務（預設）
Claude Haiku 4.5	$1.00	$5.00	簡單任務、大量操作

MTok = 百萬 token。100 萬 token 大約是 75 萬字。

預估月費

使用層級	描述	預估費用
輕度	每天 5–10 則訊息、簡單任務	$5–15/月
中度	每天 20–50 則訊息、email 摘要、偶爾研究	$20–50/月
重度	每天 100+ 則訊息、多 agent swarm、持續瀏覽	$50–150+/月

費用優化策略

1. 簡單任務用 Haiku 設定 NanoClaw 將簡單查詢（提醒、查詢、格式化）路由到 Haiku 而非 Sonnet：

@Andy set model haiku for simple tasks

2. 啟用 prompt caching NanoClaw 支援 Anthropic 的 prompt caching。重複的 system prompt 和 CLAUDE.md 內容會被快取，快取部分的輸入 token 成本最多可降低 90%。

bash

# 在 .env 中
ENABLE_PROMPT_CACHING=true

3. 使用 Ollama 進行免費本地推理 對不需要 Claude 推理能力的任務，跑一個本地模型：

bash

# 安裝 Ollama
brew install ollama

# 拉取模型
ollama pull llama3.3:70b

# 設定 NanoClaw fallback
# 在 .env 中
LOCAL_MODEL_PROVIDER=ollama
LOCAL_MODEL_NAME=llama3.3:70b

將低風險任務（格式化、簡單摘要、提醒）路由到本地模型。把 Claude 留給複雜推理、研究和多步驟任務。

4. 積極設定 idle timeout 存活的容器會消耗 API token 來維護 context。設定較短的 idle timeout：

bash

IDLE_TIMEOUT=120000   # 2 分鐘而非預設的 5 分鐘

5. 監控使用量 定期檢查你的費用：

@Andy cost today
@Andy cost this week
@Andy cost breakdown by agent

Part 11: Troubleshooting Quick Reference

Common Issues and Solutions

Problem	Likely Cause	Solution
WhatsApp "Conflict" error	Another WhatsApp Web session is active	Close all other WhatsApp Web tabs/apps. Only one NanoClaw session can be active alongside your phone.
WhatsApp QR expired	Took longer than 60 seconds to scan	Refresh the QR code by restarting `/add-whatsapp`. Have your phone ready before generating the QR.
WhatsApp session drops after sleep	Laptop was sleeping for extended period	NanoClaw auto-reconnects. If it doesn't, restart: `npm run start`. Credentials are preserved.
Docker not starting	Docker Desktop not running or insufficient memory	Restart Docker Desktop. Ensure at least 8 GB RAM allocated in Docker Settings > Resources.
Container won't start	Stale container state	Run `docker sandbox ls` to check status. Then `docker sandbox rm {name}` and recreate.
Gmail OAuth "app isn't verified"	Normal for personal OAuth apps	Click Advanced > Go to app (unsafe). This is expected — your app isn't published to Google's marketplace.
Gmail token expired	Token hasn't been refreshed in 7+ days	Delete `~/.gmail-mcp/token.json` and re-authenticate by running `/add-gmail`.
Agent stuck in loop	Rate limit hit or infinite reasoning loop	Check `@Andy status` in admin channel. Increase `IDLE_TIMEOUT`. If stuck, `@Andy stop all` and restart.
High API costs	Using Opus for everything	Switch default model to Sonnet or Haiku. Enable prompt caching. Set shorter `IDLE_TIMEOUT`.
Agent Browser timeout	Target site has aggressive anti-bot measures	Try a different retailer. Some sites (Cloudflare-protected) will consistently block headless Chromium.
Mount permission denied	Path not in allowlist or blocked pattern matched	Check `~/.config/nanoclaw/mount-allowlist.json`. Ensure the path is listed and `allowReadWrite` matches your needs.
Telegram bot not responding	Bot token invalid or webhook conflict	Verify token with BotFather. Ensure no other service is using the same bot token.
Scheduled task not firing	Scheduler tick interval too long	Check `SCHEDULER_POLL_INTERVAL` in `.env`. Verify task exists with `@Andy list schedules`.
Container out of memory	Too many concurrent containers	Reduce `MAX_CONCURRENT_CONTAINERS`. On 18 GB M3 Pro, 4 is safe; 6 is the practical limit.

Diagnostic Commands

bash

# Check NanoClaw process status
npm run status

# View orchestrator logs (last 100 lines)
npm run logs -- --tail 100

# Check container resource usage
docker sandbox ls --format "table {{.Name}}\t{{.Status}}\t{{.Memory}}"

# Test API key validity
claude --print "ping" 2>&1 | head -5

# Test WhatsApp connection
npm run test:whatsapp

# Test Telegram connection
npm run test:telegram

# Full health check
npm run verify

When All Else Fails

Stop everything: npm run stop
Kill orphan containers: docker sandbox ls | xargs -I{} docker sandbox rm {}
Clear caches: rm -rf store/cache/
Preserve credentials: Keep store/auth/ and .env intact
Restart: npm run start

This resolves 90% of issues. If it doesn't, check the NanoClaw GitHub Issues or the Discord community.

Part 11：疑難排解快速參考

常見問題與解決方案

問題	可能原因	解決方案
WhatsApp「Conflict」錯誤	另一個 WhatsApp Web session 正在運行	關閉所有其他 WhatsApp Web 分頁/app。NanoClaw session 只能和你的手機並存一個。
WhatsApp QR 過期	掃描超過 60 秒	重啟 `/add-whatsapp` 刷新 QR code。在產生 QR 前先準備好手機。
WhatsApp session 在休眠後中斷	筆電長時間休眠	NanoClaw 會自動重連。如果沒有，重啟：`npm run start`。憑證會保留。
Docker 無法啟動	Docker Desktop 未運行或記憶體不足	重啟 Docker Desktop。確認在 Docker Settings > Resources 中至少分配 8 GB RAM。
容器無法啟動	過時的容器狀態	執行 `docker sandbox ls` 檢查狀態。然後 `docker sandbox rm {name}` 並重建。
Gmail OAuth「app isn't verified」	個人 OAuth app 的正常現象	點擊 Advanced > Go to app (unsafe)。這是預期的——你的 app 沒有發布到 Google marketplace。
Gmail token 過期	Token 超過 7 天未刷新	刪除 `~/.gmail-mcp/token.json` 並重新執行 `/add-gmail` 認證。
Agent 卡在迴圈中	速率限制或無限推理迴圈	在管理員頻道檢查 `@Andy status`。增加 `IDLE_TIMEOUT`。如果卡住了，`@Andy stop all` 並重啟。
API 費用過高	所有事都用 Opus	將預設模型切換為 Sonnet 或 Haiku。啟用 prompt caching。縮短 `IDLE_TIMEOUT`。
Agent Browser 超時	目標網站有激進的反 bot 措施	換一個零售商試試。某些網站（Cloudflare 保護的）會持續阻擋 headless Chromium。
Mount 權限被拒	路徑不在 allowlist 或匹配到阻擋模式	檢查 `~/.config/nanoclaw/mount-allowlist.json`。確認路徑已列出且 `allowReadWrite` 符合你的需求。
Telegram bot 沒回應	Bot token 無效或 webhook 衝突	用 BotFather 驗證 token。確認沒有其他服務在用同一個 bot token。
排程任務未觸發	Scheduler tick 間隔太長	檢查 `.env` 中的 `SCHEDULER_POLL_INTERVAL`。用 `@Andy list schedules` 驗證任務存在。
容器記憶體不足	太多同時運行的容器	減少 `MAX_CONCURRENT_CONTAINERS`。在 18 GB 的 M3 Pro 上，4 個是安全的；6 個是實際上限。

診斷指令

bash

# 檢查 NanoClaw 程序狀態
npm run status

# 查看 orchestrator 日誌（最後 100 行）
npm run logs -- --tail 100

# 檢查容器資源使用
docker sandbox ls --format "table {{.Name}}\t{{.Status}}\t{{.Memory}}"

# 測試 API key 有效性
claude --print "ping" 2>&1 | head -5

# 測試 WhatsApp 連線
npm run test:whatsapp

# 測試 Telegram 連線
npm run test:telegram

# 完整健康檢查
npm run verify

當一切都不管用時

停止一切： npm run stop
殺掉孤立容器： docker sandbox ls | xargs -I{} docker sandbox rm {}
清除快取： rm -rf store/cache/
保留憑證： 保持 store/auth/ 和 .env 不動
重啟： npm run start

這解決 90% 的問題。如果還是不行，查看 NanoClaw GitHub Issues 或 Discord 社群。

Closing Thoughts

You now have a fully operational AI assistant running on your MacBook M3 Pro. It lives in WhatsApp and Telegram — the apps you already use. It's secured by hypervisor-level container isolation. It reads your email, compares prices, manages your knowledge base, and can scale into a multi-agent company when you need it to.

Total infrastructure cost: $0/month (excluding Claude API usage).

The M3 Pro is quietly one of the best machines for this setup. 18 GB of unified memory handles 4–6 concurrent agent containers without breaking a sweat. The ARM64 native support means no emulation overhead. And the machine's efficiency means you can leave NanoClaw running all day without draining your battery.

Start with one agent on WhatsApp. Add Gmail when you're comfortable. Experiment with price alerts. Build your knowledge base. And when you're ready, spin up the swarm.

Your AI company is a /setup away.

結語

你現在有一個在 MacBook M3 Pro 上完整運行的 AI 助手。它住在 WhatsApp 和 Telegram 裡——你本來就在用的 app。它被 hypervisor 層級的容器隔離保護。它讀你的 email、幫你比價、管理你的知識庫，在你需要時還能擴展成多 agent 公司。

總基礎設施費用：$0/月（不含 Claude API 使用量）。

M3 Pro 悄悄地成為這種設定最好的機器之一。18 GB 統一記憶體輕鬆處理 4–6 個同時運行的 agent 容器。ARM64 原生支援意味著沒有模擬開銷。而這台機器的效率意味著你可以讓 NanoClaw 整天運行而不會耗盡電池。

從 WhatsApp 上的一個 agent 開始。等你習慣了再加 Gmail。嘗試價格提醒。建立你的知識庫。當你準備好了，啟動 swarm。

你的 AI 公司只差一個 /setup。

NanoClaw on MacBook M3 Pro ​

Complete Deployment Guide From Setup to AI Company ​

NanoClaw MacBook M3 Pro 部署與實戰完全指南 ​

從安裝到 AI 公司 ​

Who This Guide Is For ​

這份指南適合誰 ​

Part 1: Prerequisites and Installation ​

Prerequisites ​

Fork and Clone ​

Launch Claude Code and Run Setup ​

Docker Sandboxes for Apple Silicon ​

Apple Containers Alternative ​

Key Environment Variables ​

Directory Structure After Setup ​

Verification ​

Part 1：前置需求與安裝 ​

前置需求 ​

Fork 並 Clone ​

啟動 Claude Code 並執行 Setup ​

Apple Silicon 的 Docker Sandboxes ​

Apple Containers 替代方案 ​

關鍵環境變數 ​

設定完成後的目錄結構 ​

驗證 ​

Part 2: WhatsApp Setup (Free) ​

Why It's Free ​

Setup ​

Authentication Methods ​

Step-by-Step Linking ​

Session Persistence ​

Media Support ​

Limitations ​

Admin Channel ​

Part 2：WhatsApp 設定（免費） ​

為什麼是免費的 ​

設定方式 ​

驗證方式 ​

逐步連結 ​

Session 持久化 ​

媒體支援 ​

限制 ​

管理員頻道 ​

Part 3: Telegram as Fallback (Also Free) ​

Why Telegram as a Second Channel ​

Create a Bot via @BotFather ​

Setup in NanoClaw ​

Telegram Swarm Skill ​

Telegram vs WhatsApp Quick Comparison ​

Part 3：Telegram 作為備用（也免費） ​

為什麼要有第二頻道 ​

透過 @BotFather 建立 Bot ​

在 NanoClaw 中設定 ​

Telegram Swarm Skill ​

Telegram vs WhatsApp 快速比較 ​

Part 4: Security Deep Dive ​

Mount Allowlist ​

7-Step Validation Process ​

Default Blocked Patterns ​

Three-Tier Privilege Model ​

Docker Sandboxes on M3 Pro ​

Why --dangerously-skip-permissions Is Safe Here ​

The "Lethal Trifecta" Limitation ​

Part 4：安全深入剖析 ​

Mount Allowlist ​

7 步驟驗證流程 ​

預設阻擋模式 ​

三層權限模型 ​

M3 Pro 上的 Docker Sandboxes ​

為什麼 --dangerously-skip-permissions 在這裡是安全的 ​

「致命三連」限制 ​

Part 5: Gmail Integration — Daily Top 10 Email Digest ​

Setup ​

Google Cloud Console OAuth Setup ​

Two Modes: Tool Mode vs Channel Mode ​

Capabilities ​

Setting Up the Daily Digest ​

Privacy Considerations ​

Part 5：Gmail 整合——每日 Top 10 重要信件摘要 ​

設定 ​

Google Cloud Console OAuth 設定 ​

NanoClaw on MacBook M3 Pro

Complete Deployment Guide From Setup to AI Company

NanoClaw MacBook M3 Pro 部署與實戰完全指南

從安裝到 AI 公司

Who This Guide Is For

這份指南適合誰

Part 1: Prerequisites and Installation

Prerequisites

Fork and Clone

Launch Claude Code and Run Setup

Docker Sandboxes for Apple Silicon

Apple Containers Alternative

Key Environment Variables

Directory Structure After Setup

Verification

Part 1：前置需求與安裝

前置需求

Fork 並 Clone

啟動 Claude Code 並執行 Setup

Apple Silicon 的 Docker Sandboxes

Apple Containers 替代方案

關鍵環境變數

設定完成後的目錄結構

驗證

Part 2: WhatsApp Setup (Free)

Why It's Free

Setup

Authentication Methods

Step-by-Step Linking

Session Persistence

Media Support

Limitations

Admin Channel

Part 2：WhatsApp 設定（免費）

為什麼是免費的

設定方式

驗證方式

逐步連結

Session 持久化

媒體支援

限制

管理員頻道

Part 3: Telegram as Fallback (Also Free)

Why Telegram as a Second Channel

Create a Bot via @BotFather

Setup in NanoClaw

Telegram Swarm Skill

Telegram vs WhatsApp Quick Comparison

Part 3：Telegram 作為備用（也免費）

為什麼要有第二頻道

透過 @BotFather 建立 Bot

在 NanoClaw 中設定

Telegram Swarm Skill

Telegram vs WhatsApp 快速比較

Part 4: Security Deep Dive

Mount Allowlist

7-Step Validation Process

Default Blocked Patterns

Three-Tier Privilege Model

Docker Sandboxes on M3 Pro

Why `--dangerously-skip-permissions` Is Safe Here

The "Lethal Trifecta" Limitation

Part 4：安全深入剖析

Mount Allowlist

7 步驟驗證流程

預設阻擋模式

三層權限模型

M3 Pro 上的 Docker Sandboxes

為什麼 `--dangerously-skip-permissions` 在這裡是安全的

「致命三連」限制

Part 5: Gmail Integration — Daily Top 10 Email Digest

Setup

Google Cloud Console OAuth Setup

Two Modes: Tool Mode vs Channel Mode

Capabilities

Setting Up the Daily Digest

Privacy Considerations

Part 5：Gmail 整合——每日 Top 10 重要信件摘要

設定

Google Cloud Console OAuth 設定