Openclaw Email Orientation

Explain how email and Google Calendar work for OpenClaw agents, including the distinction between agent email and owner email, how gog and the Google Workspa...

Security Scan

This is an instruction-only orientation guide about OpenClaw agent email and Google Calendar usage; its recommendations, file/path references, and required actions are coherent with the described purpose and it does not request extraneous credentials or installs.

Purpose & Capability

The skill's name and description match the SKILL.md content: it's an orientation/troubleshooting guide for agent vs owner email and using gog to access Gmail/Calendar. It does not ask for unrelated credentials, binaries, or installs.

Instruction Scope

Instructions are limited to explanation and CLI examples for gog, account distinction, OAuth flows, calendar sharing steps, and troubleshooting checks. It references sensitive local paths (e.g., ~/.openclaw/.gog/credentials.json) but explicitly instructs not to print their contents — this is appropriate for an orientation guide.

Install Mechanism

No install spec or code is included (instruction-only). No downloads, extracted artifacts, or package installs are requested.

Credentials

The skill requires no declared environment variables or credentials; it does reference using GOG_ACCOUNT when running gog commands and points to local credential files. The references are proportional to the topic, but users should understand those files contain sensitive OAuth credentials and should not be shared.

Persistence & Privilege

The skill is not always-enabled and does not request elevated or persistent system privileges. It does not modify other skills or system-wide settings.

Assessment

This skill is a readable how-to for setting up agent access to Gmail and Calendar and appears coherent. Before installing or using it, ensure you: (1) understand the distinction between the human "owner" account and any agent account and only grant the agent the minimum calendar permissions needed; (2) keep the referenced files (e.g., ~/.openclaw/.gog/credentials.json and auth-profiles.json) private — do not paste their contents into chat; and (3) only run gog commands you trust on machines you control. There are no hidden installs or unexpected network endpoints in this skill, but the instructions do involve OAuth credentials and consent flows — handle those secrets the same way you would for any Google API client.

OpenClaw Email & Calendar Orientation

Minimum Model

Any model. This is an explanation and troubleshooting guide — no complex reasoning needed.

---

The Core Concept (Read This First)

There are two separate accounts:

	Account
Owner	The human's Google account (e.g. [e-mail])
Agent	The PA's own Google account (e.g. [e-mail])

These are separate. Having an agent email does NOT automatically give access to the owner's email or calendar.

To access the owner's email/calendar:

1. Owner must share access with the agent email (explicit step).
2. Agent must authenticate using gog (explicit step).

If someone is confused → start with this distinction. It resolves most questions.

---

Key Paths and Files

File	Purpose
~/.openclaw/.gog/credentials.json	gog OAuth client credentials
~/.openclaw/agents/main/agent/auth-profiles.json	OpenClaw auth profiles
~/.openclaw/workspace/skills/gog/SKILL.md	gog usage reference

Security rule: Never show the contents of these files in chat. Mentioning the path is fine; printing the content is not.

---

Using gog

# One-time setup: load OAuth credentials
gog auth credentials /path/to/client_secret.json

# Add an account (opens browser for OAuth flow)
gog auth add [e-mail] --services gmail,calendar,drive,contacts,sheets,docs

# Verify the account was added
gog auth list

# Use the account in commands (always include GOG_ACCOUNT=...)
GOG_ACCOUNT=[e-mail] gog gmail search 'is:unread' --max 10

Common Commands

# Search email
GOG_ACCOUNT=[e-mail] gog gmail search 'newer_than:7d' --max 10

# Send email
GOG_ACCOUNT=[e-mail] gog gmail send \
  --to "[e-mail]" \
  --subject "Hello" \
  --body "Message text"

# List calendar events in a time window
GOG_ACCOUNT=[e-mail] gog calendar events primary \
  --from "2026-04-01T09:00:00Z" \
  --to "2026-04-01T18:00:00Z"

# Create a calendar event
GOG_ACCOUNT=[e-mail] gog calendar create primary \
  --summary "Meeting" \
  --start "2026-04-02T10:00:00+00:00" \
  --end "2026-04-02T11:00:00+00:00"

---

Calendar Write Access — Step by Step

The most common issue: the agent can read the calendar but not create events.

Step 1 — Owner does this:

1. Open calendar.google.com.
2. Find the primary calendar → three-dot menu → Settings and sharing.
3. Click "+ Add people" → enter the agent email.
4. Set permission to "Make changes to events" (not "See all event details").
5. Click Send.

Step 2 — Agent does this:

# Authenticate with calendar scope
gog auth add [e-mail] --services calendar

# Test write access by creating a test event
GOG_ACCOUNT=[e-mail] gog calendar create primary \
  --summary "Test Event" \
  --start "2026-04-02T10:00:00Z" \
  --end "2026-04-02T11:00:00Z"

If the test event appears in the owner's calendar → success.

---

Troubleshooting

Work through these checks in order:

1. Clarify accounts: Is the question about agent email or owner email?
2. Check gog is installed: Run which gog — if not found, check PATH.
3. Check account was added: Run gog auth list — does owner's account appear?
4. Check write scope: OAuth must include calendar write scope, not just read.
5. Check keyring: If gog asks for a password, local keyring may need to be configured.
6. Check GOG_ACCOUNT: All commands must include GOG_ACCOUNT=[e-mail].
7. Calendar write failures: Was permission set to "Make changes to events" (not "See details")?

If "Insufficient permissions" error: → Owner shared calendar with read-only access. Redo Step 1 with the correct permission level.

If "Token expired" error:

# Remove the expired account
gog auth remove [e-mail]

# Re-add it (will open browser for re-auth)
gog auth add [e-mail] --services gmail,calendar,drive,contacts

---

Response Style

• Lead with the owner vs. agent distinction — this resolves most confusion.
• Give commands first, explanation second.
• When asked "where is X stored?" → give the path, do not print the file contents.
• When asked for step-by-step → follow the Calendar Write Access section above.

---

Cost Tips

• Very cheap: This skill is explanation only — minimal LLM tokens needed.
• Small model OK: Any model can explain these concepts and provide commands.
• Avoid: Do not re-explain the full orientation every time. Ask what specifically is confusing, then address only that.