OpenClaw 接入 Gmail:gog + Google OAuth
Polished by GPT5.4
一、先看结论
OpenClaw 要稳定接入 Gmail,至少要满足下面 4 件事:
- Google Cloud 已启用
Gmail API和Google Calendar API gog已导入 OAuth credentials,并完成账号授权- OpenClaw 运行环境能找到
gog命令 - OpenClaw 服务环境里设置了
GOG_KEYRING_PASSWORD
前 3 项都对,第 4 项漏掉,通常就会卡住。
二、我这次踩到的两个坑
1) 终端已授权,但 OpenClaw 里还是失败
在交互 shell 里:
gog auth list
能看到账号,例如:
jiajian2233@gmail.com default gmail 2026-03-18T08:01:07Z oauth
但在 OpenClaw 环境里跑同一条命令会报错:
read token for jiajian2233@gmail.com: read token: no TTY available for keyring file backend password prompt; set GOG_KEYRING_PASSWORD
这类报错的含义很直接:
- OAuth 凭据是有的
- token 文件也是有的
- 问题出在后台进程没有 TTY,
gog无法弹密码输入框
所以要把密码提前注入环境变量:
GOG_KEYRING_PASSWORD
2) 环境变量写进了错误的 unit
我一开始改的是 openclaw.service,但实际在跑的是:
openclaw-gateway.service
而且是 user-level systemd:
~/.config/systemd/user/openclaw-gateway.service
unit 写错,配置再正确都不会生效。
三、接入流程
第 1 步:在 Google Cloud 创建 OAuth 凭据
- 打开 https://console.cloud.google.com/
- 新建一个项目(例如
OpenClaw Gmail) - 启用 API:
Gmail APIGoogle Calendar API
- 按提示完成 OAuth consent screen(个人使用一般默认配置就够)
- 在
Credentials页面创建OAuth client ID,类型选Desktop app - 下载凭据 JSON,比如:
client_secret_xxxxx.json
第 2 步:把凭据导入服务器上的 gog
先把 JSON 上传到 OpenClaw 所在机器,例如:
/home/jiajian/client_secret.json
导入命令:
gog auth credentials /home/jiajian/client_secret.json
可选检查:
ls -l /home/jiajian/client_secret.json
第 3 步:授权 Google 账号
gog auth add your@gmail.com --services gmail,calendar --manual
例如:
gog auth add jiajian2233@gmail.com --services gmail,calendar --manual
流程是:
- 复制终端输出的授权链接
- 浏览器打开并登录账号
- 同意 Gmail / Calendar 权限
- 跳转到
127.0.0.1回调地址后,复制完整 URL - 把 URL 粘回终端
完成后执行:
gog auth list
能看到账号就说明授权成功。
第 4 步:确认 gog 命令可用
which gog
gog --help
第 5 步:先在 shell 验证凭据读取
gog auth list
如果这里正常,说明当前 shell 可以读取并解密 token。
注意,这不代表 OpenClaw 服务进程也能读取。
第 6 步:给 OpenClaw 服务注入 GOG_KEYRING_PASSWORD
后台服务没有交互终端,gog 读 keyring 时如果需要密码,就必须从环境变量获取。
报错通常是:
no TTY available for keyring file backend password prompt; set GOG_KEYRING_PASSWORD
看到这条,优先检查服务环境变量,不要先怀疑 OAuth 流程。
第 7 步:确认实际运行的 systemd unit
openclaw gateway status
如果输出类似:
Service file: ~/.config/systemd/user/openclaw-gateway.service
那要改的是 openclaw-gateway,不是 openclaw。
第 8 步:为 openclaw-gateway 写入环境变量
推荐用 override:
systemctl --user edit openclaw-gateway
写入:
[Service]
Environment="GOG_KEYRING_PASSWORD=密码"
然后执行:
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway
第 9 步:重启后回到 OpenClaw 环境复查
echo "${GOG_KEYRING_PASSWORD:+SET}"
gog auth list
期望结果:
- 输出
SET gog auth list可以正常列出账号
第 10 步:做一次真实 Gmail 查询
gog gmail search "in:inbox newer_than:7d" --plain | head
或指定账号:
gog gmail search "newer_than:7d" --max 5 --account your@gmail.com
能返回邮件列表,说明链路已打通。
四、收尾
这次排障的关键点其实很朴素:授权并不等于服务可用。OAuth 通了,只代表“我有票”;systemd 环境变量配对了,服务进程才“能进场”。