OpenClaw GitHub (gh) 스킬 가이드

OpenClaw GitHub 스킬 개요

GitHub (gh) 스킬은 공식 GitHub CLI (gh)를 통해 OpenClaw를 GitHub 플랫폼에 연결합니다. 설치 후 OpenClaw 에이전트는 자연어를 사용하여 저장소, Pull Request, 이슈, Actions 워크플로 등과 상호작용할 수 있습니다.

이것은 OpenClaw 생태계에서 가장 인기 있고 다재다능한 스킬 중 하나입니다. 이슈 분류, PR 생성, CI 상태 확인 등 GitHub 스킬은 여러 단계의 Git 워크플로를 간단한 대화로 전환합니다.

일반적인 워크플로:

1. OpenClaw에게 대기 중인 PR을 확인하도록 요청합니다.
2. 에이전트가 백그라운드에서 gh pr list를 실행합니다.
3. 결과가 읽기 쉬운 요약으로 반환됩니다 — 컨텍스트 전환이 필요 없습니다.

GitHub 스킬 사전 요구사항

GitHub 스킬을 설치하기 전에 다음을 준비하세요:

• OpenClaw 설치 및 실행 중 (v1.0+)
• GitHub CLI (gh) 설치 완료 — 설치 가이드
• 관리하려는 저장소에 접근 가능한 GitHub 계정
• 스킬 관리를 위한 clawhub CLI 설치 완료

설정 확인:

# OpenClaw 버전 확인
openclaw --version

# GitHub CLI 버전 확인
gh --version

# GitHub 인증 상태 확인
gh auth status

GitHub 스킬 설치 방법

한 줄의 명령어로 GitHub 스킬을 설치합니다:

npx clawhub@latest install github

설치 확인:

clawhub list

설치된 스킬 목록에 github가 표시되어야 합니다.

GitHub 스킬 구성 가이드

GitHub 스킬은 개인 액세스 토큰(PAT) 또는 GitHub CLI 인증이 필요합니다. 가장 간단한 설정을 위해 gh auth login 사용을 권장합니다.

토큰 스코프

PAT를 선호하는 경우 github.com/settings/tokens에서 다음 스코프를 가진 토큰을 생성하세요:

| 스코프 | 필수 여부 | 용도 | |-------|---------|------| | repo | 예 | 저장소 전체 액세스 | | read:org | 권장 | 조직 멤버십 읽기 | | workflow | 선택 | GitHub Actions 워크플로 관리 | | read:project | 선택 | 프로젝트 보드 읽기 | | gist | 선택 | Gist 생성 및 관리 |

환경 설정

# 방법 1: GitHub CLI 인증 사용 (권장)
gh auth login

# 방법 2: 개인 액세스 토큰 설정
export GITHUB_TOKEN=ghp_your_token_here

중요: 토큰을 구성 파일에 하드코딩하지 마세요. 환경 변수 또는 비밀 관리자(1Password 또는 Bitwarden 등)를 사용하세요.

GitHub 스킬 사용 예시

1. 열린 이슈 목록 및 분류

사용자: "메인 저장소에서 bug 라벨이 있는 열린 이슈를 보여줘."

에이전트가 gh issue list --label bug --state open에 해당하는 명령을 실행하고 이슈 번호, 제목, 담당자가 포함된 포맷된 요약을 반환합니다.

사용자: "이슈 #42를 나에게 할당하고 priority:high 라벨을 추가해."

에이전트가 gh issue edit 42 --add-assignee @me --add-label priority:high를 실행합니다.

2. Pull Request 생성

사용자: "feature/auth 브랜치에서 main으로 'Add OAuth2 login' 제목의 PR을 만들고 변경 사항을 요약해줘."

에이전트가 gh pr create를 사용하여 PR을 생성하고, 제목을 입력하고, 커밋 차이를 기반으로 설명을 생성합니다.

3. Pull Request 리뷰

사용자: "PR #128의 변경 사항을 요약해줘."

에이전트가 gh pr diff 128로 차이를 가져오고, 변경 사항을 분석하여 다음을 포함하는 간결한 요약을 제공합니다:

• 변경된 파일 및 추가/삭제 행 수
• 주요 로직 변경 사항
• 잠재적 우려 사항 또는 제안

4. CI 상태 확인

사용자: "main 브랜치의 최신 Actions 실행 상태는?"

에이전트가 gh run list --branch main --limit 1을 확인하고 실행이 성공, 실패 또는 진행 중인지 보고합니다 — 전체 로그 링크와 함께.

보안 및 모범 사례

GitHub 스킬은 저장소에서 쓰기 작업을 수행할 수 있습니다. 안전을 위해 다음 지침을 따르세요:

• 최소 권한 원칙을 따르세요. 실제로 필요한 토큰 스코프만 부여하세요. 저장소 읽기만 필요한 경우 workflow 스코프를 건너뛰세요.
• 가능하면 gh auth login으로 인증하세요. 장기 유효한 PAT 대신 CLI를 사용하세요. CLI가 자동으로 토큰 갱신을 처리합니다.
• 병합 전에 리뷰하세요. PR 병합 및 파괴적인 작업은 항상 확인하세요. OpenClaw는 기본적으로 승인을 요청합니다.
• 토큰을 정기적으로 교체하세요. PAT를 사용하는 경우 만료일을 설정하고 최소 90일마다 교체하세요.
• 관리자 스코프 부여를 피하세요. admin:org 및 delete_repo 스코프는 거의 필요하지 않습니다. 필요하지 않는 한 부여하지 마세요.
• 활동을 감사하세요. GitHub 감사 로그를 정기적으로 확인하여 API를 통해 수행된 작업을 리뷰하세요.

일반적인 오류 및 문제 해결

"gh: command not found"

GitHub CLI가 설치되지 않았거나 PATH에 포함되지 않았습니다.

# macOS
brew install gh

# Ubuntu / Debian
sudo apt install gh

# Windows
winget install GitHub.cli

설치 후 gh auth login으로 인증하세요.

"HTTP 401: Bad credentials"

토큰이 없거나 만료되었거나 필요한 스코프가 부족합니다.

1. gh auth status를 실행하여 현재 인증 상태를 확인합니다.
2. 만료된 경우 gh auth login으로 재인증합니다.
3. PAT를 사용하는 경우 github.com/settings/tokens에서 repo 스코프가 있는지 확인합니다.

"Resource not accessible by integration"

토큰에 권한이 없는 저장소 또는 조직에 접근하려고 합니다.

1. 토큰에 read:org 스코프가 포함되어 있는지 확인합니다.
2. GitHub 계정이 대상 저장소에 접근할 수 있는지 확인합니다.
3. 조직 저장소의 경우 관리자가 Settings → Third-party access에서 토큰을 승인해야 할 수 있습니다.