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. Push-mode runtime values (service-level):
• These values are loaded by systemd services from /etc/default/graph-mail-webhook (usually written by setup scripts).
• OPENCLAW_HOOK_URL (required)
• OPENCLAW_HOOK_TOKEN (required)
• GRAPH_WEBHOOK_CLIENT_STATE (required; auto-generated in minimal e2e setup when omitted)
• OPENCLAW_SESSION_KEY (optional; default hook:graph-mail)

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

```

1. The script prints a URL and device code.
2. Open https://microsoft.com/devicelogin, enter the code, and approve with the target account.
3. Check and manage auth state:
• python scripts/graph_auth.py status
• python scripts/graph_auth.py refresh
• python scripts/graph_auth.py clear
4. Other scripts call utils.get_access_token(), which refreshes tokens automatically when needed.
5. Scope override is disabled in graph_auth.py; the skill always uses DEFAULT_SCOPES.

Detailed reference: references/auth.md.

3. Email operations

• List/filter: python scripts/mail_fetch.py --folder Inbox --top 20 --unread
• Fetch specific message: ... --id --include-body --mark-read
• Move message: add --move-to to the command above.
• Send email (saveToSentItems enabled by default):

```bash

python scripts/mail_send.py \

--to user@example.com \

--subject "Update" \

--body-file replies/thais.html --html \

--cc teammate@example.com \

--attachment docs/proposal.pdf

```

• Use --no-save-copy only when you intentionally do not want Sent Items storage.

More examples and filters: references/mail.md.

4. Calendar operations

• List custom date window:

```bash

python scripts/calendar_sync.py list \

--start 2026-03-03T00:00Z --end 2026-03-05T23:59Z --top 50

```

• Create Teams or in-person event: use create; add --online for Teams link.
• For personal Microsoft accounts (tenant=consumers), Teams meeting provisioning via Graph might not return a join URL; create the Teams meeting in Outlook/Teams first and add the resulting link to the event body when needed.
• Update/cancel events by event_id returned in JSON output.

Full examples: references/calendar.md.

5. OneDrive / Files

• List folders/files: python scripts/drive_ops.py list --path /
• Upload: ... upload --local notes/briefing.docx --remote /Clients/briefing.docx
• Download: ... download --remote /Clients/briefing.docx --local /tmp/briefing.docx
• Move / share links: use move and share subcommands.
• The script resolves localized/special-folder aliases (for example Documents and Documentos).

More details: references/drive.md.

6. Contacts

• List/search: python scripts/contacts_ops.py list --top 20
• Create: ... create --given-name Jane --surname Doe --email jane.doe@example.com
• Update/Delete: ... update ... / ... delete
• Contacts are part of the default scope set and supported as a first-class workflow.

More details: references/contacts.md.

7. Mail push mode (Webhook Adapter)

• Adapter server (Graph handshake + clientState validation + enqueue):

```bash

python scripts/mail_webhook_adapter.py serve \

--host 0.0.0.0 --port 8789 --path /graph/mail \

--client-state "$GRAPH_WEBHOOK_CLIENT_STATE"

```

• Subscription lifecycle (create/status/renew/delete/list):

```bash

python scripts/mail_subscriptions.py create \

--notification-url "https://graph-hook.example.com/graph/mail" \

--client-state "$GRAPH_WEBHOOK_CLIENT_STATE" \

--minutes 4200

```

• Default resource is me/messages (recommended for better delivery coverage). Override with --resource only for advanced/scoped scenarios.
• Async worker (dedupe + default wake signal to OpenClaw /hooks/wake):

```bash

python scripts/mail_webhook_worker.py loop \

--session-key "$OPENCLAW_SESSION_KEY" \

--hook-url "$OPENCLAW_HOOK_URL" \

--hook-token "$OPENCLAW_HOOK_TOKEN"

```

• Default mode is wake (/hooks/wake, mode=now). Use --hook-action agent only when you explicitly need per-message rich payload delivery.
• Worker queue files:
• state/mail_webhook_queue.jsonl
• state/mail_webhook_dedupe.json
• Automated EC2 bootstrap (Caddy + systemd + renew timer):

```bash

sudo bash scripts/setup_mail_webhook_ec2.sh \

--domain graphhook.example.com \

--hook-url http://127.0.0.1:18789/hooks/wake \

--hook-token "" \

--session-key "hook:graph-mail" \

--client-state "" \

--repo-root "$(pwd)"

```

• Use --dry-run to preview all privileged writes and service actions before applying changes.
• One-command setup (steps 2..6):

```bash

sudo bash scripts/run_mail_webhook_e2e_setup.sh \

--domain graphhook.example.com \

--hook-token "" \

--hook-url "http://127.0.0.1:18789/hooks/wake" \

--session-key "hook:graph-mail" \

--test-email "tar.alitar@outlook.com"

```

• Use --dry-run for a no-mutation execution plan (no /etc writes, no systemctl, no subscription create, no email send).
• Output ends with READY_FOR_PUSH: YES when setup is fully validated.
• Include OpenClaw hook config in automation:

```bash

sudo bash scripts/run_mail_webhook_e2e_setup.sh \

--domain graphhook.example.com \

--hook-token "" \

--configure-openclaw-hooks \

--openclaw-config "/home/ubuntu/.openclaw/openclaw.json" \

--openclaw-service-name "auto" \

--openclaw-hooks-path "/hooks" \

--openclaw-allow-request-session-key true \

--test-email "tar.alitar@outlook.com"

```

• Minimal-input smoke tests:

```bash

sudo bash scripts/run_mail_webhook_smoke_tests.sh \

--domain graphhook.example.com \

--create-subscription \

--test-email tar.alitar@outlook.com

```

• Output ends with READINESS VERDICT: READY_FOR_PUSH only after all critical checks pass.
• Setup and runbook: references/mail_webhook_adapter.md.

8. Privileged operations boundary

The core Graph scripts are unprivileged (graph_auth.py, mail_fetch.py, mail_send.py, calendar_sync.py, drive_ops.py, contacts_ops.py).

The setup scripts below are privileged and should be manually reviewed before execution:

• scripts/setup_mail_webhook_ec2.sh
• scripts/run_mail_webhook_e2e_setup.sh

When run without --dry-run, they can:

• Write /etc/default/graph-mail-webhook
• Write /etc/caddy/Caddyfile
• Write /etc/systemd/system/.service and .timer
• Enable/restart services via systemctl
• Optionally patch OpenClaw config and restart OpenClaw services

Recommended safety sequence:

1. Run with --dry-run
2. Review emitted actions and target files
3. Run on a non-production host first
4. Apply to production only after approval

9. Logging and conventions

• Each script appends one JSON line to state/graph_ops.log with timestamp, action, and key parameters.
• Tokens and logs must never be committed.
• Commands assume execution from the repository root. Adjust paths if running elsewhere.

10. Troubleshooting

This skill provides OAuth-driven workflows for email, calendar, files, contacts, and push-based mail automation via Microsoft Graph.