OpenCodeReview 튜토리얼 2026: 알리바바 오픈소스 AI Code Review CLI 설치, Git Diff·스캔·Claude/GPT

「리뷰 Skill을 하나 더」로는 리뷰가 안 고쳐지는 이유

2026년 대부분의 팀이 겪는 고통은 「AI 리뷰가 없다」가 아니다. 리뷰 진입점이 범용 Agent에 묶여 있다는 것이다. Claude Code에 「이 PR 리뷰해 줘」라고 하면 일부 파일은 읽고 다른 파일은 빠뜨리며, 코멘트 줄번호가 가끔 미끄러지고, 다음번에 프롬프트 한 줄만 바꿔도 품질이 다시 흔들린다. 공식 README도 이 통증을 직설한다. 커버가 비고, 위치가 드리프트하며, 순수 자연어 Skill은 디버깅이 어렵다.

뿌리는 모델이 덜 똑똑해서가 아니다. 순수 언어 구동 아키텍처가 리뷰 과정에 하드 제약을 걸지 않기 때문이다. 이번 리뷰에 파일을 넣을지, 관련 파일을 같이 묶을지, 규칙을 어떤 파일 종류에 떨어뜨릴지——이 단계는 「절대 틀리면 안 되는」 일인데도 같은 채팅에 맡겨 버린다. GPT로 바꾸든 Claude로 바꾸든, 파일을 빠뜨리는 방식만 바뀔 뿐이다.

비대칭 결론은 이렇다. 분수령은 Claude와 GPT 중 누가 더 강한가가 아니라, 리뷰 진입점이 「결정적 엔지니어링 + Agent」인가이다. 파일 선택·번들·규칙 매칭은 엔지니어링이 보장하고, 모델은 동적 증거 수집만 맡는다. 업그레이드해야 할 것은 진입점(ocr review / ocr scan / CI)이지, 더 두꺼운 Review Skill이 아니다. 사이트에서 「harness가 뭔가」를 풀어 쓴 글은 Omnigent Agent Harness 완전 이해를 보면 된다. 이 글은 OpenCodeReview를 설치하고, Git Diff와 스캔을 통과시키고, Claude와 GPT를 연결하는 실무만 다룬다.

OpenCodeReview란: Git Diff와 전체 스캔

명령부터 외우지 말고 먼저 분류한다. OpenCodeReview는 또 하나의 채팅창이 아니다. 같은 리뷰 루프를 여는 두 가지 문이다. 분류 축은 여전히 진입점, 실행, 컨텍스트, 적합한 사람이다.

공식 사이트와 npm 패키지 설명은 철학을 숨기지 않는다. 결정적 엔지니어링이 「틀리면 안 되는」 단계를 맡는다——파일을 정확히 고르고, 관련 파일을 한 묶음으로 묶고(예: message_en.properties와 message_zh.properties), 파일 특성으로 규칙을 맞추고, 외부 위치 지정·반성 모듈로 줄번호와 내용을 보정한다. Agent는 동적 결정과 동적 증거만 한다. 전체 파일을 읽고, 저장소를 검색하고, 같은 변경의 다른 파일을 본다. 공식 벤치마크는 오픈소스 저장소 50개, 실제 PR 200개, 언어 10종을 교차 주석했다. 범용 Agent(Claude Code 포함) 대비 Precision / F1이 더 높고 토큰은 약 1/9, 완료도 더 빠르다고 주장하지만 Recall은 더 낮다——정밀도로 노이즈를 줄이려는 의도이지, 놓친 이슈가 곧 실패라는 뜻은 아니다.

OCR vs Claude Code / Copilot / 사람

선정에서 먼저 「Claude가 센가, GPT가 센가」를 물으면 진짜 차이를 놓친다. OpenCodeReview, 범용 Agent Skill, IDE 내장 리뷰, 사람을 한 표에 놓고 진입점·실행·컨텍스트·적합한 사람으로 맞춘다.

멀티 모델 코딩 하네스에 키를 어떻게 다는지는 Pi Coding Agent 설치와 멀티 모델 접속을 보면 된다. 그 글은 「코드를 쓰는 백엔드를 어떻게 바꾸나」에 답한다. 이 글은 「리뷰 진입점을 채팅창에서 재현 가능한 CLI로 어떻게 떼어 내나」에 답한다.

설치와 LLM 설정

선행 조건

공식 하드 요구는 Git ≥ 2.41이다. diff 생성, 코드 검색, 저장소 작업이 모두 Git을 탄다. 먼저 git --version을 보고, 오래된 배포판은 올린 뒤에 CLI를 깐다. Node가 유일한 설치 경로는 아니지만, npm이 문서가 권하는 기본이다.

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

설치가 끝나면 ocr가 PATH에 있어야 한다. command not found가 나면 npm 전역 bin이 PATH에 들어갔는지 확인한다. 「설치 성공」을 「이미 리뷰할 수 있다」로 읽지 말 것——LLM 설정이 없으면 Delegation Mode를 제외하고 바로 실패한다.

다른 설치 방법

CI 베이스 이미지와 헤드리스 환경은 설치 스크립트를 쓸 수 있다(GitHub Release 바이너리를 감싸고 검증을 붙인다):

curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh
# OCR_INSTALL_DIR=/usr/local/bin（默认）
# OCR_VERSION=v1.2.3   # 可选：钉某个 release

Node를 들이기 싫으면 GitHub Releases에서 정적 바이너리를 받는다. OCR 자체를 고치려면 소스에서 빌드한다(Go ≥ 1.25 + Make). 플랫폼 세부사항은 설치 가이드가 기준이다. 버전 번호는 바뀌니, 「어느 날의 모델 이름」보다 명령 형태가 더 오래 간다.

모델부터 연결하고, 그다음 리뷰

설정은 ~/.opencodereview/config.json에 쓴다. 대화형이 가장 편하다. ocr config provider로 내장 또는 커스텀 공급자를 고르고, 키를 넣고, 모델을 고르면 연결 테스트를 자동으로 돌린다. 이후에는 ocr config model로 모델을 바꾼다. 스크립트와 CI는 비대화형 ocr config set을 쓴다.

ocr config provider    # 选 anthropic / openai / 自定义
ocr config model       # 为当前供应商选模型
ocr llm test           # 再测一次连通性
ocr llm providers      # 列出内置供应商

Git Diff 세 가지 리뷰 모드 실측

설치 검수는 ocr version이 아니다. 실제 저장소에서 줄번호가 붙은 첫 의견을 뽑아내는 것이다. 세 진입점이 로컬 변경, 브랜치 비교, 단일 커밋을 덮는다.

cd your-project

# 工作区：暂存 + 未暂存 + 未跟踪
ocr review

# 分支：相对 merge-base 审 feature 相对 main 的变更
ocr review --from main --to feature-branch

# 单个 commit
ocr review --commit abc123

# 中断后续跑
ocr session list
ocr review --from main --to feature-branch --resume <session-id>

# 给宿主 Agent 或 CI 落盘
ocr review --format json --output result.json

워크스페이스 모드는 「고쳤지만 아직 PR을 안 열었을 때, 먼저 혼자 한 번 두들겨 보는」 용이다. 브랜치 모드는 CI에 맞다. base는 기본 브랜치, head는 PR 헤드. 단일 커밋은 문제 있던 제출을 다시 재생할 때 쓴다. 큰 변경은 여러 bundle로 쪼개지고, 각 bundle은 격리된 컨텍스트의 서브 Agent다. 공식은 이 분할로 초대형 changeset의 누락을 누른다.

첫 실행에서 no valid LLM endpoint configured가 나면 설정 체인에 (URL, token, model)이 안 모인 것이다. 공식 FAQ대로 ~/.opencodereview/config.json을 쓰거나, OCR_LLM_URL / OCR_LLM_TOKEN / OCR_LLM_MODEL을 보내거나, 이미 있는 Claude Code의 ANTHROPIC_*를 재사용한다. OCR는 첫 번째 완전한 삼중항을 쓰지, 마지막 세트를 쓰지 않는다——설정 파일이 갖춰지면 환경 변수는 무시된다.

ocr scan 전체 스캔 쓰는 법

ocr review는 「이번에 무엇이 바뀌었나」에 답한다. ocr scan은 「이 디렉터리가 지금 안전한가 / 읽기 좋은가」에 답한다. 의미 있는 diff가 없을 때——방금 clone한 낯선 저장소, 리뷰 베이스라인을 처음부터 만들 때, 커밋이 거의 없는 디렉터리——빈 커밋을 만들어 review를 속이지 말 것.

ocr scan                          # 扫描整个仓库
ocr scan --path internal/agent    # 目录或具体文件
ocr scan --resume <session-id>    # 中断后恢复

스캔은 diff보다 비싸다. 토큰과 시간이 「고친 몇 줄」이 아니라 「파일 전체」로 잡힌다. 기본은 진짜 인수할 서브트리부터 보고, 처음부터 저장소 전체의 vendor/와 생성물을 쓸지 않는다. 규칙과 경로 필터는 공식 Review Rules를 본다. 의존성과 산출물을 먼저 빼고, 그다음 모델을 이야기한다.

Claude와 GPT 연결, 결과 읽는 법

내장 공급자에서 anthropic은 https://api.anthropic.com을 타고, 키 환경 변수는 ANTHROPIC_API_KEY다. openai는 https://api.openai.com/v1을 타고, 키 환경 변수는 OPENAI_API_KEY다. providers.*.api_key를 안 쓰면 해당 환경 변수로 떨어진다. Claude Code 환경이 이미 있으면 OCR가 ANTHROPIC_*도 집어 간다.

# Claude
ocr config set provider anthropic
ocr config set model claude-opus-4-6
ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY"
ocr llm test

# GPT（OpenAI）
ocr config set provider openai
ocr config set model gpt-4o
ocr config set providers.openai.api_key "$OPENAI_API_KEY"
ocr llm test

# 自定义 OpenAI 兼容网关
ocr config set provider my-gateway
ocr config set custom_providers.my-gateway.url https://gateway.internal.com/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.model llama-3-70b
ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY"

모델 ID는 공급자 목록과 함께 바뀐다. 공식 예제에는 claude-opus-4-6, gpt-4o가 나온 적 있다. 도입할 때는 ocr config model이 나열하는 선택지를 기준으로 하고, 블로그 스냅샷을 프로덕션에 넣지 말 것. 401 / 403이면 먼저 프로토콜을 맞춘다. Anthropic은 /v1/messages, OpenAI 호환은 /v1/chat/completions다. llm.protocol / use_anthropic은 URL과 같은 가족이어야 한다.

같은 저장소, 같은 diff에서 백엔드를 바꿀 때 볼 것

실측에서 「누가 문장을 더 길게 쓰나」를 겨루지 말 것. 작은 PR 하나를 고정한다. 널 포인터 위험 한 곳, 분명한 테스트 공백 한 곳, 스타일 노이즈 한 곳. Claude와 GPT로 각각 ocr review --from main --to HEAD --format json --output out.json을 돌리고 세 가지만 본다. 잡아야 할 결함에 줄번호가 맞았는지, 스타일 노이즈가 눌렸는지, 토큰과 벽시계가 CI 예산에 들어가는지. 공식 벤치의 지향은 고정밀도, 낮은 노이즈, 낮은 토큰이다. GPT가 더 싸더라도 nit를 세 배 더 올리면, CI 안의 사람은 파이프라인 전체를 꺼 버린다.

- name: Open Code Review
  uses: alibaba/open-code-review@main
  with:
    provider: openai
    model: gpt-4o
    api-key: ${{ secrets.OPENAI_API_KEY }}

GitLab CI, Gerrit, GitFlic도 지원한다. 키는 저장소 Secrets에 넣고, 워크플로 파일에 쓰지 않는다. 자체 macOS 러너와 클라우드 Mac의 층은 GitHub Actions macOS 자체 러너와 클라우드 Mac을 보면 된다.

시나리오별 선택

진짜 질문은 「OpenCodeReview를 깔 것인가」가 아니다. 첫 제약이 무엇인가다. 재현 가능한 diff 리뷰가 필요한가, diff 없는 디렉터리를 감사해야 하는가, 아니면 채팅창의 구두 의견만 있으면 되는가.

추천 조합

도구는 겹쳐도 된다. OpenCodeReview가 푸는 것은 「재현 가능한 리뷰 진입점」이다. 뚜껑을 안 닫는 Mac을 대신 주지 않고, Claude나 GPT 청구서도 대신 내지 않는다.

• 개인 일상 조합: 전역 ocr + ANTHROPIC_API_KEY 또는 OPENAI_API_KEY + 워크스페이스 ocr review. PR을 열기 전에 한 번 돌리고, 규칙 파일은 저장소에 넣는다.
• PR / CI 조합: ocr review --from base --to head --format json + 공식 GitHub Action + Secrets. 실패 전략은 먼저 「코멘트만, 차단은 나중에」. 오탐률이 안정된 뒤에 하드 게이트로 올린다.
• 베이스라인 감사 조합: 처음 인수할 때 ocr scan --path로 이슈 목록을 만들고, 이후에는 증분에만 review를 돌린다. 모든 PR에서 저장소 전체를 스캔하지 말 것.
• 이미 있는 Coding Agent 조합: 로컬에서는 Claude Code / Cursor로 코드를 쓰고, 리뷰는 ocr delegate 또는 OCR가 직접 관리하는 모델로 간다. 쓰기와 리뷰를 가르고, 키도 갈라도 된다.
• 최소 검증 조합: CLI만 깔고, 키 하나만 넣고, 작은 저장소에서 ocr review와 워크스페이스 변경을 돌린다. 네 박자(설치→자격 증명→한 번 review→한 번 scan)가 통과한 뒤에 CI로 간다.

흔한 오해

• OCR를 Claude Code의 무료 복제로 읽는다. 파일 선택과 줄번호를 모델 손에서 일부러 빼앗는다. 필요한 것은 리뷰 커버이지, 파일을 고치는 또 하나의 채팅창이 아니다.
• LLM을 안 붙이고 「설치가 깨졌다」고 탓한다. Delegation Mode를 빼면 완전한 엔드포인트 삼중항이 있어야 한다. ocr llm test가 안 되면 Git 파라미터부터 만지지 말 것.
• 모든 PR 리뷰를 scan으로 대신한다. 전체 스캔은 비싸고, 역사 노이즈를 다시 올린다. 증분은 review, 베이스라인은 scan.
• 블로그의 모델 ID를 Action에 박아 넣는다. 목록은 바뀐다. Action의 model은 바꿀 수 있는 입력으로 두고, 먼저 로컬에서 ocr config model로 확인한다.
• 개인 구독 키를 CI에 커밋한다. CI는 저장소 Secrets 또는 권한이 조여진 머신 수준 config.json을 쓴다. 회사 코드를 감사하지 않은 게이트웨이로 보내지 말 것.
• 절전하는 노트북에서 저장소 전체 scan을 돌린다. 세션은 --resume할 수 있지만, 벽시계와 청구서가 보기 싫어진다. 긴 스캔은 항상 켜 둔 노드로 옮긴다.

도입 단계

1. 타협 불가 항목을 적는다: 로컬 자체 리뷰만 필요한가, CI 코멘트만 필요한가, 둘 다인가. 첫 주에 Claude와 GPT를 동시에 붙일 것인가. CI는 먼저 코멘트인가, 바로 차단인가.
2. CLI를 설치하고 한 번 공회전한다: npm install -g @alibaba-group/open-code-review, ocr version, PATH와 Git ≥ 2.41을 확인한다.
3. 키는 하나만 붙인다: ocr config provider 또는 ocr config set, ocr llm test가 통과한 뒤에 다음으로 간다.
4. 실제 작은 PR에서 ocr review를 돌린다: 워크스페이스 또는 --from/--to. 검수 기준은 「줄번호가 맞고, 잡아야 할 것을 잡았다」이지 「코멘트가 더 길다」가 아니다.
5. ocr scan --path를 한 번 보탠다: 인수할 서브트리만 스캔하고, review와의 분업을 확인한다. 베이스라인 vs 증분.
6. 그다음 두 번째 모델 또는 Delegation을 결정한다: 같은 diff에서 Claude / GPT를 바꿔 오탐과 비용을 비교한다. 이미 호스트 Agent가 있으면 ocr delegate를 시험한다.
7. 실행 환경을 고른 뒤에 CI로 간다: 로컬 시험은 괜찮다. 야간 스캔과 게이트는 항상 켜 둔 클라우드 Mac 또는 자체 러너에 두고, 로그는 비식별화하고, 키는 아티팩트에 넣지 않는다.

FAQ

OpenCodeReview와 Claude Code는 어떤 관계인가?

Claude Code는 Anthropic의 공식 코딩 워크플로다. 코드 작성과 구두 리뷰가 같은 창에서 가능하다. OpenCodeReview는 알리바바가 공개한 리뷰 CLI이고, 모델은 Claude, GPT, 호환 엔드포인트로 바꿀 수 있다. 「공식의 깊은 파일 수정」을 대체하지 않는다. 대체하는 것은 「리뷰 커버와 줄번호를 전부 프롬프트에 맡기는 일」이다.

Claude와 GPT를 동시에 설정해야 하나?

아니다. 키 하나만으로 설치 검수는 통과한다. 두 번째 키의 의미는 이것이다. 같은 파일 선택과 규칙 위에서, 비용과 오탐에 따라 백엔드를 바꾸는 것. 두 번째 청구서가 없으면 「비교 평가」를 위해 운영면을 넓히지 말 것.

ocr review와 ocr scan은 서로 대체할 수 있나?

같은 명령으로 쓰면 안 된다. review는 Git Diff를 먹고, PR과 로컬 변경에 맞다. scan은 파일 전체를 먹고, diff 없는 감사에 맞다. 진입점을 잘못 고른 것은 모델이 덜 똑똑해서가 아니라, 엔지니어링 층이 입력을 잘못 본 것이다.

Windows와 헤드리스 클라우드 Mac에도 설치되나?

된다. npm 전역 패키지는 크로스 플랫폼이다. 설치 스크립트는 darwin / linux의 amd64와 arm64를 덮고, Windows는 Release 바이너리 또는 npm을 쓴다. 헤드리스 머신은 비대화형 ocr config set과 --format json을 쓰고 TUI에 기대지 말 것. 클라우드 Mac에서는 Git, PATH, ~/.opencodereview 권한을 먼저 고정하는 편이 맞다.

왜 클라우드 Mac이 또 필요한가? 로컬 npm만으로 부족한가?

로컬은 명령을 배우기에 충분하다. 야간 전체 스캔, 뚜껑을 닫은 뒤의 PR 게이트, Xcode / 서명과 같은 환경의 CI에는 부족하다. ocr는 모델을 분리했지만, Git과 파일 도구는 여전히 프로세스가 돌아가는 그 머신에 묶여 있다.

정리

OpenCodeReview 설치 튜토리얼은 겉으로 npm, 환경 변수, ocr review / ocr scan이다. 진짜로 심어야 할 것은 한 층의 분리이다. 결정적 엔지니어링과 모델을 가르고, Git Diff 진입점과 전체 스캔 진입점을 가르고, 대화형 설정과 CI 설정을 가른다. 2026년 9월에 버티는 쓰임은 이렇다. 로컬에서 키 하나로 review를 통과시키고, 규칙은 저장소에 넣고, CI는 Secrets로 JSON을 남기고, scan은 베이스라인에만 쓴다.

비대칭 결론은 그대로다. 분수령은 Claude와 GPT 중 누가 더 강한가가 아니라, 리뷰 진입점을 하드 제약으로 만들 수 있는가이다. 키 하나로 ocr review 한 번을 통과시킨 뒤에 scan과 두 번째 모델을 더한다. 실행면이 필요하면 프로세스를 절전하는 노트북에서 클라우드 Mac으로 옮긴다. 업그레이드해야 할 것은 진입점, 자격 증명, 노드이지, Review Skill을 하나 더 깔는 일이 아니다.