OpenClaw Sentry CLI 技能

OpenClaw Sentry CLI 技能概述

Sentry CLI 技能通过官方 sentry-cli 工具将 OpenClaw 连接到 Sentry — 业界领先的错误监控和性能追踪平台。安装后，你的 OpenClaw 智能体可以管理版本发布、上传 Source Map、查询问题、注册部署以及监控定时任务，一切通过自然语言完成。

错误监控对于生产环境应用至关重要，但管理版本和调试问题往往涉及大量重复的 CLI 命令。OpenClaw Sentry CLI 技能简化了这一工作流程。无需记忆 sentry-cli releases 的各种子命令，也不用在每次构建后手动上传 Source Map，只需描述你的需求，让智能体来处理剩下的工作。

典型工作流程：

1. 告诉 OpenClaw 在构建完成后创建新版本并上传 Source Map。
2. 智能体执行 sentry-cli releases new，上传 Map 文件，并完成版本发布。
3. 你将收到一份包含版本号和上传状态的确认摘要 — 无需任何手动操作。

Sentry CLI 技能安装前的准备

在安装 Sentry CLI 技能之前，请确保你已具备：

• 已安装并运行 OpenClaw（v1.0+）
• 已安装 Sentry CLI — 安装指南
• 拥有 Sentry 账号，并有权访问你需要管理的项目
• 拥有具备适当权限范围的 Sentry 认证令牌
• 已安装 clawhub CLI 用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

# 检查 Sentry CLI 版本
sentry-cli --version

# 验证 Sentry 认证状态
sentry-cli info

安装 Sentry CLI

选择适合你环境的安装方式：

# macOS / Linux（自动安装脚本）
curl -sL https://sentry.io/get-cli/ | sh

# macOS（Homebrew）
brew install getsentry/tools/sentry-cli

# NPM
npm install -g @sentry/cli

# Windows（Scoop）
scoop install sentry-cli

如何安装 Sentry CLI 技能

使用一条命令即可安装 Sentry CLI 技能：

npx clawhub@latest install sentry-cli

验证安装结果：

clawhub list

你应该能在已安装的技能列表中看到 sentry-cli。安装前可以使用 clawhub inspect sentry-cli 预览该技能。

Sentry CLI 技能配置指南

Sentry CLI 技能需要认证令牌来与 Sentry API 交互。你可以使用组织令牌（推荐用于 CI/CD）或个人认证令牌。

创建认证令牌

1. 前往 sentry.io/settings/auth-tokens 创建新令牌。
2. 对于版本管理和 Source Map 上传，请授予以下权限范围：

| 权限范围 | 用途 | |-------|---------| | project:releases | 创建和管理版本发布 | | org:read | 读取组织数据 | | project:read | 读取项目信息 | | project:write | 上传 Source Map 和调试文件 |

环境变量设置

# 设置 Sentry 认证令牌
export SENTRY_AUTH_TOKEN=sntrys_your_token_here

# 设置组织和项目（可选，避免每条命令都需要指定）
export SENTRY_ORG=your-org-slug
export SENTRY_PROJECT=your-project-slug

# 用于自托管 Sentry 实例
export SENTRY_URL=https://sentry.your-company.com/

重要提示： 切勿在配置文件中硬编码令牌。请使用环境变量或密钥管理工具，例如 1Password。令牌权限应遵循最小权限原则 — 尽量使用组织令牌而非个人令牌。

Sentry CLI 技能使用示例

1. 部署后创建版本发布

你： "为版本 2.4.0 创建一个新的 Sentry 发布，关联上一个版本以来的提交记录，从 ./dist 文件夹上传 Source Map，并完成发布。"

智能体将依次执行以下命令：sentry-cli releases new 2.4.0、sentry-cli releases set-commits 2.4.0 --auto、sentry-cli sourcemaps upload --release=2.4.0 ./dist 以及 sentry-cli releases finalize 2.4.0。它会确认每个步骤并报告上传的文件总数。

2. 部署后检查最新错误

你： "显示前端项目最近 24 小时内未解决的问题，按出现频率排序。"

智能体会查询 Sentry 获取最近的未解决问题，按指定的项目和时间范围进行筛选，并返回一个汇总表格，包含问题标题、事件数量、受影响用户数以及 Sentry 面板中各问题的链接。

3. 注册部署

你： "为版本 2.4.0 注册一次生产环境部署。"

智能体执行 sentry-cli releases deploys 2.4.0 new -e production 来注册部署。之后 Sentry 会跟踪该部署前后的错误率，在 Sentry 面板中启用部署健康监控。

4. 监控定时任务

你： "为我们每晚凌晨 2 点运行的数据库备份脚本设置 Sentry 监控。"

智能体使用 sentry-cli monitors run 包装备份命令，配置向 Sentry Crons 报告签到状态。如果任务失败或错过预定时间，Sentry 将发送告警通知。

安全与最佳实践

Sentry CLI 技能会与你的错误监控数据和发布流水线交互。请遵循以下准则确保安全：

• 使用组织令牌而非个人令牌。 组织令牌的作用范围限定在单个组织内，可以独立撤销而不影响你的个人访问权限。
• 授予最小必要权限。 对于只读监控，org:read 和 project:read 就足够了。仅在需要版本管理时才添加 project:releases 和 project:write。
• 定期轮换令牌。 为认证令牌设置过期时间，至少每 90 天轮换一次。
• 保护敏感的错误数据。 Sentry 问题可能包含个人身份信息（PII）、堆栈跟踪或环境详情。在分享智能体生成的摘要或日志时请注意保密。
• 谨慎使用 .sentryclirc。 如果你使用配置文件，请确保将其添加到 .gitignore 中，不要提交到版本控制。
• 确认后再执行发布操作。 在完成版本发布或上传 Source Map 之前，务必核实版本号和目标项目，避免发布到错误的项目。

常见错误与故障排除

"error: API request failed — 401 Unauthorized"

你的认证令牌缺失、已过期或缺少所需的权限范围。

1. 使用 sentry-cli info 验证认证状态。
2. 检查环境中是否已设置 SENTRY_AUTH_TOKEN。
3. 在 sentry.io/settings/auth-tokens 确认令牌具有所需的权限范围。

# 快速认证检查
sentry-cli info

"error: Could not find organization"

组织 slug 与你的 Sentry 账号不匹配，或令牌没有该组织的访问权限。

1. 使用 sentry-cli organizations list 验证组织 slug。
2. 检查 SENTRY_ORG 是否与令牌可访问的组织匹配。
3. 对于自托管实例，确保 SENTRY_URL 指向正确的服务器。

"error: No source maps found in the specified path"

上传目录中缺少 Source Map 文件，或路径不正确。

1. 确认构建输出目录包含 .map 文件。
2. 检查构建工具是否已配置生成 Source Map。
3. 使用绝对路径或从当前工作目录验证相对路径。

# 列出构建目录中的文件进行验证
ls -la ./dist/*.map