ClawSweeper: Codex로 이슈와 PR을 검토해 안전하게 정리하는 유지보수 봇

9bow · 7월 11, 2026, 6:30오전

ClawSweeper 소개

빠르게 성장하는 오픈소스 조직은 이슈와 PR이 사람이 감당하기 어려운 속도로 쌓입니다. OpenClaw 조직도 openclaw/openclaw, openclaw/clawhub 두 저장소를 중심으로 이런 상황을 겪었고, 이를 해결하기 위해 만든 것이 ClawSweeper입니다. 백로그를 검토해 무엇을 닫을 수 있는지와 그 이유를 제안하고, 유지보수자가 남긴 명령에 따라 리베이스·CI 수정·자동 병합(merge)까지 수행하는 유지보수 봇입니다. README는 "OpenClaw 저장소를 위한 보수적인(conservative) 유지보수 봇"이라는 문구로 이 프로젝트를 소개하고 있습니다.

ClawSweeper의 핵심 설계는 검토(review)와 적용(apply)을 분리한 것입니다. 검토 단계는 항목마다 근거·제안 코멘트·판정을 담은 마크다운 리포트만 작성할 뿐 아무것도 닫지 않습니다. 실제로 이슈나 PR을 닫는 적용 단계는 그 리포트가 여전히 유효한지 라이브 GitHub 상태를 다시 조회해 라벨, 작성자 권한, 스냅샷 변경 여부를 확인한 뒤에만 움직입니다. README는 이 프로젝트가 "범용 자동 닫기 봇이 아니다"라고 명시하며, 검토는 제안에 그치고 적용은 항상 별도로 안전장치(guardrail)를 거친다는 점을 강조합니다.

지원 범위도 닫기 제안에 그치지 않습니다. 예약 실행과 GitHub 이벤트에 반응하는 이슈·PR 검토, 유지보수자 명령으로 시작하는 리베이스·CI 수정·자동 병합, 신뢰할 수 있는 검토 결과를 바탕으로 한 이슈-투-PR 구현, 그리고 커밋 단위로 별도 진행되는 커밋 리뷰까지 포함합니다. 검토와 수정 작업 모두 Codex가 담당하며, 실제 GitHub 변경(코멘트·닫기·병합)은 결정론적인 실행기(executor)가 따로 맡습니다.

ClawSweeper의 네 가지 작업 레인

ClawSweeper는 리뷰, 적용, 리페어, 커밋 리뷰라는 네 개의 독립된 레인으로 나뉘어 동작합니다.

리뷰 레인은 열려 있는 이슈와 PR을 스캔하며, 대상 저장소가 repository_dispatch로 정확한 이벤트를 전달하면 해당 항목 하나만 낮은 지연으로 검토합니다. 항목마다 결정·근거·제안 코멘트·실행 메타데이터·GitHub 스냅샷 해시를 담은 리포트를 records/<repo-slug>/items/<number>.md에 작성하고, 마커가 붙은 공개 검토 코멘트 하나를 그 자리에서 갱신합니다. 스케줄러는 새 항목이나 활발한 항목은 시간 단위로, 30일 이내의 이슈·PR은 하루 단위로, 오래되고 조용한 이슈는 주 단위로 확인 주기를 늦춥니다.

적용 레인은 저장된 리포트를 읽어 GitHub 상태가 그 사이 바뀌지 않았을 때만 반영합니다. 변경 없는 고신뢰 제안만 닫고, 닫힌 리포트는 records/<repo-slug>/closed/<number>.md로 옮깁니다. 15분마다 깨어나 반영할 제안이 없으면 바로 종료하며, 한 체크포인트당 최대 20건까지만 닫아 GitHub App 토큰의 수명 안에서 동작하도록 제한합니다.

리페어 레인은 유지보수자가 @clawsweeper autofix나 @clawsweeper automerge를 남기면 시작됩니다. PR 브랜치를 가져와 정확한 head 기준 검토를 먼저 수행하고, 문제가 있으면 Codex가 리베이스·PR 리뷰 코멘트 반영·CI 수정을 진행한 뒤 구조화된 수정 결과물을 돌려줍니다. 실제로 그 결과물을 브랜치에 반영하고 병합 여부를 판단하는 것은 결정론적 실행기의 몫입니다.

커밋 리뷰 레인은 이슈·PR 정리와 완전히 분리되어 있으며, 코멘트를 남기거나 코드를 고치지 않습니다. main 브랜치에 커밋이 올라오면(현재는 수동 실행 기준) 문서·자산 전용 커밋은 건너뛰고, 코드가 포함된 커밋마다 Codex 워커 하나를 띄워 records/<repo-slug>/commits/<sha>.md에 리포트를 하나씩 남깁니다.

ClawSweeper의 안전장치

ClawSweeper가 스스로 밝히는 원칙은 "증거가 확실할 때만 움직인다"는 것입니다. 유지보수자가 직접 작성한 이슈나 PR은 main에 이미 반영되었다고 검증되지 않는 한 자동으로 닫히지 않고, 보호 라벨이 붙은 항목은 닫기 제안 자체가 나오지 않습니다. Fixes #123처럼 GitHub의 닫기 구문으로 이슈를 참조하는 PR이 열려 있으면 그 PR이 병합되거나 닫힐 때까지 이슈는 열린 채로 남습니다. 같은 작성자의 이슈-PR 쌍은 한쪽만 따로 닫히지 않도록 함께 묶여 있으며, PR을 다른 PR로 대체되었다는 이유로 닫으려면 그 대체 PR이 실제로 병합 가능한 상태여야 합니다.

Codex의 권한도 단계별로 분리되어 있습니다. 검토가 진행되는 동안 Codex는 GitHub 쓰기 토큰을 전혀 받지 않으며, 이슈·PR 이벤트 작업은 Codex가 종료된 뒤에야 쓰기·리포트 푸시 자격 증명을 생성합니다. 커밋 리뷰 워커에는 이슈·PR·워크플로 실행·커밋 메타데이터를 읽을 수 있는 읽기 전용 토큰만 전달되고, 쓰기·체크 자격 증명 역시 Codex 종료 후에 만들어집니다. CI는 검토 중 대상 체크아웃을 읽기 전용으로 만들며, Codex가 추적되거나 추적되지 않는 변경을 남기고 종료하면 그 검토 자체를 실패로 처리합니다.

ClawSweeper 유지보수자 명령어

유지보수자는 대상 저장소의 이슈·PR 코멘트에서 @clawsweeper 멘션으로 봇을 직접 제어할 수 있습니다.

@clawsweeper status          # 현재 상태 요약
@clawsweeper review          # 리페어 없이 검토만 다시 실행
@clawsweeper autofix         # 리뷰·수정 루프 진입 (병합은 하지 않음)
@clawsweeper automerge       # 리뷰·수정·병합 루프 진입
@clawsweeper approve         # 사람 검토 일시정지 상태 해제
@clawsweeper explain         # 짧은 요약 코멘트 게시
@clawsweeper stop            # 자동 병합/수정 루프 중단

명령 처리 결과는 이슈·PR·의도·head SHA별로 마커가 붙은 상태 코멘트 하나에 그 자리에서 갱신되며, 진행 상황은 로봇 이모지 하나와 단계 아이콘(확인 , 검토 , 수정 , 완료 )으로 표시됩니다. 명령을 실행할 수 있는 사용자는 저장소에 대해 admin, maintain, write 권한을 가진 협업자로 제한되어, 권한이 없는 사용자의 명령은 조용히 무시됩니다.

ClawSweeper 로컬 실행과 자체 호스팅

README는 OpenClaw가 운영하는 ClawSweeper 인스턴스가 제3자 저장소를 위한 공개 리뷰 서비스가 아니라고 명시합니다. 다른 프로젝트에서 쓰려면 이 저장소를 포크해 자신의 조직에 직접 배포하고 설정해야 합니다. 로컬에서 동작을 확인하려면 Node 24와 pnpm이 필요합니다.

corepack enable
pnpm install
pnpm run build

# 특정 이슈/PR 하나만 로컬에서 advisory 검토
codex login --device-auth -c 'service_tier="fast"'
pnpm run codex:local:check
pnpm run review -- --local-only --target-repo owner/name --item-number 123

--local-only 옵션은 검토 시작 플레이스홀더 코멘트를 생략하고 결과를 지정한 아티팩트 디렉터리에만 남기는 advisory 실행 모드로, GitHub에 어떤 코멘트도 남기지 않습니다. GitHub Actions로 실서비스를 운영하려면 OPENAI_API_KEY와 ClawSweeper GitHub App의 클라이언트 ID·프라이빗 키를 시크릿으로 등록해야 합니다.

ClawSweeper의 라이선스

ClawSweeper는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

ClawSweeper 공식 홈페이지

ClawSweeper 라이브 파이프라인 대시보드

ClawSweeper 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~