nanobot: Ultra-Lightweight Personal AI Assistant

• 2026-03-05 ⚡️ Telegram draft streaming, MCP SSE support, and broader channel reliability fixes.
• 2026-03-04 🛠️ Dependency cleanup, safer file reads, and another round of test and Cron fixes.
• 2026-03-03 🧠 Cleaner user-message merging, safer multimodal saves, and stronger Cron guards.
• 2026-03-02 🛡️ Safer default access control, sturdier Cron reloads, and cleaner Matrix media handling.
• 2026-03-01 🌐 Web proxy support, smarter Cron reminders, and Feishu rich-text parsing improvements.
• 2026-02-28 🚀 Released v0.1.4.post3 — cleaner context, hardened session history, and smarter agent. Please see release notes for details.
• 2026-02-27 🧠 Experimental thinking mode support, DingTalk media messages, Feishu and QQ channel fixes.
• 2026-02-26 🛡️ Session poisoning fix, WhatsApp dedup, Windows path guard, Mistral compatibility.
• 2026-02-25 🧹 New Matrix channel, cleaner session context, auto workspace template sync.
• 2026-02-24 🚀 Released v0.1.4.post2 — a reliability-focused release with a redesigned heartbeat, prompt cache optimization, and hardened provider & channel stability. See release notes for details.
• 2026-02-23 🔧 Virtual tool-call heartbeat, prompt cache optimization, Slack mrkdwn fixes.
• 2026-02-22 🛡️ Slack thread isolation, Discord typing fix, agent reliability improvements.
• 2026-02-21 🎉 Released v0.1.4.post1 — new providers, media support across channels, and major stability improvements. See release notes for details.
• 2026-02-20 🐦 Feishu now receives multimodal files from users. More reliable memory under the hood.
• 2026-02-19 ✨ Slack now sends files, Discord splits long messages, and subagents work in CLI mode.
• 2026-02-18 ⚡️ nanobot now supports VolcEngine, MCP custom auth headers, and Anthropic prompt caching.
• 2026-02-17 🎉 Released v0.1.4 — MCP support, progress streaming, new providers, and multiple channel improvements. Please see release notes for details.
• 2026-02-16 🦞 nanobot now integrates a ClawHub skill — search and install public agent skills.
• 2026-02-15 🔑 nanobot now supports OpenAI Codex provider with OAuth login support.
• 2026-02-14 🔌 nanobot now supports MCP! See MCP section for details.
• 2026-02-13 🎉 Released v0.1.3.post7 — includes security hardening and multiple improvements. Please upgrade to the latest version to address security issues. See release notes for more details.
• 2026-02-12 🧠 Redesigned memory system — Less code, more reliable. Join the discussion about it!
• 2026-02-11 ✨ Enhanced CLI experience and added MiniMax support!
• 2026-02-10 🎉 Released v0.1.3.post6 with improvements! Check the updates notes and our roadmap.
• 2026-02-09 💬 Added Slack, Email, and QQ support — nanobot now supports multiple chat platforms!
• 2026-02-08 🔧 Refactored Providers—adding a new LLM provider now takes just 2 simple steps! Check here.
• 2026-02-07 🚀 Released v0.1.3.post5 with Qwen support & several key improvements! Check here for details.
• 2026-02-06 ✨ Added Moonshot/Kimi provider, Discord integration, and enhanced security hardening!
• 2026-02-05 ✨ Added Feishu channel, DeepSeek provider, and enhanced scheduled tasks support!
• 2026-02-04 🚀 Released v0.1.3.post4 with multi-provider & Docker support! Check here for details.
• 2026-02-03 ⚡ Integrated vLLM for local LLM support and improved natural language task scheduling!
• 2026-02-02 🎉 nanobot officially launched! Welcome to try 🐈 nanobot!

1. Create a bot

• Open Telegram, search @BotFather
• Send /newbot, follow prompts
• Copy the token

2. Configure

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

You can find your User ID in Telegram settings. It is shown as @yourUserId. Copy this value without the @ symbol and paste it into the config file.

3. Run

nanobot gateway

Uses Socket.IO WebSocket by default, with HTTP polling fallback.

1. Ask nanobot to set up Mochat for you

Simply send this message to nanobot (replace xxx@xxx with your real email):

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 will automatically register, configure ~/.nanobot/config.json, and connect to Mochat.

2. Restart gateway

nanobot gateway

That's it — nanobot handles the rest!

{
  "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
    }
  }
}

1. Create a bot

• Go to https://discord.com/developers/applications
• Create an application → Bot → Add Bot
• Copy the bot token

2. Enable intents

• In the Bot settings, enable MESSAGE CONTENT INTENT
• (Optional) Enable SERVER MEMBERS INTENT if you plan to use allow lists based on member data

3. Get your User ID

• Discord Settings → Advanced → enable Developer Mode
• Right-click your avatar → Copy User ID

4. Configure

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

groupPolicy controls how the bot responds in group channels:

• "mention" (default) — Only respond when @mentioned
• "open" — Respond to all messages DMs always respond when the sender is in allowFrom.

5. Invite the bot

• OAuth2 → URL Generator
• Scopes: bot
• Bot Permissions: Send Messages, Read Message History
• Open the generated invite URL and add the bot to your server

6. Run

nanobot gateway

Install Matrix dependencies first:

pip install nanobot-ai[matrix]

1. Create/choose a Matrix account

• Create or reuse a Matrix account on your homeserver (for example matrix.org).
• Confirm you can log in with Element.

2. Get credentials

• You need:
  • userId (example: @nanobot:matrix.org)
  • accessToken
  • deviceId (recommended so sync tokens can be restored across restarts)
• You can obtain these from your homeserver login API (/_matrix/client/v3/login) or from your client's advanced session settings.

3. Configure

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@nanobot:matrix.org",
      "accessToken": "syt_xxx",
      "deviceId": "NANOBOT01",
      "e2eeEnabled": true,
      "allowFrom": ["@your_user:matrix.org"],
      "groupPolicy": "open",
      "groupAllowFrom": [],
      "allowRoomMentions": false,
      "maxMediaBytes": 20971520
    }
  }
}

Keep a persistent matrix-store and stable deviceId — encrypted session state is lost if these change across restarts.

4. Run

nanobot gateway

Requires Node.js ≥18.

1. Link device

nanobot channels login
# Scan QR with WhatsApp → Settings → Linked Devices

2. Configure

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

3. Run (two terminals)

# Terminal 1
nanobot channels login

# Terminal 2
nanobot gateway

WhatsApp bridge updates are not applied automatically for existing installations. After upgrading nanobot, rebuild the local bridge with: rm -rf ~/.nanobot/bridge && nanobot channels login

Uses WebSocket long connection — no public IP required.

1. Create a Feishu bot

• Visit Feishu Open Platform
• Create a new app → Enable Bot capability
• Permissions: Add im:message (send messages) and im:message.p2p_msg:readonly (receive messages)
• Events: Add im.message.receive_v1 (receive messages)
  • Select Long Connection mode (requires running nanobot first to establish connection)
• Get App ID and App Secret from "Credentials & Basic Info"
• Publish the app

2. Configure

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

encryptKey and verificationToken are optional for Long Connection mode. allowFrom: Add your open_id (find it in nanobot logs when you message the bot). Use ["*"] to allow all users. groupPolicy: "mention" (default — respond only when @mentioned), "open" (respond to all group messages). Private chats always respond.

3. Run

nanobot gateway

Uses botpy SDK with WebSocket — no public IP required. Currently supports private messages only.

1. Register & create bot

• Visit QQ Open Platform → Register as a developer (personal or enterprise)
• Create a new bot application
• Go to 开发设置 (Developer Settings) → copy AppID and AppSecret

2. Set up sandbox for testing

• In the bot management console, find 沙箱配置 (Sandbox Config)
• Under 在消息列表配置, click 添加成员 and add your own QQ number
• Once added, scan the bot's QR code with mobile QQ → open the bot profile → tap "发消息" to start chatting

3. Configure

• allowFrom: Add your openid (find it in nanobot logs when you message the bot). Use ["*"] for public access.
• msgFormat: Optional. Use "plain" (default) for maximum compatibility with legacy QQ clients, or "markdown" for richer formatting on newer clients.
• For production: submit a review in the bot console and publish. See QQ Bot Docs for the full publishing flow.

{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "secret": "YOUR_APP_SECRET",
      "allowFrom": ["YOUR_OPENID"],
      "msgFormat": "plain"
    }
  }
}

4. Run

nanobot gateway

Now send a message to the bot from QQ — it should respond!

Uses Stream Mode — no public IP required.

1. Create a DingTalk bot

• Visit DingTalk Open Platform
• Create a new app -> Add Robot capability
• Configuration:
  • Toggle Stream Mode ON
• Permissions: Add necessary permissions for sending messages
• Get AppKey (Client ID) and AppSecret (Client Secret) from "Credentials"
• Publish the app

2. Configure

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

allowFrom: Add your staff ID. Use ["*"] to allow all users.

3. Run

nanobot gateway

Uses Socket Mode — no public URL required.

1. Create a Slack app

• Go to Slack API → Create New App → "From scratch"
• Pick a name and select your workspace

2. Configure the app

• Socket Mode: Toggle ON → Generate an App-Level Token with connections:write scope → copy it (xapp-...)
• OAuth & Permissions: Add bot scopes: chat:write, reactions:write, app_mentions:read
• Event Subscriptions: Toggle ON → Subscribe to bot events: message.im, message.channels, app_mention → Save Changes
• App Home: Scroll to Show Tabs → Enable Messages Tab → Check "Allow users to send Slash commands and messages from the messages tab"
• Install App: Click Install to Workspace → Authorize → copy the Bot Token (xoxb-...)

3. Configure nanobot

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

4. Run

nanobot gateway

DM the bot directly or @mention it in a channel — it should respond!

Give nanobot its own email account. It polls IMAP for incoming mail and replies via SMTP — like a personal email assistant.

1. Get credentials (Gmail example)

• Create a dedicated Gmail account for your bot (e.g. my-nanobot@gmail.com)
• Enable 2-Step Verification → Create an App Password
• Use this app password for both IMAP and SMTP

2. Configure

• consentGranted must be true to allow mailbox access. This is a safety gate — set false to fully disable.
• allowFrom: Add your email address. Use ["*"] to accept emails from anyone.
• smtpUseTls and smtpUseSsl default to true / false respectively, which is correct for Gmail (port 587 + STARTTLS). No need to set them explicitly.
• Set "autoReplyEnabled": false if you only want to read/analyze emails without sending automatic replies.

{
  "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

Here we use wecom-aibot-sdk-python (community Python version of the official @wecom/aibot-node-sdk).

Uses WebSocket long connection — no public IP required.

1. Install the optional dependency

pip install nanobot-ai[wecom]

2. Create a WeCom AI Bot

Go to the WeCom admin console → Intelligent Robot → Create Robot → select API mode with long connection. Copy the Bot ID and Secret.

3. Configure

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "your_bot_id",
      "secret": "your_bot_secret",
      "allowFrom": ["your_id"]
    }
  }
}

4. Run

nanobot gateway

Codex uses OAuth instead of API keys. Requires a ChatGPT Plus or Pro account.

1. Login:

nanobot provider login openai-codex

2. Set model (merge into ~/.nanobot/config.json):

{
  "agents": {
    "defaults": {
      "model": "openai-codex/gpt-5.1-codex"
    }
  }
}

3. Chat:

nanobot agent -m "Hello!"

# Target a specific workspace/config locally
nanobot agent -c ~/.nanobot-telegram/config.json -m "Hello!"

# One-off workspace override on top of that config
nanobot agent -c ~/.nanobot-telegram/config.json -w /tmp/nanobot-telegram-test -m "Hello!"

Docker users: use docker run -it for interactive OAuth login.

Connects directly to any OpenAI-compatible endpoint — LM Studio, llama.cpp, Together AI, Fireworks, Azure OpenAI, or any self-hosted server. Bypasses LiteLLM; model name is passed as-is.

{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.your-provider.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "your-model-name"
    }
  }
}

For local servers that don't require a key, set apiKey to any non-empty string (e.g. "no-key").

Run a local model with Ollama, then add to config:

1. Start Ollama (example):

ollama run llama3.2

2. Add to config (partial — merge into ~/.nanobot/config.json):

{
  "providers": {
    "ollama": {
      "apiBase": "http://localhost:11434"
    }
  },
  "agents": {
    "defaults": {
      "provider": "ollama",
      "model": "llama3.2"
    }
  }
}

provider: "auto" also works when providers.ollama.apiBase is configured, but setting "provider": "ollama" is the clearest option.

Run your own model with vLLM or any OpenAI-compatible server, then add to config:

1. Start the server (example):

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

2. Add to config (partial — merge into ~/.nanobot/config.json):

Provider (key can be any non-empty string for local):

{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  }
}

Model:

{
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

nanobot uses a Provider Registry (nanobot/providers/registry.py) as the single source of truth. Adding a new provider only takes 2 steps — no if-elif chains to touch.

Step 1. Add a ProviderSpec entry to PROVIDERS in nanobot/providers/registry.py:

ProviderSpec(
    name="myprovider",                   # config field name
    keywords=("myprovider", "mymodel"),  # model-name keywords for auto-matching
    env_key="MYPROVIDER_API_KEY",        # env var for LiteLLM
    display_name="My Provider",          # shown in `nanobot status`
    litellm_prefix="myprovider",         # auto-prefix: model → myprovider/model
    skip_prefixes=("myprovider/",),      # don't double-prefix
)

Step 2. Add a field to ProvidersConfig in nanobot/config/schema.py:

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

That's it! Environment variables, model prefixing, config matching, and nanobot status display will all work automatically.

Common ProviderSpec options:

The gateway wakes up every 30 minutes and checks HEARTBEAT.md in your workspace (~/.nanobot/workspace/HEARTBEAT.md). If the file has tasks, the agent executes them and delivers results to your most recently active chat channel.

Setup: edit ~/.nanobot/workspace/HEARTBEAT.md (created automatically by nanobot onboard):

## Periodic Tasks

- [ ] Check weather forecast and send a summary
- [ ] Scan inbox for urgent emails

The agent can also manage this file itself — ask it to "add a periodic task" and it will update HEARTBEAT.md for you.

Note: The gateway must be running (nanobot gateway) and you must have chatted with the bot at least once so it knows which channel to deliver to.