Microsoft 365 Graph for OpenClaw Skill

1. Quick prerequisites

1. 1. Python 3 with requests installed.
2. Default auth values:

1. 3. Tokens are stored in state/graph_auth.json (ignored by git).
2. Push-mode runtime values (service-level):

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

2. Assisted OAuth flow (Device Code)

1. 1. Run:

   python scripts/graph_auth.py device-login \
     --client-id 952d1b34-682e-48ce-9c54-bac5a96cbd42 \
     --tenant-id consumers
   

1. 2. 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:

1. 5. Other scripts call utils.get_access_token(), which refreshes tokens automatically when needed.
2. Scope override is disabled in graph_auth.py; the skill always uses DEFAULT_SCOPES.

Detailed reference: references/auth.md.

3. Email operations

• - List/filter: INLINECODE22
• Fetch specific message: INLINECODE23
• Move message: add --move-to <folderId> to the command above.
• Send email (saveToSentItems enabled by default):

  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:

  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: INLINECODE33
• Upload: INLINECODE34
• Download: INLINECODE35
• 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: INLINECODE41
• Create: INLINECODE42
• Update/Delete: ... update <contactId> ... / INLINECODE44
• 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):

  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):

  python scripts/mail_subscriptions.py create \
    --notification-url "https://graph-hook.example.com/graph/mail" \
    --client-state "$GRAPH_WEBHOOK_CLIENT_STATE" \
    --minutes 4200
  

• - Async worker (dedupe + default wake signal to OpenClaw /hooks/wake):

  python scripts/mail_webhook_worker.py loop \
    --session-key "$OPENCLAW_SESSION_KEY" \
    --hook-url "$OPENCLAW_HOOK_URL" \
    --hook-token "$OPENCLAW_HOOK_TOKEN"
  

• - Worker queue files:

• - Automated EC2 bootstrap (Caddy + systemd + renew timer):

  sudo bash scripts/setup_mail_webhook_ec2.sh \
    --domain graphhook.example.com \
    --hook-url http://127.0.0.1:18789/hooks/wake \
    --hook-token "<OPENCLAW_HOOK_TOKEN>" \
    --session-key "hook:graph-mail" \
    --client-state "<GRAPH_WEBHOOK_CLIENT_STATE>" \
    --repo-root "$(pwd)"
  

• - One-command setup (steps 2..6):

  sudo bash scripts/run_mail_webhook_e2e_setup.sh \
    --domain graphhook.example.com \
    --hook-token "<OPENCLAW_HOOK_TOKEN>" \
    --hook-url "http://127.0.0.1:18789/hooks/wake" \
    --session-key "hook:graph-mail" \
    --test-email "tar.alitar@outlook.com"
  

• - Include OpenClaw hook config in automation:

  sudo bash scripts/run_mail_webhook_e2e_setup.sh \
    --domain graphhook.example.com \
    --hook-token "<OPENCLAW_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:

  sudo bash scripts/run_mail_webhook_smoke_tests.sh \
    --domain graphhook.example.com \
    --create-subscription \
    --test-email tar.alitar@outlook.com
  

• - 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:

• - INLINECODE70
• INLINECODE71

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

• - Write INLINECODE73
• Write INLINECODE74
• Write /etc/systemd/system/*.service and INLINECODE76
• Enable/restart services via INLINECODE77
• Optionally patch OpenClaw config and restart OpenClaw services

Recommended safety sequence:

1. 1. Run with INLINECODE78
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

Symptom	Action
401/invalid_grant	Run graph_auth.py refresh; if it fails, run clear and repeat device login.
403/AccessDenied

Missing scope or licensing/policy issue. Re-run device login with required scope(s). |

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