IronClaw 在 0.25.0 版本解决了一系列与 OAuth 有关的 bug，配置好 Gmail 工具后，不会出现 OAuth 认证频繁失效的问题了。这篇文章记录为 IronClaw 配置 Gmail 工具的完整过程。
1. 背后的考量
1.1 为什么选择 IronClaw
IronClaw 从设计之初对安全考虑的比较充分，采用了基于 wasm 组件的隔离机制（参考之前写过的名为 IronClaw 安全机制解析 的文章）。并且 IronClaw 采用 Rust 实现，Rust 是我个人长期关注的编程语言，尽管它的学习曲线陡峭是公认的，但在 debug 过各种“奇葩问题”，并且见过一些所谓资深程序员堆的“屎山”后，我才觉得 Rust 未来大有可为：不是因为人们津津乐道的“内存安全”，而是因为它在软件工程学方面向前迈了一大步。
AI 生成代码日益成熟，淡化了 Rust 在软件工程学方面的优势，不过同样地，学习曲线也不再成为采用 Rust 的主要障碍。
1.2 为什么接入 Gmail 而不是国内邮件厂商
对于经常混迹国外计算机技术网站、论坛的开发人员，Gmail 邮箱应该是必备的：基本所有网站，比如 Reddit、ChatGPT 都可以直接用 Gmail 账号登入；另外用国外邮箱接收国外各类技术订阅邮件也会很方便。
1.3 如何在接入 AI 助手的同时，保护个人信息
到目前为止，我个人常用的 Gmail 邮箱中除了越来越多的技术订阅邮件，还有个人信息混杂其中。我想让 AI 助手帮忙整理分析技术订阅邮件，又不想让它接触含个人信息，怎么办？
我的做法是：新建一个 Gmail 邮箱，在常用 Gmail 邮箱中添加邮件过滤规则，将满足规则的邮件转发给新建的 Gmail 邮箱，把新建的 Gmail 邮箱丢给 IronClaw。只要规则设置得当，就不用担心 IronClaw 背后的 LLM 触及个人敏感信息。
2. 配置过程
2.1 安装 gmail 工具
IronClaw 内置实现了 Gmail 工具，在 IronClaw Gateway 页面上可以很方便的安装，也可以本地编译 Gmail 工具后手动安装。
Gmail 工具在 IronClaw 中以 wasm 组件的形式存在，默认安装在 $HOME/.ironclaw/tools 目录下，包括两个文件：gmail.wasm 和 gmail.capabilities.json。
2.2 获取 Google OAuth 凭证
配置 Gmail 工具需要的 OAuth 客户端 ID 和秘钥通过 Google Cloud Console 获取。
第一步：创建 Google Cloud 项目
在使用任何 Google API 之前，你需要一个云端项目来管理身份验证和配额。
- 登录 Google Cloud 控制台
- 点击顶部导航栏的项目选择器，选择 “新建项目”
- 输入项目名称（例如
My Gmail App），点击 “创建”
第二步：启用 Gmail API
- 在控制台左侧菜单，选择 “API 和服务” -> “库”
- 在搜索框输入 “Gmail API”
- 点击搜索结果中的 Gmail API，然后点击 “启用”
第三步：配置 OAuth 权限请求页面
这是用户在权限请求页面看到的信息。
- 前往 “API 和服务” -> OAuth 权限请求页面
- 在 “品牌塑造” 选项卡填写应用信息：
- 设置 “应用名称”、“用户支持邮箱”
- 填写 “开发者联系信息”
- 在 “目标对象” 选项卡
- 选择 “用户类型” - 非 Google Workspace 用户只能选择 “外部”
- “添加测试用户” - 仅测试用户可以访问应用，添入新建的 Gmail 邮箱账号
第四步：创建 OAuth 2.0 客户端凭据
- 切换到左侧的 “客户端” 选项卡
- 点击 “创建客户端”
- 选择 “应用类型”，
- Web 应用 - 适用于服务器端应用，需设置 “已授权的重定向 URI”
- 桌面应用 - 适用于本地运行的脚本或软件，不需要设置 URI（建议选这个）
- 点击 “创建”
- 下载包含客户端 ID 和客户端密钥的 json 文件
注意：应用类型选择 Web 应用 时，需要设置 “已授权的重定向 URI”，谷歌会检查 URI 合法性。URI 可以是 https 或者 http 协议的，如果是 http 协议，不允许写内网地址，例如 http://192.168.1.100 是非法的。另外向谷歌发起授权请求时，谷歌会检查 URI 设置值与请求中重定向 URI 是否一致，不一致时会报错（见下图）。
虽然通过环境变量
IRONCLAW_OAUTH_CALLBACK_URL可以为 IronClaw 设置公网重定向 URI，但对于本地部署环境，一般需要借助 ngrok、cloudflare 这类工具将本地 IronClaw 暴露在公网后才能完成授权。简单起见，建议 “应用类型” 选择 “桌面应用”。
OAuth 相关术语
| 参数 | 说明 |
|---|---|
| Client ID | 应用的公开标识符，用于向 Google 标识自己 |
| Client Secret | 应用的私钥，必须严格保密 |
| Redirect URI | 用户授权后，Google 将授权码发送回你的服务器地址 |
| Refresh Token | 用于在访问令牌过期后，无需用户再次登录即可换取新的 Access Token |
2.3 配置 IronClaw
gmail 工具激活流程
tool_activate("gmail")
↓
ToolActivateTool::execute()
↓
ExtensionManager::ensure_extension_ready(
name="gmail",
intent=ExplicitActivate
)
↓
┌─────────────────────────────────────────────────────────────┐
│ 1. 检查扩展是否已安装 │
│ determine_installed_kind("gmail", user_id) │
│ ├─ 如果未安装 + ExplicitActivate │
│ │ └─ 从注册表自动安装 (auto-install) │
│ └─ 返回扩展类型 (wasm_tool) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 2. 检查认证状态 │
│ auth("gmail", user_id) │
│ ├─ AwaitingAuthorization │
│ │ └─ 返回 NeedsAuth (需要 OAuth 授权) │
│ ├─ AwaitingToken │
│ │ └─ 返回 NeedsAuth (需要提交 token) │
│ ├─ NeedsSetup │
│ │ └─ 返回 NeedsSetup (需要手动设置) │
│ └─ Authenticated / NoAuthRequired │
│ └─ 继续激活流程 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 3. 检查是否已激活 │
│ is_extension_active("gmail", kind) │
│ ├─ 已激活 │
│ │ └─ 返回 Ready (已就绪) │
│ └─ 未激活 │
│ └─ 继续激活 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 4. 激活扩展 │
│ activate("gmail", user_id) │
│ ├─ 成功 │
│ │ └─ 返回 Ready + ActivationResult │
│ └─ 失败 (AuthRequired) │
│ └─ 重新检查认证状态 │
│ └─ 返回 NeedsAuth 或 NeedsSetup │
└─────────────────────────────────────────────────────────────┘
↓
返回 EnsureReadyOutcome
├─ Ready: 激活成功
├─ NeedsAuth: 需要 OAuth 授权
├─ NeedsSetup: 需要手动设置
└─ NotInstalled: 未安装
配置 gmail 认证信息
通过环境变量配置 gmail 工具认证信息，可以在 IronClaw 配置文件追加下面两行：
## 替换为实际的
GOOGLE_OAUTH_CLIENT_ID="xxxx-yyyy.apps.googleusercontent.com"
GOOGLE_OAUTH_CLIENT_SECRET="XXXX-YYYY-CC_asdfa1"
一个技巧
我的 IronClaw 运行在本地一台迷你主机上，平时通过 ssh 登录操作，OAuth 认证需要在 MacBook Pro 的浏览器上完成。由于谷歌对重定向 URI 的限制，不配置公网端点的情况下，IronClaw 生成的重定向 URI 是 http://localhost:3000/oauth/callback 这样的，所以需要在 MacBook Pro 上将对 localhost 的访问重定向到迷你主机上（见下图）。
在 MacBook Pro 执行下面的命令建立 SSH 隧道，将对 localhost:3000 的访问转发到迷你主机 3000 端口：
## 假设迷你主机地址为 192.168.1.100
ssh -L 3000:192.168.1.100:3000 -N [email protected]
重启 IronClaw
IronClaw 服务启动后，在交互页面输入 tool_activate gmail 来完成 OAuth 授权。
提前在浏览器所在的电脑配置好 SSH 隧道，然后粘贴生成的 URI，按提示一步步完成 OAuth 授权。认证成功后，浏览器会有下面的提示：
注意：IronClaw 生成的 OAuth 授权请求必须在一定的时间内完成，默认 60 秒，超时则认证失败，需要重新发起请求。
写在最后
最近尝试给 IronClaw 增加了一个功能：Gmail 邮箱收到技术订阅邮件后实时通知 IronClaw，IronClaw 自动获取邮件内容，总结分析后把结果保存下来，供我有空时翻看。这样不至于错过有价值的邮件。
代码已经完成了，踩了不少坑，烧了一些 token，不过在接入免费 LLM 后，效果不是很好，待我打磨一下再发出来。