Google Workspace CLI「gog」OAuth Token 过期？这几招帮你快速定位问题

dctc_青龙

用 gog 的过程中，401 报错大概是最让人头疼的。一上来就不给你任何喘息机会，直接 `unauthorized` 甩脸上。这里整理了四种最常见的原因，基本能覆盖你遇到的大部分认证翻车场景。

---

## 先说现象

执行 `gog gmail list` 之类的命令后，常见的报错长这样：

```
Error: googleapi: got HTTP response code 401 with body: {
  "error": "unauthorized",
  "error_description": "Invalid Credentials"
}
```

或者这个：

```
Error: failed to refresh access token: oauth2: cannot refresh token
```

有时候程序直接崩掉，有时候静默返回空结果——取决于走了哪条 API 路径。但不管表象怎么变，401 的意思就一个：凭证验证失败了。

---

## Token 过期

这是头号嫌疑犯。

gog 默认不会主动刷新 token，credential 文件放久了自然会过期。稍微科普一下：OAuth 2.0 有两层 token——`access_token` 用来调用 API，有效期一般就 1 小时；`refresh_token` 用来在 access_token 过期后换新的，生命周期长得多。首次授权时两个都能拿到，但 gog 的刷新策略比较保守，不是每次执行前都检查过期时间，而是等到收到 401 了才想起来去刷新。

所以如果你在脚本里循环调用 gog，连续执行的时候第二次大概率直接躺平。

怎么查：

```bash
gog auth list
```

输出里哪个账号的 `Status` 显示 `Expired` 或 `Invalid`，就是它了。

怎么修：

```bash
gog auth add your@gmail.com --services gmail,calendar,drive
```

浏览器会自动弹出来走授权流程，完事 token 就刷新了。不需要删原来的 credentials 文件。

有个细节容易被忽略：即便 access_token 过期了理论上 gog 应该自动用 refresh_token 换新的，但如果 credentials 文件的写入权限不够（比如说先用 root 跑了一遍 gog，后来又切回普通用户），refresh 这个动作会悄悄失败，下次调用直接收到 401。团队共用服务器的时候这个问题特别容易冒头。

---

## Credentials 文件损坏或路径错误

先确认文件在不在：

```bash
ls -la ~/.config/gog/credentials/
```

gog 的 credentials 是 JSON 格式，里面有 `client_id`、`client_secret`、`access_token`、`refresh_token`、`token_uri` 这些字段。要是磁盘突然满了导致写入中断，JSON 格式就会出问题，读的时候自然就报 `Invalid Credentials`。

验证一下文件能不能正常解析：

```bash
python3 -c "import json; json.load(open('~/.config/gog/credentials/your-project.json'))" && echo "格式正常"
```

多账号的情况下还有个坑：系统里可能存了多个 Google 账号的 `client_secret.json`，gog 有可能读错了那个。显式指定一下就好：

```bash
gog gmail list --account your@gmail.com
```

gog 解析账号的优先级是这样的：先看环境变量 `GOG_ACCOUNT`，再看 `--account` 参数，最后才去 credentials 文件里找第一个有效的。三条都没命中？那就直接报错，不会偷偷给你用第一个。

---

## OAuth Consent Screen 配置问题

在 Google Cloud Console 里动了 OAuth 同意屏幕的配置也会翻车——比如从「测试用户」改成正式发布，已签发的 refresh token 会全部失效。

去 [Google Cloud Console](https://console.cloud.google.com/apis/credentials) 的 OAuth consent screen 看一下：

| 配置项 | 容易踩的坑 |
|--------|------------|
| Publishing Status | 选「Testing」的话 token 7 天必过期，不管你有没有在用 |
| Scopes | 新增 scope 需要用户重新同意 |
| Test Users | 把之前的测试账号删了 |

解决办法：测试环境建议改成正式发布；已经失效了就老老实实 `gog auth add` 重新走一遍流程。

这里有个实际的坑很多人不知道：「Testing」和正式发布对应完全不同的 token 生命周期。Testing 状态下签发的 refresh_token，不管用不用，7 天后铁定失效——这是 Google 的安全策略，不是 gog 抽风。切到正式发布需要过 Google 的安全审查，但其实对个人项目挺友好的，填个基本表单基本就能过。

---

## Gmail API 没启用

这个主要坑新手，安装完 gog 就开始用，结果对应的 Google Cloud 项目里压根没开 Gmail API。

这种情况报错是 403，不是 401：

```
Error: googleapi: got HTTP response code 403
```

去 Google Cloud Console → Enabled APIs & services，确认 `gmail.googleapis.com` 是 Enabled 状态。

401 和 403 长得像但意思完全不一样：401 是认证失败——token 无效；403 是授权失败——token 有效但你没权限。看到 403 先别急着去重新生成 credentials，第一反应应该是去检查这个 API 在当前项目里有没有开启。

---

## 排查顺序

按这个顺序来，能覆盖绝大多数认证问题：

1. 先看错误码：401 查 token，403 查 API 启用状态
2. 跑一下 `gog auth list`，看哪个账号状态不对
3. 检查 credentials 文件——格式对不对、权限够不够
4. 去 Google Cloud Console 看 OAuth Consent Screen 是不是 Testing 状态
5. 以上都搞不定？`gog auth add` 重新授权走起

---

## 几个常见疑问

**Q：gog 的核心概念是什么？**
说白了就是一套通过命令行操作 Google 服务的工具链，核心依赖 OAuth 2.0 做认证，接入 Gmail Calendar Drive 这些服务。跟现有系统集成的话，主要就是靠 credentials 文件和 token 管理。

**Q：内存占用怎么优化？**
主要是三块：缩小缓存和上下文大小、限制并发数和队列长度、定期清理会话释放对象。长时间跑的话建议做个压测观察有没有泄漏趋势。

**Q：适合什么场景？**
日常管理、Gmail 批量处理、日历事件创建、Drive 文件操作这些。自动化脚本里用起来特别爽，比网页操作省事多了。

---

基本上 gog 的认证问题就这些，平时用记住一点就够了：`gog auth list` 是你遇到问题时的第一排查命令，能省不少瞎耽误功夫的时间。要是你碰上过其他奇葩的认证问题，评论区说出来大家交流交流。