邮件与工具官方

Gmail

将 Gmail 添加为 MCP 工具。通过智能体读取、搜索、发送、添加标签和起草邮件。

功能特性

在消息触发时读取、搜索、发送、起草、添加标签和过滤邮件
OAuth 由 OneCLI 管理——不会有原始凭据进入容器
通过中央数据库按智能体组启用（ncl groups config）
MCP 服务器集成，实现容器安全的邮件访问
与 /add-gcal-tool 无缝配合（同类技能，相同模式）

前置条件

已安装并运行 NanoClaw
已初始化 OneCLI Agent Vault（先运行 /init-onecli）
已在 OneCLI 中连接 Gmail
gmail.readonly + gmail.modify + gmail.send 权限范围

安装

/add-gmail-tool

工作原理

/add-gmail-tool 技能将 @gongrzhe/server-gmail-autoauth-mcp stdio MCP 服务器接入选定的智能体组。智能体在被要求时即可获得 Gmail 能力——读取、搜索、发送、起草以及管理标签和过滤器。智能体不会自动监控你的收件箱，而是由你从消息通道中触发邮件操作：“查看我的收件箱”、“给 Sarah 发一封关于会议的邮件”或”搜索上个月的发票”。

MCP 服务器读取 ~/.gmail-mcp/ 中包含 onecli-managed 占位符的桩凭据。OneCLI 的网关会拦截发往 gmail.googleapis.com 的出站调用，并将占位符替换为其保管库中真实的 OAuth 令牌。容器永远不会收到原始 API 密钥——这是 v2 的不变原则。

设置

三个步骤，大部分是自动化的：

在 OneCLI 中连接 Gmail。 技能会检查 onecli apps get --provider gmail，如果尚未连接，会提示你打开 OneCLI Web 界面（http://127.0.0.1:10254）进行授权。权限范围应包括 gmail.readonly、gmail.modify 和 gmail.send。
写入桩凭据，位于 ~/.gmail-mcp/gcp-oauth.keys.json 和 ~/.gmail-mcp/credentials.json——两者都包含 onecli-managed 占位符。无需设置 GCP 项目或进行浏览器 OAuth 流程；令牌刷新由 OneCLI 负责。
按智能体组接入。 技能会在中央数据库中注册 gmail MCP 服务器和 ~/.gmail-mcp 挂载（ncl groups config add-mcp-server 加上 container_configs 更新），为每个需要邮件访问权限的组进行配置。groups/<folder>/container.json 会在每次启动时从数据库物化生成，因此在其中手动编辑不会保留。

然后它会在 Dockerfile 中固定 GMAIL_MCP_VERSION 并重新构建。无需编辑允许列表——允许模式（mcp__gmail__*）会根据组的 mcpServers 注册自动派生。

智能体能做什么

Gmail 设置完成后，智能体可以使用以下功能（工具名称以 mcp__gmail__<name> 形式出现）：

读取邮件 — read_email、download_attachment。
发送邮件 — send_email，用于新邮件或回复。
搜索 — search_emails，使用 Gmail 的搜索语法。
起草 — draft_email 创建草稿而不发送，供你审阅。
整理 — 标签工具（list_email_labels、create_label……）、过滤器工具（create_filter……）以及批量修改/删除。

使用建议

此技能仅为工具模式。入站邮件作为通道（邮件直接触发智能体）尚未移植到 v2 的通道架构。
此技能与 /add-gcal-tool 相似。如果两者都已安装，它们将共享 OneCLI 管理的模式和相同的 Dockerfile pnpm 安装块。
首次调用需要一两秒钟，因为 MCP 服务器正在启动且 OneCLI 正在进行令牌交换。后续调用会很快。
如果智能体说”我没有 Gmail 工具”，最常见的原因是该组的 mcpServers 中未注册 gmail MCP 服务器——重新运行 ncl groups config add-mcp-server 步骤并重启，或重新构建过时的镜像。
如果你看到来自 gmail.googleapis.com 的 401 Unauthorized，说明 OneCLI 没有注入令牌——请检查智能体的密钥模式（onecli agents secrets）以及 Gmail 是否已连接（onecli apps get --provider gmail）。