夜雨聆风
30.1k星NanoClaw:Docker容器Claude官方AI管家,OpenClaw轻量平替多渠道记忆定时主动办事
1. 项目概述
NanoClaw 是一个轻量级、个人可完全掌控的开源 AI 代理框架，核心运行在用户本地机器上，通过 Docker（或 Docker Sandboxes 微 VM、Apple Container opt-in）将每个 Agent Group 隔离在独立 Linux 容器中执行。Host 端为单进程 Node.js/TypeScript 编排器，Agent 端使用 Anthropic 官方 Claude Agent SDK（容器内 Bun 运行时）。提供与 OpenClaw 类似的核心能力，但代码库极小（易于理解与修改）、安全边界为真实 OS 容器隔离而非仅应用层权限检查、无配置膨胀、无共享内存。
核心功能点：
●多渠道消息接入（Multi-channel Messaging）：支持 WhatsApp（Baileys 实现）、Telegram、Slack、Discord、Microsoft Teams、iMessage、Matrix、Google Chat、Webex、Linear、GitHub、WeChat、Email（Resend）。渠道通过skills按需安装（/add-xxx 或 ncl 相关命令），非核心内置，避免 bloat。每个渠道适配器负责接收（webhook/poll/websocket）、过滤触发（正则/@mention/状态ful）、提取标准化 ID（platformChannelId + platformThreadId，支持 per-thread 或 shared session 灵活性）、出站富内容投递（支持 Block Kit、embeds、buttons、streaming post+edit 等，平台不支持时优雅降级为文本）。Chat SDK 桥接或直接实现，concurrency 配置 per-channel（chat 并发、tasks 队列、webhooks debounce）。
●灵活隔离模型（Flexible Isolation V2，三级解耦 messaging_groups 与 agent_groups）：通过 DB wiring（messaging_group_agents 表，含 session_mode、trigger_rules、priority）实现。
○Level 1: Shared Session (agent-shared)：多渠道汇聚同一会话线程，Agent 看到跨平台完整上下文。适合 webhook 通知 + 聊天渠道联动（如 GitHub PR + Slack 讨论）。
○Level 2: Same Agent, Separate Sessions (shared / per-thread)：共享 workspace/memory/CLAUDE.md/personality（统一身份与长期记忆），但每个渠道/线程独立会话历史与 DB。适合个人多平台/多群统一 Agent。
○Level 3: Separate Agent Groups：完全隔离（独立 workspace、memory、CLAUDE.md、container、session DBs）。适合隐私边界严格场景（朋友群 vs 团队频道）。
规则：参与者相同 → Level 2 通常够；不同人或敏感信息 → Level 3。配置通过 /manage-channels 或 ncl wirings 完成 per-channel 决策。实体模型：agent_groups（workspace 等）↔ messaging_groups（平台具体 channel/chat） via wirings。
●Per-Agent Workspace 与 Templates：每个 agent group 拥有独立文件夹（groups/ 下）、CLAUDE.md、memory、skills 覆盖层、container 配置、仅显式允许的 mounts。Templates是可复用蓝图（public registry nanocoai/nanoclaw-templates 或本地 templates/ 目录）：必须含 context/instructions.md（persona，system-prompt 级，prepend 到 CLAUDE.md），可选 additional_context/*.md（相对路径引用）、.mcp.json（MCP servers，仅 command/args，无 secrets）、skills/
●Scheduled Tasks（定时任务）：自然语言定义 recurring jobs（如 “@Andy send an overview of the sales pipeline every weekday at 9am”），Agent 执行后可回消息。Host sweep（60s 周期）检测 due-message 并 wake 对应 container。支持 list scheduled tasks 等管理。
●Web Access 与 Tools：Agent 可搜索/获取网页内容。通过 Claude 内置工具或 MCP servers（如模板示例中的 exa-mcp-server）实现。MCP servers 在 template .mcp.json 声明，credentials 由 vault 代理注入。
●Credential Security（OneCLI Agent Vault / Credential Proxy）：核心安全亮点。Agents 永远不持有 raw API keys。Outbound HTTPS 全部路由经 OneCLI gateway 注入（host/path 匹配，request-time 注入），支持 per-group policy、rate limits、approval-gating（敏感操作 DM 审批者）。Placeholder env 仅用于 MCP 启动检查（真实 key 不进 env/container）。.env 被 /dev/null shadow，mount allowlist 外部 immutable（~/.config/nanoclaw/mount-allowlist.json），默认阻断 .ssh/.aws 等。Egress lockdown（opt-in）：容器走 Docker –internal network + nanoclaw-egress gateway，无直接互联网。
●Providers 灵活切换：原生 Claude（官方 SDK，最佳 harness，支持 Claude Code 自我修改 fork）。通过 skills 安装替代：/add-opencode（OpenRouter/Google/DeepSeek 等）、/add-ollama-provider（本地模型）、/add-codex（OpenAI）。Per agent group 配置。
●Skills 扩展模型（Skills over Features）： Trunk（核心）仅提供 registry 与基础设施。Channels/providers 作为capability skills存于长生命周期分支（channels/providers），通过 /add-
●AI-Native 混合设计：脚本化 happy path 快速安装；需判断步骤（失败诊断、定制决策）无缝 handoff 给 Claude Code（/debug、/customize）。无复杂 dashboard，问题描述即调试。Customization = code changes（小代码库安全修改），或自然语言让 Claude Code 编辑。
●其他实用功能：Per-session 双 SQLite（inbound/outbound messages_in/out，everything is message，包括 chat/tasks/webhooks/system actions/agent-to-agent）；Media 处理（inbound URL 传 container 内下载/处理，Claude native content blocks 支持 images/PDF/audio 等，不支持则 disk fallback）；Local CLI 渠道；Web access；Container 生命周期（wake spawn、idle kill、MAX_CONCURRENT 限制）；Mount 控制与 non-root/ephemeral 容器；Supply chain 防护（pnpm minReleaseAge、onlyBuiltDependencies allowlist）。
与其他方案对比亮点：OpenClaw ~50 万行 + 53 config + 70+ deps，应用层 sandbox；NanoClaw 极简 + 真实容器 OS 隔离 + 无共享内存 + 零 raw key 暴露 + 技能 additive 扩展。
2. 详细安装方法
环境要求（macOS/Linux/WSL2）：Node.js 20+、pnpm 10+、Docker Desktop/Engine（或 Docker Sandboxes / Apple Container opt-in）、Claude Code（setup/customize/debug 必需）。Windows 推荐 WSL2。
推荐一键脚本安装（官方 happy path）：
●●●bash git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2cd nanoclaw-v2 bash nanoclaw.sh
nanoclaw.sh是 wrapper：
●Phase 1: bootstrap（setup.sh 安装/验证 Node/pnpm/native modules，记录 logs/setup.log）。
●Phase 2: pnpm run setup:auto（setup/auto.ts 驱动交互 wizard）。
Wizard 步骤（clack/prompts 渲染，结构化日志 Level 1-3）：
1.bootstrap 验证。
2.environment 检查 Docker/Apple Container。
3.container 构建 nanoclaw-agent:latest 镜像。
4.user-input display_name。
5.channel_choice（Telegram/Discord/WhatsApp/local CLI 等）。
6.auth（Anthropic credential via OneCLI，OAuth 流程，token 不进日志）。
7.add-telegram 等非交互 skill 安装。
8.pair-telegram（输出 pairing code/status blocks）。
失败时自动 handoff Claude Code 诊断恢复。完成后拥有已配置 container、Anthropic token、首个 paired channel 与 agent。
从 v1 迁移：
●●●bash git clone ... nanoclaw-v2 cd nanoclaw-v2 bash migrate-v2.sh # 或指定 NANOCLAW_V1_PATH
脚本发现 v1 安装，迁移 state/DB/group data/scheduled tasks/channel auth（含 WhatsApp Baileys keystore + LID），exec Claude Code 处理需判断部分（owner seeding、CLAUDE.local.md cleanup、fork replay）。v1 保留不动，手动切换服务。
从源码手动/开发安装：
克隆后运行 nanoclaw.sh（它处理 bootstrap + pnpm install + Docker build）。或手动：
●pnpm install
●根据 package.json scripts 构建/运行（tsconfig、vitest 等）。
●Docker 相关在 container/ 与 Dockerfile（Bun + Claude SDK）。
●首次仍建议走 wizard 获取 OneCLI 凭证与 pairing。
Dev 时可用 worktrees、Claude Code 直接编辑 fork。
高级隔离运行时：默认 Docker；/convert-to-apple-containeropt-in macOS native；Docker Sandboxes 微 VM（更高隔离，参考 docs/docker-sandboxes.md）。
验证与首次使用：消息 paired channel 的 agent（trigger 规则 per wiring）。用 ncl groups create –template … 创建新 group；/manage-channels 配置 wiring/isolation/session_mode/triggers。
卸载：bash nanoclaw.sh --uninstall（dry-run/yes/manual cleanup 指引）或 uninstall.sh。服务管理：launchd/（mac）或其他。
Post-install：Agent 可立即用自然语言交互，Claude Code 随时可用/customize或聊天描述变更。
3. 高效使用方法与最佳实践
●渠道连接与 Wiring：安装 skill 后，/manage-channels 或 ncl wirings create 配置 isolation 级别、trigger_rules（@mention/regex/allowlist）、session_mode、priority。Auto-registration 规则 baked 在 adapter code（sender allowlist 等），DB 存 per-group 动态配置。
●与 Agent 交互：自然语言 + trigger。示例：
○日常任务 + 定时：”send sales overview every weekday at 9am”
○管理：”list all scheduled tasks”
○调试：”/debug” 或直接在 Claude Code 会话描述问题。
富内容（cards/buttons/streaming）自动 graceful degradation。
●模板高效创建专业 Agent：setup wizard 或ncl groups create --template sales/sdr --name "SDR Agent"（ref 相对 templates/ 目录，安全拒绝 ../ 逃逸）。Stamp 后 wiring 渠道。Persona 聚焦 <200 行 instructions.md，bulk 放 skills/ 或 additional_context/（instructions.md 内相对路径引用）。MCP servers 声明无 secrets，credentials on-demand 或 upfront 注册 vault（401 时 Agent 回复预填 connect link，用户粘贴后重试）。
●定制与扩展：
○AI 原生：聊天描述 “Change trigger word to @Bob”、”Add custom good morning greeting”，Claude Code 直接编辑代码（小代码库安全）。
○Guided：/customize。
○Skills 化扩展：新渠道/provider 作为 skill（channels/providers 分支 fetch + additive copy + tests）。贡献新 skill 需 integration tests（验证 barrel 注册、config、build/typecheck）。Fork = recipe，升级 rebuild 避免冲突。
○手动代码改也行，但建议 skill 化以 survive /update-nanoclaw。
●高级实践与 Edge Cases：
○隔离选择 nuance：隐私优先选 Level 3（信息绝不 cross-pollinate）；上下文连贯选 Level 1/2（但注意 non-main group IPC 限制：仅 own chat/tasks）。
○Media：大文件/视频在 container 内处理，避免 host 带宽。
○并发/性能：MAX_CONCURRENT_CONTAINERS 限制；idle timeout 杀容器；per-adapter concurrency。
○Scheduled 管理：自然语言设，sweep wake；跨 group 任务受 IPC 授权限制（main group 特权更高）。
○Provider 迁移：/add-xxx skill + ncl groups config update per-group。
○故障恢复：Claude Code /debug；upgrade-recovery.md 指引；snapshot before upgrade。
○MCP + Approval：敏感 action 可配置 proxy hold + DM 审批（roadmap 完善中）。
○多 Agent：并行多个 group/container，按需 wake。
○本地优先：全 offline 可能（Ollama provider + local MCP），但 web/MCP 需 egress。
最佳实践总结：从 template 起步 → wiring 选合适 isolation → 自然语言日常 + 定时 → Claude Code 深度定制 → skill 扩展新能力。始终 fork 定制，保持 recipe 可重现升级。
4. 技术原理、架构与实现
整体架构：单 Host 进程（Node.js/TS）作为 orchestrator + 多个 per-session container（Docker/Bun + Claude Agent SDK）。无 microservices、无 message broker、无共享内存。唯一跨边界 IO 是per-session 双 SQLite（inbound.db：host → agent-runner；outbound.db：agent-runner → host）。Everything is a message（chat/tasks/webhooks/system/agent-to-agent）。
详细消息流（核心实现）：
Platform event → Channel adapter（filter/trigger check、提取 platformChannelId + platformThreadId、返回 triggered）→ Host router 查 DB wirings 映射到 agent_group + session → 写 session inbound.db → wakeUpAgent（若无 container 则 spawn）→ Container 内 agent-runner 立即 poll DB → Claude 处理（tools/memory/MCP/context from instructions.md + CLAUDE.md + session history）→ 写 outbound.db → Host delivery poll 读响应 → 查 conversation → adapter 投递。
关键组件实现（src/ 核心文件）：
●src/index.ts：入口，DB init、adapters 注册、delivery poll、sweep 启动。
●src/router.ts：inbound 路由，entity model 映射。
●src/delivery.ts：outbound poll + deliver + system actions 处理。
●src/container-runner.ts：spawn container、OneCLI config 注入（applyContainerConfig 路由 HTTPS 经 gateway）、mounts。
●src/host-sweep.ts：60s 周期，stale 检测、due-message wake、recurrence 处理。
●src/db/：Central DB（users/roles/agent_groups/messaging_groups/wirings/migrations）；Per-session DBs 挂载入 container。
Container Lifecycle：wake 按需 spawn（–rm ephemeral，非 root uid 1000）；idle timeout 杀；并发上限保护。
Channel Adapter 机制：自注册（startup）。Code 层固定：auto-reg 规则、sender allowlist、platform conn。DB 层动态：wiring、trigger、session_mode、response scope。Chat SDK 桥接处理 webhook/dedup/history/rich content；NanoClaw 专注 routing/lifecycle。Thread-level subscribe（Chat SDK）与 channel-level registration 解耦。
DB 设计哲学：Two-level（central routing + per-session comms）。为什么双 DB per session？单一 writer、无 contention、无 IPC 复杂性、清晰 ownership、简单 polling 模型。Session ≠ Agent Group：group = FS/skills/CLAUDE.md；session = 对话线程 + 专属 DB（多 session 可共享 group FS）。
Credential & Security 实现（SECURITY.md 深度）：
●Vault：onecli secrets create 注册 → gateway 匹配注入 → 绝不进 container/env/files/stdout。
●Mounts：外部 allowlist + symlink/path 验证 + 非 main group read-only + blocked patterns（.ssh 等）。
●Egress：–internal network + gateway-only，fail-fast。
●Trust：main group trusted（全权）；non-main untrusted（prompt injection 防范、IPC 限 own chat）。
●Defense in depth + least privilege + “what’s not mounted can’t be attacked”。
Skills & Templates 实现：
●Templates：stamp 时 copy context/ + .mcp.json + skills/ 到 group workspace；instructions.md prepend system prompt。
●Skills：registry branch fetch (git show) → additive copy（文件/imports/config/Dockerfile edits）+ tests 注入。Recipe 驱动 apply 顺序。无 stale frozen copy。
其他实现细节：
●Media：URL 传 container，agent-runner 检测类型 → native blocks（Claude 支持 images/PDF/audio）或 disk。
●Scheduled：自然语言 → DB 存储 → sweep 检测 due → wake + agent 执行。
●Provider：SDK 抽象，per-group config。
●小代码库优势：8 分钟可理解全貌；Claude Code 安全 walk-through/edit。
设计权衡与 Nuances：Polling DB 而非 push/IPC → 简单、可靠、无 contention，但有轻微延迟（可接受）。Container vs 纯进程 sandbox → 真实隔离但有 Docker overhead（可接受换安全）。Skills additive → 升级安全但需测试 guard。Isolation 灵活 → 强大但需用户理解 trade-off（context 连贯 vs 隐私）。
NanoClaw 以极简代码 + 真实容器隔离 + AI 原生 + 技能扩展，解决了个人 AI 代理的安全、掌控、定制、长期维护痛点。特别适合已有 OpenClaw 经验或追求本地优先/隐私的用户。“可理解、可 bespoke”的工具——fork 它，让 Claude Code 帮你塑造成完美贴合个人需求的版本。
推荐路径：立即 clone + nanoclaw.sh 体验 → 选 template 创建专业 agent → 实验三级 isolation → 用 Claude Code 深度定制 → 贡献/自制 skills 扩展。关注 docs/ 下 architecture.md、isolation-model.md、SECURITY.md、templates.md、skills-model.md、setup-flow.md 等，结合 src/ 源码阅读，技术深度自现。