OpenClaw OAuth Token 管理：自动续期和多账户切换

2026-04-17 · 10 分钟安全运维

OAuth vs API Key

API Key

静态凭证
永不过期
泄漏风险高
配置简单

OAuth

动态 Token
定期过期（1 小时-数天）
泄漏时间限于过期前
需要续期管理

OAuth 更安全但需要更多管理。

支持 OAuth 的 Provider

主流 Provider 的 OAuth 支持：

Provider	OAuth	默认有效期
Anthropic	✓	1 小时
Google	✓	1 小时
Microsoft	✓	1 小时
GitHub	✓	8 小时
Notion	✓	永久（需 refresh）
Slack	✓	12 小时

初次认证

Anthropic OAuth

openclaw auth login --provider anthropic

OpenClaw 会：

打开浏览器
引导你在 Anthropic 登录
请求必要的 scope
保存 token 和 refresh token

Google OAuth

openclaw auth login --provider google

需要的 scope：

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/generative-language

GitHub OAuth

openclaw auth login --provider github

用于 GitHub Skills（代码审查、PR 管理等）。

自动续期

启用

providers:
  anthropic:
    oauth:
      autoRefresh: true
      refreshBeforeExpiry: "5m"  # 过期前 5 分钟续期

工作原理：

每次请求前检查 token 有效期
快过期时自动用 refresh_token 获取新 token
用户无感，不中断服务

续期失败处理

providers:
  anthropic:
    oauth:
      autoRefresh: true
      onRefreshFail:
        action: "notify"  # 通知
        fallback: "backup-account"  # 切换到备用
        channel: "feishu:ops"

多账户管理

配置多账户

providers:
  anthropic:
    accounts:
      - name: "primary"
        default: true
      - name: "backup"
      - name: "team-shared"

每个账户需要独立 OAuth 认证：

openclaw auth login --provider anthropic --account primary
openclaw auth login --provider anthropic --account backup
openclaw auth login --provider anthropic --account team-shared

账户切换

providers:
  anthropic:
    failover:
      enabled: true
      triggers:
        - "rate_limit"
        - "auth_failed"
        - "quota_exceeded"
      order: ["primary", "backup", "team-shared"]

主账户遇到问题时自动切换。

手动切换

openclaw auth switch --provider anthropic --account backup

过期监控

Model Auth Status

参考 Model Auth Status 监控教程：

openclaw auth status

查看所有 Provider 的 OAuth 状态。

告警配置

monitoring:
  oauthAlerts:
    channels:
      - type: "feishu"
        webhook: "$FEISHU_WEBHOOK"
    thresholds:
      # 过期预警
      - daysBeforeExpiry: 7
        level: "info"
      - daysBeforeExpiry: 3
        level: "warning"
      - daysBeforeExpiry: 1
        level: "critical"
      # 续期失败
      - refreshFailures: 3
        level: "critical"

团队共享 Token

问题场景

团队多人使用同一 Provider：

每人单独 OAuth 繁琐
费用归属不清
离职后凭证管理复杂

方案 1：服务账户

providers:
  google:
    accountType: "service-account"
    credentials: "/etc/openclaw/gcp-sa.json"

服务账户：

不需要 OAuth
永久有效（可撤销）
权限集中管理

方案 2：共享 OAuth

通过 Vault 或 Secrets Manager 共享 refresh token：

providers:
  anthropic:
    oauth:
      refreshToken: "vault://shared/anthropic-refresh"

一人认证，团队共用。

OAuth Scope 管理

最小权限原则

只请求需要的 scope：

providers:
  google:
    oauth:
      scopes:
        - "https://www.googleapis.com/auth/generative-language"
        # 不要加 drive.full 等不需要的

Scope 审计

openclaw auth scopes --provider google

查看当前 Token 的实际权限。

Scope 变更

如果需要新增权限：

# 重新认证获得新 scope
openclaw auth login --provider google --scopes "new-scope"

安全加固

1. Refresh Token 保护

Refresh Token 比 Access Token 更敏感：

oauth:
  refreshToken:
    storage: "vault"  # 存在 Vault 而非磁盘
    encryption: "aes-256"
    accessAudit: true

2. 设备绑定

oauth:
  deviceBinding:
    enabled: true
    # Token 绑定到设备指纹
    # 其他设备无法使用

3. IP 限制

oauth:
  ipRestriction:
    allowedIps:
      - "10.0.0.0/8"      # 内网
      - "203.0.113.0/24"  # 办公网

4. 审计日志

oauth:
  audit:
    enabled: true
    logFile: "/var/log/openclaw-oauth.log"
    events:
      - "login"
      - "refresh"
      - "failure"
      - "revoke"

撤销和清理

主动撤销

# 撤销单个 Provider
openclaw auth revoke --provider anthropic

# 撤销所有
openclaw auth revoke --all

离职清理

员工离职时：

# 列出该员工的所有凭证
openclaw auth list --owner john@example.com

# 批量撤销
openclaw auth revoke --owner john@example.com --all

定期清理

monitoring:
  oauthCleanup:
    unusedThreshold: "30d"
    autoRevoke: true

30 天未使用的 Token 自动撤销。

故障排查

无法打开浏览器（服务器环境）

# 服务器使用 device flow
openclaw auth login --provider anthropic --device-flow

会显示：

请访问 https://anthropic.com/device
输入代码：ABCD-EFGH

回调 URL 问题

oauth:
  callbackUrl: "http://localhost:18790/oauth/callback"

如果不是默认端口或有代理，需要调整。

Refresh Token 过期

Refresh Token 也可能过期（通常更长）：

# 重新完整认证
openclaw auth login --provider anthropic --force

多账户冲突

# 清理缓存
openclaw auth reset --provider anthropic

然后重新认证所有账户。

最佳实践

1. 分层认证

个人开发：OAuth + Keychain
团队协作：服务账户
生产部署：Vault + 自动续期

2. 监控先行

配置告警（过期、失败）
定期查看 Auth Status
审计日志保留

3. 备份账户

主账户失败时有备份
备份账户独立限流
定期测试 failover

4. 最小权限

只请求必要 scope
定期审查实际使用
及时撤销不用的 Token

5. 自动化

启用自动续期
设置自动清理
加入监控告警

注意事项

OAuth 比 API Key 更安全但更复杂
Refresh Token 是核心凭证，最高优先级保护
服务器环境使用 device flow 避免浏览器问题
多账户 failover 注意费用归属
企业部署强烈推荐服务账户 + Vault
定期审计 scope 和访问日志
离职人员凭证及时清理
Token 过期不是 bug，是安全特性，拥抱它