Sentry — OpenClaw 可观测性

查看您的 OpenClaw 实例正在发生什么：错误、结构化日志和性能追踪信息，全部集中于 Sentry。

整个流程分为两部分：设置（让遥测数据流动起来）和 调查（使用 CLI 查询数据）。

设置

1. 认证

sentry auth login

使用 OAuth 设备流 —— 按照浏览器提示操作。凭据将存储在 ~/.sentry/cli.db 中。

替代方式（一行命令）：

• sentry auth login --token <TOKEN> —— 直接粘贴认证令牌
• SENTRY_AUTH_TOKEN=<token> —— 环境变量，适用于 CI 场景

2. 创建项目

为您的 OpenClaw 实例创建一个专用的 Sentry 项目：

sentry api /teams/<org>/<team>/projects/ \
  --method POST \
  --field name="my-openclaw" \
  --field platform=node

不知道组织或团队的别名？可以先列出：

sentry api /organizations/                          # 列出所有组织
sentry api /organizations/<org>/teams/              # 列出指定组织下的所有团队

3. 获取 DSN

sentry project view <org>/my-openclaw --json | jq -r '.dsn'

或通过 keys 接口获取：

sentry api /projects/<org>/my-openclaw/keys/ | jq '.[0].dsn.public'

4. 配置 OpenClaw

将 DSN 添加到您的 openclaw.json 文件中：

{
  "plugins": {
    "entries": {
      "sentry": {
        "enabled": true,
        "config": {
          "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0",
          "enableLogs": true
        }
      }
    }
  }
}

注意： 配置项应放在 plugins.entries.sentry.config 下，而非直接放在 sentry 下。

然后安装 Sentry 插件。完整插件实现请参考 references/plugin-setup.md，使用 @sentry/node。

日志缓冲区注意事项： Sentry 的结构化日志会缓存最多 100 条记录，之后自动刷新。对于低频服务如 OpenClaw，日志可能长时间滞留在缓冲区中。插件应定期调用 _INTERNAL_flushLogsBuffer(client)（例如每 30 秒一次），并在关闭时调用 Sentry.flush() 前执行该操作。具体实现请参见 references/plugin-setup.md。

5. 验证

重启您的 OpenClaw 网关后，检查 Sentry 是否收到事件：

sentry issue list <org>/my-openclaw --limit 5

调查

当遥测数据开始流入后，可使用 CLI 查询 OpenClaw 的错误、追踪和事件。

列出问题

sentry issue list <org>/<project>
sentry issue list <org>/<project> --query "is:unresolved" --sort freq --limit 20
sentry issue list <org>/                              # 查看组织下所有项目

查看问题详情

sentry issue view <short-id>                          # 例如 MY-OPENCLAW-42
sentry issue view <short-id> --json                   # 结构化输出

AI 根因分析

sentry issue explain <issue-id>                       # Seer 分析根本原因
sentry issue explain <issue-id> --force               # 强制重新分析
sentry issue plan <issue-id>                          # 生成修复方案（需先运行 explain）

结构化日志

sentry log list <org>/<project>                       # 最近 100 条日志
sentry log list <org>/<project> --limit 50            # 最近 50 条
sentry log list <org>/<project> -q 'level:error'      # 按级别过滤
sentry log list <org>/<project> -q 'database'         # 按消息内容过滤
sentry log list <org>/<project> -f                    # 实时流式输出（每 2 秒轮询一次）
sentry log list <org>/<project> -f 5                  # 每 5 秒轮询一次
sentry log list <org>/<project> --json                # 结构化输出

查看特定日志条目：

sentry log view <log-id>                              # 32 位十六进制 ID
sentry log view <log-id> --json
sentry log view <log-id> --web                        # 在浏览器中打开

检查事件详情

sentry event view <event-id>                          # 完整堆栈跟踪 + 上下文
sentry event view <event-id> --json

直接调用 API

sentry api /projects/<org>/<project>/issues/ --paginate
sentry api /issues/<id>/ --method PUT --field status=resolved
sentry api /issues/<id>/ --method PUT --field assignedTo="user@example.com"

工作流：调查一个错误

1. sentry issue list <org>/<project> --query "is:unresolved" --sort date --limit 5
2. sentry issue view <short-id> —— 查看上下文、受影响用户、时间线
3. sentry issue explain <issue-id> —— AI 根因分析
4. sentry issue plan <issue-id> —— 生成具体修复步骤
5. 修复完成后，执行：sentry api /issues/<id>/ --method PUT --field status=resolved

参考资料

• 完整 CLI 命令：references/cli-commands.md
• 插件实现：references/plugin-setup.md
• CLI 文档：https://cli.sentry.dev
• Sentry API：https://docs.sentry.io/api/
• Node SDK：https://docs.sentry.io/platforms/javascript/guides/node/