Skip to content

funcman/nanobot013p7

Repository files navigation

nanobot

nanobot: 超轻量级 (Ultra-Lightweight) 个人 AI 助手

PyPI Downloads Python License Feishu WeChat Discord

🐈 nanobot 是一个受 OpenClaw 启发 的超轻量级 (ultra-lightweight) 个人 AI 助手。

📖 这份代码是 nanobot 的 v0.1.3.post7 版本,主要用于源码阅读。此版本的代码量比最新版本要少不少,约六千多行 Python。

⚡️ 核心 agent 功能仅需约 4,000 行代码 — 比 Clawdbot 的 430k+ 行少 99%

📏 实时代码行数:3,582 行(运行 bash core_agent_lines.sh 随时验证)。

📢 新闻 (News)

  • 2026-02-12 🧠 重新设计的记忆系统 (memory system) — 更少的代码,更高的可靠性。参与讨论
  • 2026-02-10 🎉 发布 v0.1.3.post6,各项改进!查看更新说明和我们的路线图
  • 2026-02-09 💬 新增 Slack、Email 和 QQ 支持 — nanobot 现已支持多个聊天平台!
  • 2026-02-08 🔧 重构 Provider — 现在只需 2 个简单步骤即可添加新的 LLM provider!查看此处
  • 2026-02-07 🚀 发布 v0.1.3.post5,支持 Qwen 及多项关键改进!查看详情
  • 2026-02-06 ✨ 新增 Moonshot/Kimi provider、Discord 集成和安全加固!
  • 2026-02-05 ✨ 新增飞书 (Feishu) 频道、DeepSeek provider 和增强的定时任务支持!
  • 2026-02-04 🚀 发布 v0.1.3.post4,支持多 provider 和 Docker!查看详情
  • 2026-02-03 ⚡ 集成 vLLM,支持本地 LLM 和改进的自然语言任务调度!
  • 2026-02-02 🎉 nanobot 正式发布!欢迎体验 🐈 nanobot!

nanobot 的主要特点 (Key Features):

🪶 超轻量级 (Ultra-Lightweight):仅约 4,000 行核心 agent 代码 — 比 Clawdbot 小 99%。

🔬 适合研究 (Research-Ready):代码清晰易读,易于理解、修改和扩展,用于研究目的。

⚡️ 闪电般快速 (Lightning Fast):最小化的占用空间意味着更快的启动、更低的资源消耗和更快的迭代。

💎 易于使用 (Easy-to-Use):一键部署,即可使用。

🏗️ 架构 (Architecture)

nanobot architecture

✨ 功能 (Features)

📈 24/7 实时市场分析 (Real-Time Market Analysis)

🚀 全栈软件工程师 (Full-Stack Software Engineer)

📅 智能日程管理 (Smart Daily Routine Manager)

📚 个人知识助手 (Personal Knowledge Assistant)

发现 • 洞察 • 趋势 (Discovery • Insights • Trends) 开发 • 部署 • 扩展 (Develop • Deploy • Scale) 调度 • 自动化 • 整理 (Schedule • Automate • Organize) 学习 • 记忆 • 推理 (Learn • Memory • Reasoning)

📦 安装 (Install)

从源码安装 (latest features, recommended for development)

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

使用 uv 安装 (stable, fast)

uv tool install nanobot-ai

从 PyPI 安装 (stable)

pip install nanobot-ai

🚀 快速开始 (Quick Start)

Tip

~/.nanobot/config.json 中设置你的 API key。 获取 API keys: OpenRouter (全球) · Brave Search (可选,用于网络搜索)

1. 初始化 (Initialize)

nanobot onboard

2. 配置 (Configure) (~/.nanobot/config.json)

对于 OpenRouter - 推荐全球用户使用:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

3. 聊天 (Chat)

nanobot agent -m "What is 2+2?"

就这样!你可以在 2 分钟内拥有一个可用的 AI 助手。

🖥️ 本地模型 (Local Models) (vLLM)

使用 vLLM 或任何 OpenAI 兼容服务器运行带有你自己的本地模型的 nanobot。

1. 启动你的 vLLM 服务器 (Start your vLLM server)

vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

2. 配置 (Configure) (~/.nanobot/config.json)

{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

3. 聊天 (Chat)

nanobot agent -m "Hello from my local LLM!"

Tip

对于不需要认证的本地服务器,apiKey 可以是任何非空字符串。

💬 聊天应用 (Chat Apps)

通过 Telegram、Discord、WhatsApp、飞书 (Feishu)、Mochat、钉钉 (DingTalk)、Slack、Email 或 QQ 与你的 nanobot 交谈 — 随时随地。

渠道 (Channel) 设置难度 (Setup)
Telegram 简单 (Easy) (只需一个 token)
Discord 简单 (Easy) (bot token + intents)
WhatsApp 中等 (Medium) (扫描 QR)
飞书 (Feishu) 中等 (Medium) (app credentials)
Mochat 中等 (Medium) (claw token + websocket)
钉钉 (DingTalk) 中等 (Medium) (app credentials)
Slack 中等 (Medium) (bot + app tokens)
Email 中等 (Medium) (IMAP/SMTP credentials)
QQ 简单 (Easy) (app credentials)
Telegram (推荐 / Recommended)

1. 创建一个 bot (Create a bot)

  • 打开 Telegram,搜索 @BotFather
  • 发送 /newbot,按照提示操作
  • 复制 token

2. 配置 (Configure)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

你可以在 Telegram 设置中找到你的 User ID。显示为 @yourUserId去掉 @ 符号后复制此值,粘贴到配置文件中。

3. 运行 (Run)

nanobot gateway
Mochat (Claw IM)

默认使用 Socket.IO WebSocket,并有 HTTP polling 作为后备。

1. 让 nanobot 为你设置 Mochat

只需发送此消息给 nanobot(将 xxx@xxx 替换为你的真实邮箱):

Read https://raw.githubusercontent.com/HKUDS/MoChat/refs/heads/main/skills/nanobot/skill.md and register on MoChat. My Email account is xxx@xxx Bind me as your owner and DM me on MoChat.

nanobot 将自动注册、配置 ~/.nanobot/config.json 并连接到 Mochat。

2. 重启 gateway (Restart gateway)

nanobot gateway

就这样 — nanobot 会处理其余一切!


手动配置 (advanced)

如果你更喜欢手动配置,将以下内容添加到 ~/.nanobot/config.json

保持 claw_token 私密。它只应在你向 Mochat API 端点发送的 X-Claw-Token header 中使用。

{
  "channels": {
    "mochat": {
      "enabled": true,
      "base_url": "https://mochat.io",
      "socket_url": "https://mochat.io",
      "socket_path": "/socket.io",
      "claw_token": "claw_xxx",
      "agent_user_id": "6982abcdef",
      "sessions": ["*"],
      "panels": ["*"],
      "reply_delay_mode": "non-mention",
      "reply_delay_ms": 120000
    }
  }
}
Discord

1. 创建一个 bot (Create a bot)

2. 启用 intents (Enable intents)

  • 在 Bot 设置中,启用 MESSAGE CONTENT INTENT
  • (可选)如果你计划使用基于成员数据的允许列表,启用 SERVER MEMBERS INTENT

3. 获取你的 User ID (Get your User ID)

  • Discord 设置 → 高级 → 启用 开发者模式 (Developer Mode)
  • 右键点击你的头像 → 复制用户 ID (Copy User ID)

4. 配置 (Configure)

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

5. 邀请 bot (Invite the bot)

  • OAuth2 → URL Generator
  • Scopes: bot
  • Bot Permissions: Send Messages, Read Message History
  • 打开生成的邀请 URL,将 bot 添加到你的服务器

6. 运行 (Run)

nanobot gateway
WhatsApp

需要 Node.js ≥18

1. 关联设备 (Link device)

nanobot channels login
# 用 WhatsApp → 设置 → 已关联的设备 扫描 QR

2. 配置 (Configure)

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

3. 运行 (Run) (两个终端 / two terminals)

# Terminal 1
nanobot channels login

# Terminal 2
nanobot gateway
飞书 (Feishu)

使用 WebSocket 长连接 — 无需公网 IP。

1. 创建一个飞书 bot (Create a Feishu bot)

  • 访问 飞书开放平台 (Feishu Open Platform)
  • 创建新应用 → 启用 Bot 能力
  • 权限 (Permissions):添加 im:message(发送消息)
  • 事件 (Events):添加 im.message.receive_v1(接收消息)
    • 选择长连接 (Long Connection) 模式(需要先运行 nanobot 以建立连接)
  • 从"凭证与基础信息"获取 App IDApp Secret
  • 发布应用

2. 配置 (Configure)

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": []
    }
  }
}

长连接模式下 encryptKeyverificationToken 是可选的。 allowFrom:留空允许所有用户,或添加 ["ou_xxx"] 限制访问。

3. 运行 (Run)

nanobot gateway

[!TIP] 飞书使用 WebSocket 接收消息 — 无需 webhook 或公网 IP!

QQ (QQ单聊)

使用 botpy SDK 配合 WebSocket — 无需公网 IP。目前仅支持私聊 (private messages)

1. 注册并创建 bot (Register & create bot)

  • 访问 QQ 开放平台 (QQ Open Platform) → 注册为开发者(个人或企业)
  • 创建新的 bot 应用
  • 进入开发设置 (Developer Settings) → 复制 AppIDAppSecret

2. 设置沙箱进行测试 (Set up sandbox for testing)

  • 在 bot 管理控制台中找到沙箱配置 (Sandbox Config)
  • 消息列表配置下,点击添加成员并添加你自己的 QQ 号
  • 添加后,用手机 QQ 扫描 bot 的 QR 码 → 打开 bot 个人资料 → 点击"发消息"开始聊天

3. 配置 (Configure)

  • allowFrom:留空公开访问,或添加用户 openid 限制访问。你可以在 nanobot 日志中找到 openid,当用户向 bot 发消息时。
  • 对于生产环境:在 bot 控制台提交审核并发布。查看 QQ Bot 文档 了解完整的发布流程。
{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "secret": "YOUR_APP_SECRET",
      "allowFrom": []
    }
  }
}

4. 运行 (Run)

nanobot gateway

现在从 QQ 向 bot 发送消息 — 它应该会回复!

钉钉 (DingTalk)

使用流模式 (Stream Mode) — 无需公网 IP。

1. 创建一个钉钉 bot (Create a DingTalk bot)

  • 访问 钉钉开放平台 (DingTalk Open Platform)
  • 创建新应用 -> 添加 Robot 能力
  • 配置 (Configuration)
    • 开启流模式 (Stream Mode)
  • 权限 (Permissions):添加发送消息所需的权限
  • 从"凭证"获取 AppKey(Client ID)和 AppSecret(Client Secret)
  • 发布应用

2. 配置 (Configure)

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APP_KEY",
      "clientSecret": "YOUR_APP_SECRET",
      "allowFrom": []
    }
  }
}

allowFrom:留空允许所有用户,或添加 ["staffId"] 限制访问。

3. 运行 (Run)

nanobot gateway
Slack

使用套接字模式 (Socket Mode) — 无需公共 URL。

1. 创建一个 Slack 应用 (Create a Slack app)

  • 前往 Slack API创建新应用 (Create New App) → "从零开始 (From scratch)"
  • 选择名称并选择你的工作区

2. 配置应用 (Configure the app)

  • Socket Mode:开启 → 生成具有 connections:write 作用域的应用级令牌 (App-Level Token) → 复制(xapp-...
  • OAuth & Permissions:添加 bot scopes:chat:writereactions:writeapp_mentions:read
  • Event Subscriptions:开启 → 订阅 bot 事件:message.immessage.channelsapp_mention → 保存更改
  • App Home:滚动到显示标签页 (Show Tabs) → 启用消息标签页 (Messages Tab) → 勾选**"允许用户从消息标签页发送斜杠命令和消息"**
  • 安装应用 (Install App):点击安装到工作区 (Install to Workspace) → 授权 → 复制 Bot Tokenxoxb-...

3. 配置 nanobot

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention"
    }
  }
}

4. 运行 (Run)

nanobot gateway

直接向 bot 发 DM 或在频道中 @提及它 — 它应该会回复!

[!TIP]

  • groupPolicy"mention"(默认 — 仅在 @提及时回复)、"open"(回复所有频道消息)或 "allowlist"(限制特定频道)。
  • DM 策略默认为开放。设置 "dm": {"enabled": false} 可禁用 DM。
Email

给 nanobot 一个专属的邮箱账户。它通过 IMAP 轮询来邮件,并通过 SMTP 回复 — 就像一个个人邮件助手。

1. 获取凭据 (Gmail 示例) (Get credentials (Gmail example))

  • 为你的 bot 创建一个专用的 Gmail 账户(例如 my-nanobot@gmail.com
  • 启用两步验证 → 创建应用密码 (App Password)
  • 对 IMAP 和 SMTP 使用此应用密码

2. 配置 (Configure)

  • consentGranted 必须为 true 才能允许访问邮箱。这是一个安全门 — 设置 false 可完全禁用。
  • allowFrom:留空接受来自任何人的邮件,或限制特定发件人。
  • smtpUseTlssmtpUseSsl 分别默认为 true / false,这对于 Gmail(端口 587 + STARTTLS)是正确的。无需显式设置。
  • 如果你只想阅读/分析邮件而不发送自动回复,设置 "autoReplyEnabled": false
{
  "channels": {
    "email": {
      "enabled": true,
      "consentGranted": true,
      "imapHost": "imap.gmail.com",
      "imapPort": 993,
      "imapUsername": "my-nanobot@gmail.com",
      "imapPassword": "your-app-password",
      "smtpHost": "smtp.gmail.com",
      "smtpPort": 587,
      "smtpUsername": "my-nanobot@gmail.com",
      "smtpPassword": "your-app-password",
      "fromAddress": "my-nanobot@gmail.com",
      "allowFrom": ["your-real-email@gmail.com"]
    }
  }
}

3. 运行 (Run)

nanobot gateway

🌐 Agent 社交网络 (Agent Social Network)

🐈 nanobot 能够连接到 agent 社交网络(agent 社区)。只需发送一条消息,你的 nanobot 就会自动加入!

平台 (Platform) 如何加入(将此消息发送给你的 bot)(How to Join)
Moltbook Read https://moltbook.com/skill.md and follow the instructions to join Moltbook
ClawdChat Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat

只需通过 CLI 或任何聊天频道将上述命令发送给 nanobot,它会处理其余一切。

⚙️ 配置 (Configuration)

配置文件:~/.nanobot/config.json

Provider

Tip

  • Groq 通过 Whisper 提供免费的语音转录。如果配置了,Telegram 语音消息将自动转录。
  • 智谱编程计划 (Zhipu Coding Plan):如果你使用的是智谱的编程计划,在 zhipu provider 配置中设置 "apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"
  • MiniMax(大陆):如果你的 API key 来自 MiniMax 的大陆平台(minimaxi.com),在你的 minimax provider 配置中设置 "apiBase": "https://api.minimaxi.com/v1"
Provider 用途 (Purpose) 获取 API Key
openrouter LLM(推荐,访问所有模型)(recommended, access to all models) openrouter.ai
anthropic LLM(Claude 直接访问)(Claude direct) console.anthropic.com
openai LLM(GPT 直接访问)(GPT direct) platform.openai.com
deepseek LLM(DeepSeek 直接访问)(DeepSeek direct) platform.deepseek.com
groq LLM + 语音转录 (Voice transcription) (Whisper) console.groq.com
gemini LLM(Gemini 直接访问)(Gemini direct) aistudio.google.com
minimax LLM(MiniMax 直接访问)(MiniMax direct) platform.minimax.io
aihubmix LLM(API 网关,访问所有模型)(API gateway, access to all models) aihubmix.com
dashscope LLM(Qwen) dashscope.console.aliyun.com
moonshot LLM(Moonshot/Kimi) platform.moonshot.cn
zhipu LLM(智谱 GLM)(Zhipu GLM) open.bigmodel.cn
vllm LLM(本地,任何 OpenAI 兼容服务器)(local, any OpenAI-compatible server)
添加新的 Provider(开发者指南)(Adding a New Provider)

nanobot 使用Provider 注册表 (nanobot/providers/registry.py) 作为唯一事实来源。 添加一个新的 provider 只需2 个步骤 — 无需修改 if-elif 链。

步骤 1。nanobot/providers/registry.pyPROVIDERS 中添加 ProviderSpec 条目:

ProviderSpec(
    name="myprovider",                   # 配置字段名 (config field name)
    keywords=("myprovider", "mymodel"),  # 用于自动匹配的模型名关键词 (model-name keywords for auto-matching)
    env_key="MYPROVIDER_API_KEY",        # LiteLLM 的环境变量 (env var for LiteLLM)
    display_name="My Provider",          # 在 `nanobot status` 中显示 (shown in `nanobot status`)
    litellm_prefix="myprovider",         # 自动前缀:模型 → myprovider/model
    skip_prefixes=("myprovider/",),      # 不要双重前缀 (don't double-prefix)
)

步骤 2。nanobot/config/schema.pyProvidersConfig 中添加字段:

class ProvidersConfig(BaseModel):
    ...
    myprovider: ProviderConfig = ProviderConfig()

就这样!环境变量、模型前缀、配置匹配和 nanobot status 显示都会自动工作。

常用的 ProviderSpec 选项:

字段 (Field) 描述 (Description) 示例 (Example)
litellm_prefix 为 LiteLLM 自动添加模型名前缀 "dashscope"dashscope/qwen-max
skip_prefixes 如果模型已以这些开头则不添加前缀 ("dashscope/", "openrouter/")
env_extras 要设置的其他环境变量 (("ZHIPUAI_API_KEY", "{api_key}"),)
model_overrides 按模型覆盖参数 (("kimi-k2.5", {"temperature": 1.0}),)
is_gateway 可以路由任何模型(如 OpenRouter) True
detect_by_key_prefix 通过 API key 前缀检测网关 "sk-or-"
detect_by_base_keyword 通过 API 基础 URL 检测网关 "openrouter"
strip_model_prefix 在重新前缀之前去除现有前缀 True(用于 AiHubMix)

安全 (Security)

对于生产部署,在配置中设置 "restrictToWorkspace": true 以沙箱化 agent。

选项 (Option) 默认 (Default) 描述 (Description)
tools.restrictToWorkspace false 当为 true 时,将所有 agent 工具(shell、文件读/写/编辑、列表)限制在工作区目录内。防止路径遍历和越界访问。
channels.*.allowFrom [](允许所有人)(allow all) 用户 ID 白名单。空 = 允许所有人;非空 = 仅列出的用户可以交互。

CLI 参考 (CLI Reference)

命令 (Command) 描述 (Description)
nanobot onboard 初始化配置和工作区 (Initialize config & workspace)
nanobot agent -m "..." 与 agent 聊天 (Chat with the agent)
nanobot agent 交互式聊天模式 (Interactive chat mode)
nanobot agent --no-markdown 显示纯文本回复 (Show plain-text replies)
nanobot agent --logs 在聊天期间显示运行时日志 (Show runtime logs during chat)
nanobot gateway 启动 gateway
nanobot status 显示状态 (Show status)
nanobot channels login 关联 WhatsApp(扫描 QR)(Link WhatsApp)
nanobot channels status 显示渠道状态 (Show channel status)

交互模式退出命令:exitquit/exit/quit:qCtrl+D

定时任务 (Scheduled Tasks) (Cron)
# 添加任务 (Add a job)
nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
nanobot cron add --name "hourly" --message "Check status" --every 3600

# 列出任务 (List jobs)
nanobot cron list

# 删除任务 (Remove a job)
nanobot cron remove <job_id>

🐳 Docker

Tip

-v ~/.nanobot:/root/.nanobot 标志将你的本地配置目录挂载到容器中,这样你的配置和工作区在容器重启后就会保留。

在容器中构建和运行 nanobot:

# 构建镜像 (Build the image)
docker build -t nanobot .

# 初始化配置(仅首次)(Initialize config (first time only))
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# 在主机上编辑配置以添加 API keys
vim ~/.nanobot/config.json

# 运行 gateway(连接到已启用的渠道,例如 Telegram/Discord/Mochat)
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

# 或者运行单个命令
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot status

📁 项目结构 (Project Structure)

nanobot/
├── agent/          # 🧠 核心 agent 逻辑 (Core agent logic)
│   ├── loop.py     #    Agent 循环 (Agent loop)(LLM ↔ 工具执行 (tool execution))
│   ├── context.py  #    Prompt 构建器 (Prompt builder)
│   ├── memory.py   #    持久化记忆 (Persistent memory)
│   ├── skills.py   #    技能加载器 (Skills loader)
│   ├── subagent.py #    后台任务执行 (Background task execution)
│   └── tools/      #    内置工具 (Built-in tools)(包括 spawn)
├── skills/         # 🎯 捆绑技能 (Bundled skills)(github, weather, tmux...)
├── channels/       # 📱 聊天渠道集成 (Chat channel integrations)
├── bus/            # 🚌 消息路由 (Message routing)
├── cron/           # ⏰ 定时任务 (Scheduled tasks)
├── heartbeat/      # 💓 主动唤醒 (Proactive wake-up)
├── providers/      # 🤖 LLM providers(OpenRouter 等)
├── session/        # 💬 对话会话 (Conversation sessions)
├── config/         # ⚙️ 配置 (Configuration)
└── cli/            # 🖥️ 命令 (Commands)

🤝 贡献与路线图 (Contribute & Roadmap)

欢迎提交 PR!代码库特意保持小而可读。🤗

路线图 (Roadmap) — 选择一个项目提交 PR

  • 语音转录 (Voice Transcription) — 支持 Groq Whisper(问题 #13)
  • 多模态 (Multi-modal) — 看和听(图像、语音、视频)
  • 长期记忆 (Long-term memory) — 永不忘记重要的上下文
  • 更好的推理 (Better reasoning) — 多步骤规划和反思
  • 更多集成 (More integrations) — 日历等
  • 自我改进 (Self-improvement) — 从反馈和错误中学习

贡献者 (Contributors)

Contributors

⭐ Star 历史 (Star History)

感谢访问 ✨ nanobot!

Views

nanobot 仅用于教育、研究和技术交流目的

About

No description, website, or topics provided.

Resources

License

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors