google-workspace

Gmail, Calendar, Tasks, Sheets, Docs, Drive, Contacts — OAuth2 with auto-refresh; works with Hermes, OpenClaw, and any terminal agent/CLI.

Jump to install

Repository: BruceLanLan/hermes-google-workspace
Last source activity: April 18, 2026 at 17:09
Detected SKILL.md language: Chinese
Stars: 3
Forks: 1

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

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}

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 时（或先用本地路径调试：`npx -y -p /path/to/hermes-google-workspace …`）
GSETUP="npx -y -p hermes-google-workspace gws-setup"
GAPI="npx -y -p hermes-google-workspace gws"
# 从 GitHub 安装：`npx -y -p github:BruceLanLan/hermes-google-workspace gws-setup`

$GSETUP --check
# AUTHENTICATED → 已完成，跳过本节

$GSETUP --client-secret /path/to/client_secret.json

$GSETUP --auth-url
# 输出一个 URL，发给用户让其在浏览器打开

$GSETUP --auth-code "用户粘贴的URL"

$GSETUP --check

# 搜索
$GAPI gmail search "is:unread newer_than:1d" --max 10

# 读取
$GAPI gmail get MESSAGE_ID

# 发送（发送前展示草稿并确认）；--attachment 可多次
$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1>" --html \
  --attachment ~/slides.pdf --attachment ~/notes.txt

# 供 Agent 总结：--format markdown / text；或用 --format ids 管道化
$GAPI gmail get MESSAGE_ID --format markdown
$GAPI gmail search "from:boss is:unread" --format ids | xargs -I{} $GAPI gmail modify {} --add-labels STARRED

# 回复（自动 threading + In-Reply-To）
$GAPI gmail reply MESSAGE_ID --body "Got it, thanks!"

# 标签管理
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --add-labels STARRED --remove-labels UNREAD

# 列表（默认未来7天）
$GAPI calendar list

# 创建：--end 或 --duration 二选一
$GAPI calendar create \
  --summary "Sprint Planning" \
  --start 2026-04-21T10:00:00-05:00 \
  --duration 1h30m \
  --location "Google Meet" \
  --attendees "team@co.com"     # 传 --attendees 时自动 sendUpdates=all

# 更新（改时间 / 议程 / 参会人，只改传入的字段）
$GAPI calendar update EVENT_ID --start 2026-04-21T11:00:00-05:00 --duration 45m

# 删除；--notify 给参会人发送取消通知
$GAPI calendar delete EVENT_ID --notify

$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

# 读取（注意：先查 tab 名，不要硬写 "Sheet1"）
$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"]]'

$GAPI docs get DOC_ID

# 全文搜索
$GAPI drive search "budget report" --max 10

# MIME 类型筛选
$GAPI drive search "mimeType='application/vnd.google-apps.spreadsheet'" --raw-query --max 5

# WRONG: 永远是空的
for block in doc_content.get("content", []):

# CORRECT
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", "")

meta = sheets.spreadsheets().get(spreadsheetId=ID).execute()
tabs = [s["properties"]["title"] for s in meta.get("sheets", [])]
tab = tabs[0]  # 用第一个 tab 名

# Fails
tasks.tasks().insert(tasklist=ID, body={"title": "x", "due": "2026-04-14T00:00:00Z"})
# Works
t = tasks.tasks().insert(tasklist=ID, body={"title": "x"}).execute()
tasks.tasks().patch(tasklist=ID, task=t["id"], body={"due": "..."}).execute()

问题	诊断命令	解决方法
`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