| name | google-workspace |
| description | Gmail, Calendar, Tasks, Sheets, Docs, Drive, Contacts — OAuth2 with auto-refresh; works with Hermes, OpenClaw, and any terminal agent/CLI. |
| version | 2.2.0 |
| author | Hermes Agent Community |
| license | MIT |
| tags | ["Google","Gmail","Calendar","Tasks","Sheets","Docs","Drive","Contacts","OAuth"] |
| required_credential_files | [{"path":"google_token.json","description":"Google OAuth2 access token(自动刷新,setup.py 管理)"},{"path":"google_client_secret.json","description":"Google OAuth2 客户端凭证(从 Google Cloud Console 下载)"}] |
| optional_credential_files | [{"path":"google_oauth_pending.json","description":"OAuth 流程中间状态(授权完成后自动删除)"}] |
| metadata | {"hermes":{"homepage":"https://github.com/BruceLanLan/hermes-google-workspace","platform":["cli","telegram","slack","discord","whatsapp","openclaw","cursor"],"profile_scoped":true}} |
Google Workspace Skill
Gmail、Calendar、Tasks、Sheets、Docs、Drive、Contacts — 通过 Google OAuth2 集成到任意能跑终端命令的 Agent(Hermes、OpenClaw、Claude Code、Cursor 等)。Token 存放在可配置的 profile 目录,支持自动刷新。
功能覆盖
| 服务 | 读取 | 写入 | 备注 |
|---|
| Gmail | ✅ search (--format ids), get (--format json/text/markdown), labels | ✅ send / reply(--attachment, HTML), modify | 发送前建议由 Agent 确认 |
| Calendar | ✅ list | ✅ create / update / delete | ISO 8601 带时区;create --duration 30m 可省 --end |
| Tasks | ✅ tasklists, list | ✅ add(insert+patch), complete | google_api.py tasks … |
| Sheets | ✅ get | ✅ update, append | 需先查 tab 名 |
| Docs | ✅ get(纯文本) | ❌ | 只读 |
| Drive | ✅ search | ❌ | 只读 |
| Contacts | ✅ list | ❌ | 只读 |
文件索引
scripts/setup.py — OAuth 配置(check / client-secret / auth-url / auth-code / revoke)
scripts/google_api.py — Google API 的 CLI 封装
scripts/scopes.py — 唯一的 OAuth scope 列表(setup.py 与 google_api.py 均从这里导入)
scripts/_gws_env.py — 解析 token 存放目录(Hermes / OpenClaw / 自定义)
scripts/_gws_common.py — 共享的错误装饰器、scope 比对、JSON 输出
tests/test_pure_helpers.py — 纯逻辑单元测试(不触网)
references/gmail-search-syntax.md — Gmail 搜索操作符完整参考
快速安装
hermes skills install google-workspace
手动安装:
HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/skills/productivity/google-workspace"/{scripts,references}
配置 shorthand(按需把 GWORKSPACE_SKILL_DIR 换成你克隆本仓库的路径):
GWORKSPACE_SKILL_DIR="$HOME/src/hermes-google-workspace"
PYTHON_BIN="${HERMES_PYTHON:-python3}"
GSETUP="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/setup.py"
GAPI="$PYTHON_BIN $GWORKSPACE_SKILL_DIR/scripts/google_api.py"
可选:用 npm 提供的入口(需本仓库在本地或已通过 npm install -g / npx 解析到含 scripts/ 的包目录):
GSETUP="npx -y -p hermes-google-workspace gws-setup"
GAPI="npx -y -p hermes-google-workspace gws"
Token 目录解析顺序见 scripts/_gws_env.py。常用覆盖:
GOOGLE_WORKSPACE_STATE_DIR — 显式指定目录(推荐用于非 Hermes 的 CLI)
HERMES_HOME / OPENCLAW_HOME — 与对应 Agent 的 profile 对齐
首次 OAuth 配置
Step 0:检查
$GSETUP --check
Step 1:创建 Google Cloud OAuth 客户端
- 访问 https://console.cloud.google.com/apis/credentials
- 创建项目 → Enable APIs(Gmail / Calendar / Tasks / Sheets / Docs / Drive / People API(通讯录)按需启用)
- Credentials → Create Credentials → OAuth 2.0 Client ID → Desktop app
- Download JSON → 把文件路径交给 Agent / 你自己用于
--client-secret
Step 2:存储客户端凭证
$GSETUP --client-secret /path/to/client_secret.json
Step 3:按需裁剪 SCOPES(高级)
默认列表在 scripts/scopes.py。setup.py 与 google_api.py 已强制从该文件导入,避免再出现「授权范围与 CLI 不一致」的问题。若你不需要某项能力,可从列表中删除对应 scope,然后重新走 OAuth。
Step 4:获取授权 URL
$GSETUP --auth-url
Step 5:交换 Token
用户授权后浏览器跳转到 http://localhost:1/?...,用户粘贴完整 URL:
$GSETUP --auth-code "用户粘贴的URL"
Step 6:验证
$GSETUP --check
使用示例
Gmail
$GAPI gmail search "is:unread newer_than:1d" --max 10
$GAPI gmail get MESSAGE_ID
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1>" --html \
--attachment ~/slides.pdf --attachment ~/notes.txt
$GAPI gmail get MESSAGE_ID --format markdown
$GAPI gmail search "from:boss is:unread" --format ids | xargs -I{} $GAPI gmail modify {} --add-labels STARRED
$GAPI gmail reply MESSAGE_ID --body "Got it, thanks!"
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels STARRED --remove-labels UNREAD
Calendar
$GAPI calendar list
$GAPI calendar create \
--summary "Sprint Planning" \
--start 2026-04-21T10:00:00-05:00 \
--duration 1h30m \
--location "Google Meet" \
--attendees "team@co.com"
$GAPI calendar update EVENT_ID --start 2026-04-21T11:00:00-05:00 --duration 45m
$GAPI calendar delete EVENT_ID --notify
Tasks
$GAPI tasks tasklists
$GAPI tasks list --tasklist TASKLIST_ID
$GAPI tasks add --tasklist TASKLIST_ID --title "Review deck" --notes "Friday" --due "2026-04-20T00:00:00.000Z"
$GAPI tasks complete --tasklist TASKLIST_ID --task TASK_ID
Sheets
$GAPI sheets get "SHEET_ID" "Sheet1!A1:D10"
$GAPI sheets update "SHEET_ID" "Sheet1!A1:B2" --values '[["Alice","100"],["Bob","95"]]'
$GAPI sheets append "SHEET_ID" "Sheet1!A:C" --values '[["Carol","88"]]'
Docs
$GAPI docs get DOC_ID
Drive
$GAPI drive search "budget report" --max 10
$GAPI drive search "mimeType='application/vnd.google-apps.spreadsheet'" --raw-query --max 5
扩展现有认证(添加新 Scope)
- 编辑
scripts/scopes.py
$GSETUP --auth-url(重新获取 URL)
$GSETUP --auth-code "URL"(用户重新授权)
$GSETUP --check
API 已知问题
Docs — body 内容要这样提取
for block in doc_content.get("content", []):
for block in doc_content.get("body", {}).get("content", []):
for elem in block.get("paragraph", {}).get("elements", []):
if "textRun" in elem:
text += elem["textRun"].get("content", "")
Sheets — tab 名不是 "Sheet1"
先查 metadata:
meta = sheets.spreadsheets().get(spreadsheetId=ID).execute()
tabs = [s["properties"]["title"] for s in meta.get("sheets", [])]
tab = tabs[0]
Tasks — insert 时不能设 due date
必须分两步:先 insert,再 patch:
tasks.tasks().insert(tasklist=ID, body={"title": "x", "due": "2026-04-14T00:00:00Z"})
t = tasks.tasks().insert(tasklist=ID, body={"title": "x"}).execute()
tasks.tasks().patch(tasklist=ID, task=t["id"], body={"due": "..."}).execute()
Sheets — 403 权限错误
文件所有者没有和你的 OAuth 客户端共享。请求访问权限或换个已共享的文件。
故障排除
| 问题 | 诊断命令 | 解决方法 |
|---|
NOT_AUTHENTICATED | $GSETUP --check | 完成 OAuth Step 4 |
REFRESH_FAILED | — | Token 被 Google 撤销,重新授权 |
HttpError 403: Insufficient Permission | 检查 scopes | 重新授权 |
HttpError 403: Access Not Configured | Google Cloud Console | 启用对应 API |
ModuleNotFoundError | — | $GSETUP --install-deps |
| Advanced Protection 阻止 | — | Workspace 管理员白名单 OAuth 客户端 ID |
撤销权限
$GSETUP --revoke