Nanobot AI Assistant

---
name: nanobot-ai-assistant
description: Ultra-lightweight personal AI assistant framework with multi-channel support, MCP integration, and agent capabilities
triggers:
  - set up nanobot AI assistant
  - configure nanobot with telegram discord
  - install nanobot agent framework
  - connect nanobot to chat platforms
  - nanobot MCP tool integration
  - deploy lightweight AI agent
  - nanobot provider configuration
  - build AI assistant with nanobot
---

# nanobot AI Assistant

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

nanobot is an ultra-lightweight personal AI assistant framework (~99% fewer lines of code than OpenClaw) that delivers full agent functionality including multi-channel chat integrations, MCP (Model Context Protocol) support, memory, scheduled tasks, web search, and extensible skills.

## Installation

### From Source (recommended for development)
```bash
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

From PyPI (stable)

pip install nanobot-ai

With uv (fast, isolated)

uv tool install nanobot-ai

Update

pip install -U nanobot-ai
# or
uv tool upgrade nanobot-ai

Requirements: Python ≥ 3.11

Quick Start

# 1. Initialize workspace
nanobot onboard

# 2. Edit config at ~/.nanobot/config.json
# 3. Start chatting
nanobot agent

Configuration

All configuration lives in ~/.nanobot/config.json.

Minimal Configuration

{
  "providers": {
    "openrouter": {
      "apiKey": "$OPENROUTER_API_KEY"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  }
}

Full Configuration Example

{
  "providers": {
    "openrouter": {
      "apiKey": "$OPENROUTER_API_KEY"
    },
    "openai": {
      "apiKey": "$OPENAI_API_KEY"
    },
    "anthropic": {
      "apiKey": "$ANTHROPIC_API_KEY"
    },
    "deepseek": {
      "apiKey": "$DEEPSEEK_API_KEY"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  },
  "memory": {
    "enabled": true
  },
  "search": {
    "provider": "tavily",
    "apiKey": "$TAVILY_API_KEY"
  }
}

Supported Providers

CLI Reference

# Initialize workspace
nanobot onboard

# Start interactive agent chat
nanobot agent

# Start all configured channels (Telegram, Discord, etc.)
nanobot channels start

# Login / setup a specific channel
nanobot channels login

# List available skills
nanobot skills list

# Install a skill from ClawHub
nanobot skills install <skill-name>

# Show version
nanobot --version

# Restart bot (useful in channel sessions)
/restart

Channel Setup

Telegram (Recommended)

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "$TELEGRAM_BOT_TOKEN",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}

Setup steps:

1. Message @BotFather on Telegram → /newbot
2. Copy the token into config
3. Find your User ID in Telegram settings
4. Run nanobot channels start

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "$DISCORD_BOT_TOKEN",
      "allowFrom": ["YOUR_DISCORD_USER_ID"]
    }
  }
}

Requires Message Content Intent enabled in Discord Developer Portal.

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "$SLACK_BOT_TOKEN",
      "appToken": "$SLACK_APP_TOKEN"
    }
  }
}

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }
}

nanobot channels login   # Scan QR code to authenticate

After upgrading nanobot with WhatsApp:

rm -rf ~/.nanobot/bridge
nanobot channels login

Feishu (Lark)

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "$FEISHU_APP_ID",
      "appSecret": "$FEISHU_APP_SECRET"
    }
  }
}

DingTalk

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "appKey": "$DINGTALK_APP_KEY",
      "appSecret": "$DINGTALK_APP_SECRET"
    }
  }
}

Email

{
  "channels": {
    "email": {
      "enabled": true,
      "imap": {
        "host": "imap.gmail.com",
        "port": 993,
        "user": "$EMAIL_USER",
        "password": "$EMAIL_PASSWORD"
      },
      "smtp": {
        "host": "smtp.gmail.com",
        "port": 587,
        "user": "$EMAIL_USER",
        "password": "$EMAIL_PASSWORD"
      }
    }
  }
}

MCP (Model Context Protocol)

nanobot supports MCP for connecting external tools and data sources.

MCP Configuration

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
        }
      },
      "remote-sse": {
        "url": "https://your-mcp-server.com/sse",
        "headers": {
          "Authorization": "Bearer $MCP_TOKEN"
        }
      }
    }
  }
}

MCP servers can expose tools, prompts, and resources that nanobot's agent can use automatically during conversations.

Web Search

{
  "search": {
    "provider": "tavily",
    "apiKey": "$TAVILY_API_KEY"
  }
}

Supported search providers: tavily, and other multi-provider options. Web search enables the agent to retrieve real-time information.

Memory System

Token-based memory is enabled by default. The agent automatically stores and retrieves relevant context across conversations.

{
  "memory": {
    "enabled": true,
    "maxTokens": 4000
  }
}

Scheduled Tasks (Cron)

nanobot supports natural language cron scheduling. Tell the agent:

"Remind me every day at 9am to check emails"
"Send me a market summary every weekday at 8am"

The agent will set up recurring tasks stored in your workspace.

Skills / Plugins

# Browse available skills on ClawHub
nanobot skills list

# Install a skill
nanobot skills install web-scraper

# Skills live in ~/.nanobot/skills/

Custom skills are Python files placed in ~/.nanobot/skills/. Each skill exposes tools the agent can call.

Writing a Custom Skill

# ~/.nanobot/skills/my_skill.py

from nanobot.skill import skill, tool

@skill(name="my-skill", description="My custom skill")
class MySkill:

    @tool(description="Fetch data from an API")
    async def fetch_data(self, url: str) -> str:
        """Fetch data from the given URL."""
        import httpx
        async with httpx.AsyncClient() as client:
            response = await client.get(url)
            return response.text

    @tool(description="Process text input")
    async def process_text(self, text: str, uppercase: bool = False) -> str:
        """Process the input text."""
        if uppercase:
            return text.upper()
        return text.strip()

Docker Deployment

# Build image
docker build -t nanobot .

# Run with config volume
docker run -d \
  -v ~/.nanobot:/root/.nanobot \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  --name nanobot \
  nanobot

Docker Compose example:

version: "3.8"
services:
  nanobot:
    image: hkuds/nanobot:latest
    volumes:
      - ~/.nanobot:/root/.nanobot
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    restart: unless-stopped

Linux Service (systemd)

# /etc/systemd/system/nanobot.service
[Unit]
Description=nanobot AI Assistant
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser
ExecStart=/usr/local/bin/nanobot channels start
Restart=on-failure
RestartSec=5
Environment=OPENROUTER_API_KEY=your_key_here

[Install]
WantedBy=multi-user.target

sudo systemctl enable nanobot
sudo systemctl start nanobot
sudo systemctl status nanobot

Multiple Instances

Run multiple nanobot instances with different configs:

# Specify a custom config directory
NANOBOT_HOME=~/.nanobot-work nanobot agent
NANOBOT_HOME=~/.nanobot-personal nanobot channels start

Each instance maintains its own memory, skills, and channel configurations.

Web Proxy Support

{
  "proxy": {
    "http": "http://proxy.example.com:8080",
    "https": "http://proxy.example.com:8080"
  }
}

LangSmith Integration

{
  "langsmith": {
    "apiKey": "$LANGSMITH_API_KEY",
    "project": "nanobot-traces"
  }
}

Project Structure

~/.nanobot/
├── config.json          # Main configuration
├── skills/              # Custom skill plugins
├── memory/              # Persistent agent memory
├── sessions/            # Chat session history
├── bridge/              # WhatsApp bridge data
└── workspace/           # Agent working directory

Repository structure:

nanobot/
├── nanobot/
│   ├── agent/           # Core agent logic
│   ├── channels/        # Chat platform integrations
│   ├── providers/       # LLM provider adapters
│   ├── skills/          # Built-in skills
│   ├── memory/          # Memory system
│   └── mcp/             # MCP client
├── core_agent_lines.sh  # Line count verification
└── pyproject.toml

Troubleshooting

Agent not responding

# Check version
nanobot --version

# Verify config is valid JSON
python -m json.tool ~/.nanobot/config.json

# Test provider connectivity
nanobot agent  # try a simple message

Channel not connecting

# Re-run channel login
nanobot channels login

# Check channel is enabled in config
cat ~/.nanobot/config.json | python -m json.tool

WhatsApp session lost after upgrade

rm -rf ~/.nanobot/bridge
nanobot channels login   # scan QR code again

Memory issues

# Memory files are in ~/.nanobot/memory/
# Clear to reset (loses all stored context)
rm -rf ~/.nanobot/memory/

MCP server not found

Ensure npx / node is installed for Node.js-based MCP servers:

node --version
npx --version

Model not available

Check that the model name matches the provider's format:

• OpenRouter: anthropic/claude-opus-4-5
• OpenAI direct: gpt-4o
• Anthropic direct: claude-opus-4-5
• Ollama: llama3.2

Verify line count claim

cd /path/to/nanobot
bash core_agent_lines.sh

Common Patterns

Environment variable substitution in config

nanobot supports $ENV_VAR syntax in config values:

{
  "providers": {
    "openai": {
      "apiKey": "$OPENAI_API_KEY"
    }
  }
}

Thinking mode (experimental)

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "thinking": true
    }
  }
}

Multi-agent / subagents

Subagents are supported in both CLI and channel modes. The main agent can spawn subagents for parallel tasks automatically based on the conversation context.

Access control for channels

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "$TELEGRAM_BOT_TOKEN",
      "allowFrom": ["user_id_1", "user_id_2"]
    }
  }
}

Leave allowFrom empty array [] for open access (not recommended for public bots).