OpenClaw GitHub 봇 계정 설정 가이드 - 안전한 권한 분리

OpenClaw에게 GitHub 작업을 시키면서도 main 브랜치에 직접 push는 막고 싶다면 어떻게 해야 할까?

처음엔 "Fine-grained Personal Access Token(PAT)만 쓰면 되겠지"라고 생각했다. 하지만 직접 해보니 함정 이 있었다. GitHub App도 고려했지만 너무 복잡 하다.

결론부터 말하면, 별도 봇 계정을 만드는 게 가장 간단하고 안전하다. 이 가이드에서는 내가 직접 겪은 시행착오와 해결 과정을 정리했다.

목표

OpenClaw에게 다음과 같이 작업을 시키고 싶다:

• ✅ 브랜치 생성 및 커밋 가능
• ✅ PR 생성 가능
• ❌ main 브랜치에 직접 push 불가능
• ✅ PR merge는 내가 직접 리뷰 후 승인

간단해 보이지만, 실제로 구현하려면 생각보다 복잡하다.

PAT만으로는 부족한 이유

시도한 방법

Fine-grained PAT로 권한을 Contents와 Pull requests만 주고, Branch Protection Rules로:

• "Require a pull request before merging" 설정
• "Require approvals (1명)" 설정

이렇게 하면 OpenClaw가 main에 직접 push는 못하니까 안전할 거라 생각했다.

치명적인 문제

GitHub의 기본 규칙: PR author는 자기 PR을 approve할 수 없다.

• OpenClaw가 내 PAT (내 계정)를 사용해서 PR 만듦
• PR author는 나
• 나는 내 PR을 approve할 수 없음
• 아무도 approve를 못해서 PR이 막혀버림

그럼 approval requirement를 없애면?

그럼 OpenClaw가 PAT 권한으로 바로 merge도 할 수 있게 된다. 내가 원하는 건 "PR은 만들되, merge는 내가 확인 후 하는 것"인데, PAT만으로는 이걸 구현할 수 없다.

GitHub App은 어떨까?

GitHub App을 만들어서 fine-grained permissions를 주면 되지 않을까?

이론상 가능하지만...

GitHub App으로도 할 수 있다. 하지만 실전에서는 복잡하다:

문제점:

1. gh CLI가 GitHub App의 private key 인증을 직접 지원하지 않음
2. Private key로 JWT를 생성하고, 이걸로 installation access token(1시간 유효)을 발급받아야 함
3. Token이 1시간마다 만료되므로 갱신 스크립트 필요
4. OpenClaw가 gh CLI를 그대로 쓰는 구조라 잘 통합 안 될 가능성

가능은 하지만 귀찮고 복잡하다. 더 간단한 방법이 있다.

봇 계정이 정답이다

가장 깔끔한 해결책은 별도 GitHub 계정을 만드는 것 이다.

구조

계정 A (본인)
  - Repository owner
  - CODEOWNERS
  - PR approve & merge 담당

계정 B (봇, 예: steve-bot)
  - Repository collaborator (Write 권한)
  - OpenClaw가 사용
  - PR만 생성

장점

• ✅ 무료 (GitHub 계정은 무료)
• ✅ 간단 (5분이면 설정 완료)
• ✅ gh CLI 그대로 사용 가능
• ✅ PR author ≠ 본인 이므로 본인이 approve 가능
• ✅ 봇 계정은 main에 직접 push 불가능 (repository rule 적용)

설정 방법

1단계: 봇 계정 만들기

새 이메일 주소로 GitHub 계정 생성 (예: steve-bot)

• Gmail의 + 기능 활용 가능: yourmail+stevebBot@gmail.com
• 또는 임시 이메일 서비스 사용

2단계: Repository에 collaborator로 추가

Repository → Settings → Collaborators → Add people

봇 계정 초대 (Write 권한)

⚠️ 중요: 봇 계정으로 로그인해서 초대 수락 필수!

GitHub 알림 또는 이메일에서 초대 링크를 찾아 Accept invitation 클릭

3단계: 봇 계정으로 PAT 생성

봇 계정으로 로그인해서 PAT 생성

Fine-grained PAT의 함정

처음에는 Fine-grained PAT를 시도했다.

Repository access → Only select repositories

하지만 본인이 소유한 repository만 목록에 나타난다. Collaborator로 초대받은 repository(frontalnh/personal-blog)는 선택 목록에 없었다.

All repositories 옵션을 선택하면 접근은 되지만, 보안상 좋지 않다. 봇 계정이 소유한 repository가 없으니 모든 repository를 선택하면 향후 추가될 모든 repository에 접근 권한 이 생긴다.

해결책: Classic PAT 사용

결국 Classic Personal Access Token 을 사용하기로 했다.

Classic PAT는:

• ✅ Collaborator로 초대받은 repository에 자동으로 접근 가능
• ✅ repo scope 하나면 충분 (코드 읽기/쓰기, PR 생성)
• ⚠️ Fine-grained보다 권한이 넓지만, 봇 전용 계정이라 괜찮음

토큰 생성

1. https://github.com/settings/tokens (Classic 탭)
2. Generate new token (classic) 클릭
3. Scopes 선택:
   • ✅ repo (Full control of private repositories)
   • ✅ read:org (Read org and team membership, optional but gh CLI가 더 잘 작동함)
   • ✅ workflow (Update GitHub Action workflows, 필요시)
4. Generate token 클릭
5. 생성된 토큰 복사 (ghp_로 시작)

4단계: OpenClaw에 PAT 추가

openclaw gateway config.patch --raw '{"env":{"GH_TOKEN":"ghp_xxxxx..."}}'

Gateway가 자동으로 재시작되고, 이제 gh CLI가 collaborator repository에도 정상 작동한다.

확인

# 봇 계정으로 인증되었는지 확인
GH_TOKEN="ghp_xxxxx..." gh api user

# Repository 접근 권한 확인
GH_TOKEN="ghp_xxxxx..." gh api repos/frontalnh/personal-blog

permissions에 "push": true가 있으면 성공이다.

5단계: Branch Protection Rules 설정

Repository → Settings → Rules → Rulesets → New ruleset

• Target branches: main
• Rules:
  • ✅ Require a pull request before merging
    • ✅ Required approvals: 1
    • ✅ Require review from Code Owners (선택사항)

Create 클릭

6단계: CODEOWNERS 파일 생성 (선택사항)

.github/CODEOWNERS 파일 생성:

* @본인계정

이렇게 하면 모든 PR에 본인의 리뷰가 필수 가 된다.

워크플로우

실제 사용 흐름은 이렇다:

1. OpenClaw(봇 계정)에게 "블로그에 XX 글 추가해줘" 요청
2. 봇이 브랜치 생성 → 파일 작성 → 커밋 → push
3. 봇이 gh pr create로 PR 생성
4. 본인이 GitHub에서 PR 확인 & approve & merge

봇은 PR만 만들고, 최종 머지는 본인이 한다. 안전하고 통제 가능하다.

실전 팁

gh CLI와 환경 변수

OpenClaw의 exec 도구로 gh 명령어를 실행할 때, Gateway의 환경 변수가 자동으로 전달되지 않을 수 있다.

이 경우 명령어에 직접 환경 변수를 포함 시키면 된다:

GH_TOKEN="ghp_xxxxx..." gh pr create ...

또는 exec의 env 파라미터를 사용한다 (OpenClaw가 지원하는 경우).

Collaborator 초대 수락 잊지 말기

봇 계정에게 collaborator 초대를 보낸 후, 반드시 봇 계정으로 로그인해서 초대를 수락 해야 한다.

수락 전까지는 repository 접근이 불가능하다. GitHub 알림 또는 이메일에서 초대 링크를 찾아 Accept invitation 을 클릭한다.

권한 확인

Repository → Settings → Collaborators

봇 계정이 Write 권한 으로 표시되는지 확인한다. Read 권한만 있으면 PR을 만들 수 없다.

토큰 만료 대비

Classic PAT는 만료일을 설정할 수 있다. 만료일 없음(No expiration) 또는 1년 으로 설정하는 게 좋다.

만료되면 봇이 작동을 멈추므로, 캘린더에 알림을 설정해두자.

봇 계정 이메일 확인

GitHub는 이메일 인증이 필요한 경우가 있다. 봇 계정 이메일을 확인할 수 있도록 설정해두자.

보안 고려사항

토큰 관리

• 설정 파일 권한 설정

  chmod 600 ~/.openclaw/config.json
  

  복사

• 토큰을 GitHub에 올리지 말 것

  • .gitignore에 config.json 추가

봇 계정 격리

봇 계정은:

• ✅ 필요한 repository에만 초대
• ✅ Write 권한만 부여 (Admin 권한 절대 금지)
• ✅ PAT는 필요한 scope만 선택

샌드박스 모드

OpenClaw를 그룹 채널에서 사용한다면 샌드박스 모드 설정:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

DM은 풀 액세스, 그룹 채널은 샌드박스에서만 실행된다.

실제 경험담

처음엔 "PAT 권한만 제한하면 되겠지" 라고 생각했다. Branch protection rules도 걸어두고, Fine-grained PAT로 세밀하게 권한 제어했다.

그런데 막상 OpenClaw에게 블로그 글 작성을 시키고 나니, 내가 내 PR을 approve할 수 없어서 막혔다.

"GitHub App으로 하면 되지 않을까?" 생각했지만, gh CLI가 App의 private key를 직접 지원하지 않는다는 걸 알았다. Token 갱신 스크립트를 만들어야 하고, OpenClaw와 통합도 복잡하다.

결국 가장 간단한 해결책은 별도 계정 만들기 였다. 5분 만에 설정 끝나고, 깔끔하게 권한 분리가 된다. 봇 계정으로 PR 만들면 본인이 approve할 수 있고, repository protection rules도 정상 작동한다.

혼자 쓰는 프로젝트에 계정을 하나 더 만드는 게 과하다고 느껴질 수 있지만, 실제로 해보니 이게 제일 실용적이고 안전했다.

대안: GitHub App (고급)

정말로 GitHub App을 쓰고 싶다면, 다음과 같은 과정이 필요하다:

1. GitHub App 생성

   • GitHub Developer Settings
   • Repository permissions: Contents (Read & Write), Pull requests (Read & Write)

2. Private Key 생성

   • 앱 설정에서 "Generate a private key" 클릭
   • .pem 파일 다운로드

3. JWT 토큰 생성 스크립트

   // Node.js example
   const jwt = require('jsonwebtoken');
   const fs = require('fs');
   
   const privateKey = fs.readFileSync('app-private-key.pem');
   const payload = {
     iat: Math.floor(Date.now() / 1000),
     exp: Math.floor(Date.now() / 1000) + 600, // 10분
     iss: 'YOUR_APP_ID'
   };
   
   const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });
   console.log(token);
   

   복사

4. Installation Access Token 발급

   curl -X POST \
     -H "Authorization: Bearer JWT_TOKEN" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/app/installations/INSTALLATION_ID/access_tokens
   

   복사

5. Token 갱신 자동화

   • Cron job 또는 스크립트로 1시간마다 갱신

복잡하다. 봇 계정이 훨씬 간단하다.

다음 단계

이제 OpenClaw가 GitHub PR을 만들 수 있다. 다음과 같은 작업을 시킬 수 있다:

• "블로그에 XX 주제로 글 작성해줘"
• "README 파일에 설치 섹션 추가해줘"
• "package.json 버전 업데이트하고 PR 만들어줘"

OpenClaw가 PR을 만들면, 본인이 GitHub에서 리뷰하고 merge하면 된다.

추가 가이드

• OpenClaw 완벽 가이드 - 기본 개념과 설치
• OpenClaw Discord 연동 가이드 - Discord 연결
• OpenClaw Slack 연동 가이드 - Slack 연결

참고

• GitHub Personal Access Tokens
• GitHub Apps
• Branch Protection Rules