Déploiement du réseau

Déploiement de ZeroClaw pour qu’il puisse recevoir du trafic entrant : exposition de la passerelle, canaux webhook, tunnels, et configurations uniquement en LAN ou accessibles publiquement. Les Raspberry Pi et autres hôtes du réseau domestique sont des cibles de premier plan ici.

Lorsque les ports entrants sont importants

Conclusion : un bot exclusivement Telegram fonctionne sur un Pi derrière un routeur grand public sans aucune redirection de port. Tout ce qui repose sur des webhooks nécessite une URL accessible, et c’est là que les tunnels entrent en jeu.

Liaison de la passerelle

Par défaut, la passerelle se lie à 127.0.0.1, inaccessible depuis les autres appareils. Trois options pour l’exposer :

Option 1 : Liaison publique (LAN)

Ensuite, n’importe quel appareil sur le réseau local peut accéder à http://<pi-ip>:42617. Cela ne suffit pas pour les webhooks accessibles depuis Internet, l’IP publique de votre routeur n’est pas redirigée vers le Pi.

Sécurité : allow_public_bind = true est requis car la liaison à 0.0.0.0 constitue un changement significatif de posture. Sans cette option, le daemon refuse. C’est intentionnel.

Option 2 : Tunnel (accessible depuis Internet)

Redémarrez ensuite le démon, le tunnel est géré de manière déclarative depuis la configuration, démarrant en même temps que la passerelle.

Le tunnel redirige depuis une URL publique vers la passerelle sur 127.0.0.1. Aucune configuration de routeur, aucun port ouvert. Définissez tunnel.tunnel_provider sur l’une des valeurs prises en charge ; chacune fonctionne de manière similaire :

tunnel_provider = "none" (la valeur par défaut) garde la passerelle locale sans tunnel. Consultez la référence de configuration pour les champs [tunnel.<provider>] de chaque fournisseur.

Option 3 : Proxy inverse

Exécutez nginx / Caddy / Traefik devant la passerelle. Terminez TLS là-bas, puis faites un proxy vers localhost:42617. Convient pour :

• Serveurs avec une adresse IP publique réelle
• Configurations de proxy inversé existantes avec Let’s Encrypt
• Servir plusieurs services sur le même hôte

Une configuration minimale de Caddy :

agent.example.com {
    reverse_proxy localhost:42617
}

La passerelle reste liée à 127.0.0.1, c’est le proxy qui se charge de l’écoute.

Authentification générique des webhooks de passerelle

Les routes POST /webhook et POST /sop/* réservées au SOP de la passerelle peuvent exiger, indépendamment de l’appairage, un en-tête contenant exactement le secret partagé :

[gateway]
webhook_secret = "replace-with-a-random-secret"

Envoyez la valeur dans X-Webhook-Secret. Lorsque require_pairing = true et que webhook_secret est défini, les appelants doivent envoyer à la fois le jeton bearer associé et le secret du webhook. Le secret générique de la passerelle est délibérément distinct de [channels.webhook.<alias>].secret ; les alias de canal utilisent leurs propres écouteurs et une vérification HMAC du corps à la place.

Les écritures de configuration de la passerelle prennent effet via la vue de configuration de la passerelle en cours d’exécution. Les modifications directes des fichiers nécessitent le rechargement normal du démon (ou le redémarrage d’une passerelle autonome).

Rechargement du démon distant

POST /admin/reload relit config.toml et reconstruit chaque sous-système sur place (même PID, temps d’arrêt inférieur à la seconde). C’est la méthode officiellement prise en charge pour appliquer des modifications de configuration sans redémarrage complet. Par défaut, il n’accepte que les appelants en loopback, donc un tableau de bord distant ou un curl depuis une autre machine reçoit 403 Forbidden.

Pour autoriser les rechargements à distance authentifiés :

[gateway]
allow_remote_admin = true    # off by default
require_pairing = true        # required for remote reload (also the default)

Lorsque cette option est activée, un appelant non loopback peut accéder à /admin/reload uniquement s’il réussit également l’authentification par appairage (Authorization: Bearer <token>). Les appelants loopback (la CLI locale) sont toujours autorisés et n’ont pas besoin de jeton. /admin/shutdown et les points de terminaison de code d’appairage restent accessibles uniquement depuis localhost, indépendamment de cet indicateur.

Comme l’accès distant est appliqué via l’appairage, allow_remote_admin n’a aucun effet sauf si require_pairing est également activé : si l’appairage est désactivé, un appelant distant ne peut pas être authentifié, donc la requête est rejetée avec 403 Forbidden plutôt qu’autorisée de manière anonyme. Cela rend impossible l’exposition d’un rechargement distant non authentifié en basculant un seul indicateur.

Sécurité : laissez allow_remote_admin désactivé sauf si vous avez spécifiquement besoin de recharger depuis un autre hôte. Conservez require_pairing = true (la valeur par défaut) afin que les rechargements ne puissent pas être déclenchés anonymement.

Déploiement sur Raspberry Pi

Prérequis

• Raspberry Pi 3/4/5 (ou un SBC similaire) avec Raspberry Pi OS ou Alpine
• Connectivite reseau (WiFi ou Ethernet)
• Facultatif : périphériques USB pour l’intégration matérielle

Installer

Clonez et exécutez l’installateur. Sans aucun flag, il ouvre un sélecteur interactif dans lequel vous choisissez le type de build et les fonctionnalités à compiler, y compris les fonctionnalités matérielles pour GPIO/I2C/SPI. Sur le Pi, il utilise également les profils cargo optimisés pour le Pi ; consultez Configuration du Raspberry Pi pour la configuration du swap et la matrice de build par modèle.

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

apk add curl rust cargo openssl-dev pkgconf git
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

Accorde l’accès à GPIO, I2C, SPI via rppal lorsque vous choisissez les fonctionnalités matérielles. L’unité de service par défaut ajoute déjà l’utilisateur aux groupes gpio, spi, i2c.

Liste de contrôle

• Installez le binaire (./install.sh, choisissez vos fonctionnalités dans le sélecteur)
• Exécutez zeroclaw quickstart
• Configurez vos canaux. Telegram n’a pas besoin de port ; les webhooks nécessitent un tunnel
• Installez le service : zeroclaw service install && zeroclaw service start
• Pour l’accès LAN : définissez [gateway] host = "0.0.0.0" + allow_public_bind = true
• Pour les webhooks : configurez [tunnel] avec un fournisseur

Alpine Linux (OpenRC)

Les services OpenRC s’exécutent à l’échelle du système. Installez en tant que root :

sudo zeroclaw service install

Crée :

• /etc/init.d/zeroclaw : script d’initialisation
• /etc/zeroclaw/ : répertoire de configuration
• /var/log/zeroclaw/ : fichiers journaux

Activer et démarrer :

sudo rc-update add zeroclaw default
sudo rc-service zeroclaw start
sudo rc-service zeroclaw status

Journaux :

sudo tail -f /var/log/zeroclaw/error.log

Notes sur OpenRC

• Le service s’exécute en tant que zeroclaw:zeroclaw (privilège minimal)
• Échelle système uniquement : pas de services OpenRC au niveau utilisateur
• Toutes les opérations de service nécessitent sudo.

Inconvénient du sondage Telegram

L’API getUpdates du Bot Telegram n’autorise qu’un seul poller par token de bot. Vous ne pouvez pas exécuter deux instances avec le même token ; la seconde reçoit Conflict: terminated by other getUpdates request.

Si vous voyez ceci :

1. ps aux | grep zeroclaw et confirmez qu’un seul daemon est en cours d’exécution

2. Vérifiez que vous n’avez pas cargo run --bin zeroclaw -- channel start telegram d’une session de développement en cours d’exécution.

3. Si périmé, réinitialiser la session de sondage de Telegram :

   sh

   curl -X POST "https://api.telegram.org/bot$TOKEN/close"
   

Exposer des webhooks en toute sécurité

Une URL de webhook accessible publiquement constitue une surface d’attaque. Au minimum :

• Vérification de signature HMAC : secret configuré sur chaque canal de webhook
• Liste d’adresses IP autorisées pour les services disposant d’adresses IP de sortie fixes (GitHub, AWS SNS)
• Limitation de débit : rate_limit_per_sec dans la configuration du canal webhook

Voir Canaux → Webhooks pour l’ensemble complet des options de configuration.

Voir aussi

• Setup → Container : configuration réseau spécifique à Docker
• Configuration → Gestion des services : intégration des services de la plateforme
• Opérations → Aperçu
• Sécurité → Aperçu