# Connecting Google Workspace (/docs/meet-your-personal-ai-employee/12-connecting-google-workspace) --- type: Document title: "Connecting Google Workspace" description: "Connect your AI Employee to Gmail, Calendar, and Drive using gog, experience the moment your agent processes real email, and confront the security implications of OAuth access" status: stable order: 9612 chapter: 56 lesson: 12 duration_minutes: 35 generated: by: ag-archive/0.1.0 at: 2026-08-26T00:00:00Z ksor: audience: [public] approval: by: ag-archive/0.1.0 at: 2026-08-26T00:00:00Z trust_tier: unverified build_id: sha256:c8912c3008ae345a7fdc33ace656531ad74f37c065177057c390c7d759f1e970 source_commit: dad4758bb59919c7b9130444778ade062a2dce3e ksor_version: 0.0.47 --- ## What You Will Learn In this lesson, your agent touches your real data for the first time, and the security conversation stops being theoretical. By the end, you should be able to connect Gmail, Calendar, and Drive using **gog** (a CLI that bridges OpenClaw and Google Workspace), apply **least privilege** by scoping OAuth to only the services you need, and run `openclaw secrets audit` to verify your credentials are stored safely. You will also understand why **read-only Gmail access** is not as safe as it sounds: the agent can see every email, including password resets and financial statements. Use a test Google account, not your primary one. --- 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." --- > [!CAUTION] > **[Use a Dedicated Test Google Account]** > > 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 > [!TIP] > **Google Cloud Console Feeling Overwhelming?** > > 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 > [!TIP] > **Selected gog During Setup?** > > 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 ```bash brew install gogcli ``` ### Windows Download `gogcli__windows_amd64.zip` from the [gogcli releases page](https://github.com/openclaw/gogcli/releases) (look under **Assets** on the latest release). Then in PowerShell: ```powershell # Extract to C:\Tools\gogcli (creates the folder if needed) New-Item -ItemType Directory -Path "C:\Tools\gogcli" -Force | Out-Null Expand-Archive -Path "$HOME\Downloads\gogcli_*_windows_amd64.zip" -DestinationPath "C:\Tools\gogcli" -Force # Add to User PATH (no admin needed, persists across sessions) $current = [Environment]::GetEnvironmentVariable("Path", "User") if ($current -notlike "*C:\Tools\gogcli*") { [Environment]::SetEnvironmentVariable("Path", "$current;C:\Tools\gogcli", "User") } ``` Open a **new** PowerShell window before continuing. The updated PATH only takes effect in fresh shells. ### Linux **Arch:** ```bash yay -S gogcli ``` **Other distributions:** Build from source: ```bash git clone https://github.com/openclaw/gogcli.git cd gogcli && make sudo cp ./bin/gog /usr/local/bin/ ``` Verify the installation: ```bash 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](https://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: ```bash gog auth credentials ~/Downloads/client_secret_*.json ``` ### Part 3: Authorize Your Account ```bash 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**. > [!TIP] > **If you see "Access blocked: 403 access_denied"** > > The browser will refuse the consent flow with a message like _"<app-name> has not completed the Google verification process"_ if your email is not yet listed as a test user on the OAuth consent screen. > > **Fix in 2 minutes:** > > 1. Open [console.cloud.google.com/auth/audience](https://console.cloud.google.com/auth/audience) (confirm the project selector at the top matches the project where you created the OAuth client). > 2. Scroll to **Test users**, click **+ Add users**, add the email you are authorizing, click **Save**. > 3. Retry `gog auth add you@gmail.com`. > > **The 7-day token catch:** while the app stays in **Testing** mode, OAuth refresh tokens expire weekly, so you will re-authorize every 7 days. To stop the weekly re-auth, click **Publish app** on the same audience page. The app stays personal; publishing only removes the testing-mode token expiry. For personal use with sensitive Gmail scopes, this works without going through Google's full verification review. By default, gog requests access to Gmail, Calendar, Drive, Contacts, Sheets, and Docs. If you want to limit scope to specific services: ```bash gog auth add you@gmail.com --services gmail,calendar,drive ``` Set your default account so you do not need to specify it every time: ```bash export GOG_ACCOUNT=you@gmail.com ``` Add that line to your shell profile (`~/.zshrc` or `~/.bashrc`) to make it permanent. ### Verify Everything Works ```bash gog auth list ``` For a deeper check that scopes, tokens, and API access are all healthy, run the doctor: ```bash gog auth doctor --check ``` Quick test: list your Gmail labels: ```bash 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. ### Block Sends Even When Authorized OAuth scope decides what tokens _could_ do; gog can also enforce a second guard at the binary level so the agent _drafts_ replies but never actually sends them. This is the pattern most people want for an AI Employee touching real email: agent does the writing, you click Send. Turn on the persistent no-send guard for your account: ```bash gog config no-send set you@gmail.com gog config no-send list ``` Once set, every Gmail send path refuses to run for that account: `gog gmail send`, `gog gmail forward`, `gog gmail autoreply`, and `gog gmail drafts send` all error out. Reads, searches, labels, archives, and `gog gmail drafts create` (which only saves to your Drafts folder) keep working normally. Verify the guard: ```bash # Should error out gog gmail send --to test@example.com --subject "test" --body "test" # Should succeed (saves a draft, does not send) gog gmail drafts create --to test@example.com --subject "draft test" --body "hello" ``` Two layers of defense are now in place: OAuth scope (what the token is allowed to do) and the no-send guard (what the binary will refuse to do even with a valid token). A malicious skill would have to bypass both to send mail from your account. ### 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 9. 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. --- ## What You Should Remember ### The Turning Point Everything before this lesson used data the agent generated itself. This lesson connects it to YOUR inbox, YOUR calendar, YOUR files. That is when "AI Employee" stops being a metaphor. ### Least Privilege Grant only the OAuth scopes your agent actually needs. Start with `--services gmail,calendar --readonly`. Add services incrementally. Even read-only Gmail means the agent can see every email, including password resets and financial statements. ### The OAuth Pattern Register credentials once in Google Cloud Console. Authorize with `gog auth add`. This pattern (register, authorize, scope) repeats for every SaaS integration: Slack, GitHub, Notion, Jira. ### Secrets Audit After adding any integration, run `openclaw secrets audit`. It checks for plaintext credentials that should be migrated to SecretRefs. The audit command is your safety net when connecting real accounts. --- 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." ```bash 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 11. Two agents. Voice. Proactive behavior. And now, real productivity tools. "This feels like it is ready for other people to use." "Almost. Lesson 13: your agents learn to delegate to each other. Then we talk about who gets to approve what they do." ## Flashcards Study Aid