Connecting Google Workspace
James scrolled through the dashboard. Two agents, voice enabled, heartbeats running, MCP servers connected. Ten lessons of building. He opened WhatsApp and typed a message to his agent: "Summarize my unread emails."
The agent responded immediately. It apologized and explained that it did not have access to his email. It offered to write a sample email summary template instead.
James stared at the response. "It can list files on my machine. It can search the web. It can delegate to a second agent. But it cannot read my email."
Emma looked over. "Everything your agent has done so far used data it generated itself. Competitor research from training data. Goal files it created. Reports it wrote." She paused. "Your agent has never touched YOUR data."
"So how do I connect it?"
"One OAuth setup. Thirty minutes of GCP Console pain. Then your agent reads your inbox, checks your calendar, and searches your Drive." She stood up. "Use a test Google account, not your real one. When you see the email summary come through on WhatsApp, that is when you will understand why two hundred thousand people starred this project."
This lesson grants your AI Employee OAuth access to a real Google account, including email, calendar, and files. Use a dedicated test Google account, not your primary one. This removes security anxiety and lets you experiment freely. You can always switch to your real account later once you are comfortable with the access model and security controls.
You are doing exactly what James is doing: connecting your AI Employee to the systems where your actual work lives. Until now, every task operated on self-generated data. This lesson breaks that boundary.
What gog Connects
gog is a command-line tool that bridges OpenClaw and Google Workspace. One OAuth setup gives your AI Employee access to Google services through a unified CLI. gog supports Gmail, Calendar, Drive, Contacts, Sheets, Docs, Slides, Forms, Chat, Classroom, Tasks, People, Keep, and more. This lesson focuses on three:
| Service | What Your Agent Can Do |
|---|---|
| Gmail | Search messages, read threads, send mail, manage labels, handle drafts |
| Calendar | List events, create meetings, check availability, respond to invitations |
| Drive | Search files, upload and download documents, manage permissions |
Your agent accesses each through subcommands: gog gmail, gog calendar, gog drive, and so on. Run gog auth services to see the full list of available services and their scopes. Every command supports JSON output (--json) for scripting, which is how OpenClaw parses the results into natural language responses.
Setting Up gog
The OAuth credential setup below is a one-time process. If you get stuck on any step, ask your AI Employee (through your messaging channel or TUI): "Help me set up Google Cloud OAuth credentials for a desktop app called gog." It can walk you through each screen. You can also skip this lesson entirely and return when you need Google Workspace access.
The setup has three parts: install the CLI, register your Google OAuth credentials, and authorize your account.
Part 1: Install gog
If you chose gog from the skills picker during QuickStart in Lesson 2, it may already be installed. Run gog --version to check. If it works, skip to Part 2.
- macOS
- Windows
- Linux
brew install gogcli
npm install -g gogcli
Arch:
yay -S gogcli
Other distributions: Build from source:
git clone https://github.com/steipete/gogcli.git
cd gogcli && make
sudo cp ./bin/gog /usr/local/bin/
Verify the installation:
gog --version
Part 2: Create and Register OAuth Credentials
gog needs a Google Cloud OAuth client to authenticate. This is a one-time setup.
Step 1: Go to console.cloud.google.com and sign in with the Google account you want your agent to access.
Step 2: Create a project (or select an existing one). The project name does not matter; something like "AI Employee" works fine.
Step 3: Enable the APIs your agent will use. Navigate to APIs & Services > Library and enable:
- Gmail API
- Google Calendar API
- Google Drive API
These are the three you will use in this lesson. You can enable Contacts API, Sheets API, and Docs API later if needed.
Step 4: Configure the OAuth consent screen. Go to APIs & Services > OAuth consent screen:
- Choose External (unless you have a Google Workspace organization)
- Fill in the required fields (app name, support email)
- Add your email as a test user
Step 5: Create credentials. Go to APIs & Services > Credentials:
- Click Create Credentials > OAuth client ID
- Application type: Desktop app
- Name it anything ("gog CLI" works)
- Click Create, then Download JSON
This downloads a file named something like client_secret_123456.json. Save it somewhere you can find it.
Step 6: Register the credentials with gog:
gog auth credentials ~/Downloads/client_secret_*.json
Part 3: Authorize Your Account
gog auth add you@gmail.com
Replace you@gmail.com with your actual email address. This opens your browser for the standard Google OAuth flow. Review the permissions and click Allow.
By default, gog requests access to Gmail, Calendar, Drive, Contacts, Sheets, and Docs. If you want to limit scope to specific services:
gog auth add you@gmail.com --services gmail,calendar,drive
Set your default account so you do not need to specify it every time:
export GOG_ACCOUNT=you@gmail.com
Add that line to your shell profile (~/.zshrc or ~/.bashrc) to make it permanent.
Verify Everything Works
gog auth list
Quick test: list your Gmail labels:
gog gmail labels list
If you see your labels, the connection works. You can also confirm gog is working from your messaging channel by asking your AI Employee:
List my Gmail labels
If your employee returns a list of labels (INBOX, SENT, DRAFT, etc.), the full pipeline is working end-to-end: from your messaging channel through OpenClaw to gog to Google's API and back.
Real Employee Tasks
Open your chat with your AI Employee. These tasks use your actual data, not practice exercises.
Task 1: Email Summary (Gmail)
What to type:
Summarize my top 5 unread emails. For each, give me the sender,
subject, and a one-sentence summary of what they want.
What to observe: Your agent calls gog gmail search 'is:unread' --max 5, reads the thread content, and produces a structured summary. The data flowing through is your real inbox: names you recognize, subjects you have been ignoring, requests that actually need your attention.
This is the moment. Not a demo email. Not sample data. Your actual unread messages, summarized by your agent, delivered to your phone.
Task 2: Calendar Check (Calendar)
What to type:
What meetings do I have tomorrow? Include the time, title, and
who else is attending.
What to observe: The agent calls gog calendar list-events with tomorrow's date range and formats the results. Notice how the agent handles time zones: it uses whatever your calendar is configured for.
Task 3: File Search (Drive)
What to type:
Find the document I was working on most recently that has "budget"
or "proposal" in the name. Show me the title, last modified date,
and a link to open it.
What to observe: The agent searches Drive with query filters, finds matching files, and returns direct links you can tap to open the document.
What Just Happened
You delegated three tasks that would normally require you to open three different apps (Gmail, Calendar, Drive), navigate their interfaces, and manually compile the information. Your agent did all three from a single chat window on your phone.
The agent loop you learned in Lesson 3 (intake, context assembly, model inference, tool execution, reply) is now operating on your real data. The same five phases. The same execution engine. But instead of generating practice files, it is reading your actual inbox, checking your actual calendar, and searching your actual Drive.
The Security Reality
Stop and consider what you just did. You granted your AI Employee OAuth access to your Google account. Look at what that means through the lens of the security concerns from Lesson 5:
| Component | Before gog | After gog |
|---|---|---|
| Private data access | Agent reads files it created itself | Agent reads your email, calendar, contacts, documents |
| Untrusted content | Your typed messages only | Incoming emails, shared documents, calendar invitations from anyone |
| External communication | Agent writes files locally | Agent can send emails, create calendar events, modify shared documents |
Every security rule from Lesson 5 applies with higher stakes now.
Scope Awareness
gog requests broad access by default. Ask yourself which services your agent actually needs, and whether it needs write access:
| If your agent only needs to... | Then limit scope to... |
|---|---|
| Summarize unread emails | --services gmail --gmail-scope readonly |
| Check tomorrow's schedule | --services calendar --readonly |
| Find recent documents | --services drive --drive-scope readonly |
| All of the above (read-only) | --services gmail,calendar,drive --readonly |
| Send emails on your behalf | --services gmail (full scope): think carefully |
The --readonly flag limits every service to read access. The --gmail-scope and --drive-scope flags give finer control per service.
The principle is least privilege: grant only the access your agent needs for the tasks you actually delegate. You can always re-authorize with broader scopes later by running gog auth add again with updated flags.
What Could Go Wrong
A malicious skill (remember ClawHavoc from Lesson 6) with gog access could:
- Read your email and extract sensitive information
- Send emails from your account without your knowledge
- Access confidential documents in your Drive
- Exfiltrate contacts to an external server
This is why Lesson 5 came before this lesson. The security checklist you learned is not abstract best practice. It is the difference between a useful employee and a compromised account.
What Transfers
OAuth integration is universal. Every productivity tool your agent will access (Slack, GitHub, Notion, Jira) uses the same pattern: register credentials, authorize access, scope permissions.
Least privilege is architectural. Granting minimum necessary access is not just a security rule for gog. It is a design principle for every agent integration you build.
The employee threshold is tool access. Intelligence alone does not make an agent an employee. The agent loop (Lesson 3) gives it capability. Skills (Lesson 6) give it expertise. But tool access, connecting to the systems where your actual work lives, is what makes the "employee" label accurate.
Try With AI
Prompt 1: Design a Daily Briefing
Setup: Use your AI Employee through your messaging channel or Claude Code.
Design a daily morning briefing for my AI Employee that combines
Gmail (unread, prioritized), Calendar (today's meetings with prep
notes), and Drive (recently modified docs). Output as a single
2-minute read with "requires action" and "FYI" sections.
My role: [YOUR ROLE]
What you're learning: Workflow composition: combining multiple data sources into a single actionable output. This is the foundation of autonomous invocation from Lesson 8. A morning briefing that runs on a schedule transforms your agent from "tool I use" to "employee that works while I sleep."
Prompt 2: Push Notification Pipeline (Advanced Design)
Setup: Use Claude Code or your preferred AI assistant.
Design the architecture for a Gmail push notification pipeline:
detect important emails, summarize them, send to my messaging channel.
I know it involves Google Pub/Sub. Give me component architecture
and data flow with an ASCII diagram, not a full implementation.
What you're learning: Event-driven agent architecture. Most agent interactions are pull-based (you ask, it answers). Push-based agents that react to external events represent the next level of autonomy.
Prompt 3: Security Audit Your Own Setup
Setup: Use Claude Code or your AI Employee.
I just connected my AI Employee to Google Workspace via gog with
OAuth access to Gmail, Calendar, and Drive. Audit my setup: worst
realistic attack scenario, which services I actually need, and the
exact gog command to reduce scope to the minimum.
What you're learning: Applied security auditing on your own infrastructure. You are evaluating real OAuth scopes on your real account, not a hypothetical scenario.
Safety Note: The OAuth credentials you created grant real access to your Google account. Do not share your client_secret.json file, your gog auth tokens, or screenshots showing your email content.
James stared at his phone. Five unread emails, summarized in four seconds. Names he recognized. Subjects he had been ignoring. One required action, flagged by the agent without being asked.
"That is different," he said quietly.
Emma glanced at the summary. "What changed?"
"Everything before this was the agent working on things it made up. Competitor research from training data. Goal files it created. This is MY inbox." He paused. "My agent just read an email from my old boss asking about a reference letter."
"And that is exactly when the security conversation stops being theoretical." Emma pointed at the phone. "Your agent can now read every email you receive. Including password resets. Including financial statements. Including that reference letter."
James thought about it. At his old company, the new hire's access card worked on every floor by default. Nobody questioned it until someone from marketing accidentally walked into the server room. After that, every card was scoped to the floors the employee actually needed.
"Least privilege," he said. "I gave gog access to everything. I only need Gmail and Calendar."
"Fix it."
gog auth add me@gmail.com --services gmail,calendar --readonly
Emma nodded. "Now your agent reads email and checks your calendar. Read-only. It cannot send emails, cannot touch your Drive, cannot access your Contacts or Sheets. If a malicious skill tries to exfiltrate documents, it gets a permission error."
"The OAuth setup was the hardest part. Thirty minutes for the GCP Console." James looked at the dashboard. "Daily use is just messages."
"That is the pattern for every integration. One painful setup. Then it disappears into the workflow." She paused. "I once connected my personal Gmail by accident instead of the test account. Spent an uncomfortable ten minutes reading the secrets audit output before I realized nothing had leaked. The audit command was the only thing that kept me from panicking."
James looked at the orchestration setup from Lesson 10. Two agents. Voice. Proactive behavior. And now, real productivity tools. "This feels like it is ready for other people to use."
"Almost. Lesson 12: your agents learn to delegate to each other. Then we talk about who gets to approve what they do."