# Send Gmail OAuth Setup to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "gmail-oauth", "name": "Gmail OAuth Setup", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/kai-jar/gmail-oauth", "canonicalUrl": "https://clawhub.ai/kai-jar/gmail-oauth", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/gmail-oauth", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=gmail-oauth", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "scripts/gmail-auth.sh" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "gmail-oauth", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T00:43:32.027Z", "expiresAt": "2026-05-07T00:43:32.027Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=gmail-oauth", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=gmail-oauth", "contentDisposition": "attachment; filename=\"gmail-oauth-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "gmail-oauth" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/gmail-oauth" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/gmail-oauth", "downloadUrl": "https://openagent3.xyz/downloads/gmail-oauth", "agentUrl": "https://openagent3.xyz/skills/gmail-oauth/agent", "manifestUrl": "https://openagent3.xyz/skills/gmail-oauth/agent.json", "briefUrl": "https://openagent3.xyz/skills/gmail-oauth/agent.md" } } ``` ## Documentation ### Gmail OAuth Setup Headless-friendly OAuth flow for Gmail API access using gog CLI. ### Prerequisites gog CLI installed (brew install steipete/tap/gogcli) Google Cloud project with OAuth credentials (Desktop app type) Gmail API enabled in the project ### 1. Create Google Cloud Project & Credentials Go to https://console.cloud.google.com Create a new project (or select existing) Enable Gmail API: APIs & Services → Library → search "Gmail API" → Enable Configure OAuth consent screen: APIs & Services → OAuth consent screen Choose "External" user type Fill in app name, user support email Add scopes: gmail.modify (or others as needed) Important: Click "PUBLISH APP" for permanent tokens (see Troubleshooting) Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID Application type: Desktop app Download the JSON file ### 2. Configure gog gog auth credentials /path/to/client_secret.json gog auth keyring file # Use file-based keyring for headless export GOG_KEYRING_PASSWORD="your-password" # Add to .bashrc ### 3. Run Auth Flow Run scripts/gmail-auth.sh interactively, or: # Generate URL scripts/gmail-auth.sh --url # User opens URL, approves, copies code from localhost redirect # Exchange code (do this quickly - codes expire in minutes!) scripts/gmail-auth.sh --exchange CODE EMAIL ### 4. Verify gog gmail search 'is:unread' --max 5 --account you@gmail.com ### "Access blocked: [app] has not completed the Google verification process" Cause: App is in "Testing" mode and the Gmail account isn't a test user. Solutions (choose one): Publish the app (recommended): Google Cloud Console → APIs & Services → OAuth consent screen Click "PUBLISH APP" → Confirm No Google review needed for personal use Tokens become permanent Add test user: OAuth consent screen → Test users → + ADD USERS Add the Gmail address you're authorizing Tokens still expire in 7 days ### "Google hasn't verified this app" warning screen This is normal for personal apps. Click: Advanced (bottom left) Go to [app name] (unsafe) Safe to proceed since you own the app. ### Token expires in 7 days Cause: App is in "Testing" mode. Fix: Publish the app (see above). Published apps get permanent refresh tokens. ### "invalid_request" or "invalid_grant" errors Causes: Authorization code expired (they only last a few minutes) Code was already used Redirect URI mismatch Fix: Generate a fresh auth URL and complete the flow quickly. Paste the code immediately after getting it. ### "redirect_uri_mismatch" error Cause: The redirect URI in the token exchange doesn't match what was used in the auth URL. Fix: This script uses http://localhost. Make sure both the auth URL and exchange use the same redirect URI. ### Page hangs after approving permissions (mobile) Cause: Browser trying to connect to localhost which doesn't exist on phone. Fix: Use a desktop browser instead Or tap the address bar while it's "hanging" - the URL contains the code The URL will look like: http://localhost/?code=4/0ABC... ### Multiple permission checkboxes causing hangs Cause: Too many OAuth scopes requested. Fix: Use minimal scopes. gmail.modify alone is usually sufficient and shows just one permission. ### Can't find project in Google Cloud Console Cause: Signed into wrong Google account. Fix: Check which account owns the project: Click profile icon (top right) Switch accounts Check project dropdown for each account ### "invalid_request" with oob redirect (new projects) Cause: Google deprecated urn:ietf:wg:oauth:2.0:oob for OAuth clients created after 2022. Fix: Use http://localhost redirect instead (this script's default). After approval, browser redirects to localhost with code in URL. ### Scopes Reference ScopeAccessgmail.modifyRead, send, delete, manage labels (recommended)gmail.readonlyRead onlygmail.sendSend onlygmail.composeCreate drafts, send ### Files scripts/gmail-auth.sh — Interactive auth helper ### Tips Publish your app — Avoids test user limits and 7-day token expiry Exchange codes quickly — They expire in minutes Use desktop browser — Mobile browsers can be finicky with localhost redirects One scope is enough — gmail.modify covers most use cases ## Trust - Source: tencent - Verification: Indexed source record - Publisher: kai-jar - Version: 1.0.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-30T00:43:32.027Z - Expires at: 2026-05-07T00:43:32.027Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/gmail-oauth) - [Send to Agent page](https://openagent3.xyz/skills/gmail-oauth/agent) - [JSON manifest](https://openagent3.xyz/skills/gmail-oauth/agent.json) - [Markdown brief](https://openagent3.xyz/skills/gmail-oauth/agent.md) - [Download page](https://openagent3.xyz/downloads/gmail-oauth)