Gmail Gog Setup

Set up Gog CLI for Gmail access and authenticate agent mailboxes.

Security Scan

The skill's steps and requirements broadly match its stated purpose (setting up Gog to access Gmail), but there are a few minor inconsistencies and operational risks you should be aware of before running the listed install/auth commands.

Purpose & Capability

Name/description, required binary (gog), and the SKILL.md all describe installing and configuring Gog for Gmail OAuth access — this is internally consistent. The skill legitimately needs Gog and Google OAuth credentials to do what it says.

Instruction Scope

Instructions concentrate on Gmail OAuth and Gog usage (creating an OAuth client, adding test user, running gog auth commands). They also include OS-level install commands (curl, tar, install to /usr/local/bin) and guidance to store client JSON under ~/.openclaw; these are appropriate for the task but require local filesystem and possibly elevated privileges. The SKILL.md also references an environment variable (GOG_KEYRING_PASSWORD) and a recommended credential path that are not declared in the skill metadata.

Install Mechanism

The SKILL.md contains a direct download from a GitHub Releases URL and a tar extraction followed by installing a binary to /usr/local/bin. GitHub Releases is a known host, so this is expected for installing a CLI, but it is higher-risk than a package-manager install because it writes files to disk and may require elevated privileges. The skill has no formal install spec in metadata (it's instruction-only).

Credentials

The skill metadata declares no required environment variables, but the instructions explicitly tell the user to set GOG_KEYRING_PASSWORD and to store OAuth client JSON in ~/.openclaw/credentials/google/. Asking users to create/store OAuth credentials and a keyring password is reasonable for the purpose, however the omission from declared requirements and lack of guidance about protecting these secrets is an inconsistency and a risk (sensitive data handling).

Persistence & Privilege

The skill is instruction-only, does not request 'always: true', and contains no code that would persist or modify other skills. It does instruct the operator to install a system binary under /usr/local/bin (may require sudo), but that is a user-operated step rather than an automated persistent presence requested by the skill.

Assessment

This skill appears to do what it claims (configure Gog to access Gmail), but take these precautions before running the commands: 1) Verify the GitHub release URL and prefer checksums/signatures or your OS package manager where possible rather than piping curl into an install location. 2) Installing to /usr/local/bin may require sudo—only install binaries you trust. 3) The SKILL.md asks you to set GOG_KEYRING_PASSWORD and store OAuth client JSON in ~/.openclaw, but these environment/config requirements are not declared in metadata — treat those files and variables as sensitive secrets and use a secret manager or restrictive file permissions. 4) When creating OAuth credentials, limit scopes, add only necessary test users, and revoke the client when no longer needed. 5) If you intend an agent to use this access autonomously, be extra cautious: verify access controls and rotate credentials regularly. If you want higher assurance, ask the skill author to add a formal install spec, declare required env vars (e.g., GOG_KEYRING_PASSWORD), and provide CI-verified binary checksums or a package-manager-based install option.

Use this skill when you need to give an agent (e.g., Facet, competitions agent) access to a Gmail inbox via Gog CLI.

When to use

• Creating a new agent mailbox (e.g., [e-mail])
• Setting up Gmail reading capability for an existing agent
• Troubleshooting Gog auth failures
• Adding new OAuth clients or test users

Prerequisites

1. Google Cloud OAuth client

• Create a Desktop app OAuth client in Google Cloud Console
• Enable Gmail API
• Add target Gmail address as a test user in OAuth consent screen
• Download the client JSON file

2. Gog installed

# Install Gog from latest release
cd /tmp
curl -L -o gogcli_0.12.0_linux_amd64.tar.gz https://github.com/steipete/gogcli/releases/download/v0.12.0/gogcli_0.12.0_linux_amd64.tar.gz
tar -xzf gogcli_0.12.0_linux_amd64.tar.gz
install -m 0755 gog /usr/local/bin/gog

Steps

1. Store OAuth credentials

gog auth credentials /path/to/client_secret_....json

2. Authenticate the Gmail account

export GOG_KEYRING_PASSWORD='your-keyring-password'
gog auth add [e-mail] --services gmail --manual

• Open the provided auth URL in browser
• Log in as the target Gmail account
• Approve requested permissions
• Copy the redirect URL (localhost) after Google redirects
• Paste it into the waiting Gog prompt

3. Verify access

gog auth list
gog gmail messages search 'newer_than:7d' --account [e-mail] --json

4. Check spam

New senders often land in spam:

gog gmail messages search 'in:spam newer_than:7d' --account [e-mail] --json

Common issues

"No auth for gmail"

• Verify test user is added in Google Cloud OAuth consent screen
• Re-run auth with --force-consent if needed

"state mismatch"

The auth session restarted. Use the latest auth URL and callback.

"no TTY available for keyring file backend"

Set GOG_KEYRING_PASSWORD environment variable before running gog auth add.

Emails going to spam

• Move from spam to inbox: gog gmail messages modify <msg_id> --remove SPAM --add INBOX
• Consider training Gmail by marking as "Not spam"

Notes

• Store OAuth client JSON in ~/.openclaw/credentials/google/
• Keep GOG_KEYRING_PASSWORD in a secure environment variable or secret manager
• For production, consider service account with domain-wide delegation instead of OAuth
• Always check spam folder for important verification/API emails

References

• Gog CLI
• Google Cloud OAuth setup
• OpenClaw Gmail Pub/Sub docs