🤖 NanoClaw AI Research Agent

Autonomous arXiv Research Assistant — Powered by NanoClaw · Delivered via Telegram

Search papers · Extract insights · Deliver daily digests · All for free

---

📋 Table of Contents

1. What This Does
2. What is NanoClaw?
3. How It Works
4. Prerequisites
5. Installing NanoClaw Dependencies
   • Node.js 20+
   • Docker
   • Claude Code CLI
6. Getting API Keys
   • OpenRouter API Key
   • Telegram Bot Token
   • Your Telegram Chat ID
7. Installation
8. Configuration
9. Running the Agent
   • Option A: Manual (Testing)
   • Option B: Background (Persistent)
   • Option C: Systemd (Production)
10. Using the Telegram Bot
11. 📸 Screenshots
12. Project Structure
13. Customization
14. Troubleshooting
15. SysAdmin Best Practices
16. FAQ

---

✨ What This Does

This project is a NanoClaw-powered fully autonomous AI research assistant that runs 24/7 on your Linux machine — even a low-spec laptop. It:

• Searches arXiv for the latest AI/ML papers on any topic you request
• Summarizes each paper using a free cloud LLM (via OpenRouter), extracting key ideas and limitations
• Delivers results to Telegram via a clean, structured bot interface
• Sends a daily 7AM digest automatically — no interaction required
• Runs as a hardened systemd service with auto-restart on failure
• Isolated by NanoClaw inside a Docker container for security and reproducibility

💡 Zero cost to run. Uses the OpenRouter free tier (no credit card needed) and the arXiv public API.

---

🦾 What is NanoClaw?

NanoClaw is an open-source, lightweight personal AI agent framework designed to give you full control and ownership of your AI assistant. This repo uses NanoClaw as its runtime environment.

Why NanoClaw?

Feature	What It Means For You
Minimal footprint	A single Node.js process — no bloated framework overhead
Container isolation	Agent sessions run inside Docker containers for filesystem-level security
Multi-platform messaging	Native support for Telegram, WhatsApp, Slack, Discord, and Signal
Skill system	Extend the agent's behavior by writing skills in plain text
Claude Agent SDK	Powered by Anthropic's Claude under the hood
AI-native setup	The /setup skill command guides you through the entire configuration interactively

How NanoClaw Fits Into This Project

[NanoClaw Runtime]  ◄──── Node.js 20+ process
        │
        ├── Docker Container  ◄──── Isolated agent session
        │       │
        │       └── Python venv  ◄──── agent.py + scheduler.py
        │
        └── Claude Agent SDK  ◄──── Skill execution, LLM calls

NanoClaw handles the container lifecycle, messaging platform integration, and skill routing. The Python scripts (agent.py, scheduler.py) handle the arXiv search and OpenRouter summarization logic.

---

🏗️ How It Works

You (Telegram)
     │
     ▼
[NanoClaw Runtime]  ◄──── Node.js 20+ / Claude Agent SDK
     │
     ▼
[Docker Container]  ◄──── Isolated agent session (filesystem security)
     │
     ▼
[Telegram Bot]  ◄──── python-telegram-bot library
     │
     ▼
[agent.py]  ─────► arXiv API  ──► Latest papers (title, abstract, PDF)
     │
     ▼
[LangChain + OpenRouter]  ──► Free Cloud LLM (Qwen, etc.)
     │
     ▼
Structured JSON: { key_ideas, limitations }
     │
     ▼
Formatted Telegram Message  ────► You 📱

─────────────────────────────────────────

[scheduler.py]  ─────► Checks time every 60s
     │
     ▼ (at 07:00 daily)
Calls search_papers() + extract_insights()
     │
     ▼
Sends digest directly to your TELEGRAM_CHAT_ID

Two services run in parallel:

• agent.py — Responds to your /research commands interactively
• scheduler.py — Sends an automated 7AM digest without any input from you

---

✅ Prerequisites

Before you begin, make sure you have the following installed:

Requirement	Version	Purpose	Check Command
Python	3.12+	Runs agent.py & scheduler.py	python3 --version
pip	Latest	Installs Python packages	pip --version
git	Any	Cloning the repo	git --version
systemd	Any	Production service management	systemctl --version
Node.js	20+	NanoClaw runtime	node --version
npm	10+	NanoClaw package manager	npm --version
Docker	Any	NanoClaw container isolation	docker --version
Claude Code	Latest	NanoClaw setup & skill runner	claude --version

Install Python 3.12+ if needed:

# Debian / Ubuntu
sudo apt update && sudo apt install python3.12 python3.12-venv python3-pip -y

# Arch / EndeavourOS
sudo pacman -S python python-pip

# Fedora
sudo dnf install python3.12 python3-pip

---

🦅 Installing NanoClaw Dependencies

NanoClaw requires Node.js 20+, Docker, and the Claude Code CLI. Install them in this order.

---

1. Node.js 20+

NanoClaw runs on a single Node.js process. Version 20 or later is required (22+ recommended).

# ── Debian / Ubuntu ──────────────────────────────────
# Using NodeSource (official recommended method)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version   # Should show v22.x.x or higher
npm --version    # Should show 10.x.x or higher

# ── Arch / EndeavourOS ───────────────────────────────
sudo pacman -S nodejs npm

# Verify
node --version
npm --version

# ── Fedora ───────────────────────────────────────────
sudo dnf module install nodejs:22

# Verify
node --version
npm --version

# ── Any Linux (using nvm — recommended for flexibility) ──
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc   # or ~/.zshrc
nvm install 22
nvm use 22

# Verify
node --version

💡 Using nvm (Node Version Manager) is the most flexible approach — it lets you switch Node versions without affecting system packages.

---

2. Docker

NanoClaw uses Docker to run agent sessions in isolated containers, preventing the agent from accessing unintended parts of your filesystem.

# ── Debian / Ubuntu ──────────────────────────────────
# Install Docker Engine (official script)
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group (so you don't need sudo)
sudo usermod -aG docker $USER
newgrp docker   # Apply group change immediately

# Start and enable Docker service
sudo systemctl enable --now docker

# Verify
docker --version
docker run hello-world   # Should pull and run a test container

# ── Arch / EndeavourOS ───────────────────────────────
sudo pacman -S docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version

# ── Fedora ───────────────────────────────────────────
sudo dnf install docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version

⚠️ Important: After adding yourself to the docker group, you may need to log out and log back in for the change to fully apply. The newgrp docker command is a temporary workaround for the current session.

---

3. Claude Code CLI

Claude Code is the CLI used to manage NanoClaw agents, run skills (like /setup), and interact with the Claude Agent SDK.

Prerequisites for Claude Code:

• Node.js 20+ (installed above)
• An Anthropic account (free to sign up)

# Install Claude Code globally via npm
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Authenticate Claude Code:

# Start the authentication flow
claude
# Follow the prompts to log in with your Anthropic account
# or set your API key:
export ANTHROPIC_API_KEY=sk-ant-your-key-here

💡 Free Tier: Claude Code has a free usage tier. You do not need a paid Anthropic plan to use NanoClaw's basic features.

Verify NanoClaw can run:

# After cloning this repo, run the NanoClaw setup skill
# (This guides you through container setup interactively)
claude
# Then inside claude: /setup

---

🔑 Getting API Keys

You need 3 things before configuring the project. All are free.

---

1. OpenRouter API Key (Free)

OpenRouter gives you access to many LLMs (including Qwen, Mistral, Llama) without needing a paid subscription.

Steps:

1. Go to https://openrouter.ai
2. Click Sign Up (you can use Google or GitHub)
3. Navigate to API Keys in your dashboard
4. Click Create Key → give it a name like ai-research-agent
5. Copy the key — it looks like: sk-or-v1-xxxxxxxxxxxxxxxxxxxx

⚠️ Free tier limits: The free models (e.g. qwen/qwen3.6-plus:free) have rate limits. This agent is designed to work within those limits by adding delays between requests.

---

2. Telegram Bot Token (Free)

Steps:

1. Open Telegram and search for @BotFather
2. Start a chat and send: /newbot
3. Choose a name for your bot (e.g. My Research Bot)
4. Choose a username — must end in bot (e.g. myresearch_bot)
5. BotFather will reply with your token — looks like:

   123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

6. Copy and save this token

---

3. Your Telegram Chat ID

The scheduler needs to know which chat to send the daily digest to.

Steps:

1. Start a conversation with your new bot on Telegram (send /start)
2. Now visit this URL in your browser (replace YOUR_TOKEN with your bot token):

   https://api.telegram.org/botYOUR_TOKEN/getUpdates
   

3. Look for "chat":{"id": in the JSON response
4. The number after "id": is your Chat ID (e.g. 987654321)

💡 Tip: If the response is empty, send your bot any message first, then reload the URL.

---

📦 Installation

Step 1: Clone the Repository

git clone https://github.com/bmo1177/ai-research-agent.git
cd ai-research-agent

Step 2: Run the Setup Script

The setup.sh script handles everything automatically:

chmod +x setup.sh
./setup.sh

This script will:

• ✅ Create a Python virtual environment (venv/)
• ✅ Upgrade pip, setuptools, and wheel
• ✅ Install all dependencies from requirements.txt
• ✅ Copy .env.example → .env (if .env doesn't exist yet)
• ✅ Lock .env permissions to chmod 600 (owner-only read/write)

Expected output:

🚀 Setting up AI Research Agent...
📦 Creating virtual environment...
📥 Installing Python dependencies...
⚙️  Creating .env from template...
🔒 Please edit .env with your API keys before continuing!

✅ Dependencies installed.
📝 Next steps:
   1. Edit .env with your OpenRouter & Telegram credentials
   2. Run: systemctl --user daemon-reexec
   3. Enable services: systemctl --user enable ai-research.service ai-research-scheduler.service
   4. Start: systemctl --user start ai-research.service ai-research-scheduler.service

---

⚙️ Configuration

Open .env in your editor:

nano .env
# or
vim .env

Fill in your credentials:

# ========================
# OpenRouter API (Free Tier)
# ========================
OPENROUTER_API_KEY=sk-or-v1-your-actual-key-here
OPENAI_BASE_URL=https://openrouter.ai/api/v1
DEFAULT_MODEL=qwen/qwen3.6-plus:free

# ========================
# Telegram Bot Configuration
# ========================
TELEGRAM_BOT_TOKEN=123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHAT_ID=987654321

Save and secure the file:

chmod 600 .env

Changing the AI Model

To use a different free model from OpenRouter, update DEFAULT_MODEL. Some options:

Model	Value	Notes
Qwen 3.6 Plus (default)	qwen/qwen3.6-plus:free	Fast, good quality
Mistral 7B	mistralai/mistral-7b-instruct:free	Reliable
Llama 3 8B	meta-llama/llama-3-8b-instruct:free	Open-source
Gemma 3	google/gemma-3-27b-it:free	Google's model

Browse all free models at openrouter.ai/models.

---

▶️ Running the Agent

There are three ways to run this project. Start with Option A to test everything works, then move to Option C for production.

---

Option A: Manual (For Testing)

Run the bot directly in your terminal — good for verifying credentials work.

# Activate the virtual environment
source venv/bin/activate

# Start the bot
python agent.py

You should see:

✅ AI Research Agent started! Model: qwen/qwen3.6-plus:free

Open Telegram, send /start to your bot, and test with /research transformers.

To stop: Ctrl + C

---

Option B: Background (nohup)

Run the bot detached from your terminal — it keeps running after you close the SSH session or terminal.

source venv/bin/activate

# Start agent in background
nohup python agent.py > logs/agent.log 2>&1 &
echo "Agent PID: $!"

# Start scheduler in background
nohup python scheduler.py > logs/scheduler.log 2>&1 &
echo "Scheduler PID: $!"

Check logs:

tail -f logs/agent.log
tail -f logs/scheduler.log

Stop the processes:

pkill -f "python agent.py"
pkill -f "python scheduler.py"

⚠️ These will stop if the machine reboots. Use Option C for true persistence.

---

Option C: Systemd (Recommended for Production)

This runs the agent as a proper Linux service — starts on boot, restarts on crash, logs to journald.

Step 1: Link the service files

mkdir -p ~/.config/systemd/user

ln -sf "$(pwd)/systemd/ai-research.service" ~/.config/systemd/user/ai-research.service
ln -sf "$(pwd)/systemd/ai-research-scheduler.service" ~/.config/systemd/user/ai-research-scheduler.service

Step 2: Reload and enable the services

systemctl --user daemon-reexec
systemctl --user daemon-reload

systemctl --user enable ai-research.service
systemctl --user enable ai-research-scheduler.service

Step 3: Start the services

systemctl --user start ai-research.service
systemctl --user start ai-research-scheduler.service

Step 4: Verify they are running

systemctl --user status ai-research.service
systemctl --user status ai-research-scheduler.service

You should see Active: active (running) in green.

Step 5 (Optional): Enable boot persistence without login

By default, user services only run after you log in. To make them start at boot (even on a headless server):

sudo loginctl enable-linger $USER

This is required if you're running on a VPS or server where you don't interactively log in.

---

💬 Using the Telegram Bot

Once the agent is running, open Telegram and chat with your bot.

Commands

Command	Description	Example
/start	Initialize the bot and show help	/start
/help	Show available commands	/help
/research [topic]	Search arXiv and summarize recent papers	/research mixture of experts
/daily	Manually trigger today's research digest	/daily

Example Session

You:    /research vision transformers

Bot:    🔍 Searching arXiv for: vision transformers
        ⏳ Please wait 30-60 seconds...

Bot:    📄 Analyzing 1/4...

Bot:    📄 Efficient Vision Transformer with Sparse Attention
        👥 Authors: Li Wei, Zhang Hui, Chen Ming
        🔗 arXiv: 2401.12345
        📅 Published: 2024-01-15

        🔑 Key Ideas:
        • Sparse attention mechanism reduces quadratic complexity
        • Achieves 94.2% accuracy on ImageNet with 40% less compute
        • Compatible with standard ViT architectures

        ⚠️ Limitations:
        • Only tested on image classification, not detection
        • Requires specific hardware for sparse ops

        📎 PDF Link
        ---

Searching for Custom Topics

The /research command accepts any topic string:

/research reinforcement learning from human feedback
/research protein structure prediction
/research energy-efficient neural networks
/research federated learning privacy
/research code generation LLM

The agent builds an arXiv query targeting cs.AI and cs.LG categories, sorted by newest submissions.

---

📸 Screenshots

Real screenshots of the bot running in Telegram:

Bot in Action

💡 Tip: Images are loaded from Google Drive. If they don't render in your browser, make sure the files are set to "Anyone with the link can view" in Google Drive sharing settings.

---

📁 Project Structure

ai-research-agent/
│
├── README.md                   # This file
├── LICENSE                     # MIT License
├── .gitignore                  # Excludes secrets, venv, data
├── .env.example                # Template — copy to .env and fill in
├── requirements.txt            # Python dependencies
├── setup.sh                    # One-command installer
│
├── agent.py                    # Main Telegram bot
│   ├── search_papers()         #   Queries arXiv API
│   ├── extract_insights()      #   Calls LLM via LangChain
│   ├── handle_research()       #   /research command handler
│   ├── handle_daily()          #   /daily command handler
│   └── start_command()         #   /start + /help handler
│
├── scheduler.py                # Daily 7AM digest service
│   └── send_daily_digest()     #   Sends papers to TELEGRAM_CHAT_ID
│
└── systemd/
    ├── ai-research.service           # Systemd unit for agent.py
    └── ai-research-scheduler.service # Systemd unit for scheduler.py

---

🔧 Customization

Change the Daily Digest Topic

In scheduler.py, find and edit this line:

topic = "efficient large language models"

Change it to any research topic you're interested in:

topic = "multimodal language models"
# or
topic = "reinforcement learning robotics"
# or
topic = "quantum machine learning"

Change the Digest Time

In scheduler.py, find:

if now.hour == 7 and now.minute == 0:

Change 7 to any hour (0–23) in 24-hour format:

if now.hour == 9 and now.minute == 0:   # 9:00 AM
if now.hour == 18 and now.minute == 0:  # 6:00 PM

Change the Number of Papers

In agent.py, the search_papers() function accepts max_results:

def search_papers(topic: str, max_results: int = 4):

Change the default or pass a different value when calling it.

Change the arXiv Categories

By default, results are from cs.AI and cs.LG. Modify the query in search_papers():

query=f"cs.AI OR cs.LG AND ({topic})",

Other useful categories:

• cs.CV — Computer Vision
• cs.CL — Computation and Language (NLP)
• cs.RO — Robotics
• stat.ML — Machine Learning (statistics)
• cs.NE — Neural and Evolutionary Computing

---

🔧 Troubleshooting

Bot doesn't respond to commands

# 1. Check if agent.py is running
systemctl --user status ai-research.service

# 2. Check logs for errors
journalctl --user -u ai-research.service -n 50 --no-pager

# 3. Make sure .env has the correct TELEGRAM_BOT_TOKEN
cat .env

---

"Conflict" error — bot already running elsewhere

telegram.error.Conflict: Conflict: terminated by other getUpdates request

This means two instances of agent.py are running at the same time.

# Kill all running instances
pkill -f "python agent.py"

# Restart via systemd
systemctl --user restart ai-research.service

---

"Unauthorized" error at startup

telegram.error.Unauthorized: Unauthorized

Your TELEGRAM_BOT_TOKEN is wrong or expired.

# Verify the token
cat .env | grep TELEGRAM_BOT_TOKEN

Go back to @BotFather on Telegram → /mybots → select your bot → API Token to get a fresh token.

---

OpenRouter API error / no output from LLM

# Check logs
journalctl --user -u ai-research.service -f --no-pager

# Verify the API key
cat .env | grep OPENROUTER_API_KEY

• Make sure the key starts with sk-or-v1-
• Check your usage at openrouter.ai/activity
• Try a different free model in .env (DEFAULT_MODEL=mistralai/mistral-7b-instruct:free)

---

Daily digest not sending

# 1. Check scheduler is running
systemctl --user status ai-research-scheduler.service

# 2. Check TELEGRAM_CHAT_ID is set
cat .env | grep TELEGRAM_CHAT_ID

# 3. Manually trigger the digest to test
source venv/bin/activate
python -c "import asyncio; from scheduler import send_daily_digest; asyncio.run(send_daily_digest())"

---

Services stop after reboot / logout

Enable linger so user services survive without a login session:

sudo loginctl enable-linger $USER

# Verify
loginctl show-user $USER | grep Linger
# Should show: Linger=yes

---

Checking all logs at once

# Follow both services in real time (split terminal or tmux)
journalctl --user -u ai-research.service -f --no-pager &
journalctl --user -u ai-research-scheduler.service -f --no-pager

---

🔒 SysAdmin Best Practices

This project implements production-grade Linux practices out of the box:

Practice	Implementation
Secret Management	.env.example for safe commits; .env excluded by .gitignore; chmod 600 .env; EnvironmentFile= in systemd (never exposed to process list)
Process Isolation	NoNewPrivileges=true — service cannot gain elevated privileges
Filesystem Protection	ProtectSystem=full — /usr, /boot, /etc are read-only to the service
Temp Directory Isolation	PrivateTmp=true — service gets its own /tmp, isolated from system
Write Scope Limiting	ReadWritePaths= restricts writes to the project directory only
Resilience	Restart=on-failure + RestartSec=15 — auto-recovers from crashes
Structured Logging	StandardOutput=journal — all logs are queryable via journalctl
User-Level Services	Runs in user slice, no sudo required, unaffected by system updates
Boot Persistence	loginctl enable-linger for headless/server boot startup
Token Conflict Prevention	Single systemd-managed instance + drop_pending_updates=True in bot

---

❓ FAQ

Q: Does this cost anything? No. The OpenRouter free tier, arXiv API, and Telegram Bot API are all free with no credit card required.

Q: What hardware does this need? Very little. It runs fine on a 5th gen i3 with 8GB RAM. It uses ~50MB RAM at idle.

Q: Can I run this on a Raspberry Pi or VPS? Yes. Any Linux machine with Python 3.12+ works. A $5/month VPS (e.g. Hetzner, DigitalOcean) runs this perfectly.

Q: Does it work on Windows or macOS? The Python agent (agent.py and scheduler.py) works cross-platform. The systemd setup is Linux-only. On macOS/Windows you can use nohup or a process manager like pm2.

Q: Can I search topics other than AI? Yes. The arXiv query can be changed to any category or keyword. See the Customization section.

Q: The bot is slow — it takes 30-60 seconds to respond. Is that normal? Yes. The delay is intentional: arXiv requests a delay between API calls (delay_seconds=3.0), and the LLM inference on the cloud adds latency. The agent notifies you it's working while it processes.

Q: Can multiple users use the same bot? Yes — any Telegram user who has the bot link can send commands. If you want it private, check Telegram's privacy settings for bots.

Q: How do I update the project?

git pull origin main
source venv/bin/activate
pip install -r requirements.txt
systemctl --user restart ai-research.service ai-research-scheduler.service

---

📜 License

MIT — free to use, modify, and distribute. See LICENSE.

---

Built with ❤️ using NanoClaw · Python · LangChain · arXiv · OpenRouter · Telegram · Docker

NanoClaw Docs · OpenRouter Models · arXiv API

Star ⭐ this repo if it helped you!