gog：在终端中掌控 Google Workspace 的命令行客户端使用指南

gog：在终端中掌控 Google Workspace 的命令行客户端使用指南

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

gog 是一个面向 Gmail、Calendar、Drive、Docs、Sheets 等 Google Workspace 服务的单一命令行客户端，为个人开发者、脚本、CI 流水线与 Agent 提供显式账户路由、机器可读输出与内置安全控制。本文基于 gogcli 仓库的 README 及配套源码，系统讲解其安装、快速上手、多服务覆盖、认证机制与自动化安全实践。

项目概览：为什么需要一个终端版 Google Workspace

gog将 Google Workspace 的常用能力收敛到一个可脚本化的命令行入口。与浏览器端操作不同，CLI 形态天然适合批处理、定时任务、CI 集成与 AI Agent 调用：一次配置 OAuth 后，即可通过管道串联邮件的查询、日历日程的获取、Drive 文件的审计等操作。

仓库根目录的 README.md 给出了三条最具代表性的命令，展示了"只读 + JSON"的典型用法：

gog --readonly gmail search 'is:unread newer_than:7d' --max 10 --json gog --readonly calendar events --today --json gog --readonly drive audit sharing --parent <folderId> --json

这三条命令分别覆盖邮件检索、当日日程与 Drive 共享审计，均以--readonly兜底、以--json输出结构化结果，是脚本与 Agent 使用 gog 的推荐姿势。

从源码结构看，项目以 Go 实现，模块路径为github.com/openclaw/gogcli（见 go.mod），要求 Go 1.26+。命令行解析使用alecthomas/kong，OAuth 与 Google API 客户端分别基于golang.org/x/oauth2与google.golang.org/api构建。程序入口在 cmd/gog/main.go，实际逻辑全部位于internal/cmd包中，其中 internal/cmd/root.go 定义了完整的命令树：既有gmail、drive、calendar、docs、sheets等服务命名空间，也提供send、ls、search、open、login、logout、me等"动作优先"的快捷别名命令。

安装：从 Homebrew、Go 到 Docker

Homebrew（macOS / Linux 最短路径）

brew install openclaw/tap/gogcli gog --version

Go 源码安装

go install github.com/openclaw/gogcli/cmd/gog@latest gog --version

README 特别提醒：早期使用github.com/steipete/gogcli模块路径的安装脚本，应统一切换到github.com/openclaw/gogcli。Docker 镜像、Windows 压缩包、macOS/Linux 原始二进制以及源码构建的完整说明，见 docs/install.md。

从源码构建与测试

仓库自带 Makefile，开发者可用如下命令构建、测试与执行 CI 检查：

make build make test make ci

其中 CI 相关细节记录在 docs/live-testing.md（可选的 Google API 冒烟测试）与 docs/RELEASING.md（维护者发布流程）。

快速开始：五分钟接入你的 Google 账户

gog 的授权流程围绕"Desktop OAuth Client"展开。完整步骤如下：

1. 在 Google Cloud 控制台的 OAuth 客户端页面创建一个Desktop 类型的 OAuth 客户端，并下载其 JSON 文件；
2. 将凭据文件导入 gog，并只授权你实际需要的服务；
3. 设置默认账户；
4. 用auth doctor自检；
5. 开始查询。

gog auth credentials set ~/Downloads/client_secret_*.json gog auth add you@gmail.com --services gmail,calendar,drive export GOG_ACCOUNT=you@gmail.com gog auth doctor --check gog gmail search 'newer_than:7d' --max 10

其中 API 启用、OAuth 同意屏幕、每周令牌过期规避、无头（headless）授权与账户默认值等进阶内容，在 docs/quickstart.md 的"五分钟快速上手"中有完整覆盖。

从源码看，gog auth add是授权命令的核心实现，位于 internal/cmd/auth_add.go。它支持的--services取值包括user（默认，授权默认的用户 OAuth 服务）、all（全部默认用户 OAuth 服务）以及逗号分隔的服务列表；adsense、photospicker属于需要显式声明的服务。该命令还提供多种浏览器外授权模式：

• --manual：无浏览器流程（粘贴重定向 URL）；
• --remote --step 1/2：面向远程/服务器场景的两步流程（先打印 URL，再交换授权码）；
• --listen-addr：自定义 OAuth 回调监听地址；
• --force-consent：强制展示同意屏幕以获得刷新令牌。

权限收窄是 gog 的突出特性：--drive-scope支持full|readonly|file三种模式，--gmail-scope支持full|readonly|send|read-send四种模式。例如"只发信"的最小权限 Gmail 授权是：

gog auth add you@example.com --services gmail --gmail-scope send

而--gmail-scope read-send则在可读邮件的同时，不授予邮箱修改与设置管理权限。源码中的authScopeModes函数（internal/cmd/auth_add.go）还会校验权限模式与只读标记的兼容性：例如--readonly不能与--gmail-scope send或--drive-scope file组合，因为这些模式具备写能力。

服务矩阵：一个 CLI 覆盖整个 Google Workspace

gog 的命令遵循"先资源后操作"的组织方式。README 按工作场景给出了常用入口：

完整命令面可参考 docs/examples.md 与生成的命令索引 docs/commands/README.md。

值得注意的两个能力边界：

1. Discovery API 兜底：当中央目录对某服务返回 404 时，gog api系列命令可对接服务托管的 Discovery 文档（例如 Meet v2）。显式设置GOG_DISCOVERY_BASE_URL可覆盖默认目录地址，且行为保持向后兼容。
2. 消费者账户与托管域差异：面向用户的 API（如 Gmail、Calendar、Drive）支持普通 Google 消费者账户；而 Admin Directory、Cloud Identity Groups、Chat、Keep 以及域级授权（domain-wide delegation）则必须依赖托管的 Google Workspace 域，具体配置见 docs/workspace-admin.md。

支持的 OAuth 服务一览

README 内置了一张由脚本生成的服务表（标记为auth-services:start/end注释块，README.md），运行gog auth services可从已安装的二进制获得同等信息。下表摘录关键服务与其 OAuth 作用域：

表中可见一个清晰的安全设计：默认面向普通用户的服务均申请"够用即可"的只读或细分作用域（如driveactivity、drivelabels明确为只读），而管理类服务（admin、groups、keep）一律标注"仅 Workspace + 域级委派"，从授权源头上限制权限边界。

认证与账户路由：多账户、别名与服务账户

gog 支持单次安装内路由到多个 Google 账户、命名 OAuth 客户端项目、直接访问令牌、应用默认凭据（ADC）以及 Workspace 服务账户。令牌默认存储在平台密钥环（keyring）中；无头系统可切换到加密文件后端。

gog auth list --check gog auth alias set work you@company.com gog --account work gmail search 'is:unread'

--account参数接受邮箱、别名或auto（自动选择已认证账户），并支持短标志-a。OAuth 客户端选择与服务账户的细节见 docs/auth-clients.md；GOG_HOME、XDG 路径与密钥环存储布局见 docs/paths.md。

从 internal/cmd/root.go 的全局标志定义可以看到认证相关的完整能力：

• --access-token（或环境变量GOG_ACCESS_TOKEN）：直接使用访问令牌，绕过存储的刷新令牌，令牌约 1 小时过期；
• --quota-project（或GOG_QUOTA_PROJECT）：指定计入 API 用量的 Google Cloud 项目（以X-Goog-User-Project头发送），部分 API 在使用--access-token或 ADC 时必需；
• --client：选择存储凭据与令牌桶对应的 OAuth 客户端名称；
• 自动重认证（auto-reauth）：当存储的刷新令牌过期或失效（invalid_grant）时，gog 会启动浏览器 OAuth 流程并持久化新令牌，行为与gog auth add一致（见 internal/cmd/root.go 中reauthFn的实现注释）。

安全自动化：为脚本、CI 与 Agent 而生的输出与执行边界

README 强调 gog 的自动化设计目标：面向"人、脚本、CI 与 Agent"，需要"显式账户路由、机器可读输出与安全控制"。对应机制如下。

机器可读输出

• --json（短标志-j，别名--machine）：向 stdout 输出结构化 JSON；
• --plain（短标志-p，别名--tsv）：输出稳定的 TSV 文本；
• 所有提示、进度条与警告一律写入stderr，不污染 stdout 的机器输出。

多层安全护栏

• --readonly：在运行时拦截一切变更类 API 请求，仅放行 GET、HEAD、OPTIONS 及少量使用 POST 的查询类 API；该守卫独立于 OAuth 作用域与命令名，还会传播到 MCP 子进程并同时阻止 Zoom 会议变更（见 docs/automation.md）；
• --no-input：永不交互提示，缺失输入时直接失败，适合 CI；
• --enable-commands/--enable-commands-exact/--disable-commands：按命令前缀或精确路径限定可用命令；
• --gmail-no-send：阻断 Gmail 发送操作；
• --dry-run（别名--noop、--preview）：不实际变更，仅打印预期动作并成功退出；
• --wrap-untrusted：在 JSON/raw 输出中，为 Google 托管的自由文本包上"不可信内容"标记，防止其被 LLM 等指令感知系统直接消费。

README 给出的自动化示例将上述机制组合成一条完全可复现的命令：

gog --account you@gmail.com \ --enable-commands-exact gmail.search,gmail.get \ --gmail-no-send --readonly --no-input --wrap-untrusted --json \ gmail search 'newer_than:7d'

更完整的输出/退出码契约与安全状态发现，见 docs/automation.md；编译期固化命令策略与锁定标志值的二进制，见 docs/safety-profiles.md。

稳定退出码与运行时策略自省

自动化场景可以依赖稳定的进程退出码做分支判断，而不必解析 stderr：

运行时策略自省则通过schema命令实现：

gog schema --json gog schema gmail search --json gog help drive inventory

gog schema --json输出完整命令树、参数、标志、稳定退出码、输出格式与本次调用的生效安全状态（顶层automation对象包含output_formats、exit_codes、safety三部分）。该 schema 由运行中的二进制从同一命令树生成，保证文档与实现始终一致。

面向 Agent 的 MCP 服务器

gog mcp通过 stdio 暴露类型化的 MCP 服务器，但刻意不提供通用 shell 或任意命令桥接（见 docs/mcp.md）：没有通用命令执行工具、不接受模型提供的 argv 透传、工具 schema 固定且执行前校验、默认只读、写工具必须显式授权。README 明确其默认只读，写操作需显式命令与工具授权。

安全配置文件：编译期固化的命令策略

对于"Agent、CI 任务、沙箱或其它不应在运行时修改自身权限的调用方"，gog 提供了比运行时标志更强的安全边界：安全配置（Safety Profile）将命令策略编译进二进制，调用方无法通过标志、环境变量、配置文件或 shell 参数绕过。

仓库内置三份预设配置（safety-profiles/ 目录）：

• agent-safe.yaml：允许读取、搜索、起草、打标签、归档与文件整理等低风险可恢复操作；阻断发送、删除、共享变更、管理操作与认证写入。适用于收件箱分流 Agent、草稿回复生成、需要人工复核的汇总/报表任务；
• readonly.yaml：仅允许读/列表/搜索/获取类命令，阻断一切变更、发送、删除、共享、认证写入与本地配置写入。适用于报表、审计、监控与只读信息收集；
• full.yaml：放行一切，主要用于冒烟测试构建链路或制造与官方 gog 命令面一致的-safe二进制。

以agent-safe为例，它允许gmail search、gmail drafts create、drive ls、calendar events等，同时将gmail send、drive delete、drive share、auth add、config set等一律置为false，并整体关闭classroom、admin、backup、completion命名空间。

配置文件语法

配置文件是镜像命令路径的 YAML 映射（以 safety-profiles/agent-safe.yaml 顶部结构为例）：

name: agent-safe gmail: search: true send: false drafts: create: true send: false aliases: send: false

规则语义：

• true允许某命令路径；
• false阻断某命令路径，且阻断规则覆盖父级的允许规则；
• 当配置存在任何允许规则时，未列出的命令一律被阻断；
• 命令名在内部以点路径表达，如gmail.drafts.create；
• aliases:控制send、ls、search、upload等根级快捷命令；
• locked-flags:不是命令路径，而是用于锁定标志值。

构建与防篡改机制

构建流程（build-safe.sh）本质是一次带额外生成文件的普通 Go 构建：校验 YAML → 生成internal/cmd/safety_profile_baked_gen.go→ 以-tags safety_profile构建 → 用--version冒烟测试 → 退出时删除生成文件。普通go build不含任何配置，官方 gog 二进制不受影响。

运行时检查发生在 Kong 解析命令之后、任何命令处理器或 Google API 调用之前，顺序为：显式拒绝规则优先 → 允许规则放行 → 存在允许规则时其余全部阻断。因此调用方无法在运行时"重新打开"被烘焙阻断的命令。

防篡改方面，生成器把允许/拒绝规则集编译成基于命令点路径 FNV-64a 哈希的switch语句，而非原始 YAML：编译后的规则表不包含规则字符串本身，攻击者要重新启用被阻断命令，必须修补编译后的机器码，成本从一行sed升级到反汇编级操作（见 docs/safety-profiles.md）。

结语：从交互查询到生产级自动化

gog 的定位可以从三个层面理解：对个人用户，它是邮箱、日历、云盘与文档的终端聚合入口；对运维与数据团队，它提供稳定的 JSON/TSV 输出与退出码契约，能无缝嵌入 CI 与定时任务；对 AI 工程团队，它通过--readonly、--no-input、命令白名单、安全配置二进制与类型化 MCP 服务器，把"授予 Agent 访问 Google Workspace 的能力"约束在一个可审计、可固化的最小权限边界内。

围绕本文提到的所有机制，仓库提供了配套的深度文档与可直接运行的示例：输出与退出码契约见 docs/automation.md，安全配置构建与锁定标志见 docs/safety-profiles.md 与 cmd/bake-safety-profile/ 目录，MCP 集成见 docs/mcp.md，命令全集见 docs/commands/README.md，变更历史见 CHANGELOG.md。

说明：gog 是开源项目，与 Google 无隶属关系，遵循 MIT 许可证（LICENSE）。

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli