Gog guide: connect OpenClaw to Gmail with a read-only first search

Gog lets OpenClaw use the separate gog command-line tool to work with Gmail, Calendar, Drive, and other Google services. For a first setup, aim at one small task: read-only search of your own recent Gmail. That verifies the Skill, binary, and Google authorization before you consider more services or write access. You need an OpenClaw host with a terminal, your Google account, and a Google Cloud project you control.

Check the two different pieces

OpenClaw may already include a Skill named gog. On the machine where your Agent runs, check first:

openclaw skills info gog
openclaw skills check

If it is present and eligible, keep it. Only if the Skill is absent and you want steipete's ClawHub v1.0.0 should you install it in your own OpenClaw environment:

openclaw skills install @steipete/gog --version 1.0.0

A Skill tells the Agent how to use a tool. It does not install the gog executable or authorize Google. The current bundled OpenClaw Skill and the shorter ClawHub v1.0.0 text are not identical; avoid replacing a working bundled Skill just to follow an install button.

Install gog and prepare one-service authorization

On macOS or Linux with Homebrew, the gogcli project's documented install is:

brew install openclaw/tap/gogcli
gog --version

This installs the gog command, distinct from the ClawHub Skill. For Windows, containers, or a manual binary install, follow the gogcli installation guide linked below. The following OAuth path assumes you can operate a browser on the same machine.

In Google Cloud Console, create or choose your own project and enable Gmail API only for this first task. Configure the OAuth consent screen, create a Desktop app OAuth client, and download its client JSON. If an External project remains in Testing, add your Google account as a test user. Do not put the JSON, callback URL, access token, or keyring password into an Agent conversation or a public repository.

In your trusted local terminal, replace the file path and email with your own values:

gog auth credentials set /absolute/path/to/client_secret.json
gog --readonly auth add you@gmail.com --services gmail
gog auth list --check
gog auth doctor --check

The second command starts Google consent. It selects only the Gmail service and asks for available read-only OAuth scopes. Keep --readonly on the later query too: it is a separate runtime guard. Read the per-account results and diagnostics, not just the commands' exit status. If you already have a working authorization, you can try the read-only query below before repeating setup; note that a runtime --readonly flag does not narrow scopes on an OAuth token you previously granted.

Make one read-only query and inspect it

In the same runtime environment, substitute your own account:

gog --readonly --account you@gmail.com gmail search 'is:unread newer_than:7d' --max 5 --json --wrap-untrusted

A successful command returns structured search data. It may contain Gmail threads, or it may be empty because there are no matching unread messages. An empty result is not itself an authentication failure. If you get an API or authorization error, recheck the account, Gmail API, and OAuth diagnostics first. gog gmail search searches threads; use the official gog gmail messages search command if you later need individual messages instead of thread counts.

After the terminal query works, you can give OpenClaw a first task like this. It is a suggested prompt, not a recorded run:

Use the gog Skill to search my account you@gmail.com for unread Gmail from the past 7 days.
Show at most 5 threads with sender, subject, and date. Use --readonly.
Do not send, delete, archive, or modify mail, and do not include message bodies.
If nothing matches, say the result is empty. If it fails, report the exact error and the next check.

If the terminal succeeds but the Agent cannot, run openclaw skills check again and check whether this Agent can see the Skill and gog on its PATH, then whether its process can read the account token. A successful interactive shell query does not prove the Agent process is ready.

Three common stops

• Google says the API is disabled. Enable Gmail API in the same Cloud project that issued the Desktop OAuth client JSON. Selecting --services gmail does not turn on the Cloud API for you.
• invalid_grant appears after about a week. Google says user-data authorization for External + Testing apps normally expires after seven days. Check the Cloud Console Audience status and applicable publishing requirements; if you change it, complete a fresh authorization with the same scope as the gogcli guide explains. Other causes of invalid_grant exist, so do not assume every token error is this one.
• The shell works, but the Agent reports keyring.password. A public report observed that difference on Ubuntu 24.04 with headless OpenClaw 2026.5.7 and gog 0.15; it is not evidence that every current install fails. Check the keyring backend, HOME, and password environment of the actual Gateway/Agent process using the gogcli install guide. Do not delete working tokens merely because the Agent cannot read them. On a remote host without a browser, the current bundled Skill documents --manual and SSH port forwarding. Keep any callback URL inside a trusted gog terminal flow, never in Agent chat.

This first path intentionally covers Gmail reading only. Calendar, Drive, and Sheets each need their own Google API and service authorization. Decide separately whether a later task justifies mail sending or other modifications.