OAuth 认证

概述

OpenClaw 使用 OAuth 机制管理第三方服务的授权，让 Agent 可以安全地访问用户授权的外部服务（如 Google、GitHub、Slack 等），而无需直接存储用户的账号密码。

为什么需要 OAuth？

当 Agent 需要代你操作第三方服务时（如读取 Gmail、管理 GitHub Issue），直接使用账号密码既不安全也不灵活。OAuth 解决了这个问题：

• 安全：用户只授予有限权限，不暴露密码
• 可撤销：随时可以在第三方平台取消授权
• 细粒度：可以只授权读取邮件，而不授权删除邮件

工作流程

用户请求："帮我检查 Gmail 新邮件"
        │
        ▼
Agent 发现需要 Gmail 权限
        │
        ▼
OpenClaw 生成授权链接，发给用户
        │
        ▼
用户点击链接 → Google 登录页 → 确认授权
        │
        ▼
Google 回调 → OpenClaw 获取 Access Token
        │
        ▼
Agent 使用 Token 调用 Gmail API
        │
        ▼
返回邮件列表给用户

支持的 OAuth 服务

OpenClaw 通过 Skills 集成了多种 OAuth 服务：

服务	对应技能	授权范围
Google Workspace	gog	Gmail、Calendar、Drive、Docs
GitHub	github	仓库、Issue、PR、Actions
Slack	slack-poster	消息发送、频道管理
Notion	notion	页面读写、数据库操作
Todoist	todoist	任务管理

配置 OAuth 凭据

大多数 OAuth 集成通过 Skills 的环境变量配置。以 Google 为例：

1. 创建 OAuth 应用

在 Google Cloud Console 中：

1. 创建项目或选择已有项目
2. 启用所需的 API（Gmail API、Calendar API 等）
3. 配置 OAuth 同意屏幕
4. 创建 OAuth 2.0 客户端凭据
5. 设置重定向 URI 为 http://localhost:18789/oauth/callback

2. 配置环境变量

openclaw config set env.GOOGLE_CLIENT_ID "your-client-id"
openclaw config set env.GOOGLE_CLIENT_SECRET "your-client-secret"

或在 openclaw.json 中：

{
  "env": {
    "GOOGLE_CLIENT_ID": "your-client-id",
    "GOOGLE_CLIENT_SECRET": "your-client-secret"
  }
}

3. 安装对应技能

clawhub install gog

首次使用时，Agent 会自动引导你完成授权流程。

Token 管理

OpenClaw 自动管理 OAuth Token 的生命周期：

• Access Token：短期有效（通常 1 小时），用于 API 调用
• Refresh Token：长期有效，用于自动刷新 Access Token
• Token 存储：加密存储在 ~/.openclaw/ 目录下

Token 安全

Token 文件仅本机可读，不会通过频道消息传输。如果担心安全，可以：

1. 定期撤销并重新授权
2. 使用最小权限原则，只授权必要的 API 范围
3. 在第三方平台的安全设置中监控 Token 使用情况

自托管场景

如果 OpenClaw 部署在远程服务器上，OAuth 回调地址需要调整：

{
  "gateway": {
    "externalUrl": "https://your-server.example.com"
  }
}

确保服务器的 /oauth/callback 路径可以从外部访问（通过反向代理或 Tailscale）。

常见问题

授权过期怎么办？

OpenClaw 会自动使用 Refresh Token 续期。如果 Refresh Token 也过期（如 Google 的 6 个月未使用），Agent 会提示你重新授权。

如何撤销授权？

1. 在第三方平台的安全设置中撤销（如 Google 安全设置 → 第三方应用）
2. 删除本地 Token：openclaw config unset oauth.<service>