오픈소스

open-code-review 쓰는 법

Open Code Review(OCR)는 Alibaba가 오픈소스로 공개한 AI 코드 리뷰 CLI로, Git diff를 읽어 줄 단위 코멘트를 남깁니다. 이 글은 npm 설치부터 ocr config·review·scan·delegate까지 공식 문서 기준 사용법입니다.

jaykim

23 9월 2026 • 6 min read

Open Code Review(약칭 OCR, 명령어 ocr)는 Alibaba가 내부에서 쓰던 AI 코드 리뷰 어시스턴트를 오픈소스로 공개한 CLI 도구입니다. Git diff(변경 내역)를 읽고, 설정한 LLM(대규모 언어 모델) 에이전트—도구를 호출하며 스스로 파일을 찾아보는 AI—가 줄 단위 코멘트를 남깁니다. 2026-09-21 기준 GitHub 주간 트렌드 1위였고, npm 패키지 @alibaba-group/open-code-review 최신 버전은 1.12.9입니다. 이 글은 설치·설정·리뷰·스캔·위임(delegate)까지 공식 README·설치 문서·FAQ만 따라갑니다.

alibaba/open-code-review GitHub 저장소 OG 이미지 — alibaba/open-code-review GitHub OG. 출처: GitHub

할 수 있는 일

워크스페이스의 staged/unstaged/untracked 변경을 한 번에 리뷰 (ocr review)
브랜치 구간·단일 커밋 리뷰 (--from/--to, --commit), 중단된 세션 재개 (--resume)
diff 없이 전체 파일·디렉터리를 감사 (ocr scan)
코딩 에이전트에 리뷰를 맡기는 delegation(위임) 모드 — OCR이 파일 선택·규칙만 잡고, LLM API 키는 호스트 에이전트 쪽을 씀
Claude Code / Codex / Cursor / Kimi Code 플러그인, MCP(Model Context Protocol, AI가 외부 도구에 붙는 표준) 클라이언트로 확장
CI(GitHub Actions 등)와 Session Viewer로 결과 재생

Open Code Review 하이라이트 스크린샷 — Open Code Review 하이라이트 화면. 출처: alibaba/open-code-review README

필요한 것

버전·요구사항은 공식 Installation·README에 적힌 것만 옮겼습니다. npm 경로가 아니면 Node는 필수가 아닙니다(정적 바이너리·Homebrew·소스 빌드 대안).

항목	내용 (공식 문서 기준)
Git	≥ 2.41 — diff·검색·저장소 작업에 사용
Node / npm	권장 설치 경로(`npm install -g`)일 때 필요. 공식 문서에 Node 최소 버전 고정값은 없음
LLM	프로바이더 + API 키 + 모델. Delegation 모드면 OCR 쪽 LLM 설정 생략 가능
OS	macOS / Linux (amd64·arm64). Windows는 npm·Release 바이너리·PowerShell 설치 스크립트 지원
소스 빌드 시	Go ≥ 1.25, Git, Make
상태 저장	`~/.opencodereview/` (config·sessions·rules)

단계

1) 설치

공식 권장은 npm 글로벌 설치입니다.

npm install -g @alibaba-group/open-code-review
ocr version

다른 방법(문서에 명시):

Homebrew: brew install open-code-review
설치 스크립트: curl -fsSL https://open-codereview.ai/install.sh | sh (Windows PowerShell: irm https://open-codereview.ai/install.ps1 | iex)
GitHub Release 정적 바이너리(opencodereview-*를 ocr로 PATH에 배치)
소스: make build 후 dist/opencodereview를 ocr로 복사

npm 설치본은 기본적으로 백그라운드 자동 업데이트합니다. 끄려면 OCR_NO_UPDATE=1.

2) LLM 설정

Delegation을 쓰지 않으면 리뷰 전에 프로바이더·모델을 잡아야 합니다.

ocr config provider
ocr config model
ocr llm test

대화형 UI가 프로바이더 선택·API 키 입력·모델 고르기·연결 테스트까지 안내합니다. 환경 변수(OCR_LLM_URL / OCR_LLM_TOKEN / OCR_LLM_MODEL 또는 Anthropic 호환 변수)로도 잡을 수 있습니다.

ocr config provider 설정 UI — ocr config provider 설정 화면. 출처: alibaba/open-code-review README

3) 리뷰하기 — `ocr review`

cd your-project

# 워크스페이스 변경 전체
ocr review

# 브랜치 구간 (merge-base 기준)
ocr review --from main --to feature-branch

# 단일 커밋
ocr review --commit abc123

# 중단 재개
ocr session list
ocr review --from main --to feature-branch --resume <session-id>

# 에이전트/CI용 JSON
ocr review --format json --output result.json

비용 없이 어떤 파일이 잡히는지 보려면 ocr review --preview.

4) 전체 스캔 — `ocr scan`

ocr scan
ocr scan --path internal/agent
ocr scan --resume <session-id>

git 히스토리 없이 파일 단위로 훑을 때 씁니다. 낯선 레포·디렉터리 감사에 적합합니다.

5) 선택 — Delegation / 플러그인 / MCP

ocr delegate preview
ocr delegate rule src/main.go src/handler.go

호스트 코딩 에이전트가 자체 LLM으로 리뷰하고, OCR은 파일 선택·규칙 해석만 담당합니다.

플러그인(공식 플러그인 README 기준, 먼저 ocr CLI 설치):

Claude Code: /plugin marketplace add alibaba/open-code-review → /plugin install open-code-review@open-code-review
Codex: codex plugin marketplace add alibaba/open-code-review 후 플러그인 활성화
Cursor: plugins/open-code-review/를 ~/.cursor/plugins/local/open-code-review/에 복사 후 창 리로드

MCP: OCR이 MCP 클라이언트로 외부 서버 도구를 리뷰 에이전트에 붙일 수 있습니다. 예) ocr config set mcp_servers.docs.command npx 등. 자세한 필드는 공식 MCP 문서 참고.

Open Code Review AACR-Bench 벤치마크 표 — AACR-Bench 벤치마크 요약. 출처: alibaba/open-code-review README

막히는 지점

공식 FAQ에서 자주 나오는 항목만 골랐습니다.

증상	점검 / 해결
`no valid LLM endpoint configured`	`ocr config provider`·`model` 또는 env 삼종 세트 설정 후 `ocr llm test`
`ocr llm test` 401/403	토큰·벤더 불일치. Anthropic은 `/v1/messages`+`use_anthropic=true`, OpenAI 호환은 chat completions URL
`not a git repository`	Git 작업 트리 안으로 `cd`하거나 `--repo` 지정
파일이 리뷰에서 빠짐	`ocr review --preview`로 제외 사유 확인 (`binary`, `user_exclude`, `node_modules` 등)
로컬 모델에서 tool call 실패	네이티브 function calling 지원 모델만 동작. 텍스트로 tool을 흉내 내는 모델은 불가
`Max tool requests reached`	더 강한 모델로 바꾸거나 `--max-tools`로 상한 상향(기본 템플릿 100)
command not found	`which ocr` / PATH. 설치 위치가 PATH에 있는지 확인

마치며

OCR은 “그냥 에이전트에게 리뷰 시켜”가 아니라, 파일 선택·번들·규칙 매칭 같은 결정적 엔지니어링과 에이전트 도구 사용을 섞은 하네스입니다. 로컬에서 ocr version → ocr config provider → ocr review 한 바퀴만 돌려도, PR 전에 잡히는 결함의 밀도가 확 달라집니다. 최신 플래그와 CI 연동은 open-codereview.ai/docs와 GitHub README를 보면 됩니다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.