认证监控 - API Key 与 Token 过期追踪

在长期运行的自动化系统中，API Key 过期和 OAuth Token（OAuth 令牌）失效是导致任务中断的常见原因。OpenClaw 提供内置的 Credential Monitoring（认证监控）功能，自动追踪所有凭据的有效期并在过期前发出告警。

核心功能

• 自动追踪：监控所有已配置的 API Key 和 OAuth Token 的到期时间
• 提前告警：在凭据过期前指定天数发送提醒通知
• 自动刷新：支持 OAuth 2.0 Refresh Token（刷新令牌）自动续期
• 集中管理：在统一的仪表板查看所有凭据状态

配置

在 openclaw.json 中配置认证监控：

{
  "authMonitor": {
    "enabled": true,
    "checkInterval": 3600000,
    "alertBefore": {
      "days": 7,
      "channels": ["announce", "webhook"]
    },
    "autoRefresh": {
      "enabled": true,
      "oauthProviders": ["google", "microsoft"]
    },
    "credentials": {
      "openai": {
        "type": "api-key",
        "envVar": "OPENAI_API_KEY",
        "expiresAt": "2026-12-31T23:59:59Z"
      },
      "google-oauth": {
        "type": "oauth2",
        "credentialsFile": "~/.openclaw/gmail/credentials.json",
        "tokenFile": "~/.openclaw/gmail/token.json",
        "autoRefresh": true
      },
      "wecom-bot": {
        "type": "webhook-token",
        "envVar": "WECOM_BOT_KEY",
        "rotateEvery": "90d"
      }
    }
  }
}

配置字段说明

字段	类型	说明
enabled	boolean	启用认证监控
checkInterval	number	检查间隔（毫秒），默认 1 小时
alertBefore.days	number	提前多少天告警
alertBefore.channels	string[]	告警通知渠道
autoRefresh.enabled	boolean	是否自动刷新 OAuth Token

凭据类型 (Credential Types)

API Key

固定有效期的密钥，过期后需手动更换。

{
  "type": "api-key",
  "envVar": "OPENAI_API_KEY",
  "expiresAt": "2026-12-31T23:59:59Z",
  "provider": "openai"
}

OAuth 2.0 Token

支持通过 Refresh Token 自动续期。

{
  "type": "oauth2",
  "credentialsFile": "~/.openclaw/gmail/credentials.json",
  "tokenFile": "~/.openclaw/gmail/token.json",
  "autoRefresh": true,
  "scopes": [
    "https://www.googleapis.com/auth/gmail.readonly"
  ]
}

Webhook Token

自定义 Webhook 使用的 Token，支持定期轮换提醒。

{
  "type": "webhook-token",
  "envVar": "WEBHOOK_SECRET",
  "rotateEvery": "90d",
  "lastRotated": "2026-01-15T00:00:00Z"
}

自定义凭据

对于不属于以上类型的凭据，可使用自定义类型：

{
  "type": "custom",
  "name": "企业微信 API Secret",
  "envVar": "WECOM_SECRET",
  "checkEndpoint": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
  "healthCheck": true
}

告警通知

告警级别

级别	条件	动作
info	凭据将在 7 天内过期	发送提醒通知
warning	凭据将在 3 天内过期	加急通知 + 自动刷新尝试
critical	凭据将在 24 小时内过期	紧急通知到所有渠道
expired	凭据已过期	告警 + 禁用关联任务

告警渠道配置

{
  "alertBefore": {
    "days": 7,
    "channels": ["announce", "webhook"],
    "webhook": {
      "url": "https://hooks.example.com/alert",
      "headers": {
        "Authorization": "Bearer ${ALERT_TOKEN}"
      }
    },
    "escalation": {
      "critical": {
        "channels": ["announce", "webhook", "email"],
        "email": "admin@example.com"
      }
    }
  }
}

告警消息示例

⚠️ 凭据过期告警
━━━━━━━━━━━━━━━━━━
凭据名称: openai
类型: API Key
过期时间: 2026-12-31 23:59:59 (剩余 7 天)
关联任务: morning-report, data-sync
━━━━━━━━━━━━━━━━━━
建议: 请及时更换 API Key

OAuth Token 自动刷新

对于支持 Refresh Token 的 OAuth 2.0 Provider（OAuth 2.0 服务商），OpenClaw 可自动完成续期：

Token 即将过期
    │
    ▼
检查 Refresh Token 是否有效
    │
    ├── 有效 → 自动请求新 Access Token → 更新本地存储 → 通知成功
    │
    └── 无效 → 发送告警 → 需要用户手动重新授权

Refresh Token 也会过期

某些 Provider 的 Refresh Token 也有有效期限制（如 Google 的不活跃 Refresh Token 6 个月后失效）。请定期检查授权状态。

CLI 命令

# 查看所有凭据状态
openclaw auth status

# 输出示例：
# NAME           TYPE        EXPIRES         STATUS     AUTO-REFRESH
# openai         api-key     2026-12-31      ✅ valid   no
# google-oauth   oauth2      2026-03-12      ⚠️ 7 days  yes
# wecom-bot      webhook     rotate due      🔄 due     no

# 手动刷新特定凭据
openclaw auth refresh google-oauth

# 测试凭据有效性
openclaw auth test openai

# 查看凭据详情
openclaw auth info google-oauth

# 手动标记过期时间
openclaw auth set-expiry openai --date "2027-06-30"

与自动化任务的集成

认证监控与 Cron、Hooks 等自动化系统深度集成：

• Cron 任务：凭据过期时自动暂停关联的定时任务，刷新后恢复
• Hooks：通过 auth:expiring 和 auth:expired 事件触发自定义 Hook
• Webhooks：凭据告警可通过 Webhook 推送到外部监控系统

{
  "hooks": {
    "entries": {
      "auth-alert-handler": {
        "events": ["auth:expiring", "auth:expired"],
        "enabled": true
      }
    }
  }
}

🇨🇳 中国用户须知

• 国产大模型（如通义千问、文心一言、智谱 GLM）的 API Key 有效期各不相同，建议统一在 OpenClaw 中管理
• 企业微信和钉钉的 Access Token 有效期通常为 2 小时，务必启用 autoRefresh
• 部分国内平台不支持标准 OAuth 2.0 流程，需要使用 custom 类型并配合 healthCheck 验证