OpenClaw용 Sentry CLI 스킬

OpenClaw Sentry CLI 스킬 개요

Sentry CLI 스킬은 공식 sentry-cli 도구를 통해 OpenClaw을 Sentry — 대표적인 오류 모니터링 및 성능 추적 플랫폼 — 에 연결합니다. 설치 후 OpenClaw 에이전트는 자연어를 통해 릴리스 관리, 소스맵 업로드, 이슈 조회, 배포 등록, 크론 작업 모니터링을 모두 수행할 수 있습니다.

오류 모니터링은 프로덕션 애플리케이션에 필수적이지만, 릴리스를 관리하고 이슈를 디버깅하는 작업에는 반복적인 CLI 명령이 수반됩니다. OpenClaw Sentry CLI 스킬은 이 워크플로우를 간소화합니다. sentry-cli releases 하위 명령을 외우거나 빌드할 때마다 소스맵을 수동으로 업로드하는 대신, 필요한 작업을 설명하기만 하면 에이전트가 나머지를 처리합니다.

일반적인 워크플로우:

1. OpenClaw에 빌드 후 새 릴리스를 생성하고 소스맵을 업로드하도록 요청합니다.
2. 에이전트가 sentry-cli releases new를 실행하고, 소스맵을 업로드한 다음, 릴리스를 완료합니다.
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. 릴리스 관리 및 소스맵 업로드를 위해 다음 범위를 부여하세요:

| 범위 | 용도 | |------|------| | project:releases | 릴리스 생성 및 관리 | | org:read | 조직 데이터 읽기 | | project:read | 프로젝트 정보 읽기 | | project:write | 소스맵 및 디버그 파일 업로드 |

환경 설정

# 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 폴더에서 소스맵을 업로드한 다음, 릴리스를 완료해 주세요."

에이전트는 일련의 명령을 실행합니다: 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에 포함하고 버전 관리에 커밋하지 않도록 하세요.
• 확인 전에 릴리스 작업을 검토하세요. 릴리스를 완료하거나 소스맵을 업로드하기 전에 항상 릴리스 버전과 대상 프로젝트를 확인하여 잘못된 프로젝트에 게시하는 것을 방지하세요.

일반적인 오류 해결

"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"

소스맵 파일이 업로드 디렉토리에 없거나 경로가 올바르지 않습니다.

1. 빌드 출력 디렉토리에 .map 파일이 포함되어 있는지 확인하세요.
2. 빌드 도구가 소스맵을 생성하도록 구성되어 있는지 확인하세요.
3. 절대 경로를 사용하거나 현재 작업 디렉토리에서 상대 경로를 확인하세요.

# 빌드 디렉토리의 파일을 나열하여 확인
ls -la ./dist/*.map