体量小而可读性高的轻量个人 AI agent

现有 agent 框架把核心 loop 包成黑盒，想改一个细节要扒好几层抽象，读起来都费劲，更别说二次开发了。

我给大家安利一个超轻量开源 AI agent — nanobot。专门为「想读懂、想扩展」而设计的个人 agent，灵感来自 Claude Code / Codex，代码保持最小可读。

GitHub：https://github.com/HKUDS/nanobot

它的核心 loop 故意写得小而清晰，任何人都能看懂改动。内置 Telegram、Discord、飞书、WeChat 等 10+ 聊天平台接入，WebUI 直接打包进 wheel 里开 WebSocket 就能用，不需要单独起前端服务。多 provider 支持覆盖 OpenAI、Anthropic、DeepSeek、Gemini、Qwen 以及本地 Ollama / vLLM，随时切换不锁厂商。

主要功能： 核心 agent loop 极简可读，方便研究和二次开发 内置 memory + MCP，长期记忆与工具扩展开箱即用 /goal 指令支持跨多轮维持长期目标，可跑长任务 接入 Telegram、Discord、飞书、WeChat 等主流聊天平台 支持 OpenAI、Anthropic、DeepSeek、本地 Ollama 等多 provider 随意切换

这个项目部署也很简单，pip install nanobot-ai 然后 nanobot onboard 就行了。

适合正在搭建个人 AI 助理、或者想从源码层面研究 agent 架构的朋友收藏使用。

HKUDS/nanobot

Source: https://github.com/HKUDS/nanobot

🐈 nanobot is an open-source and ultra-lightweight AI agent in the spirit of OpenClaw, Claude Code, and Codex. It keeps the core agent loop small and readable while still supporting chat channels, memory, MCP and practical deployment paths, so you can go from local setup to a long-running personal agent with minimal overhead.

📢 News

• 2026-05-15 🚀 Released v0.2.0 — /goal holds sustained objectives across turns, WebUI now ships inside the wheel, image generation end to end, 5 new providers with fallback_models, and a real agent-loop refactor. Please see release notes for details.
• 2026-05-14 🎯 /goal for long-term objectives, visible multi-step progress, long-horizon missions in chat.
• 2026-05-13 🧠 Streaming reasoning before answers, automatic backup models, smoother plug-in reconnects.
• 2026-05-12 🎛️ Saved model presets with WebUI badge, simpler plug-in tools, quieter Feishu topic threads.
• 2026-05-11 🖥️ NVIDIA NIM support, terminal bot name and icon, streamed reasoning and MiMo toggle clarity.
• 2026-05-09 🖼️ Sharper image replay, BYO web-search keys in Settings, Feishu threads routed cleanly.
• 2026-05-08 ✨ Inline chat image, redesigned Settings and keys, Dream memory aligned with visible history.
• 2026-05-07 📜 Locale-aware slash palette in WebUI, LAN login, faithful HTTP streaming responses.
• 2026-05-06 🧩 Tunable tool hint, steadier voice and plug-in startups, schedules and reminders that stick.
• 2026-05-05 🛡️ Quiet deny for unknown Telegram chats, Dream cleanup, fuller automation summaries.

💡 Key Features of nanobot

• Ultra-lightweight: stable long-running agent behavior with a small, readable core.
• Research-ready: the codebase is intentionally simple enough to study, modify, and extend.
• Practical: chat channels, API, memory, MCP, and deployment paths are already built in.
• Hackable: you can start fast, then go deeper through repo docs instead of a monolithic landing page.

📦 Install

If you want the newest features and experiments, install from source.

If you want the most stable day-to-day experience, install from PyPI or with uv.

Install from source

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

Install with uv

uv tool install nanobot-ai

Install from PyPI

pip install nanobot-ai

🚀 Quick Start

1. Initialize

nanobot onboard

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

Configure these two parts in your config (other options have defaults). Add or merge the following blocks into your existing config instead of replacing the whole file.

Set your API key (e.g. OpenRouter, recommended for global users):

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  }
}

Set your model (optionally pin a provider — defaults to auto-detection):

{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4-6"
    }
  }
}

3. Chat

nanobot agent

• Want different LLM providers, web search, MCP, security settings, or more config options? See Configuration
• Want to run locally? Use Atomic Chat, vLLM, Ollama, and others.
• Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See Chat Apps
• Want Docker or Linux service deployment? See Deployment

🌐 WebUI

The WebUI ships inside the published wheel — no extra build step. Just enable the WebSocket channel and open it in your browser.

1. Enable the WebSocket channel in ~/.nanobot/config.json

{ "channels": { "websocket": { "enabled": true } } }

2. Start the gateway

nanobot gateway

3. Open the WebUI

Visit http://127.0.0.1:8765 in your browser. To open it from another device on your LAN, see WebUI docs → LAN access.

Working on the WebUI itself? Check out webui/README.md for the Vite dev server (HMR) workflow.

🏗️ Architecture

🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.

✨ Features

📚 Docs

Browse the repo docs for the latest features and GitHub development version, or visit nanobot.wiki for the stable release documentation.

• Talk to your nanobot with familiar chat apps: Chat Apps
• Configure providers, web search, MCP, and runtime behavior: Configuration
• Integrate nanobot with local tools and automations: OpenAI-Compatible API · Python SDK
• Run nanobot with Docker or as a Linux service: Deployment

🤝 Contribute & Roadmap

PRs welcome! The codebase is intentionally small and readable. 🤗

Branching Strategy

Unsure which branch to target? See CONTRIBUTING.md for details.

Roadmap — Pick an item and open a PR!

• Multi-modal — See and hear (images, voice, video)
• Long-term memory — Never forget important context
• Better reasoning — Multi-step planning and reflection
• More integrations — Calendar and more
• Self-improvement — Learn from feedback and mistakes

Contact

This project was started by Xubin Ren as a personal open-source project and continues to be maintained in an individual capacity using personal resources, with contributions from the open-source community. Feel free to contact [email protected] for questions, ideas, or collaboration.

Contributors

⭐ Star History

Thanks for visiting ✨ nanobot!