Microsoft 365 Graph Openclaw

Microsoft 365 Graph for OpenClaw with webhook-based wake signals. Reduce recurring LLM cost from inbox polling while managing Outlook mail, calendar, OneDriv...

Security Scan

The skill's code and instructions largely match its stated purpose (a push-mode Microsoft Graph adapter + worker that wakes OpenClaw), but there are noteworthy mismatches and high‑privilege operations (systemd/Caddy install, writing /etc, secret handling) that you should review before installing.

Purpose & Capability

The repository contains a webhook adapter, subscription lifecycle tooling, a worker, and CLI helpers for mail/calendar/drive/contacts — which matches the skill description. Required binaries (python3, bash, curl) make sense. However, the SKILL.md and scripts expect several runtime secrets and service-level env values (OPENCLAW_HOOK_URL, OPENCLAW_HOOK_TOKEN, GRAPH_WEBHOOK_CLIENT_STATE, optional OPENCLAW_SESSION_KEY) that are not declared in the registry metadata's requires.env/primaryEnv. That metadata omission is an inconsistency you should be aware of.

Instruction Scope

Runtime instructions and scripts are focused on Graph OAuth, subscription management, enqueue/dedupe, and POSTing wake signals to OpenClaw — all within stated purpose. They reference and persist tokens in state/graph_auth.json and load runtime values from /etc/default/graph-mail-webhook; they also include an advanced mode to post richer payloads to /hooks/agent. Nothing in SKILL.md instructs reading unrelated host data, but the worker/adapter will call local OpenClaw endpoints and external Microsoft Graph APIs and will persist token-bearing files locally.

Install Mechanism

The registry shows no formal install spec (instruction-only), but the repo includes privileged setup scripts (run_mail_webhook_e2e_setup.sh, setup_mail_webhook_ec2.sh, diagnose and smoke-test scripts) that install Caddy, create systemd units, write /etc/default/graph-mail-webhook, and can patch OpenClaw config. The install is script-driven (sudo) — there is no packaged installer or verified release host in the metadata, so you should review the scripts before running them with root privileges.

Credentials

The skill operates with/needs sensitive secrets: OAuth tokens (state/graph_auth.json), OPENCLAW_HOOK_TOKEN, GRAPH_WEBHOOK_CLIENT_STATE, and an OpenClaw hook URL. These are justified by the task, but the registry metadata failing to declare required env vars / primary credential is a mismatch. Additionally, the project ships with a default public client_id (Alitar app) for quick testing — using that defaults to a third‑party app issuance of tokens unless you register your own App Registration, which has privacy/security implications in production.

Persistence & Privilege

The skill does not set always:true (good), but its setup scripts intentionally create persistent system services and write to system locations (/etc, systemd units) and may patch OpenClaw config and restart the service. That is high privilege and modifies runtime/system configuration; verify the scripts and prefer --dry-run or manual inspection before allowing automated changes. The ability to auto-configure OpenClaw (other component) increases blast radius if misused.

What to consider before installing

This repo appears to implement the described push-mode Graph integration, but you should not run the provided privileged setup scripts without review. Before installing: - Audit the setup scripts (run_mail_webhook_e2e_setup.sh, setup_mail_webhook_ec2.sh, run_mail_webhook_smoke_tests.sh, diagnose scripts) to see exactly what they install and what files they write under /etc and systemd. Use --dry-run where provided. - Do not rely on the default public client_id (Alitar) for production — register your own Entra app and use its client_id so tokens are under your control. - Expect to provide and securely store OPENCLAW_HOOK_TOKEN, OPENCLAW_HOOK_URL, and GRAPH_WEBHOOK_CLIENT_STATE; the registry metadata currently does not declare these env vars (metadata/documentation mismatch). Ensure these values are managed by a secrets manager and rotated if exposed. - Inspect state/graph_auth.json handling: it contains access/refresh tokens. Ensure the state directory permissions are locked down and is gitignored (the docs state it is ignored, but verify before committing). - If you will allow the scripts to patch OpenClaw config, back up ~/.openclaw/openclaw.json first and review any automated changes; prefer manual edits in sensitive/production environments. - If you cannot audit scripts or do not want services installed on the host, consider running the adapter/worker in a contained environment (container or separate VM) and avoid running the setup scripts with sudo. Given the privileged persistence and the metadata mismatch around required secrets, treat this skill as suspicious until you've completed the checks above and replaced the test client_id with one you control.

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:

   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.

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

  python scripts/mail_send.py \
    --to [e-mail] \
    --subject "Update" \
    --body-file replies/thais.html --html \
    --cc [e-mail] \
    --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: 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 [e-mail]
• Update/Delete: ... update <contactId> ... / ... delete <contactId>
• 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
  

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

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

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

  • Use --dry-run to preview all privileged writes and service actions before applying changes.
• 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 "[e-mail]"
  

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

  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 "[e-mail]"
  

• Minimal-input smoke tests:

  sudo bash scripts/run_mail_webhook_smoke_tests.sh \
    --domain graphhook.example.com \
    --create-subscription \
    --test-email [e-mail]
  

  • 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

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).
429/Throttled	Scripts do basic retry; wait a few seconds and retry.
requests.exceptions.SSLError	Verify local system date/time and TLS trust chain.

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