{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/gmail-oauth",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=gmail-oauth",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "scripts/gmail-auth.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/gmail-oauth",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Gmail OAuth Setup",
        "body": "Headless-friendly OAuth flow for Gmail API access using gog CLI."
      },
      {
        "title": "Prerequisites",
        "body": "gog CLI installed (brew install steipete/tap/gogcli)\nGoogle Cloud project with OAuth credentials (Desktop app type)\nGmail API enabled in the project"
      },
      {
        "title": "1. Create Google Cloud Project & Credentials",
        "body": "Go to https://console.cloud.google.com\nCreate a new project (or select existing)\nEnable Gmail API: APIs & Services → Library → search \"Gmail API\" → Enable\nConfigure OAuth consent screen: APIs & Services → OAuth consent screen\n\nChoose \"External\" user type\nFill in app name, user support email\nAdd scopes: gmail.modify (or others as needed)\nImportant: Click \"PUBLISH APP\" for permanent tokens (see Troubleshooting)\n\n\nCreate credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID\n\nApplication type: Desktop app\nDownload the JSON file"
      },
      {
        "title": "2. Configure gog",
        "body": "gog auth credentials /path/to/client_secret.json\ngog auth keyring file  # Use file-based keyring for headless\nexport GOG_KEYRING_PASSWORD=\"your-password\"  # Add to .bashrc"
      },
      {
        "title": "3. Run Auth Flow",
        "body": "Run scripts/gmail-auth.sh interactively, or:\n\n# Generate URL\nscripts/gmail-auth.sh --url\n\n# User opens URL, approves, copies code from localhost redirect\n# Exchange code (do this quickly - codes expire in minutes!)\nscripts/gmail-auth.sh --exchange CODE EMAIL"
      },
      {
        "title": "4. Verify",
        "body": "gog gmail search 'is:unread' --max 5 --account you@gmail.com"
      },
      {
        "title": "\"Access blocked: [app] has not completed the Google verification process\"",
        "body": "Cause: App is in \"Testing\" mode and the Gmail account isn't a test user.\n\nSolutions (choose one):\n\nPublish the app (recommended):\n\nGoogle Cloud Console → APIs & Services → OAuth consent screen\nClick \"PUBLISH APP\" → Confirm\nNo Google review needed for personal use\nTokens become permanent\n\n\n\nAdd test user:\n\nOAuth consent screen → Test users → + ADD USERS\nAdd the Gmail address you're authorizing\nTokens still expire in 7 days"
      },
      {
        "title": "\"Google hasn't verified this app\" warning screen",
        "body": "This is normal for personal apps. Click:\n\nAdvanced (bottom left)\nGo to [app name] (unsafe)\n\nSafe to proceed since you own the app."
      },
      {
        "title": "Token expires in 7 days",
        "body": "Cause: App is in \"Testing\" mode.\n\nFix: Publish the app (see above). Published apps get permanent refresh tokens."
      },
      {
        "title": "\"invalid_request\" or \"invalid_grant\" errors",
        "body": "Causes:\n\nAuthorization code expired (they only last a few minutes)\nCode was already used\nRedirect URI mismatch\n\nFix: Generate a fresh auth URL and complete the flow quickly. Paste the code immediately after getting it."
      },
      {
        "title": "\"redirect_uri_mismatch\" error",
        "body": "Cause: The redirect URI in the token exchange doesn't match what was used in the auth URL.\n\nFix: This script uses http://localhost. Make sure both the auth URL and exchange use the same redirect URI."
      },
      {
        "title": "Page hangs after approving permissions (mobile)",
        "body": "Cause: Browser trying to connect to localhost which doesn't exist on phone.\n\nFix:\n\nUse a desktop browser instead\nOr tap the address bar while it's \"hanging\" - the URL contains the code\nThe URL will look like: http://localhost/?code=4/0ABC..."
      },
      {
        "title": "Multiple permission checkboxes causing hangs",
        "body": "Cause: Too many OAuth scopes requested.\n\nFix: Use minimal scopes. gmail.modify alone is usually sufficient and shows just one permission."
      },
      {
        "title": "Can't find project in Google Cloud Console",
        "body": "Cause: Signed into wrong Google account.\n\nFix: Check which account owns the project:\n\nClick profile icon (top right)\nSwitch accounts\nCheck project dropdown for each account"
      },
      {
        "title": "\"invalid_request\" with oob redirect (new projects)",
        "body": "Cause: Google deprecated urn:ietf:wg:oauth:2.0:oob for OAuth clients created after 2022.\n\nFix: Use http://localhost redirect instead (this script's default). After approval, browser redirects to localhost with code in URL."
      },
      {
        "title": "Scopes Reference",
        "body": "ScopeAccessgmail.modifyRead, send, delete, manage labels (recommended)gmail.readonlyRead onlygmail.sendSend onlygmail.composeCreate drafts, send"
      },
      {
        "title": "Files",
        "body": "scripts/gmail-auth.sh — Interactive auth helper"
      },
      {
        "title": "Tips",
        "body": "Publish your app — Avoids test user limits and 7-day token expiry\nExchange codes quickly — They expire in minutes\nUse desktop browser — Mobile browsers can be finicky with localhost redirects\nOne scope is enough — gmail.modify covers most use cases"
      }
    ],
    "body": "Gmail OAuth Setup\n\nHeadless-friendly OAuth flow for Gmail API access using gog CLI.\n\nPrerequisites\ngog CLI installed (brew install steipete/tap/gogcli)\nGoogle Cloud project with OAuth credentials (Desktop app type)\nGmail API enabled in the project\nQuick Setup\n1. Create Google Cloud Project & Credentials\nGo to https://console.cloud.google.com\nCreate a new project (or select existing)\nEnable Gmail API: APIs & Services → Library → search \"Gmail API\" → Enable\nConfigure OAuth consent screen: APIs & Services → OAuth consent screen\nChoose \"External\" user type\nFill in app name, user support email\nAdd scopes: gmail.modify (or others as needed)\nImportant: Click \"PUBLISH APP\" for permanent tokens (see Troubleshooting)\nCreate credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID\nApplication type: Desktop app\nDownload the JSON file\n2. Configure gog\ngog auth credentials /path/to/client_secret.json\ngog auth keyring file  # Use file-based keyring for headless\nexport GOG_KEYRING_PASSWORD=\"your-password\"  # Add to .bashrc\n\n3. Run Auth Flow\n\nRun scripts/gmail-auth.sh interactively, or:\n\n# Generate URL\nscripts/gmail-auth.sh --url\n\n# User opens URL, approves, copies code from localhost redirect\n# Exchange code (do this quickly - codes expire in minutes!)\nscripts/gmail-auth.sh --exchange CODE EMAIL\n\n4. Verify\ngog gmail search 'is:unread' --max 5 --account you@gmail.com\n\nTroubleshooting\n\"Access blocked: [app] has not completed the Google verification process\"\n\nCause: App is in \"Testing\" mode and the Gmail account isn't a test user.\n\nSolutions (choose one):\n\nPublish the app (recommended):\n\nGoogle Cloud Console → APIs & Services → OAuth consent screen\nClick \"PUBLISH APP\" → Confirm\nNo Google review needed for personal use\nTokens become permanent\n\nAdd test user:\n\nOAuth consent screen → Test users → + ADD USERS\nAdd the Gmail address you're authorizing\nTokens still expire in 7 days\n\"Google hasn't verified this app\" warning screen\n\nThis is normal for personal apps. Click:\n\nAdvanced (bottom left)\nGo to [app name] (unsafe)\n\nSafe to proceed since you own the app.\n\nToken expires in 7 days\n\nCause: App is in \"Testing\" mode.\n\nFix: Publish the app (see above). Published apps get permanent refresh tokens.\n\n\"invalid_request\" or \"invalid_grant\" errors\n\nCauses:\n\nAuthorization code expired (they only last a few minutes)\nCode was already used\nRedirect URI mismatch\n\nFix: Generate a fresh auth URL and complete the flow quickly. Paste the code immediately after getting it.\n\n\"redirect_uri_mismatch\" error\n\nCause: The redirect URI in the token exchange doesn't match what was used in the auth URL.\n\nFix: This script uses http://localhost. Make sure both the auth URL and exchange use the same redirect URI.\n\nPage hangs after approving permissions (mobile)\n\nCause: Browser trying to connect to localhost which doesn't exist on phone.\n\nFix:\n\nUse a desktop browser instead\nOr tap the address bar while it's \"hanging\" - the URL contains the code\nThe URL will look like: http://localhost/?code=4/0ABC...\nMultiple permission checkboxes causing hangs\n\nCause: Too many OAuth scopes requested.\n\nFix: Use minimal scopes. gmail.modify alone is usually sufficient and shows just one permission.\n\nCan't find project in Google Cloud Console\n\nCause: Signed into wrong Google account.\n\nFix: Check which account owns the project:\n\nClick profile icon (top right)\nSwitch accounts\nCheck project dropdown for each account\n\"invalid_request\" with oob redirect (new projects)\n\nCause: Google deprecated urn:ietf:wg:oauth:2.0:oob for OAuth clients created after 2022.\n\nFix: Use http://localhost redirect instead (this script's default). After approval, browser redirects to localhost with code in URL.\n\nScopes Reference\nScope\tAccess\ngmail.modify\tRead, send, delete, manage labels (recommended)\ngmail.readonly\tRead only\ngmail.send\tSend only\ngmail.compose\tCreate drafts, send\nFiles\nscripts/gmail-auth.sh — Interactive auth helper\nTips\nPublish your app — Avoids test user limits and 7-day token expiry\nExchange codes quickly — They expire in minutes\nUse desktop browser — Mobile browsers can be finicky with localhost redirects\nOne scope is enough — gmail.modify covers most use cases"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/kai-jar/gmail-oauth",
    "publisherUrl": "https://clawhub.ai/kai-jar/gmail-oauth",
    "owner": "kai-jar",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}