nanobot installieren & einrichten

1 Installation via pipx

pipx installiert Python-Tools isoliert in eigene Umgebungen und macht die Binary global verfügbar – perfekt um nanobot direkt auf dem System laufen zu lassen.

1.1 Vorbereitung

pipx benötigt Python 3.11+ und pip. Fehlt pipx, installierst du es so:

sudo apt update && sudo apt install pipx
pipx ensurepath

brew install pipx
pipx ensurepath

1.2 nanobot installieren

pipx install nanobot

Für die neuste Entwicklungsversion (GitHub):

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

1.3 Ersteinrichtung

Nach der Installation den Assistenten ausführen:

nanobot onboard

Der Assistent fragt nach dem Provider (z.B. OpenAI, GitHub Copilot), erstellt die config.json und zeigt die eingerichteten Kanäle an.

2 Installation via Docker

Die Docker-Installation ist die empfohlene Methode für Server-Umgebungen – nanobot läuft sauber isoliert und startet automatisch mit dem System.

2.1 Image pullen

docker pull smanx/nanobot:latest

2.2 docker-compose.yml

Erstelle eine docker-compose.yml:

version: '3.8'
services:
  nanobot:
    image: smanx/nanobot:latest
    container_name: nanobot
    restart: unless-stopped
    ports:
      - "8900:8900"       # API (optional)
    volumes:
      - ./nanobot_data:/root/.nanobot   # Konfiguration & Daten
    environment:
      - TZ=Europe/Zurich

2.3 Starten & initialisieren

docker compose up -d

# Ersteinrichtung im Container:
docker exec -it nanobot nanobot onboard

Nach dem onboard den Container neu starten damit die Config greift:

docker compose restart

3 Konfiguration anpassen

Die Hauptkonfiguration liegt in ~/.nanobot/config.json (bei Docker: ./nanobot_data/config.json).

3.1 Provider einrichten

nanobot unterstützt mehrere Provider parallel. Wähle einen oder mehrere:

{
  "openai": {
    "apiKey": "dein-api-key",
    "apiBase": "https://api.openai.com/v1"   
  },
  "github_copilot": {
    "oauth": true       
  }
}

3.2 Modell & Reasoning

{
  "model": "deepseek-v4-flash",
  "reasoningEffort": "medium",    
  "contextWindowTokens": 131072,
  "maxTokens": 8192
}

3.3 Telegram Gateway

{
  "gateway": {
    "telegram": {
      "token": "1234567890:ABCdefGHIjklmNOpqrsTUVwxyz",
      "allowedChatIds": ["123456789"]   
    }
  }
}

Den Bot-Token bekommst du von @BotFather auf Telegram. Die allowedChatIds sorgen dafür, dass nur du mit deinem Bot sprechen kannst.

3.4 Nach Änderungen

Nach jeder Config-Änderung den Assistenten ausführen ohne Überschreiben:

echo "n" | nanobot onboard

Danach nanobot und Gateway neu starten (per /restart im Chat oder Docker-Restart).

4 Home Assistant Integration

nanobot kann direkt als Conversation Agent in Home Assistant eingebunden werden. Dazu gibt es ein HACS-Custom-Component von Zeronova.

4.1 Voraussetzung: HACS

HACS muss installiert sein. Falls nicht, folge der offiziellen Anleitung.

4.2 Custom Repository hinzufügen

1. In HACS zu Integrationen → ⋮ → Custom Repositories
2. Repository-URL: https://github.com/Zeronova/HA_nanobot_conversation
3. Kategorie: Integration
4. Repository hinzufügen

4.3 Integration installieren

1. In HACS den Durchsuchen & Download-Tab öffnen
2. Nach HA nanobot conversation Agent suchen
3. Download klicken
4. Home Assistant neu starten

4.4 Integration konfigurieren

1. Einstellungen → Geräte & Dienste → Integration hinzufügen
2. Nach nanobot conversation suchen
3. Dialog abschliessen

4.5 Assist aktivieren

1. Einstellungen → Sprachassistenten → Assistent
2. Einen Assistenten auswählen oder neu erstellen
3. Unter Conversation Agent den nanobot auswählen
4. Sprechen aktivieren falls gewünscht

5 Optionale HACS Components

Für Sprach-Ein- und Ausgabe gibt es noch zwei optionale HACS-Komponenten. Beide laufen mit einem eigenen HTTP-Dienst (Piper TTS, Whisper STT) und werden als Integration in HA eingebunden.

5.1 Piper TTS (HA_piper-http)

Ermöglicht natürlich klingende Sprachausgabe auf Google Nest, Sonos & Co.

• Repository: https://github.com/Zeronova/HA_piper-http
• Erfordert einen laufenden Piper TTS Server (z.B. über Docker: zeronova/piper-http)
• Unterstützt Denglisch-Modus, dynamische Modellauswahl und CUDA-Beschleunigung

Installation: Gleiches Schema wie bei nanobot-conversation – Custom Repository in HACS, Integration installieren, konfigurieren.

5.2 Whisper STT (HA_whisper-http)

Spracherkennung fürs Mikrofon deiner Google Nests oder des Matterhubs.

• Repository: https://github.com/Zeronova/HA_whisper-http
• Erfordert einen laufenden Whisper STT Server (z.B. hwdsl2/whisper-server:cuda auf Port 9000)
• Modelle: large-v3-turbo empfohlen (gute Balance zwischen Geschwindigkeit und Genauigkeit)

Wichtig: Beide Dienste (Piper + Whisper) werden unabhängig von HA betrieben – typischerweise als Docker-Container auf demselben Server. Die HACS-Integration verbindet HA nur mit den laufenden Diensten.