OpenClaw Skills 邮件管理（Gmail）技能使用参考手册

Gmail 中文文档

概述

Gmail 是用于让 OpenClaw 通过 Gmail API 与 Gmail 平台交互的 OpenClaw 技能，该技能支持邮件的读取、发送、管理，以及线程、标签和草稿的管理，通过 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。

该技能可以帮助用户在 OpenClaw 中直接访问和操作 Gmail 平台的功能，适合需要在 AI 助手中集成 Gmail 功能的场景，例如邮件内容搜索、邮件自动回复、邮件分类管理等。

技能信息

名称：gmail
描述：通过 Gmail API 实现邮件的读取、发送、管理，以及线程、标签和草稿的管理，使用 Maton 平台的网关进行 OAuth 认证管理，无需手动处理复杂的 OAuth 流程。
版本：1.0.6
作者：maton
许可证：MIT License
依赖：
- 需要网络访问权限
- 需要有效的 Maton API Key（MATON_API_KEY）
触发词："Gmail 邮件管理"、"Gmail 邮件搜索"、"Gmail 邮件发送"、"Gmail 邮件分类"、"Gmail 草稿管理"

👤 作者：byungkyu
🦞 官方地址：https://clawhub.ai/byungkyu/gmail
👉 Skills 下载地址：gmail-1.0.6.zip

快速开始

列出邮件

在你的工作目录中运行以下命令列出邮件：

## List messages
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/google-mail/{native-api-path}

将{native-api-path}替换为实际的 Gmail API 端点路径。网关会将请求代理到gmail.googleapis.com，并自动注入你的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将你的 API 密钥设置为MATON_API_KEY环境变量：

export MATON_API_KEY="你的API密钥"

获取 API 密钥

访问maton.ai注册或登录账户
进入maton.ai/settings页面
复制你的 API 密钥

连接管理

你可以在https://ctrl.maton.ai管理你的 Google OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-mail'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "google-mail",
"metadata": {}
}
}

在浏览器中打开返回的url以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果你有多个 Gmail 连接，可以通过Maton-Connection头指定使用哪个连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早的）活动连接。

API 参考

列出邮件

GET /google-mail/gmail/v1/users/me/messages?maxResults=10

带查询过滤器：

GET /google-mail/gmail/v1/users/me/messages?q=is:unread&maxResults=10

获取邮件

GET /google-mail/gmail/v1/users/me/messages/{messageId}

仅获取元数据：

GET /google-mail/gmail/v1/users/me/messages/{messageId}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date

发送邮件

POST /google-mail/gmail/v1/users/me/messages/send
Content-Type: application/json
{
"raw": "BASE64_ENCODED_EMAIL"
}

列出标签

GET /google-mail/gmail/v1/users/me/labels

列出线程

GET /google-mail/gmail/v1/users/me/threads?maxResults=10

获取线程

GET /google-mail/gmail/v1/users/me/threads/{threadId}

修改邮件标签

POST /google-mail/gmail/v1/users/me/messages/{messageId}/modify
Content-Type: application/json
{
"addLabelIds": ["STARRED"],
"removeLabelIds": ["UNREAD"]
}

移动邮件到垃圾箱

POST /google-mail/gmail/v1/users/me/messages/{messageId}/trash

创建草稿

POST /google-mail/gmail/v1/users/me/drafts
Content-Type: application/json
{
"message": {
"raw": "BASE64URL_ENCODED_EMAIL"
}
}

发送草稿

POST /google-mail/gmail/v1/users/me/drafts/send
Content-Type: application/json
{
"id": "{draftId}"
}

获取个人资料

GET /google-mail/gmail/v1/users/me/profile

查询操作符

在q参数中使用：

is:unread - 未读邮件
is:starred - 已标星邮件
from:email@example.com - 来自特定发件人
to:email@example.com - 发送给特定收件人
subject:keyword - 主题包含关键词
after:2024/01/01 - 特定日期之后的邮件
before:2024/12/31 - 特定日期之前的邮件
has:attachment - 包含附件的邮件

代码示例

JavaScript

// 列出邮件
const response = await fetch(
'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages?maxResults=10',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);

Python

import os
import requests


## 列出未读邮件
response = requests.get(
'https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={'maxResults': 10, 'q': 'is:unread'}
)

注意事项

对于已认证的用户，使用me作为 userId
邮件正文在raw字段中以 base64url 编码
常见标签：INBOX、SENT、DRAFT、STARRED、UNREAD、TRASH
重要提示：使用 curl 命令时，如果 URL 包含括号（fields[]、sort[]、records[]），请使用curl -g以禁用 glob 解析
重要提示：当将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，$MATON_API_KEY等环境变量可能无法正确展开，可能会出现 "无效 API 密钥" 错误

错误处理

状态码	含义
400	缺少 Gmail 连接
401	无效或缺失 Maton API 密钥
429	速率限制（每个账户每秒 10 次请求）
4xx/5xx	来自 Gmail API 的传递错误

故障排除：API 密钥问题

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效应用名称

确保你的 URL 路径以google-mail开头。例如：

正确：https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
错误：https://gateway.maton.ai/gmail/v1/users/me/messages

资源链接

许可证信息

该技能采用 MIT License，完整的许可条款如下：

The MIT License (MIT)
Copyright (c) 2026 Maton
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

元数据信息

该技能的元数据信息如下：

{
"ownerId": "kn75240wq8bnv2qm2xgry748jd80b9r0",
"slug": "gmail",
"version": "1.0.6",
"publishedAt": 1770755759017
}