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、上傳 Source 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 問題可能包含個人身份資訊、堆疊追蹤或環境細節。在分享代理產生的摘要或日誌時請務必留意。
• 謹慎使用 .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"

組織代稱與您的 Sentry 帳號不符，或令牌無權存取該組織。

1. 使用 sentry-cli organizations list 確認組織代稱。
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