microsoft-365-graph-openclaw

# Microsoft 365 Graph for OpenClaw Skill

## 1. Quick prerequisites
1. Python 3 with `requests` installed.
2. Default auth values:
   - Client ID (personal-account default): `952d1b34-682e-48ce-9c54-bac5a96cbd42`
   - Tenant (personal-account default): `consumers`
   - Default scopes: `Mail.ReadWrite Mail.Send Calendars.ReadWrite Files.ReadWrite.All Contacts.ReadWrite offline_access`
   - For work/school accounts, use `--tenant-id organizations` (or tenant GUID) and a tenant-approved `--client-id`.
   - The public default client ID is for quick testing. For production, prefer your own App Registration.
3. Tokens are stored in `state/graph_auth.json` (ignored by git).
4. Required runtime envs for push mode:
   - `OPENCLAW_HOOK_URL`
   - `OPENCLAW_HOOK_TOKEN`
   - `GRAPH_WEBHOOK_CLIENT_STATE`
   - `OPENCLAW_SESSION_KEY`

Permission profiles (least privilege by use case) are documented in `docs/permission-profiles.md`.

## 2. Assisted OAuth flow (Device Code)
1. Run:
   ```bash
   python scripts/graph_auth.py device-login \
     --client-id 952d1b34-682e-48ce-9c54-bac5a96cbd42 \
     --tenant-id consumers
   ```
2. The script prints a **URL** and **device code**.
3. Open `https://microsoft.com/devicelogin`, enter the code, and approve with the target account.
4. Check and manage auth state:
   - `python scripts/graph_auth.py status`  
   - `python scripts/graph_auth.py refresh`  
   - `python scripts/graph_auth.py clear`
5. Other scripts call `utils.get_access_token()`, which refreshes tokens automatically when needed.
6. Scope override is disabled in `graph_auth.py`; the skill always uses `DEFAULT_SCOPES`.

Detailed reference: [`references/auth.md`](references/auth.md).

## 3. Email operations
- **List/filter**: `python scripts/mail_fetch.py --folder Inbox --top 20 --unread`
- **Fetch specific message**: `... --id <messageId> --include-body --mark-read`
- **Move message**: add `--move-to <folderId>` to the command above.
- **Send email** (`saveToSentItems` enabled by...

# Microsoft 365 Graph for OpenClaw

Microsoft 365 Graph for OpenClaw with webhook-based wake signals.

Reduce recurring LLM cost from inbox polling while managing Outlook mail, calendar, OneDrive, and contacts via Microsoft Graph.
This repository provides a webhook-driven Graph skill that wakes OpenClaw only when work actually happens in self-hosted deployments.

![License](https://img.shields.io/badge/license-MIT-green.svg)
![Release](https://img.shields.io/badge/release-v0.2.0-blue.svg)
![CI](https://img.shields.io/badge/ci-github_actions-informational.svg)

## Why this exists

Polling-based inbox checks are expensive in practice:
- A cron/heartbeat loop keeps waking agents even when nothing changed.
- Those recurring turns consume tokens and increase operating cost.
- They also increase noise in operational logs and incident triage.

Microsoft Graph change notifications flip the model:
- Graph pushes an event when a message changes.
- The skill validates and deduplicates events.
- OpenClaw receives a wake signal only when there is new work.

Core message: replace recurring inbox polling with event-driven notifications.

## Cost model

Assume one lightweight inbox-check wake-up uses about `2,000` input tokens and `400` output tokens.

Using GPT-5.3-Codex pricing (`$1.75 / 1M` input, `$14.00 / 1M` output), each wake-up costs about **$0.0091**. 

- **2-minute polling** = `720` wake-ups/day = about **$6.55/day** = about **$196.56/month**
- **Push mode with 5 real events/day** = `5` wake-ups/day = about **$0.05/day** = about **$1.37/month**

In this example, push reduces recurring wake-up spend by about **99%**.

These numbers are illustrative. Push does not remove the cost of processing real email work — it mainly removes the cost of waking the agent repeatedly just to check whether anything changed.

## What is included

Skill:
- `microsoft-365-graph-openclaw`

Capabilities:
- OAuth device-code auth with refresh handling
- Mail, calendar, drive, and contacts automat...