Connect Google Workspace so OpenClaw runs Gmail, Calendar, and Drive

Google Workspace is where a lot of your day already lives, which makes it one of the more useful things to hand your Operator.io agent. Once it is connected, the agent can read your agenda before a meeting, triage the overnight inbox, draft a reply for you to approve, drop notes into a Doc, and keep a tracking sheet current, all from the same chat where you ask it everything else. This connection has a reputation for being fiddly, and the Google side does ask for a few clicks, but the whole thing comes down to running a short set of commands on your computer and pasting one file into Operator. This guide walks the simple version.

What you get

OpenClaw reaches Google through gws, a command line tool Google published for the whole of Google Workspace: Drive, Gmail, Calendar, Sheets, Docs, Chat, Tasks, Meet, and the rest. It reads Google's Discovery Service at runtime rather than shipping a frozen command list, so when Google adds an API method the tool picks it up on its own. The binary is already built into OpenClaw, so there is nothing to deploy on the Operator side.

Day to day, the value shows up in the shortcuts people ask for most. You can pull today's agenda from Calendar, summarize unread mail and flag what needs a reply, send or draft a message in Gmail, append a row to a sheet, or write into a doc. Because the agent holds context across a conversation, you can say "read me today's agenda," then "move my 2pm to Thursday and let the attendees know," and it carries the thread through. The one thing it needs from you is permission to act as you, and that is what the credentials file grants.

Each Google service maps to specific OAuth 2.0 scopes, and it helps to see which scope sits behind each one:

The full lists live in the Gmail API scope reference, the Calendar API auth guide, and Google's Drive scope guide, which also covers narrower options like drive.file. You do not need to memorize the URIs because gws auth login handles the mapping when you pass service names like drive,gmail,calendar, but knowing they exist helps when you want to grant read access first and add write scopes later.

The one time setup

Google will not let an app touch your mail and calendar without your own approval. So rather than Operator holding a master key to everyone's account, you create a small set of credentials that belong to you and grant only the access you choose. You do this once, on your own computer, and you never repeat it unless you decide to change what the agent can reach. Everything below happens on your machine right up until the final paste.

Step 1: Install gws on your computer

Download the build for your operating system from the gws releases page, unzip it, and put the gws binary somewhere on your PATH. On a Mac or Linux machine, Homebrew is the quickest route:

brew install googleworkspace-cli

If you have Node installed, npm install -g @googleworkspace/cli works too and pulls the right binary for you. Check that it landed with gws --version. The gws README lists the full install matrix and the helper commands each service exposes, like gws calendar +agenda for today's events and gws gmail +triage for inbox sorting.

Step 2: Create your Google credentials

gws issues your credentials against a Google Cloud project, so you need one of those first. There are two ways to get there, and which is easier depends on what you already have.

If you have the gcloud CLI installed, a single command handles the project, switches on the Workspace APIs, and creates the OAuth client for you:

gws auth setup

If you would rather not install gcloud, set it up by hand in the Google Cloud Console, which is a short sequence of clicks. Create a project, open the OAuth consent screen, and choose External. Enter an app name and your email, then save. Under Test users, add your own Google address. This one matters. While the app sits in testing mode, only the accounts listed here can sign in, and missing it is the most common reason setup fails with an "Access blocked" message. Open Credentials, create an OAuth client ID, and pick Desktop app as the type, which matches how gws auth login opens a browser and receives the callback on localhost. Download the JSON it hands you and save it to ~/.config/gws/client_secret.json.

If the Cloud Console is the part you expect to get stuck on, this walkthrough from FewSteps goes through the consent screen and the OAuth client step in the current console layout.

Google's own OAuth consent walkthrough covers the same ground with screenshots if you want to follow along. The Create credentials guide explains the Desktop app client type in more detail.

Step 3: Sign in and choose what it can touch

Now log in and name the services you want the agent to have. Keep this to what the work needs:

gws auth login --scopes drive,gmail,calendar,sheets --account you@example.com

The --account flag matters. Without it, credentials can save under an unknown account label and every later call returns 401 until you log in again with the address named explicitly.

A browser opens. Because your app is still in testing mode, Google shows a "Google hasn't verified this app" notice, which is expected for something only you use, so click through it and approve the access. Unverified apps in testing mode are capped at roughly 25 OAuth scopes on the consent screen. The recommended preset in gws includes far more than that and will fail on a personal @gmail.com account, which is why you pass specific service names like drive,gmail,calendar rather than accepting every checkbox. Google's scope categories explain why Gmail and Drive scopes count as sensitive and trigger the unverified app warning.

When that succeeds, export the credentials to a file:

gws auth export --unmasked > credentials.json

That file holds your client ID, client secret, and a refresh token. It is the single thing Operator needs from you.

Step 4: Hand the credentials to Operator

In your Operator dashboard, open Skills and find Google Workspace. It shows a field for GWS_CREDENTIALS_JSON with a box to paste into. Drop the entire contents of credentials.json there and click Save key. The value is encrypted and shown to you only once. The skill is already installed on OpenClaw and finds this secret by name, loading it before each Google task, so there is nothing else to set up. If you prefer, you can add the same secret from the Environment page under that name and it works exactly the same.

Once it is saved, delete the local file so a copy of your refresh token is not left sitting on your disk:

rm credentials.json

Step 5: Ask it to do something

You talk to OpenClaw from Telegram or Discord, so connect one on the channels page if you have not already. Then start with something read only, where the output is easy to sanity check:

Read me my calendar agenda for today.

Summarize my unread email from the last day and tell me which three need a reply.

When you trust how it reads your account, let it write something, and tell it to show you first:

Draft a reply to the last email from Priya saying Thursday at 2 works, but show it to me before you send.

It composes the reply, shows you the draft, and sends only once you say go. The same pattern covers putting a meeting on the calendar, starting a doc, or updating a sheet.

Good to know

The refresh token in that file is standing access to the services you approved, so treat it like a password. Keep the scopes as narrow as the job needs, and if you ever want to cut the agent off, delete the GWS_CREDENTIALS_JSON secret or revoke the app from your Google account permissions. If you want to ease in, approve only the read permissions on the consent screen at first, then come back and grant sending and editing once you trust it.

A couple of snags come up often enough to flag. If login finishes but every command then returns a 401, run the login again and name your account directly with gws auth login --account you@example.com, which fixes the case where the tool never recorded a default account. If one service answers with a "not enabled" error, Google prints a link in the message to switch that API on for your project in the Cloud Console, so click it, wait a few seconds, and try the command again. Each Workspace API, Gmail, Calendar, Drive, and Sheets, must be enabled individually before gws can call it.

If you run Google Workspace through an organization and would rather skip the browser entirely, use a service account key instead. Store the service account JSON as GWS_CREDENTIALS_JSON the same way, and if you need it to act on behalf of people in your domain, add a second secret named GWS_IMPERSONATED_USER set to the address it should act as.

That route needs a Workspace admin to turn on domain wide delegation, which removes the per person login but is a larger grant than it first looks. Delegation lets the service account act as users across the domain inside whatever scopes you authorize, and it does so without each person ever seeing a consent screen, which is why it belongs to an admin decision rather than a quick wire up.

Keep the authorized scopes to the minimum the work needs, register the service account in the admin console so its access is visible there, and impersonate only the accounts you actually mean to reach. For a single mailbox the personal OAuth login above is the smaller grant and usually the better fit, and delegation is what you reach for when the agent is genuinely working across a whole domain.

If creating a Cloud project is the part you want to skip, the managed OAuth path connects Gmail through a broker instead. That path covers mail specifically; for Calendar, Drive, and Sheets you still need the gws credentials flow above or an equivalent OAuth setup.