openclaw-smart-calendar

Intelligent Google Calendar management for OpenClaw — travel buffers, conflict detection, AI scheduling suggestions, pattern detection, and daily briefings.

Uses the Google Calendar API directly via googleapis — no external CLI tools required.

Table of Contents

• Prerequisites
• Installation & Setup
• Configuration
• Usage
• Tools Reference
• Smart Features
• Troubleshooting
• Development

Prerequisites

Before installing the plugin, you need:

1. An OpenClaw instance — running on your machine, server, or DigitalOcean droplet
2. Node.js 18+
3. A Google account — with access to Google Calendar
4. A Google Cloud project with the Calendar API enabled and auth credentials ready

Follow the steps below to prepare your Google Cloud project. If you already have credentials, skip to Installation & Setup.

Step 1: Create a Google Cloud project

1. Go to Google Cloud Console
2. Click Select a project → New Project
3. Give it a name (e.g., "Smart Calendar") and click Create
4. Make sure the project is selected in the top bar

Step 2: Enable the Google Calendar API

1. Go to Google Calendar API page
2. Make sure your project is selected
3. Click Enable

Step 3: Create auth credentials

Choose one of the following based on your environment:

Option A: OAuth2 credentials (recommended for personal use)

Best for: laptops, desktops, personal servers.

1. Go to OAuth consent screen
2. Select External as user type → click Create
3. Fill in App name, support email, developer email → click Save and Continue through all screens
4. Under Test users, click Add users → add your Google email → Save
5. Go to Credentials page
6. Click Create Credentials → OAuth client ID
7. Application type: Desktop app → Name: Smart Calendar → Create
8. Note your Client ID and Client Secret — you'll need these during setup

Option B: Service Account credentials (recommended for servers/droplets)

Best for: DigitalOcean droplets, production servers, CI/CD, headless environments.

1. Go to Service Accounts
2. Click Create Service Account → give it a name → Create and Continue → Done
3. Click on the service account → Keys → Add Key → Create new key → JSON → Create
4. Save the downloaded JSON file — you'll need this during setup
5. Share your Google Calendar with the service account email (found in the JSON as client_email):
   • Go to Google Calendar → Settings → your calendar → Share with specific people
   • Add the service account email with Make changes to events permission

Installation & Setup

1. Install the plugin

openclaw plugins install openclaw-smart-calendar

2. Run the setup wizard

npx openclaw-smart-calendar setup

The wizard will prompt you to choose an auth method:

• Option 1 — Service Account: Provide the path to your service account JSON key file (from Option B above)
• Option 2 — OAuth2: Enter your Client ID and Client Secret (from Option A above)

For OAuth2 on a machine with a browser: A browser window opens automatically for Google authorization. Sign in, grant access, and the setup completes.

For OAuth2 on a headless server: The wizard shows a URL. Visit it in any browser (on any machine), authorize, then copy the code parameter from the redirect URL and paste it back in the terminal. (The redirect goes to localhost which will show an error page — that's expected. The auth code is in the URL bar: http://localhost:3000/oauth2callback?code=PASTE_THIS_PART&scope=...)

3. Restart OpenClaw

systemctl restart openclaw

Credentials are stored securely in ~/.config/smart-calendar/ with 600 permissions.

Configuration

All settings have sensible defaults. Configure via OpenClaw UI or your OpenClaw config:

| Setting | Default | Description | |---------|---------|-------------| | user_timezone | Auto-detected | Your IANA timezone (e.g., Europe/Amsterdam, America/New_York). Auto-detected from system if not set. | | google_maps_api_key | — | Google Maps API key for automatic travel time estimation | | home_address | — | Your home address for travel time calculations | | default_travel_buffer_minutes | 30 | Travel buffer in minutes for in-person meetings (when Maps API is unavailable) | | audit_log_path | ~/.openclaw/smart-cal-audit.log | Path to the audit log file |

Note on timezone: The plugin auto-detects your system timezone. You only need to set user_timezone if you want to override it (e.g., you're on a server in a different timezone than your calendar).

Note on travel buffers: Buffers are only added for in-person meetings (events with a physical address). Online meetings (Google Meet, Zoom, Teams, etc.) never get travel buffers.

Usage

Just talk to your OpenClaw agent (Telegram, CLI, etc.):

Querying your calendar

| Say this | What happens | |----------|-------------| | "What's on my calendar today?" | Lists today's events | | "What's on my calendar tomorrow?" | Lists tomorrow's events | | "Show my afternoon meetings" | Lists events for a specific period | | "What does my week look like?" | Weekly summary with breakdown |

Adding events

| Say this | What happens | |----------|-------------| | "Add dentist at 123 Main St tomorrow at 2pm" | Creates event + auto travel buffer | | "Add lunch with Raj tomorrow at 1pm at Indiranagar" | Creates event with location-aware buffer | | "Add standup at 9am" | Creates a simple event (no buffer) | | "Add team sync on Google Meet at 3pm" | Creates online event (no buffer) |

Managing events

| Say this | What happens | |----------|-------------| | "Clear tomorrow morning" | Deletes all morning events | | "Block 10am-12pm Friday for deep work" | Creates a time block | | "Move my 2pm meeting to 4pm" | Reschedules the event |

Smart features

| Say this | What happens | |----------|-------------| | "Morning briefing" or "What's my day look like?" | Full daily briefing with schedule, free time, and warnings | | "Brief me on tomorrow" | Daily briefing for a specific day | | "Find recurring patterns" or "What meetings repeat?" | Detects patterns and suggests recurring events |

Tools Reference

| Tool | Description | |------|-------------| | smart_cal_add | Add event with travel buffer (in-person only) and conflict detection. Suggests alternative slots on conflicts. | | smart_cal_query | List events for a date or time range | | smart_cal_clear | Delete all events in a time range | | smart_cal_block | Block a time slot on the calendar | | smart_cal_reschedule | Move an event to a new time | | smart_cal_status | Weekly summary with in-person vs online breakdown | | smart_cal_briefing | Daily briefing with schedule, free time, leave-by times, and warnings | | smart_cal_patterns | Detect recurring meeting patterns and suggest making them formal |

Smart Features

AI-Powered Scheduling

When you add an event that conflicts with existing ones, the plugin analyzes your past 4 weeks of calendar data and suggests optimal alternative time slots based on:

• Historically quiet hours (when you're usually free)
• Meeting type (in-person meetings prefer low-traffic hours)
• Buffer gaps between meetings
• Time-of-day preferences

Travel Buffer Intelligence

• In-person meetings (physical address detected) → automatic travel buffer added before the event
• Online meetings (Google Meet, Zoom, Teams, etc.) → no travel buffer, detected via conferenceData, URLs, and text patterns
• With a Google Maps API key configured, travel time is calculated based on actual driving distance

Meeting Type Detection

The plugin automatically detects whether a meeting is online or in-person by checking:

1. Google Calendar's conferenceData (most reliable — detects Google Meet links)
2. URL patterns in location/description (Zoom, Teams, WebEx, etc.)
3. Text patterns ("Google Meet", "video call", "virtual meeting", etc.)
4. Physical addresses in the location field

Pattern Detection

Scans your calendar history (default: 8 weeks) to find meetings that repeat without being formally set as recurring:

• Daily, weekly, biweekly, and monthly patterns
• Confidence scoring (only suggests patterns with 3+ occurrences)
• Predicted next occurrence

Daily Briefing

A comprehensive morning summary including:

• Total events with in-person vs online breakdown
• First meeting time with leave-by time for in-person events
• Complete schedule listing
• Free time blocks during working hours (8am-8pm)
• Warnings for: back-to-back meetings, short gaps between in-person meetings at different locations, missing locations, and overloaded days

Conflict Detection

Automatically checks for scheduling overlaps when creating events and warns you with details about the conflicting meetings.

Audit Log

Every calendar change (create, delete, reschedule) is logged to ~/.openclaw/smart-cal-audit.log for your records.

Troubleshooting

"Not authenticated" error

• Run the setup wizard: npx openclaw-smart-calendar setup
• Check that credentials exist: ls ~/.config/smart-calendar/

"Access blocked" or "Permission denied"

• Make sure you added yourself as a test user in the OAuth consent screen
• Make sure the Calendar API is enabled in your project
• Try running setup again: npx openclaw-smart-calendar setup

Auth not working on server (headless)

• Use Service Account auth (option 1 in setup wizard) — most reliable for servers
• For OAuth on headless: the setup wizard shows a URL to visit on any machine with a browser. After authorizing, copy the code from the redirect URL and paste it back

Events showing wrong timezone

• Check your user_timezone setting — it auto-detects from your system
• To override: set user_timezone to your IANA timezone (e.g., Europe/Amsterdam)
• Server timezone may differ from your actual timezone — set it explicitly in that case

Travel buffer added to online meetings

• This should not happen in v2.0+. The plugin detects Google Meet, Zoom, Teams, and other online meeting platforms
• If it still happens, check that the event has a meeting link in its location or description

Plugin not loading in OpenClaw

• Restart OpenClaw: systemctl restart openclaw
• Check logs: journalctl -u openclaw -f
• Reinstall: openclaw plugins install openclaw-smart-calendar

Development

git clone https://github.com/bnarasimha21/openclaw-smart-calendar
cd openclaw-smart-calendar
npm install
npm run build

# Install locally for testing
openclaw plugins install --link .

Architecture

The plugin uses the Google Calendar API directly via the googleapis npm package. No external CLI tools or shell commands are required.

• src/auth.ts — OAuth2 and service account credential management
• src/gog.ts — Google Calendar API wrapper (list, create, delete, update events)
• src/tools/ — 8 calendar operation tools registered with OpenClaw
• src/intelligence/ — Meeting type detection, travel time, conflict detection, pattern detection, schedule analysis
• src/utils/ — Timezone-aware date utilities, audit logging

Credentials are stored in ~/.config/smart-calendar/:

• oauth-client.json — OAuth client ID and secret
• tokens.json — OAuth access and refresh tokens (auto-refreshed)
• service-account.json — Service account key (alternative auth method)

Roadmap

See ROADMAP.md for the full list of planned features across 4 phases.

License

MIT