🔐 OpenClaw SQLite Auth 持久化认证

什么是 SQLite Auth？

SQLite Auth 是 OpenClaw 在 2026.6.x 版本中引入的认证凭据持久化机制。在此之前，Agent 的 OAuth token、API key 等认证信息存储在内存中，Gateway 重启后需要重新授权。

SQLite Auth 把这些凭据安全地存储在本地 SQLite 数据库中，实现了：

• 重启不丢失：Gateway 重启后自动恢复认证状态
• 多 Agent 隔离：每个 Agent 的凭据独立存储
• 加密存储：AES-256 加密，密钥由主密码派生
• 自动过期清理：过期的 token 自动清除

架构设计

# SQLite Auth 存储架构
~/.openclaw/auth/
├── credentials.db      # 主数据库（加密）
├── credentials.db.key  # 加密密钥（权限 600）
└── migrations/         # 数据库迁移脚本

# 数据库表结构
┌─────────────────────────────────┐
│ credentials                      │
├─────────────────────────────────┤
│ id (PK)                         │
│ agent_id (FK)                   │
│ provider (feishu/discord/...)   │
│ credential_type (oauth/apikey)  │
│ credential_data (encrypted)     │
│ expires_at                      │
│ created_at                      │
│ updated_at                      │
└─────────────────────────────────┘

配置方法

基本配置

# openclaw.json
{
  "auth": {
    "persistence": {
      "enabled": true,
      "backend": "sqlite",
      "path": "~/.openclaw/auth/credentials.db",
      "encryption": {
        "enabled": true,
        "algorithm": "aes-256-gcm"
      }
    }
  }
}

高级配置

{
  "auth": {
    "persistence": {
      "enabled": true,
      "backend": "sqlite",
      "path": "~/.openclaw/auth/credentials.db",
      "encryption": {
        "enabled": true,
        "algorithm": "aes-256-gcm",
        "keyDerivation": "argon2id",
        "keyRotationDays": 90
      },
      "cleanup": {
        "enabled": true,
        "expiredAfterDays": 7,
        "intervalHours": 24
      },
      "backup": {
        "enabled": true,
        "intervalHours": 12,
        "maxBackups": 5
      }
    }
  }
}

支持的认证类型

OAuth 2.0 Token

# 飞书 OAuth 示例
{
  "provider": "feishu",
  "credential_type": "oauth",
  "credential_data": {
    "access_token": "u-xxxxx",
    "refresh_token": "ur-xxxxx",
    "token_type": "Bearer",
    "expires_in": 7200,
    "scope": "bitable:app contact:user.id:readonly"
  }
}

API Key

# Discord Bot Token 示例
{
  "provider": "discord",
  "credential_type": "apikey",
  "credential_data": {
    "bot_token": "MTxxxxxxxxxxxxxxx"
  }
}

Bearer Token

# 第三方 API Token 示例
{
  "provider": "brave-search",
  "credential_type": "bearer",
  "credential_data": {
    "api_key": "BSAxxxxxxxxxxxxxxxx"
  }
}

使用场景

场景一：飞书 Agent 重启恢复

# 重启前：Agent 通过 OAuth 获取了飞书 token
# 重启后：自动从 SQLite 恢复，无需用户重新授权

# 日志输出
[auth] Loading persisted credentials for agent miaoquai...
[auth] Found 3 credential(s) in SQLite store
[auth] feishu OAuth token: valid (expires in 1h23m)
[auth] discord Bot token: valid (no expiry)
[auth] All credentials loaded successfully

场景二：多 Agent 环境

# 每个 Agent 独立的凭据空间
[auth] Agent miaoquai: 3 credentials loaded
[auth] Agent research-bot: 2 credentials loaded
[auth] Agent support-bot: 1 credential loaded
# 各 Agent 互不干扰

场景三：Token 自动刷新

# OAuth token 过期前自动刷新
[auth] feishu OAuth token expiring in 5m, refreshing...
[auth] Token refreshed successfully
[auth] New token valid for 2h
[auth] SQLite store updated

安全最佳实践

运维操作

查看存储的凭据

# 列出所有存储的凭据（不显示敏感数据）
openclaw auth list

# 输出示例
┌──────────┬──────────┬─────────────┬──────────────┐
│ Agent    │ Provider │ Type        │ Expires      │
├──────────┼──────────┼─────────────┼──────────────┤
│ miaoquai │ feishu   │ OAuth       │ 2h 15m       │
│ miaoquai │ discord  │ Bot Token   │ Never        │
│ miaoquai │ brave    │ API Key     │ Never        │
└──────────┴──────────┴─────────────┴──────────────┘

清除过期凭据

# 手动清理过期凭据
openclaw auth cleanup

# 强制清除特定 Agent 的所有凭据
openclaw auth clear --agent miaoquai --provider feishu

数据库迁移

# 升级后执行迁移
openclaw auth migrate

# 查看迁移状态
openclaw auth migrate --status

故障排查

常见问题

# 问题：启动时报 "Failed to decrypt credentials"
# 原因：密钥文件丢失或损坏
# 解决：
openclaw auth reset-key  # 重新生成密钥（会清除所有凭据）
# 然后重新授权各平台

# 问题：Token 刷新失败
# 原因：Refresh token 也过期了
# 解决：
openclaw auth reauth --provider feishu  # 重新授权