Gmail skill OpenClaw

Introduction

Relier Gmail à OpenClaw transforme l'email en canal d'entrée et de sortie pour vos agents. Vous pouvez lire une boîte partagée, envoyer des rapports automatiques, classer des messages ou déclencher des actions selon le contenu reçu. Si vous maîtrisez déjà les bases des skills OpenClaw, ce tutoriel vous montre la partie la plus sensible, l'authentification OAuth2 avec Gmail, puis les opérations utiles au quotidien. L'objectif est simple, obtenir un skill fiable, réutilisable et assez sûr pour automatiser des workflows email sans réauthentification manuelle à chaque exécution.

Résumé rapide

1. Créez un projet Google Cloud, activez Gmail API et générez un client OAuth2 Desktop App.
2. Installez google-auth-oauthlib et google-api-python-client dans l'environnement du skill.
3. Stockez credentials.json et persistez token.json pour réutiliser le refresh token.
4. Exposez trois briques dans le skill, lire, envoyer et labelliser des emails.
5. Limitez les scopes, filtrez les données sensibles et évitez d'envoyer des informations confidentielles via l'agent.

Explication

Un Gmail skill OpenClaw est un connecteur entre vos agents et l'API Gmail. Au lieu de manipuler l'interface web de Google, le skill appelle l'API officielle pour lister des messages, lire leur contenu, créer un brouillon, envoyer un email ou modifier des labels. C'est plus robuste qu'un scraping de boîte mail, plus propre pour la maintenance et mieux adapté aux automatisations récurrentes.

Dans l'écosystème OpenClaw, ce skill joue souvent deux rôles. Premier rôle, la sortie. Un agent de veille peut envoyer un digest hebdomadaire, un agent d'exploitation peut transmettre un rapport d'erreur, un agent commercial peut préparer un brouillon à relire. Deuxième rôle, l'entrée. Une boîte Gmail dédiée peut devenir une file de demandes à traiter, par exemple pour classifier des messages entrants ou prioriser des demandes internes.

La vraie difficulté n'est pas la lecture d'un message, mais l'authentification. Gmail impose OAuth2. Vous devez donc créer des identifiants dans Google Cloud, lancer un premier consentement utilisateur, enregistrer le token obtenu, puis laisser la librairie Google le rafraîchir automatiquement. Une fois cette base en place, le reste ressemble à un skill Python classique, dans l'esprit de l'API skills d'OpenClaw, avec une couche supplémentaire de sécurité et de gestion des quotas.

Développement principal

Prérequis

Avant de coder, préparez ces éléments:

• un compte Google dédié au workflow si possible
• un projet Google Cloud
• Gmail API activée
• un client OAuth2 de type Desktop App
• Python 3.10+ dans l'environnement OpenClaw
• les dépendances google-auth-oauthlib, google-auth-httplib2 et google-api-python-client

Installez les dépendances:

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

Étape 1, créer le projet et activer Gmail API

Dans Google Cloud Console, créez un projet puis activez Gmail API. Ensuite, ouvrez la section OAuth consent screen. Pour un usage interne ou de test, une configuration minimale suffit, mais renseignez au moins le nom de l'application et l'email de support. Créez ensuite un identifiant OAuth Client ID de type Desktop App et téléchargez le fichier credentials.json.

Placez ce fichier dans un répertoire non publié, par exemple:

secrets/gmail/credentials.json

N'ajoutez jamais ce fichier au dépôt Git.

Étape 2, gérer le token OAuth2 proprement

Le point important est de persister le token après la première autorisation. Sans cela, votre skill vous redemandera une connexion à chaque exécution. Le snippet ci-dessous crée le service Gmail, recharge un token existant si possible et le rafraîchit automatiquement.

from pathlib import Path
import json

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = [
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/gmail.send",
]

BASE_DIR = Path(__file__).resolve().parent
CREDENTIALS_FILE = BASE_DIR / "secrets" / "gmail" / "credentials.json"
TOKEN_FILE = BASE_DIR / "secrets" / "gmail" / "token.json"


def get_gmail_service():
    creds = None

    if TOKEN_FILE.exists():
        creds = Credentials.from_authorized_user_file(str(TOKEN_FILE), SCOPES)

    if creds and creds.expired and creds.refresh_token:
        creds.refresh(Request())
        TOKEN_FILE.write_text(creds.to_json(), encoding="utf-8")
    elif not creds or not creds.valid:
        flow = InstalledAppFlow.from_client_secrets_file(str(CREDENTIALS_FILE), SCOPES)
        creds = flow.run_local_server(port=0)
        TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
        TOKEN_FILE.write_text(creds.to_json(), encoding="utf-8")

    return build("gmail", "v1", credentials=creds)

Ce premier lancement ouvre un navigateur local pour le consentement Google. Une fois le token.json créé, vos exécutions suivantes deviennent non interactives, ce qui est indispensable pour l'automatisation.

Étape 3, lire les derniers emails

Pour lire les messages récents, commencez petit. Listez les IDs, puis récupérez chaque message en format metadata ou full selon le besoin. Exemple simple:

def list_recent_messages(service, max_results=10, query=""):
    response = service.users().messages().list(
        userId="me",
        maxResults=max_results,
        q=query,
    ).execute()
    return response.get("messages", [])


def get_message(service, message_id):
    return service.users().messages().get(
        userId="me",
        id=message_id,
        format="full",
    ).execute()

Le paramètre q est très utile. Vous pouvez filtrer par expéditeur, label ou objet, par exemple:

• from:client@example.com is:unread
• label:inbox newer_than:7d
• subject:(facture) has:attachment

Pour un agent email OpenClaw, ne passez pas tout le corps du message au modèle par défaut. Extrayez d'abord les métadonnées utiles, sujet, expéditeur, date, labels, puis ne transmettez le contenu complet qu'en cas de besoin. Cela réduit les coûts, le bruit et les risques de fuite.

Étape 4, envoyer un email formaté

L'envoi passe par un message MIME encodé en base64 URL-safe. Voici une implémentation minimale:

import base64
from email.mime.text import MIMEText


def send_email(service, to, subject, body):
    message = MIMEText(body, "plain", "utf-8")
    message["to"] = to
    message["subject"] = subject

    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
    payload = {"raw": raw}

    return service.users().messages().send(userId="me", body=payload).execute()

Pour des pièces jointes, utilisez MIMEMultipart et ajoutez les fichiers comme parties MIME. Gardez cette logique dans une fonction séparée afin que le skill reste lisible.

Un bon usage est l'envoi d'un digest hebdomadaire. Chaque lundi à 8h, un agent récupère les signaux d'une veille, produit un résumé structuré et l'envoie à une liste courte. Si votre besoin relève plutôt de l'alerte instantanée que du compte rendu email, vous pouvez aussi envisager un canal temps réel via Slack ou un autre outil de messagerie d'équipe. OpenClaw couvre bien ces scénarios grâce à ses skills et à ses intégrations documentées dans les tutoriels du site.

Étape 5, trier, archiver et marquer comme lu

Le vrai gain opérationnel vient souvent du triage. Gmail permet de modifier les labels d'un message pour l'archiver, le classer ou le marquer comme lu.

def modify_message_labels(service, message_id, add_labels=None, remove_labels=None):
    body = {
        "addLabelIds": add_labels or [],
        "removeLabelIds": remove_labels or [],
    }
    return service.users().messages().modify(
        userId="me",
        id=message_id,
        body=body,
    ).execute()

Exemples de règles utiles:

1. si l'expéditeur appartient à une liste VIP, ajouter un label PRIORITY
2. si l'objet contient newsletter, retirer INBOX pour archiver
3. si un agent a déjà extrait le contenu et stocké le résultat ailleurs, marquer le message comme lu

Vous pouvez aussi créer une couche de décision côté OpenClaw. L'agent lit les métadonnées, propose une action, puis le skill exécute uniquement une commande bornée, par exemple archive, label_finance ou mark_read. Cette séparation limite le risque d'actions trop larges.

Checklist de validation

Avant de considérer le tutoriel terminé, vérifiez:

• le consentement OAuth2 s'ouvre bien au premier lancement
• token.json est créé et réutilisé
• la lecture d'un email fonctionne avec une requête simple
• l'envoi vers votre propre adresse aboutit
• une modification de label archive ou classe correctement le message
• aucun secret n'est versionné dans Git

Exemple concret

Prenons un cas reproductible, un agent qui envoie automatiquement un digest hebdomadaire chaque lundi matin. Le workflow est simple. Une tâche planifiée exécute un script OpenClaw. Le script collecte des notes internes, des indicateurs ou des articles de veille. Un agent résume ces éléments en cinq blocs, priorités, risques, opportunités, décisions attendues, liens utiles. Enfin, le Gmail skill envoie ce texte à une liste de destinataires.

L'implémentation minimale ressemble à ceci:

def build_weekly_digest(items):
    lines = ["Digest hebdomadaire", ""]
    for item in items:
        lines.append(f"- {item}")
    return "\n".join(lines)

service = get_gmail_service()
content = build_weekly_digest([
    "3 leads prioritaires détectés",
    "1 incident production résolu",
    "2 opportunités SEO à traiter",
])

send_email(
    service,
    to="equipe@example.com",
    subject="Digest hebdomadaire OpenClaw",
    body=content,
)

Résultat attendu, l'équipe reçoit un email stable, horodaté et lisible sans ouvrir un dashboard. C'est particulièrement utile pour des destinataires qui ne vivent pas dans OpenClaw toute la journée. Si vous voulez aller plus loin, ajoutez une étape de lecture des réponses pour identifier les emails contenant un mot-clé comme VALIDÉ ou À REVOIR, puis déclenchez une action interne. Ce type de boucle simple suffit souvent avant d'envisager une architecture plus complexe comme un agent multi-canal ou un système plus large d'automatisation OpenClaw.

Bonnes pratiques

Utilisez toujours le scope minimal. Si votre agent doit seulement envoyer des emails, n'accordez pas gmail.modify. À l'inverse, si vous devez lire et classer des messages, documentez clairement pourquoi ce niveau d'accès est nécessaire. Séparez idéalement le compte Gmail personnel et le compte utilisé par l'agent.

Deuxième point, ne laissez pas le modèle décider librement d'envoyer n'importe quoi à n'importe qui. Encadrez les destinataires autorisés, les types de messages et les labels modifiables. Une approche sûre consiste à exposer des commandes applicatives très bornées au lieu de l'API brute.

Troisième point, soyez prudent sur la confidentialité et le RGPD. Évitez d'injecter des données sensibles, des pièces d'identité, des informations RH ou des documents financiers entiers dans le contexte d'un agent. Préférez l'extraction locale de champs utiles et la pseudonymisation si possible.

Enfin, surveillez les quotas et les erreurs 401, 403 ou 429. Un refresh token révoqué, un scope changé ou un excès de requêtes peut casser le workflow. Logguez explicitement ces cas pour pouvoir réagir vite.

Questions fréquentes

Comment connecter Gmail à OpenClaw ?

Il faut créer un projet Google Cloud, activer Gmail API, générer un client OAuth2, puis utiliser google-auth-oauthlib et google-api-python-client dans votre skill. Le premier lancement crée un token réutilisable. C'est la base d'un gmail skill openclaw stable.

Peut-on envoyer des emails automatiquement avec OpenClaw ?

Oui. Un agent email OpenClaw peut générer un rapport, préparer un corps d'email puis le transmettre à Gmail API pour envoi. Le plus sûr est de limiter les destinataires et de valider le format attendu avant tout envoi automatique à des tiers.

Faut-il utiliser IMAP ou Gmail API ?

Pour un projet moderne, Gmail API est généralement préférable. Vous obtenez OAuth2 natif, une meilleure gestion des labels et un modèle d'autorisation plus propre. IMAP reste utile dans certains environnements historiques, mais pour openclaw gmail api, l'API officielle est le choix le plus robuste.

Peut-on trier une boîte mail avec un agent OpenClaw ?

Oui, si vous accordez le scope adapté. Le skill peut rechercher des messages, lire leurs métadonnées puis ajouter ou retirer des labels pour archiver, marquer comme lu ou classer. C'est une bonne porte d'entrée pour automatiser emails OpenClaw sans construire un système trop complexe.

Articles liés

Le Gmail skill OpenClaw est pertinent si vous voulez brancher vos agents sur un canal universel, asynchrone et très simple à adopter côté équipe. Commencez par la version minimale, lecture ou envoi, puis ajoutez le triage seulement quand vos règles sont claires. La prochaine étape logique consiste à renforcer vos skills et à connecter d'autres canaux ou automatisations.

• Comprendre les skills OpenClaw
• Exemples de skills OpenClaw à réutiliser
• Créer un skill via l'API OpenClaw
• Mettre en place une automatisation OpenClaw
• Panorama des outils pour agents IA