gws-gmail-watch

What This Skill Does

The gws-gmail-watch skill is a specialized OpenClaw agent capability designed to provide real-time monitoring of your Gmail inbox via Google Cloud Pub/Sub. Unlike traditional polling methods that can be inefficient or rate-limited, this skill leverages Google's push notifications to alert the agent to new incoming emails as they arrive. Once triggered, the skill streams these emails directly to the agent in Newline Delimited JSON (NDJSON) format, allowing for seamless integration into automated workflows, data processing pipelines, or real-time alert systems. It abstracts the complexity of setting up GCP Pub/Sub topics and subscriptions, providing a clean command-line interface to manage incoming communication streams.

Installation

To install this skill, use the ClawHub CLI command: clawhub install openclaw/skills/skills/googleworkspace-bot/gws-gmail-watch. Ensure that you have first initialized your workspace with gws generate-skills to satisfy the prerequisite gws-shared dependencies, which handle the necessary OAuth2 authentication scopes for Gmail and Google Cloud Platform access. You may also need to ensure your GCP project has the Gmail API enabled and appropriate permissions configured for Pub/Sub topic publication.

Use Cases

This skill is perfect for developers and power users who need to bridge the gap between their inbox and external systems. Common use cases include: 1) Triggering automated ticket creation in Jira or Linear when a support email arrives. 2) Building a real-time sentiment analysis dashboard for customer feedback. 3) Archiving emails to a local file system or a vector database for future RAG-based search. 4) Creating custom notifications that bridge Gmail with other messaging platforms like Slack or Discord.

Example Prompts

• "OpenClaw, start watching my inbox for emails labeled 'Urgent', and save every new message to the local ./urgent-tasks directory as a JSON file.
• "Listen for new emails in my inbox using the existing Pub/Sub topic 'gmail-watch-topic' and output the stream directly to my terminal for debugging.
• "Monitor my inbox for any incoming correspondence from '[email protected]' and notify me immediately by executing a local script.

Tips & Limitations

• The Gmail Watch API has a natural expiration window of 7 days; you must restart the watch process periodically to maintain the connection.
• When using the --cleanup flag, the agent will remove Pub/Sub resources upon termination, which is excellent for ephemeral tasks but requires re-provisioning on the next run.
• Use the --label-ids flag to strictly filter incoming traffic, reducing the noise processed by your agent and improving overall performance.