OpenClaw审计日志与操作记录

前言

随着 OpenClaw 服务的用户增多和团队协作加深，你需要清楚地知道：谁在什么时间通过什么频道进行了什么操作？配置被谁修改了？敏感指令是谁执行的？审计日志（Audit Log）就是解答这些问题的关键工具。本文将全面讲解 OpenClaw 的审计日志配置和使用方法。

一、什么是审计日志

审计日志与运行日志不同。运行日志记录的是系统的技术状态（错误、性能、连接），而审计日志记录的是用户和管理员的操作行为，回答的核心问题是**"谁 (Who) 在什么时候 (When) 做了什么 (What)"**。

1.1 审计日志记录的事件类型

二、启用审计日志

2.1 基本配置

// ~/.config/openclaw/openclaw.json5
{
  "audit": {
    "enabled": true,
    // 审计日志存储路径
    "logDir": "~/.openclaw/audit/",
    // 日志格式
    "format": "json",
    // 记录级别：minimal / standard / verbose
    "level": "standard",
    // 保留天数
    "retention": 90
  }
}

2.2 记录级别说明

2.3 选择性记录

可以精细控制哪些事件需要记录：

{
  "audit": {
    "enabled": true,
    "events": {
      // 消息操作
      "message.received": true,
      "message.sent": true,
      "message.failed": true,
      // 配置变更
      "config.changed": true,
      "config.apiKeyRotated": true,
      // 管理操作
      "service.started": true,
      "service.stopped": true,
      "service.restarted": true,
      // 安全事件
      "auth.login": true,
      "auth.failed": true,
      "user.banned": true,
      "user.unbanned": true,
      // 频道操作
      "channel.connected": true,
      "channel.disconnected": true,
      "channel.added": true,
      "channel.removed": true,
      // 技能操作
      "skill.installed": true,
      "skill.executed": true
    }
  }
}

三、审计日志格式

3.1 JSON 日志结构

每条审计记录包含以下标准字段：

{
  "id": "audit_20260314_001",
  "timestamp": "2026-03-14T09:15:32.456Z",
  "event": "message.received",
  "actor": {
    "type": "user",
    "id": "telegram:123456789",
    "name": "张三"
  },
  "target": {
    "type": "channel",
    "id": "telegram",
    "name": "Telegram Bot"
  },
  "action": "send_message",
  "details": {
    "messageId": "msg_abc123",
    "messageType": "text",
    "length": 42
  },
  "result": "success",
  "ip": null,
  "userAgent": null
}

3.2 配置变更审计记录

{
  "id": "audit_20260314_002",
  "timestamp": "2026-03-14T10:30:00.000Z",
  "event": "config.changed",
  "actor": {
    "type": "admin",
    "id": "dashboard:admin",
    "ip": "192.168.1.100"
  },
  "action": "update_config",
  "details": {
    "path": "model.model",
    "oldValue": "claude-3-5-haiku",
    "newValue": "claude-3.5-sonnet",
    "method": "dashboard"
  },
  "result": "success"
}

3.3 安全事件审计记录

{
  "id": "audit_20260314_003",
  "timestamp": "2026-03-14T11:00:00.000Z",
  "event": "auth.failed",
  "actor": {
    "type": "unknown",
    "ip": "203.0.113.50"
  },
  "action": "dashboard_login",
  "details": {
    "reason": "invalid_password",
    "attemptCount": 3
  },
  "result": "failure"
}

四、查询审计日志

4.1 使用 openclaw audit 命令

# 查看最近的审计日志
openclaw audit log

# 按事件类型筛选
openclaw audit log --event config.changed
openclaw audit log --event auth.failed

# 按时间范围筛选
openclaw audit log --since "2026-03-14 09:00" --until "2026-03-14 18:00"

# 按操作者筛选
openclaw audit log --actor "telegram:123456789"
openclaw audit log --actor "dashboard:admin"

# 按结果筛选
openclaw audit log --result failure

# 组合筛选
openclaw audit log --event config.changed --since 7d --format table

4.2 表格格式输出

openclaw audit log --since today --format table

┌──────────────────────┬──────────────────┬──────────────────┬─────────┐
│ 时间                  │ 事件             │ 操作者            │ 结果    │
├──────────────────────┼──────────────────┼──────────────────┼─────────┤
│ 2026-03-14 09:15:32  │ message.received │ telegram:123456  │ success │
│ 2026-03-14 09:15:34  │ message.sent     │ system           │ success │
│ 2026-03-14 10:30:00  │ config.changed   │ dashboard:admin  │ success │
│ 2026-03-14 11:00:00  │ auth.failed      │ 203.0.113.50     │ failure │
│ 2026-03-14 14:20:15  │ skill.installed  │ dashboard:admin  │ success │
└──────────────────────┴──────────────────┴──────────────────┴─────────┘

4.3 统计分析

# 今日操作统计
openclaw audit stats --since today

# 输出
# 今日审计统计 (2026-03-14)
# ─────────────────────────
# 消息收发:      342 次
# 配置变更:      2 次
# 登录成功:      3 次
# 登录失败:      1 次
# 技能执行:      85 次
# 活跃用户数:    28
# 最活跃用户:    telegram:123456 (52条消息)

# 按用户统计消息量
openclaw audit stats --group-by actor --since 7d

# 按小时统计消息分布
openclaw audit stats --group-by hour --since today

五、Dashboard 审计查看

5.1 审计日志面板

OpenClaw Web Dashboard 提供可视化的审计日志查看界面：

1. 打开 Dashboard（http://localhost:18789/dashboard）
2. 进入"审计日志"页面
3. 使用过滤器按时间、事件类型、操作者筛选
4. 支持导出为 CSV/JSON 格式

5.2 实时事件流

Dashboard 中可以实时查看事件流：

● [09:15:32] 张三 通过 Telegram 发送消息
● [09:15:34] AI 回复 张三 (1.7s, 285 tokens)
● [10:30:00] 管理员 修改模型配置: haiku → sonnet
● [11:00:00] ⚠ 登录失败 来自 203.0.113.50 (第3次)

六、审计日志存储与归档

6.1 日志轮转

{
  "audit": {
    "rotation": {
      "maxSize": "100MB",
      "maxAge": 90,       // 保留90天
      "compress": true,   // 压缩归档
      "archiveDir": "~/.openclaw/audit/archive/"
    }
  }
}

6.2 导出到外部系统

将审计日志发送到集中式日志管理平台：

{
  "audit": {
    "export": {
      // 发送到 Syslog
      "syslog": {
        "enabled": true,
        "host": "syslog.example.com",
        "port": 514,
        "facility": "auth"
      },
      // 发送到 Webhook（可对接 SIEM 系统）
      "webhook": {
        "enabled": true,
        "url": "https://siem.example.com/api/audit",
        "headers": {
          "Authorization": "Bearer YOUR_TOKEN"
        },
        "batchSize": 100,
        "flushInterval": "30s"
      }
    }
  }
}

6.3 定期归档

# 手动归档旧审计日志
openclaw audit archive --older-than 30d

# 导出指定时间范围的审计记录
openclaw audit export --since "2026-01-01" --until "2026-01-31" --output january-audit.json

七、安全与合规建议

1. 审计日志不可篡改：将审计日志发送到独立的存储系统，防止被篡改或删除
2. 保留期限：根据行业合规要求设置保留期限（金融行业通常要求至少保留 1 年）
3. 敏感信息脱敏：审计日志中不应包含完整的 API Key 或用户消息内容原文
4. 访问控制：限制审计日志的查看权限，只有管理员可以访问
5. 定期审查：每月审查安全相关事件（登录失败、配置变更、异常操作模式）
6. 告警联动：对异常审计事件（如多次登录失败）配置自动告警

{
  "audit": {
    // 隐私保护：对敏感字段脱敏
    "privacy": {
      "maskUserMessages": true,   // 不记录消息原文
      "maskApiKeys": true,        // API Key 只显示前后几位
      "maskPhoneNumbers": true    // 手机号中间部分用 * 替代
    }
  }
}

审计日志是运维监控体系中不可或缺的一环。它不仅帮助你追踪问题根源、回溯操作历史，更是满足安全合规要求的基础设施。建议从 standard 级别开始，根据实际需求逐步调整记录范围。