Nanobot Tutorial: A Lightweight OpenClaw Alternative

Nanobot is a lightweight personal AI assistant, an alternative to OpenClaw. It is 98% smaller than OpenClaw while delivering the same core agent functionality.  Just like OpenClaw, it can run on your machine, connect to your favorite apps, and, given the small size, you can easily inspect the code. 

Nanobot connects your favorite closed and open-source models to run a local coding agent. Once you send messages through Telegram, WhatsApp, or the terminal, the agent responds by running commands on your machine, such as reading logs, executing scripts, and searching files. 

In this tutorial, I’ll show you how to set up Nanobot from scratch and explore how to build a full-featured AI agent in a few minutes. I’ll also cover some gotchas you must be aware of when using this technology. 

What Is Nanobot?

Nanobot is an OpenClaw alternative that has become so popular, quickly garnering over 21,000 GitHub stars as of this writing. Like OpenClaw, it supports popular messaging platforms such as Discord, Slack, and Telegram. 

Just like the OpenClaw agent, your Nanobot agent can also join the social media party at Moltbook, as we show in our Getting Started With Moltbook tutorial. 

Nanobot key capabilities

Despite being small, Nanobot covers three main things you need from a powerful agent: 

• Stateful Memory: Nanobot builds a local graph of your history. That means that if you are working on a Python data analysis project today, it will still know this even a week from now. 
• Model Agnostic: You are not locked to any specific model provider. You can use OpenAI’s, Anthropic, or even local models running on your own hardware. 
• Instant UI: Nanobot can be used in your favorite messaging apps, meaning that you keep using the interfaces you are used to. 

Prerequisites for Running Nanobot

To follow this tutorial, you need a few basics:

• Python 3.11 or higher installed on your computer (Mac, Windows, or Linux).
• An API Key from a provider like OpenRouter, OpenAI, or Anthropic, or set up a local model via Ollama.
• A Telegram Account (I will use Telegram for the interface because it is the easiest to set up).

Nanobot Step-by-Step Tutorial: Building A "Research Agent"

Let’s build an agent that lives in your Telegram, can search the web, and remembers your interests.

Step 1: Install Nanobot

The cleanest way to install Python tools these days is using pip or uv, which keeps them isolated from your system Python. If you don't have those, standard pip works too.

Open your terminal and run:

# run inside your env
pip install nanobot-ai 
# OR if you prefer uv
uv tool install nanobot-ai

Once installed, you will see a message like the one below:

Successfully installed nanobot-0.4.1

Step 2: Get Your Interface Token

To set up the interface:

• Open Telegram and search @BotFather 
• Type /newbot and follow the prompts 
• Copy the token you will get from BotFather 
• Next, obtain your user ID to ensure the bot only accepts commands from you. Search for @userinfobot in Telegram and click start. Copy the user ID. 

Step 3: Initialize 

Run nanobot onboard to initialize your bot. You should see a message similar to the one below:

✓ Created config at /Users/derrickmwiti/.nanobot/config.json
✓ Created workspace at /Users/derrickmwiti/.nanobot/workspace
  Created AGENTS.md
  Created SOUL.md
  Created USER.md
  Created memory/MEMORY.md
  Created memory/HISTORY.md
🐈 nanobot is ready!
Next steps:
  1. Add your API key to ~/.nanobot/config.json
     Get one at: https://openrouter.ai/keys
  2. Chat: nanobot agent -m "Hello!"
Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps

Step 4: Configuration

Run the command below and add the API key for the model provider you would like to use under the providers section: 

nano ~/.nanobot/config.json

Edit the file to add the API key to your chosen provider:

{
  "workspace": "./workspace",
  "providers": {
    // Option 1: OpenAI
    "openai": {
      "apiKey": "sk-YOUR-OPENAI-KEY-HERE",
      "model": "gpt-4o"
    },
    // Option 2: Anthropic (Claude)
    "anthropic": {
      "apiKey": "sk-ant-YOUR-CLAUDE-KEY-HERE",
      "model": "claude-3-5-sonnet-20240620"
    },
    // Option 3: Google Gemini
    "google": {
      "apiKey": "AIza-YOUR-GOOGLE-KEY-HERE",
      "model": "gemini-1.5-pro"
    },
    // Option 4: OpenRouter (Best for flexibility)
    "openrouter": {
      "apiKey": "sk-or-YOUR-OPENROUTER-KEY-HERE",
      "model": "nousresearch/hermes-3-llama-3.1-405b"
    },
    // Option 5: Local (Ollama or vLLM)
    "local": {
      "apiBase": "http://localhost:11434/v1",
      "apiKey": "ollama",
      "model": "llama3"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allowFrom": ["YOUR_NUMERIC_USER_ID"]
    }
  }
}

Edit the Telegram section and add the token and user ID you obtained earlier. You need to do this so that you are the only one who can send instructions to your agent. 

"telegram": {
      "enabled": true,
      "token": "",
      "allowFrom": [""],
      "proxy": null
}

   Modify the agents section to reflect the chosen provider:

"agents": {
    "defaults": {
      "workspace": "~/.nanobot/workspace",
      "model": "openai/gpt-5",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 20,
      "memoryWindow": 50
    }
  }

Test your agent on the terminal:

nanobot agent -m "Hello"   

🐈 nanobot
Hi there! How can I help you today?    

Step 5: Set up the Gateway

To finish the Telegram integration, run the command below in the terminal: 

nanobot gateway

You should now see that Telegram is enabled, as you can see from my messages below: 

🐈 Starting nanobot gateway on port 18790...
2026-02-13 09:59:35.405 | INFO     | nanobot.channels.manager:_init_channels:46 - Telegram channel enabled
✓ Channels enabled: telegram
✓ Heartbeat: every 30m
2026-02-13 09:59:35.406 | INFO     | nanobot.cron.service:start:154 - Cron service started with 0 jobs
2026-02-13 09:59:35.406 | INFO     | nanobot.heartbeat.service:start:81 - Heartbeat started (every 1800s)
2026-02-13 09:59:35.406 | INFO     | nanobot.agent.loop:run:116 - Agent loop started
2026-02-13 09:59:35.406 | INFO     | nanobot.channels.manager:start_all:159 - Starting telegram channel...
2026-02-13 09:59:35.406 | INFO     | nanobot.channels.manager:_dispatch_outbound:187 - Outbound dispatcher started
2026-02-13 09:59:35.411 | INFO     | nanobot.channels.telegram:start:140 - Starting Telegram bot (polling mode)...
2026-02-13 09:59:39.245 | INFO     | nanobot.channels.telegram:start:148 - Telegram bot @mwitibananabot connected
2026-02-13 09:59:39.417 | DEBUG    | nanobot.channels.telegram:start:152 - Telegram bot commands registered

Head over to Telegram and test it: 

You can learn how to use Anthropic's Claude Code to improve software development workflows through a practical example using the Supabase Python library from our Claude Code tutorial. 

Leveling Up Nanobot: The "Multi-Tool" Agent

Now that the setup is complete, it’s time to make your agent more functional. Most models have information only up to the cut-off date for their training data. We can make it more functional by connecting it to the internet.

Nanobot supports the Model Context Protocol (MCP), adding capabilities to your agent, such as web search or database queries. Let’s add the Brave Search Server that will enable our agent to access the internet:

1. Get an API key from Brave
2. Update the config with the key

"tools": {
    "web": {
      "search": {
        "apiKey": "",
        "maxResults": 5
      }
    },
    "exec": {
      "timeout": 60
    },
    "restrictToWorkspace": false
  }

Restart your gateway.

Now in Telegram, ask a question like “What is the current price of the Apple Stock?” On the terminal, you can see that it’s actually searching the web: 

2026-02-13 10:14:48.753 | INFO     | nanobot.agent.loop:_process_message:164 - Processing message from telegram:7045522516: What is the current price of the Apple Stock
2026-02-13 10:14:59.726 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_search({"query": "AAPL stock price Yahoo Finance", "count": 5})
2026-02-13 10:15:22.066 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://finance.yahoo.com/quote/AAPL/", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:15:26.886 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://www.google.com/finance/quote/AAPL:NASDAQ", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:15:51.361 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://query1.finance.yahoo.com/v7/finance/quote?symbols=AAPL", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:15:52.018 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://query2.finance.yahoo.com/v10/finance/quoteSummary/AAPL?modules=price", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:16:07.071 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://www.marketwatch.com/investing/stock/aapl", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:16:07.406 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://finviz.com/quote.ashx?t=AAPL", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:16:35.897 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://financialmodelingprep.com/api/v3/quote/AAPL?apikey=demo", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:16:36.919 | INFO     | nanobot.agent.loop:_process_message:246 - Tool call: web_fetch({"url": "https://stooq.com/q/l/?s=aapl.us&i=5", "extractMode": "text", "maxChars": 20000})
2026-02-13 10:17:14.870 | INFO     | nanobot.agent.loop:_process_message:266 - Response to telegram:7045522516: Reflection:
- JS-heavy sites (Yahoo/Google) hid the live quote; Yahoo's JSON APIs blocked (401). 
- Finviz returned a pr...

Local and Private: Running Nanobot Offline

Like OpenClaw, one of Nanobot's biggest selling features is privacy. You can use it without sending any data to any cloud provider. Since Nanobot supports vllm and OpenAI-compatible endpoints, you can point it to a local model runner like Ollama. 

1. Install Ollama and run ollama
2. Update your config.json provider section (see the "local" example in Step 4 above).

Check out our Using OpenClaw with Ollama tutorial to learn how to build a fully local AI data analyst using OpenClaw and Ollama that orchestrates multi-step workflows, analyzes datasets, and generates visual reports, without sending your data to the cloud.

Nanobot Common Pitfalls and Troubleshooting

Even with a simple tool like Nanobot, things can go wrong. Here are a few issues you are likely to face and how to solve them. 

Connection refused errors

If you try to run Nanobot on a server but try to access local models, you will get a connection refused error.  This is because the online server can’t access your local computer. 

To mitigate this, you have to make sure that the open-source models are also running on the same server or use something like ngrok to bridge the connection. 

Context window limits

Local models often have smaller memory limits (context windows). Even cloud-based models have a limited context window. Since Nanobot stores its memory as simple files, the best way to "reset" its brain is to manually delete the memory files inside your ./workspace folder. 

Alternatively, simply switch to a model with a larger context window, like gemini-1.5-pro or Claude Opus 4.6.

Conclusion

Nanobot proves that powerful software doesn’t have to be big. It provides the same core features as OpenClaw while still being massively smaller. However, it still carries the same problem as far as security is concerned, so I advise that you set it up in a sandbox environment to prevent catastrophic problems such as getting your entire hard drive wiped.  

To learn more about working with AI tools, I recommend checking out our guide to the best free AI tools. For broader AI coding skills, try our AI-Assisted Coding for Developers course to develop the skills that make AI assistants more reliable partners in your development workflow. 

You can also discover how to build AI-powered applications using LLMs, prompts, chains, and agents in LangChain from our Developing LLM Applications with LangChain course.