Skip to content

Google Workspace Companion Setup

The Google Workspace companion lets your bot work with your real Google account: search and summarize your inbox, send replies (with your confirmation), check your calendar, find Drive files, and read or update Docs and Sheets.

It’s powered by gog, the open-source Google Workspace CLI from the OpenClaw team. Your OAuth credentials and tokens are stored encrypted on your own VPS, they never touch ClawOps servers.

Why do I need my own OAuth client?

You authorize your bot through a small “app” that you own in Google Cloud. This means you never grant a third party access to your Google account, you’re granting access to your own app, running on your own server. It takes about 5 minutes and is completely free.

Step 1: Install the companion

Dashboard → Companions tab → Google Workspace → Install. This installs the gog CLI on your VPS and prepares encrypted credential storage.

Step 2: Create a Google Cloud OAuth client

  1. Go to console.cloud.google.com and sign in with your Google account.
  2. Create a new project (top bar → project picker → New Project). Name it anything, e.g. my-bot.
  3. Enable the APIs you want your bot to use: search for and enable Gmail API, Google Calendar API, Google Drive API, Google Docs API, Google Sheets API, and People API (for contacts).
  4. Configure the consent screen: APIs & Services → OAuth consent screen → choose External → fill in the app name and your email → save. You don’t need to submit for verification, just add your own Gmail address under Test users instead.
  5. Create the client: APIs & Services → Credentials → Create Credentials → OAuth client ID → application type Desktop app → Create.
  6. Click Download JSON on the new client.

Step 3: Connect in the dashboard

  1. Back in your ClawOps Dashboard → Companions → Google Workspace card.
  2. Enter your Gmail address and paste the full contents of the downloaded client_secret_*.json file. It’s saved straight to your VPS.
  3. Click Generate sign-in link and open it. Approve access for your account (you’ll see an “unverified app” warning, that’s your own app; click Continue).
  4. After approving, your browser lands on a localhost page that won’t load. That’s expected. Copy the full address from the address bar (it contains code=...) and paste it into the dashboard, then click Finish.

That’s it. Ask your bot “any new email today?” to try it out.

Security notes

  • Your bot always asks for confirmation before sending email or creating events.
  • Content fetched from your inbox is treated as untrusted data, your bot won’t follow instructions embedded in emails.
  • Disconnect anytime from the dashboard; removing the companion wipes all Google credentials from your VPS.

Troubleshooting

  • “This is a Web application OAuth client”: you created the wrong client type. Create a new one with type Desktop app.
  • Google blocks the sign-in (“app not verified”): add your email as a Test user on the OAuth consent screen.
  • Sign-in link expired: links are single-use and short-lived; click Generate a new one.