nanoclaw：500 行 TypeScript 实现的安全隔离 Claude 个人助手

nanoclaw 是一个极简的个人 AI 助手框架，核心代码大约 500 行，主要使用 TypeScript 和 Node.js 编写。它的目标不是把功能堆到最满，而是把 Claude 这类 AI Agent 的本地执行风险降下来。

本地 AI Agent 最危险的地方不在“聊天”，而在“能执行工具”。一旦它可以调用 Shell、读写文件、联网请求，就不再只是一个问答系统，而是一个能对本机环境产生实际影响的自动化程序。

如果 Agent 直接运行在宿主系统上，模型误判、提示词注入、工具调用参数生成错误，都可能造成真实损失。比如它执行了下面这种命令：

rm -rf /

普通聊天机器人只是回复一句话，本地 Agent 却可能真的把命令交给系统执行。nanoclaw 的核心设计就是：不要让 Agent 直接拿到宿主机的完整操作权限。

它采用的思路很明确：

用尽量少的代码实现核心 Agent 能力；
每个会话、每个任务都运行在独立的 macOS Apple 容器中；
让 AI 可以在隔离文件系统里执行命令，而不是直接操作宿主机；
保留个人助手常见能力，例如记忆、联网、定时任务。

本地 Agent 为什么需要隔离

一个典型的本地 Agent 通常由三部分组成：

大语言模型负责理解任务和规划步骤；
Agent 框架负责把模型输出转换成工具调用；
本地工具负责执行命令、读写文件、访问网络。

问题出在第三步。只要工具在宿主机上执行，AI 的错误就会变成系统层面的错误。

flowchart LR
    U[用户输入任务] --> LLM[Claude 生成计划]
    LLM --> A[Agent 框架解析工具调用]
    A --> SH[宿主机 Shell]
    SH --> FS[(宿主机文件系统)]
    SH --> NET[网络请求]
    FS --> A
    NET --> A
    A --> LLM
    LLM --> U

这种结构简单直接，但安全边界很弱。Agent 能访问什么，主要取决于当前用户权限。如果当前用户能删除某个目录，Agent 通常也能删除；如果当前用户环境变量里有密钥，Agent 也可能读取到。

对于个人开发者来说，这类风险很常见：

风险类型	例子	影响
误删文件	生成错误 Shell 命令，删除工作目录	代码、配置、数据丢失
泄露密钥	读取 `.env`、SSH Key、云服务凭证	账号和基础设施风险
污染环境	修改全局 npm、Python、系统配置	本机开发环境异常
提示词注入	网页内容诱导 Agent 执行恶意指令	Agent 被外部内容劫持
资源失控	死循环、无限下载、频繁请求	CPU、内存、网络被占满

Agent 的安全边界不能只依赖模型“听话”。更可靠的做法是让操作系统提供隔离，把危险操作限制在一个可丢弃的运行环境里。

nanoclaw 的核心机制：一个任务一个沙盒

nanoclaw 使用 macOS 的原生容器能力，为会话和任务创建隔离环境。可以把它理解成：Claude 仍然负责思考，nanoclaw 负责调度，但真正执行命令的地方被放进了容器。

flowchart TB
    U[用户] --> C[Claude / Claude Code]
    C --> N[nanoclaw 调度层]

    subgraph HOST[macOS 宿主机]
        N --> M[会话与任务管理]
        M --> AC[Apple 容器管理]
    end

    AC --> S1[Session A 容器]
    AC --> S2[Session B 容器]

    subgraph CA[Session A 隔离环境]
        S1 --> FA[(隔离文件系统)]
        S1 --> TA[Shell / 工具执行]
        S1 --> NA[网络访问]
    end

    subgraph CB[Session B 隔离环境]
        S2 --> FB[(隔离文件系统)]
        S2 --> TB[Shell / 工具执行]
    end

这种结构的关键点在于：AI 执行命令时，影响范围被限制在容器内部。即使模型生成了破坏性命令，它删除的也是容器里的临时文件系统，而不是宿主机的完整目录。

执行流程可以拆成几步：

sequenceDiagram
    participant User as 用户
    participant Claude as Claude
    participant Nano as nanoclaw
    participant Container as Apple 容器
    participant FS as 隔离文件系统

    User->>Claude: 提交任务
    Claude->>Nano: 请求执行工具或命令
    Nano->>Container: 在对应会话容器中运行
    Container->>FS: 读写隔离环境内的文件
    FS-->>Container: 返回结果
    Container-->>Nano: 返回命令输出
    Nano-->>Claude: 提供执行结果
    Claude-->>User: 生成回复

这套设计带来的变化很直接：

宿主机不再是 Agent 的默认工作区；
会话之间天然隔离，A 会话的文件不会直接污染 B 会话；
任务失败时，可以丢弃容器环境，重新创建干净环境；
安全边界由操作系统容器提供，而不是完全依赖提示词约束。

“500 行代码”意味着什么

nanoclaw 的另一个特点是代码量很小。轻量并不只是“看起来简洁”，它在 Agent 框架里有实际意义。

AI Agent 框架通常会连接很多高风险能力：Shell、文件系统、网络、定时任务、记忆存储。代码越复杂，审计安全边界越困难；依赖越多，隐藏行为越多。

nanoclaw 选择把核心逻辑压缩到约 500 行 TypeScript，重点放在几个基础能力上：

能力	作用
Claude 集成	把用户任务交给 Claude，由模型生成执行计划
会话管理	为不同对话维护独立上下文
容器隔离	使用 macOS Apple 容器运行任务
文件系统隔离	避免 Agent 直接操作宿主机文件
联网能力	允许任务访问外部信息
定时任务	支持周期性或延迟执行的个人助手任务
记忆能力	让助手在会话中保留必要状态

代码少并不等于功能更强，它的优势是更容易理解和修改。对于想研究 Agent 框架实现方式的人来说，小型项目比大型框架更适合拆开看：入口在哪里、工具如何调度、容器如何创建、执行结果如何回传，都更容易追踪。

和 OpenClaw、Nanobot 的区别

nanoclaw 更像是一个“安全优先的极简版本”，而不是全功能平台。把它和几个类似项目放在一起看，取向会更清楚。

项目	技术取向	主要特点	适合场景	不适合场景
OpenClaw	功能完整型 Agent 框架	能力和生态更丰富，但整体更重	需要完整 Agent 平台、插件体系、复杂任务编排	只想快速理解核心实现，或只需要个人轻量助手
Nanobot	超轻量 Python 方案	用较少代码复刻同类 Agent 能力，便于研究和二次开发	偏 Python 技术栈、教学、实验、快速改造	对 macOS 容器隔离有强需求
nanoclaw	TypeScript + Node.js，安全优先	约 500 行核心代码，强调 macOS 容器隔离	macOS 用户、本地 Claude 助手、安全敏感的个人任务	Windows/Linux 环境、需要大型平台能力、需要完整企业级权限系统

如果目标是“功能越多越好”，nanoclaw 不是最合适的选择。它更适合这样的需求：想要一个能执行本地任务的 Claude 助手，但不希望 AI 直接在主系统上乱跑。

适合使用 nanoclaw 的场景

nanoclaw 的价值集中在个人本地 Agent，而不是大规模团队平台。

比较适合：

在 macOS 上使用 Claude 做个人自动化；
希望 Agent 能执行命令，但不想直接暴露宿主机；
想研究轻量 Agent 框架的实现方式；
想基于 TypeScript/Node.js 改造自己的助手；
对安全隔离比复杂插件生态更敏感。

不太适合：

主要使用 Windows 或 Linux；
需要多用户权限管理、审计后台、团队协作能力；
需要大量现成插件和复杂工作流编排；
需要把宿主机大量目录直接挂进执行环境；
期望开箱即用覆盖所有企业级 Agent 场景。

安装和启动

项目地址：

https://github.com/gavrielc/nanoclaw

基础启动流程很短：

git clone https://github.com/gavrielc/nanoclaw.git
cd nanoclaw
claude

进入 Claude Code 后运行：

/setup

/setup 会处理初始化工作，包括依赖安装、认证、容器设置和服务配置。完成后，就可以通过 Claude 把任务交给 nanoclaw，由它在隔离环境中执行。

可以把启动过程理解成两层：

flowchart LR
    A[克隆 nanoclaw 仓库] --> B[进入项目目录]
    B --> C[启动 Claude Code]
    C --> D[运行 /setup]
    D --> E[配置依赖与认证]
    E --> F[配置 Apple 容器环境]
    F --> G[开始使用隔离 Agent]

使用时要注意的边界

容器隔离能显著降低破坏宿主机的风险，但它不是万能安全方案。使用这类本地 Agent 时，仍然需要控制好权限和数据边界。

不要随意挂载敏感目录

如果把宿主机的家目录、代码仓库、密钥目录完整暴露给容器，隔离效果会明显下降。更稳妥的做法是只给任务提供必要目录。

例如，优先使用临时工作区：

mkdir -p ~/nanoclaw-workspaces/task-001

不要把下面这些路径随意开放给 Agent：

~/.ssh
~/.aws
~/.config
~/Library
~/Documents

不要把密钥放进任务环境

如果任务需要访问外部服务，尽量使用范围更小、权限更低、可随时撤销的 Token。不要直接把主账号密钥交给 Agent。

联网能力也需要边界

即使文件系统被隔离，联网能力仍然可能带来数据泄露风险。只要 Agent 能读取到某些内容，并且能访问外部网络，就有可能把内容发送出去。

小代码量不等于零风险

500 行核心代码更容易审计，但依赖、运行环境、Claude Code、容器配置都仍然属于整体安全边界的一部分。真正使用前，应当看清楚它创建了什么服务、赋予了哪些权限、容器能访问哪些路径。

macOS 依赖限制了适用范围

nanoclaw 的隔离能力依赖 macOS 原生容器技术。对于非 macOS 环境，不能直接获得同样的运行模型。跨平台需求强的场景，需要考虑其他容器方案或 Agent 框架。

小型 Agent 框架的核心取舍

nanoclaw 的取舍很清晰：牺牲一部分“大而全”的框架能力，换来更少的代码和更强的本地隔离边界。

它解决的不是“怎么做一个最强 Agent”，而是一个更具体的问题：当 Claude 需要在本机执行任务时，怎样避免它直接接触主系统。

对于个人助手来说，这个问题非常现实。AI Agent 越能干活，就越需要限制它能碰到什么。nanoclaw 的做法是把任务放进容器，让 Agent 有地方执行命令，也有边界可以约束破坏范围。

菜单