OAuth 认证

OAuth（开放授权）是 OpenClaw 支持的一种认证方式，允许 Agent 通过第三方授权服务获取模型 API 访问权限，而无需直接管理 API Key。

OAuth 流程

OpenClaw 实现标准的 OAuth 2.0 Authorization Code（授权码）流程：

┌────────┐     1. 授权请求     ┌──────────────┐
│  用户  │──────────────────▶│  OAuth 提供商  │
│        │                    │  (Google 等)  │
│        │◀──────────────────│               │
│        │  2. 授权码(Code)   └──────────────┘
└───┬────┘
    │  3. 提交授权码
    ▼
┌────────┐     4. 换取 Token   ┌──────────────┐
│OpenClaw│──────────────────▶│  OAuth 提供商  │
│Gateway │                    │               │
│        │◀──────────────────│               │
│        │  5. Access Token   └──────────────┘
└────────┘     + Refresh Token

步骤详解

1. 授权请求 — OpenClaw 生成授权 URL，引导用户到 OAuth 提供商的登录页面
2. 用户授权 — 用户在提供商页面登录并授权 OpenClaw 访问
3. 授权码回调 — 提供商将授权码（Authorization Code）发送到 OpenClaw 的回调 URL
4. Token 交换 — OpenClaw 用授权码换取 Access Token 和 Refresh Token
5. API 访问 — 使用 Access Token 调用模型 API

Token 刷新

Access Token 有有效期（通常 1 小时）。OpenClaw 自动处理 Token 刷新：

API 调用
    │
    ▼
Token 是否过期？
    │
  ┌─┴──┐
  │    │
  否   是
  │    │
  ▼    ▼
直接使用  使用 Refresh Token
  │      获取新 Access Token
  │         │
  ▼         ▼
     API 请求发送

# Token 刷新配置
oauth:
  tokenRefresh:
    beforeExpiry: 300      # 提前 5 分钟刷新（秒）
    retryOnFailure: true   # 刷新失败后重试
    maxRetries: 3

Refresh Token 过期

Refresh Token 也有有效期（通常 14-90 天）。过期后需要用户重新授权。OpenClaw 会在 Refresh Token 即将过期时提醒用户。

支持的 OAuth 提供商

提供商	用途	授权范围
Google	Gemini / Vertex AI	generativelanguage
Microsoft	Azure OpenAI	cognitive-services
GitHub	Copilot API	copilot

配置

Google OAuth

providers:
  google:
    auth: oauth
    oauth:
      clientId: "your-client-id.apps.googleusercontent.com"
      clientSecret: "your-client-secret"
      scopes:
        - "https://www.googleapis.com/auth/generative-language"
      redirectUri: "http://localhost:18789/oauth/callback"

Azure OAuth

providers:
  azure:
    auth: oauth
    oauth:
      clientId: "your-azure-app-id"
      clientSecret: "your-azure-secret"
      tenantId: "your-tenant-id"
      scopes:
        - "https://cognitiveservices.azure.com/.default"
      redirectUri: "http://localhost:18789/oauth/callback"

启动 OAuth 流程

通过 CLI 启动 OAuth 授权：

# 为 Google Provider 启动 OAuth
openclaw auth login google

# 为 Azure Provider 启动 OAuth
openclaw auth login azure

浏览器自动打开

执行 auth login 命令后，OpenClaw 会自动打开浏览器进入授权页面。在无头服务器（Headless）环境中，会打印授权 URL 供手动访问。

Token 存储

OAuth Token 安全存储在本地：

~/.openclaw/auth/
├── google.json          # Google OAuth Token
├── azure.json           # Azure OAuth Token
└── ...

{
  "accessToken": "ya29.a0...",
  "refreshToken": "1//0e...",
  "expiresAt": "2025-01-15T11:30:00Z",
  "scope": "https://www.googleapis.com/auth/generative-language"
}

安全警告

Token 文件包含敏感信息。确保 ~/.openclaw/auth/ 目录权限设置为仅当前用户可读：

chmod 700 ~/.openclaw/auth/
chmod 600 ~/.openclaw/auth/*.json

管理 OAuth 连接

# 查看已授权的 Provider
openclaw auth list

# 登出（撤销 Token）
openclaw auth logout google

# 刷新 Token
openclaw auth refresh google

# 检查 Token 状态
openclaw auth status

OAuth vs API Key

特性	OAuth	API Key
安全性	更高（Token 有时效）	较低（长期有效）
复杂度	较高（需要授权流程）	低（直接配置）
适用场景	企业部署、多用户	个人使用、开发测试
Token 管理	自动刷新	手动轮换

选择建议

个人使用推荐 API Key 方式（更简单）。企业或多用户场景推荐 OAuth（更安全、更易于管理）。

下一步

• 了解 模型提供商 配置多种服务
• 查看 模型管理 了解模型选择
• 探索 网关架构 了解认证在系统中的位置