NanoClaw

你的个人 AI Agent。安全、轻量、真正属于你。

NanoClaw 将 Claude 驱动的 Agent 工作流运行在隔离容器中，支持消息通道、计划任务、分组记忆与 AI 原生定制，同时保持足够精简，便于理解、审计与修改。

开始使用 GitHub

运行流程

消息输入

通道

SQLite

群组队列

容器

Claude SDK

响应

NanoClaw 由单个 Node.js 主进程编排消息、队列、容器、IPC、存储与响应流程，并按群组边界隔离。

支持能力

消息通道、定时任务、分组记忆、容器隔离与 Skills 扩展都在同一套轻量架构中运行。

消息应用

默认先支持 WhatsApp，Telegram、Slack、Discord、Gmail、Signal 等通道通过 Skills 扩展。

容器隔离

Agent 在 macOS 上使用 Apple Container，在 macOS 与 Linux 上使用 Docker，并且只暴露显式挂载路径。

Agent 协作

NanoClaw 可以组织具备不同职责的 Agent 协同处理更复杂的个人任务。

分组记忆

每个群组都有独立的 CLAUDE.md、文件系统、会话状态和工作历史。

计划任务

定时任务可自动运行 Claude，并回传摘要、评审、提醒或日报。

Skills 系统

新能力通过 Claude Code Skills 扩展，避免核心不断膨胀。

AI 原生配置

Claude Code 可以完成安装、依赖检查、认证配置、运行时初始化以及后续改造。

网页访问

NanoClaw 可以搜索网络、抓取页面并为研究型工作流提供信息。

为什么是 NanoClaw？

它保留了个人 AI Agent 真正有价值的能力，同时把代码规模、依赖数量与复杂度控制在更容易掌握的范围内。

指标	NanoClaw	OpenClaw
源码文件数	15	3,680
代码行数	约 3,900	434,453
依赖数量	<10	70
配置文件	0	53
理解时间	8 分钟	1-2 周
安全模型	操作系统级容器隔离	应用层检查
架构	单进程 + 隔离容器	单进程，共享内存

设计理念

保持核心足够小，以隔离保障安全，面向个人使用，并通过 Skills 扩展能力。

足够小，便于理解

一个主进程，少量核心文件，没有微服务迷宫。

以隔离保障安全

安全核心依赖容器边界、显式挂载与非 root 执行。

面向单个用户

NanoClaw 的目标是成为你自己的专属分叉，而不是通用控制台。

AI 原生

安装、修改、调试与扩展通过 Claude Code 驱动完成。

Skills 优先于堆功能

只要不必进入核心的新集成都应该尽量做成 Skills。

原生对接 Claude

NanoClaw 基于 Claude Agent SDK，因此能直接发挥 Claude Code 的能力。

3 行命令快速开始

克隆仓库、进入目录、启动 Claude Code，然后在 Claude 提示符中运行 /setup。

git clone https://github.com/seaoss/nanoclaw

cd nanoclaw

claude

在 Claude Code 中运行 /setup

运行要求

macOS 或 Linux
Node.js 20+
Claude Code
Apple Container（macOS）或 Docker（macOS/Linux）
Claude Code OAuth Token 或 Anthropic API Key

常用命令

/setup

/add-whatsapp

/add-telegram

/add-gmail

/customize

/convert-to-apple-container

使用示例

@Andy 在每个工作日早上 9 点发送销售管道概览

@Andy 每周五检查过去一周的 git 历史并在有偏差时更新 README

@Andy 每周一早上 8 点整理 AI 动态并发我一份简报

@Andy 列出所有群组中的计划任务

@Andy 暂停周一简报任务

@Andy 加入 Family Chat 群组

核心教程

安装01

Installation and requirements

Quick start is git clone, cd nanoclaw, claude, then /setup inside Claude Code.
Supported platforms are macOS and Linux with Node.js 20+.
Container runtime is Apple Container on macOS or Docker on macOS/Linux.
Authentication can use Claude Code OAuth or Anthropic API keys.

通道02

Channel system

Channels are not hardcoded into the base product; they self-register through a registry and are commonly installed by skills.
A channel factory can return null if credentials are missing, allowing startup to skip unavailable channels cleanly.
Each channel implements connect, sendMessage, isConnected, ownsJid, disconnect, and optional typing or group sync methods.

记忆03

Folder structure and runtime layout

Important paths include groups/, store/, data/sessions/, data/ipc/, logs/, container/, and .claude/skills/.
Groups are the main isolation unit and each gets its own working directory and memory files.
Session data for each group is stored independently under data/sessions/{group}/.claude/.

安全04

Configuration model

Configuration is concentrated in src/config.ts rather than scattered across many config files.
Important settings include assistant name, polling intervals, scheduler interval, container image, timeout, idle timeout, max concurrency, and trigger regex.
Mount paths must be absolute because container mounts require absolute host paths.

安装05

Memory and sessions

Global memory lives in groups/CLAUDE.md and is writable only from the trusted main channel.
Each group also has groups/{group}/CLAUDE.md plus local markdown files and working files.
The Claude Agent SDK loads parent and current CLAUDE.md files, producing hierarchical memory behavior.
Group sessions are isolated to prevent leakage across chats.

通道06

Message flow and execution

Messages are stored in SQLite, polled by the host loop, and dispatched into a per-group FIFO queue.
GroupQueue enforces ordered execution within a group and limits global concurrency with retry backoff.
The container runner starts an isolated execution environment, runs Claude Agent SDK, and streams the response back to the channel.

记忆07

Commands and customization

Core operational commands include /setup, /add-whatsapp, /add-telegram, /add-gmail, /customize, and /convert-to-apple-container.
Customization is intentionally code-centric: instead of giant settings panels, you ask Claude Code to modify the fork for your needs.
Trigger word changes, response style changes, and new integrations are handled through AI-native workflows.

安全08

Scheduled tasks and MCP

NanoClaw supports recurring jobs, interval jobs, cron-like schedules, and one-shot tasks.
Tasks can send follow-up messages, compile briefings, review repositories, or automate recurring workflows.
MCP tools are available inside the agent runtime, while task and message operations are validated by the host through IPC authorization.

安装09

Deployment

NanoClaw can be run directly in development or configured as a background service after setup.
On macOS, launchd placeholders such as PROJECT_ROOT, NODE_PATH, and HOME must be set correctly when using service files.
Docker is the default cross-platform runtime, while Apple Container is available on macOS for a more native isolation path.

通道10

Security model

Trust model: main group is trusted, non-main groups are untrusted, container agents are sandboxed, and incoming messages are treated as user input.
Primary boundary is container isolation with explicit mounts, isolated filesystems, non-root execution, and ephemeral containers.
The mount allowlist lives outside the project root and is never mounted into containers.
Sensitive patterns such as .ssh, .gnupg, .aws, .azure, .gcloud, .kube, .docker, credentials, .env, .netrc, .npmrc, and private keys are blocked.
Real credentials do not enter containers; a host-side credential proxy injects auth headers on outbound model requests.

权限边界

能力	主群组	非主群组
项目根目录访问	/workspace/project（只读）	无
群组目录	/workspace/group（读写）	/workspace/group（读写）
全局记忆	通过项目隐式获得	/workspace/global（只读）
附加挂载	可配置	除非允许否则只读
网络访问	不受限	不受限
MCP 工具	全部	全部

云服务器推荐

将配套服务部署到云服务器

如果你需要部署文档镜像、Webhook 中转、管理后台或支持 API，云服务器能提供更稳定的运行环境与弹性扩展能力。

阿里云 ECS

适合部署文档站、机器人服务、后台系统与 API 的弹性 Linux 云服务器。

腾讯云 CVM

适合承载稳定部署、自动化任务与扩容场景的云服务器实例。

常见问题

NanoClaw 是什么？

NanoClaw 是一个围绕 Claude Agent SDK 构建的轻量级开源个人 AI Agent。它运行在你自己的机器上，通过消息应用工作，并将每次 Agent 会话放在隔离容器中执行。

NanoClaw 和 OpenClaw 有什么不同？

NanoClaw 反对框架膨胀，核心代码更小、依赖更少、主进程更简单，并使用操作系统级容器隔离，而不是主要依赖应用层检查。

NanoClaw 安全吗？

NanoClaw 的安全设计围绕容器隔离、显式挂载、会话隔离、宿主侧 IPC 授权、外部挂载白名单与凭据代理展开，避免敏感信息进入 Agent 容器。

NanoClaw 支持哪些消息应用？

默认重点路径是 WhatsApp，Telegram、邮箱以及其他通道通过 Skills 系统与模块化通道架构扩展。

支持哪些容器运行时？

NanoClaw 在 macOS 上支持 Apple Container 与 Docker，在 Linux 上支持 Docker。

我该如何配置 NanoClaw？

核心配置流程是 AI 原生的。你只需要在 Claude Code 中运行 /setup，让它引导你完成依赖检查、认证、容器设置和服务配置。

能在 Linux 上运行吗？

可以。NanoClaw 同时支持 macOS 和 Linux，Linux 上默认使用 Docker。

可以接入第三方模型网关吗？

可以。你可以通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 配置兼容 Anthropic 协议的模型服务。