OfficeClaw: Microsoft Graph API Integration

Connect your OpenClaw agent to personal Microsoft accounts (Outlook.com, Hotmail, Live) to manage email, calendar, and tasks through the Microsoft Graph API.

Installation

Install from PyPI:

pip install officeclaw

Or with uv:

uv pip install officeclaw

Verify installation:

officeclaw --version

Setup (One-Time)

Quick start: OfficeClaw ships with a default app registration — just run

officeclaw auth login

and go. No Azure setup needed.

Advanced: Want full control? Create your own Azure App Registration (free, ~5 minutes) and set

OFFICECLAW_CLIENT_ID

in your

.env

. See Microsoft's guide or follow the steps below.

1. Create an Azure App Registration

1. Go to entra.microsoft.com → App registrations → New registration
2. Name:

   officeclaw

   (or anything you like)
3. Supported account types: Personal Microsoft accounts only
4. Redirect URI: leave blank (not needed for device code flow)
5. Click Register
6. Copy the Application (client) ID — this is your

   OFFICECLAW_CLIENT_ID

7. Go to Authentication → Advanced settings → Allow public client flows → Yes → Save
8. Go to API permissions → Add permission → Microsoft Graph → Delegated permissions. Choose based on your needs:

Read-only (safest):

• Mail.Read

  ,

  Calendars.Read

  ,

  Tasks.ReadWrite

  *

Full access (all features including send/delete):

• Mail.Read

  ,

  Mail.ReadWrite

  ,

  Mail.Send

• Calendars.Read

  ,

  Calendars.ReadWrite

• Tasks.ReadWrite

*Tasks.ReadWrite is the minimum available scope for Microsoft To Do — there is no read-only option.

Least privilege: Only grant the permissions you actually need. If you only want to read emails and calendar, skip

Mail.ReadWrite

,

Mail.Send

, and

Calendars.ReadWrite

. OfficeClaw will gracefully error on commands that require missing permissions.

2. Configure Environment

Create a

.env

OFFICECLAW_CLIENT_ID=your-client-id-here

# Capability gates (disabled by default for safety)
# OFFICECLAW_ENABLE_SEND=true    # Allow sending/replying/forwarding emails
# OFFICECLAW_ENABLE_DELETE=true   # Allow deleting emails, events, and tasks

# Recipient allowlist — STRONGLY RECOMMENDED when sending is enabled
# OFFICECLAW_ALLOWED_RECIPIENTS=user1@example.com,user2@example.com

No client secret needed for device code flow. Write operations (send, delete) are disabled by default — enable only what you need.

⚠️ Recipient Allowlist (v1.0.4+): If you enable sending, configure

OFFICECLAW_ALLOWED_RECIPIENTS

to restrict which addresses can receive email. This is especially critical for AI agent workflows — the allowlist provides a hard, code-level boundary that prevents sending to unauthorized addresses regardless of what the agent is instructed to do. Blocked attempts are logged for auditing.

3. Authenticate

officeclaw auth login

This displays a URL and code. Open the URL in a browser, enter the code, and sign in with your Microsoft account. Tokens are stored securely in

~/.officeclaw/token_cache.json

When to Use This Skill

Activate this skill when the user needs to:

Email Operations

• Read emails: "Show me my latest emails", "Find emails from john@example.com"
• Send emails: "Send an email to...", "Reply to the last email from..."
• Manage inbox: "Mark emails as read", "Archive old emails", "Delete emails"

Calendar Operations

• View events: "What's on my calendar today?", "Show meetings this week"
• Create events: "Schedule a meeting with...", "Add dentist appointment on Friday"
• Update events: "Move the 2pm meeting to 3pm", "Cancel tomorrow's standup"

Task Management

• List tasks: "What's on my to-do list?", "Show incomplete tasks"
• Create tasks: "Add 'buy groceries' to my tasks", "Create a task to review report"
• Complete tasks: "Mark 'finish proposal' as done", "Complete all shopping tasks"

Available Commands

Authentication

officeclaw auth login       # Authenticate via device code flow
officeclaw auth status      # Check authentication status
officeclaw auth logout      # Clear stored tokens

Mail Commands

officeclaw mail list --limit 10                # List recent messages
officeclaw mail list --unread                   # List unread messages only
officeclaw mail get <message-id>               # Get specific message
officeclaw mail send --to user@example.com --subject "Hello" --body "Message text"
officeclaw mail send --to user@example.com --subject "Report" --body "Attached" --attachment report.pdf
officeclaw mail search --query "from:boss@example.com"
officeclaw mail archive <message-id>           # Archive a message
officeclaw mail mark-read <message-id>         # Mark as read
officeclaw --json mail list                    # JSON output for parsing

Calendar Commands

officeclaw calendar list --start 2026-02-01 --end 2026-02-28
officeclaw calendar create \
  --subject "Team Meeting" \
  --start "2026-02-15T10:00:00" \
  --end "2026-02-15T11:00:00" \
  --location "Conference Room"
officeclaw calendar get <event-id>
officeclaw calendar update <event-id> --subject "Updated Meeting"
officeclaw calendar delete <event-id>
officeclaw --json calendar list --start 2026-02-01 --end 2026-02-28

Task Commands

officeclaw tasks list-lists                              # List task lists
officeclaw tasks list --list-id <list-id>                # List tasks
officeclaw tasks list --list-id <list-id> --status active  # Active tasks only
officeclaw tasks create --list-id <list-id> --title "Complete report" --due-date "2026-02-20"
officeclaw tasks complete --list-id <list-id> --task-id <task-id>
officeclaw tasks reopen --list-id <list-id> --task-id <task-id>

Output Format

Use

--json

officeclaw --json mail list

Returns:

{
  "status": "success",
  "data": [
    {
      "id": "AAMkADEzN...",
      "subject": "Meeting Notes",
      "from": {"emailAddress": {"address": "sender@example.com"}},
      "receivedDateTime": "2026-02-12T10:30:00Z",
      "isRead": false
    }
  ]
}

Error Handling

Common errors and solutions:

AuthenticationError

officeclaw auth login

AccessDenied

ResourceNotFound

RateLimitError

Guidelines for Agents

When using this skill:

1. Confirm destructive actions: Ask before deleting or sending
2. Summarize results: Don't show raw JSON, provide summaries
3. Handle errors gracefully: Guide user through re-authentication
4. Respect privacy: Don't log email content
5. Use JSON mode: For programmatic parsing, use

   --json

   flag
6. Batch operations: Process multiple items efficiently

Security & Privacy

• Write operations disabled by default: Send, reply, forward, and delete are all blocked unless explicitly enabled via

  OFFICECLAW_ENABLE_SEND

  and

  OFFICECLAW_ENABLE_DELETE

  environment variables. This prevents accidental or unauthorised write actions.
• Recipient allowlist (v1.0.4+): When

  OFFICECLAW_ALLOWED_RECIPIENTS

  is set, outbound email is restricted to listed addresses only. Blocked attempts are logged to

  email-blocked.log

  and an

  email-alert.json

  alert file is written for monitoring. If not set, a runtime warning is displayed on each send. Strongly recommended for any AI agent deployment.
• No client secret required: Uses device code flow (public client) by default
• Least-privilege permissions: You choose which Graph API scopes to grant — read-only is sufficient for most use cases. See the setup guide above.
• Tokens stored securely:

  ~/.officeclaw/token_cache.json

  with 600 file permissions
• No data storage: OfficeClaw passes data through, never stores email/calendar content
• No telemetry: No usage data collected
• Your own Azure app: Each user creates their own Azure app registration with their own client ID — no shared credentials

Troubleshooting

If the skill isn't working:

1. Check authentication: Run

   officeclaw auth status

2. Re-authenticate: Run

   officeclaw auth login

3. Verify network: Ensure

   graph.microsoft.com

   is reachable
4. Check environment: Verify

   OFFICECLAW_CLIENT_ID

   is set in

   .env

References

• OfficeClaw on GitHub
• OfficeClaw on PyPI
• Microsoft Graph API
• OpenClaw