OpenCodeReview Tutorial 2026: Install Alibaba’s AI Code Review CLI, Git Diff, Scan, Claude/GPT

Why another Review Skill will not fix review

Most teams in 2026 are not missing “AI review.” They are missing a review entry that is not glued to a general-purpose Agent. You tell Claude Code to “review this PR,” it reads some files, skips others, occasionally comments on a line that has already moved, and next week a slightly different prompt produces a different quality of noise. The official README names the same three failures without dressing them up: incomplete coverage, location drift, and natural-language Skills that are almost impossible to debug when they go wrong.

The root cause is not that the model is too dumb. It is that a prompt-only architecture puts no hard constraint on the review process. Whether a file belongs in this pass, whether related files should travel together, and which rule set lands on which file type are steps that must not be wrong—and they are currently happening inside the same chat that writes the comment. Swap GPT for Claude and you have only swapped one way of missing files for another. You still cannot replay last Tuesday’s review against the same diff and get the same file set.

The asymmetric takeaway: the divide is not which of Claude or GPT is stronger. It is whether the review entry is deterministic engineering plus an Agent—file selection, bundling, and rule matching guaranteed by engineering, with the model only doing dynamic evidence gathering. What you should upgrade is the entry (ocr review / ocr scan / CI), not a thicker Review Skill. For a conceptual split of what a harness actually owns, see Omnigent Agent Harness 2026 explained. This page only answers how to install OpenCodeReview, get Git Diff and scan running, and attach Claude or GPT.

Treat that as a colleague’s filter, not a slogan. If your team already has a Skill that “reviews PRs,” ask one operational question before you add another markdown file: can a new hire replay the same review next month without re-prompting? If the answer depends on which chat they opened, you do not have a review system. You have a conversation that happens to mention code. OpenCodeReview is interesting because it moves the parts that must not drift out of that conversation. The model still writes the comment. Engineering decides which files exist, which files share a bundle, and which rule pack applies. That is a boring sentence and a useful architecture.

What OpenCodeReview is: Git Diff and full-file scan

Classify first, then talk commands. OpenCodeReview is not another chat window. It is two ways to open the same review loop. The classification axes stay the same as the rest of this series: entry, execution, context, and who it is actually for.

The site and the npm package notes state the philosophy without apology: deterministic engineering owns the steps that must not be wrong—exact file selection, bundling related files (for example message_en.properties with message_zh.properties), matching rules to file traits, then correcting line numbers and content with an external locator and a reflection module. The Agent only does dynamic decisions and dynamic evidence gathering: read the full file, search the repo, look at other files in the same change. The official benchmark used 50 open-source repos, 200 real PRs, and 10 languages with cross-annotation. Versus a generic Agent (including Claude Code) they claim higher Precision / F1, about 1/9 the tokens, and faster completion, with lower Recall. That is precision traded for noise on purpose, not “a miss means the product failed.”

Read that trade the way you would read a linter default. A tool that comments on every taste difference dies in week two because humans mute it. A tool that stays quiet on a real defect is annoying, but you can add a rule. OpenCodeReview is built as if you will keep it on. That is why the marketing number that matters is not “it found more issues than Claude Code.” It is “a teammate will still look at the output on Friday.” If your current Skill writes 80 nits and three real bugs, you already know which number people stop reading.

The two entries are easy to confuse because they share a binary and a config file. Do not. ocr review answers “what changed this time.” ocr scan answers “what does this tree look like right now.” Teams that smash them together either invent an empty commit so review has something to chew, or they burn a night scanning vendor/ on every PR. Both are category errors. Keep the loop the same—select, bundle, match rules, let the Agent gather evidence—and change only the input. Diff in, incremental comments out. Path in, baseline comments out.

OCR vs Claude Code / Copilot / humans

If the first question in a buying meeting is “is Claude stronger or GPT stronger,” you will miss the real difference. Put OpenCodeReview, a generic Agent Skill, IDE-built-in review, and a human on one table, aligned by entry, execution, context, and audience. The useful argument is not model IQ. It is whether you can replay the same review, pin it to a diff, and hand the output to a machine.

How to hang keys on a multi-model coding harness is covered in Pi Coding Agent setup and multi-model keys. That article answers “how do I swap the backend that writes code.” This one answers “how do I tear the review entry out of the chat box and make it a reproducible CLI.” Keep the two jobs split. A coding Agent that can rewrite a module is a bad default owner of “which files were in scope.” A review CLI that cannot edit your tree is a better owner of coverage.

Human review does not leave the picture. OCR will not tell you the feature is the wrong feature. It will not know that last quarter’s incident makes this migration radioactive. Use it where humans are expensive and inconsistent: catching the null-deref in a file nobody opened, keeping i18n pairs in the same bundle, refusing to invent a line number. Leave architecture, product risk, and “should we even merge this” with people who can take the blame. The comparison table is a decision aid, not a replacement plan for your staff engineer.

How to install and configure the LLM

Prerequisites

The official hard requirement is Git ≥ 2.41: diff generation, code search, and repo operations all go through Git. Run git --version first and upgrade old distros before you install the CLI. Node is not the only install path, but npm is the documented default, and it is the path this page assumes unless you are on a slim CI image.

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

After install, ocr should be on PATH. If you get command not found, check whether npm’s global bin directory is on PATH. Do not read “the package installed” as “you can review now”—without an LLM config, everything except Delegation Mode fails immediately. That failure is intended. The CLI is not a linter that can guess in offline mode. It is an Agent loop that needs a complete endpoint before it will touch your diff.

Other install paths

CI base images and headless hosts can use the install script (it wraps a GitHub Release binary and verifies it):

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

If you do not want Node on the box, pull a static binary from GitHub Releases. If you want to change OCR itself, build from source (Go ≥ 1.25 + Make). Platform details live in the installation guide. Version numbers will move; the shape of the commands is more stable than “the model name that was fashionable that month.” Pin a release in CI when you care about reproducibility. Leave @main for a laptop experiment, not for a merge gate.

Configure a model before you talk about review

Config lives in ~/.opencodereview/config.json. Interactive is the least painful path on a laptop: ocr config provider picks a built-in or custom provider, you paste a key, you pick a model, and it runs a connectivity test. After that, ocr config model swaps models. Scripts and CI should use non-interactive ocr config set. Do not hand-edit JSON on the first day unless you enjoy reconstructing a triple from memory.

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

Those comments inside the fence stay as the upstream snapshot wrote them; the commands are what you run. If ocr llm test fails, stop. You do not yet have a review problem. You have a credential or protocol problem. Fix the triple before you start arguing about --from and --to.

That callout is the part teams skip and then write an incident about. “It is only a review tool” still means the changed source, and often neighboring files, leave the building. If your policy already forbids pasting snippets into a consumer chatbot, it also forbids a default ocr pointed at a personal Anthropic voucher. Use a company key, a company gateway, or Delegation Mode against a host Agent that already sits inside that policy. The CLI will not make that decision for you.

Three Git Diff review modes, hands-on

Install acceptance is not ocr version. It is producing the first line-numbered comment in a real repository. Three entries cover local edits, branch comparison, and a single commit. Run them in a repo you actually work in, not a toy folder of two Python files. You want at least one multi-file change so bundling has something to do.

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

Workspace mode is for “I finished the change, I have not opened a PR, roast me first.” It includes staged, unstaged, and untracked files, which is what you want when the interesting risk is still sitting in a file you have not added. Branch mode is what CI should run: base is the default branch, head is the PR head. Single-commit mode is for replaying a known-bad commit when you want to see whether today’s rules would have caught it. Large changesets are split into bundles. Each bundle is a sub-Agent with isolated context. That divide-and-conquer is how the project claims it can keep coverage on a huge changeset without stuffing the entire tree into one prompt.

If the first run says no valid LLM endpoint configured, the config chain is missing a complete (URL, token, model). Per the official FAQ: write ~/.opencodereview/config.json, or export OCR_LLM_URL / OCR_LLM_TOKEN / OCR_LLM_MODEL, or reuse Claude Code’s existing ANTHROPIC_*. OCR takes the first complete triple, not the last one—once the config file is complete, environment variables are ignored. That precedence surprises people who export a CI secret on a laptop that already has a file. If the file is valid, your shell exports will not save you. Open the file, or delete the incomplete keys, before you assume the CLI is broken.

JSON output is the part that makes this a CI object instead of a chat transcript. Humans can read the terminal. Machines should read --format json --output result.json. Persist that file, attach it to the job, or let a later step decide whether a finding is a comment or a hard fail. Do not parse the pretty terminal with regex. The whole point of leaving the chat window is that the result has a schema you can keep.

How to use ocr scan

ocr review answers “what changed this time.” ocr scan answers “is this directory safe and understandable right now.” When there is no meaningful diff—a freshly cloned unfamiliar repo, a review baseline you are building from zero, a directory that barely has commits—do not invent an empty commit to trick review. That hack produces an empty or misleading changeset and trains the team to distrust the tool. Use the entry that matches the question.

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

Scan is more expensive than diff: tokens and wall-clock are billed against whole files, not against the handful of lines you changed. Default to the subtree you are actually inheriting, not a first-pass sweep of the whole repo’s vendor/ and generated artifacts. Rules and path filters live in the official Review Rules docs. Exclude dependencies and build products before you debate models. A cheaper model on a dirty path still wastes money. A stronger model on a clean path is a decision you can defend.

Resume exists because a full-tree scan is a long job, not a party trick. Laptops sleep. VPNs drop. People close the lid. --resume is how you avoid paying for the same directories twice. It is not a reason to run the job on a machine that will sleep in twenty minutes. Put a baseline scan on a host that stays up, keep the session id, and treat interruption as expected ops rather than a personal failure. After the baseline exists, go back to ocr review for the next PR. Repeating scan on every push is how you turn a useful audit into a noise cannon that re-reports last year’s style debt.

How to wire Claude and GPT, how to read results

Among built-in providers, anthropic talks to https://api.anthropic.com and the key environment variable is ANTHROPIC_API_KEY; openai talks to https://api.openai.com/v1 and the key environment variable is OPENAI_API_KEY. If you omit providers.*.api_key, it falls back to the matching environment variable. If a Claude Code environment is already present, OCR will also pick up ANTHROPIC_*. That reuse is convenient on a laptop and dangerous in CI if the only key on the runner is a personal login leftover. Prefer an explicit ocr config set on shared machines.

# 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"

Model IDs move with the vendor catalog. Official samples have shown claude-opus-4-6 and gpt-4o; when you ship this, trust whatever ocr config model lists, and do not paste a blog snapshot into production. On 401 / 403, check protocol first: Anthropic uses /v1/messages, OpenAI-compatible uses /v1/chat/completions, and llm.protocol / use_anthropic must be in the same family as the URL. A custom gateway that speaks OpenAI JSON on an Anthropic-shaped path will fail in ways that look like “the model is down.” It is not. You pointed the wrong dialect at the wrong door.

Same repo, same diff: what to read when you swap backends

Do not score a bake-off by “whose sentences are longer.” Freeze a small PR: one null-deref risk, one obvious missing test, one style nit. Run Claude and GPT separately with ocr review --from main --to HEAD --format json --output out.json, and look at three things: did the real defects land on the right line numbers, did style noise stay suppressed, and do tokens and wall-clock fit a CI budget. The official benchmark leans high precision, low noise, low tokens. If GPT is cheaper but reports three times the nits, people in CI will disable the whole pipeline. A disabled pipeline is worse than a quieter model. Count mute events, not adjective quality.

Keep the file set identical across the two runs. If you change the branch, the rules, or the exclude list in the middle, you are no longer comparing backends. You are comparing two different reviews. Write the three expected findings down before either job starts. After both JSON files exist, ask only whether those three showed up, whether extra comments would survive a tired Friday reviewer, and whether the slower run still fits the merge SLA. That is enough data to pick a default. You can always add a second provider later. You cannot easily rebuild trust after a week of yellow noise.

- 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, and GitFlic are also supported. Keys go in repository Secrets, not in the workflow file. How self-hosted macOS runners layer against cloud Macs is in GitHub Actions macOS self-hosted runners and cloud Mac. If the review must share an environment with Xcode, signing, or a native toolchain, the runner OS is part of the review design. The model name is not. Pin the Action to a release when the comment stream becomes a gate. @main is fine while you are still deciding whether to fail the job.

How to choose by scenario

The real question is not “should we install OpenCodeReview.” It is the first constraint: do you need reproducible diff review, do you need to audit a directory that has no diff, or do you only want a verbal opinion inside a chat window? Answer that before you argue about Claude versus GPT. The matrix below is meant to be used in a meeting, not framed on a wiki.

Two rows get abused. Teams that only wanted a hallway opinion install OCR, hate the ceremony, and declare AI review a fad. Teams that needed a gate keep asking Claude Code in chat and then wonder why coverage jitters. Match the row you are actually in. You can graduate later. You cannot skip the constraint and still get the property the marketing page implied.

Recommended stacks

Tools are allowed to stack. OpenCodeReview solves a reproducible review entry. It does not buy you a Mac that never closes, and it does not pay your Claude or GPT bill. Pick a stack that names the host, the key, and the entry. Leave the rest for a later week.

• Personal daily stack: a global ocr plus ANTHROPIC_API_KEY or OPENAI_API_KEY plus workspace ocr review. Run it before you open the PR, and keep the rules file in the repo so the laptop and CI describe the same house style. This is the cheapest way to learn whether the comments are worth a pipeline.
• PR / CI stack: ocr review --from base --to head --format json plus the official GitHub Action plus Secrets. Start the failure policy at “comment, do not block.” Promote to a hard gate only after the false-positive rate is boring. A gate that cries wolf trains people to bypass it with a label.
• Baseline audit stack: first inheritance uses ocr scan --path to build an issue list; after that, only incremental review. Do not full-scan the repo on every PR. The second scan of the same dead code is not diligence. It is a recurring invoice.
• Existing coding-Agent stack: keep writing in Claude Code / Cursor on the laptop; send review through ocr delegate or an OCR-managed model. Writing and reviewing stay separate, and the keys can stay separate. That split is useful when the coding Agent has a personal voucher and the review Agent must use a company gateway.
• Minimum validation stack: install only the CLI, configure only one key, run ocr review against workspace changes in a small repo. Clear four beats (install → credentials → one review → one scan) before you touch CI. If beat three is already unreadable, CI will not make it wiser.

Common pitfalls

• Reading OCR as a free clone of Claude Code. It deliberately takes file selection and line numbers out of the model’s hands. You want review coverage, not another chat window that can edit files. If your demo script starts with “and then it rewrites the function,” you are evaluating the wrong product.
• Blaming a “broken install” when no LLM is configured. Except in Delegation Mode, you need a complete endpoint triple. If ocr llm test fails, do not start tuning Git arguments. The CLI is doing you a favor by refusing to invent a backend.
• Using scan as a stand-in for every PR review. Full-file scan is expensive and will re-report historical noise. Incremental work uses review; baselines use scan. Mixing them is how a useful gate becomes a style-debt newsletter.
• Hard-coding a blog’s model ID into the Action. Catalogs move. Treat model in the Action as a mutable input, and verify it locally with ocr config model first. Yesterday’s fashionable ID is tomorrow’s 404.
• Committing a personal subscription key into CI. CI uses repository Secrets or a locked-down machine-level config.json. Do not point company code at an unaudited gateway. A leaked review key is still a leaked key; the “it only reads diffs” story will not help in the postmortem.
• Running a whole-repo scan on a laptop that sleeps. Sessions can --resume, but the wall-clock and the bill will look ugly. Put long scans on an always-on node. Resume is a recovery tool, not a substitute for a host that stays awake.

Rollout steps

1. Write the non-negotiables: local self-review only, CI comments only, or both; whether week one must attach Claude and GPT at the same time; whether CI comments first or blocks immediately. If you cannot write those three answers in a short paragraph, you are not ready to argue about model IDs.
2. Install the CLI and do an empty run: npm install -g @alibaba-group/open-code-review, then ocr version, and confirm PATH plus Git ≥ 2.41. An empty run means the binary starts. It does not mean review works. That is the next step, not this one.
3. Attach only one key: ocr config provider or ocr config set, and do not continue until ocr llm test passes. One provider is enough to learn the entry. A second provider is a later comparison, not an install requirement.
4. Run ocr review on a real small PR: workspace mode or --from/--to. Acceptance is “line numbers match and the real defects showed up,” not “the comments are longer.” If the first run is only style nits, fix rules before you evangelize the tool.
5. Add one ocr scan --path: scan only the subtree you are inheriting, and confirm the split of labor with review: baseline versus increment. Write that split down so the next person does not “just scan the repo to be safe.”
6. Only then decide on a second model or Delegation: swap Claude / GPT on the same diff and compare false positives and cost; if you already have a host Agent, try ocr delegate. Keep the file set frozen. Change one variable at a time.
7. Pick the execution host, then enter CI: a laptop is fine for trials; overnight scans and merge gates belong on an always-on cloud Mac or a self-hosted runner. Redact logs, and keep keys out of artifacts. If the host sleeps, the gate is fiction.

FAQ

How does OpenCodeReview relate to Claude Code?

Claude Code is Anthropic’s official coding workflow. Writing code and a verbal review can live in the same window. OpenCodeReview is Alibaba’s open-source review CLI; the model can be Claude, GPT, or a compatible endpoint. It does not replace “the official Agent that deeply edits files.” It replaces “review coverage and line numbers that exist only because the prompt asked nicely.” Use Claude Code to change the tree. Use OCR to say, in a form CI can keep, what was wrong with the tree you already changed.

Do I have to configure Claude and GPT at the same time?

No. One key is enough to pass install acceptance. A second key is useful when the same file selection and rules should swap backends by cost and false-positive rate. If you do not already have a second bill, do not grow the ops surface just to run a comparison blog. You can add the other provider later without redesigning the entry. The entry is the scarce design. The model is a config line.

Can ocr review and ocr scan stand in for each other?

Not as the same command. Review eats a Git Diff and fits PRs and local edits. Scan eats whole files and fits audits that have no useful diff. If you pick the wrong entry, the model is not too dumb—you pointed the engineering layer at the wrong input. An empty commit is not a clever adapter. It is a way to make review look broken and scan look optional. Keep both, and keep them honest.

Can I install this on Windows and on a headless cloud Mac?

Yes. The global npm package is cross-platform. The install script covers darwin / linux amd64 and arm64; on Windows use a Release binary or npm. Headless machines should use non-interactive ocr config set and --format json; do not depend on a TUI. On a cloud Mac, freeze Git, PATH, and ~/.opencodereview permissions first. A pretty interactive wizard that you ran once on your laptop will not be there when the runner starts at 02:00.

Why do I still need a cloud Mac? Is a local npm install not enough?

A laptop is enough to learn the commands. It is not enough for overnight full-file scans, PR gates that must survive the lid closing, or CI that has to share an environment with Xcode and signing. ocr unbundled the model, but Git and the file tools still bind to the machine that is running the process. If that machine sleeps, your deterministic entry becomes a best-effort hobby. The model bill can stay with Anthropic or OpenAI. The process still needs a host that does not disappear.

Conclusion

An OpenCodeReview install tutorial looks like npm, environment variables, and ocr review / ocr scan. What you actually have to land is a split: deterministic engineering separated from the model, a Git Diff entry separated from a full-file scan entry, interactive config separated from CI config. The usage that still stands in September 2026 is one key on a laptop to get review working, rules in the repo, CI writing JSON with Secrets, and scan reserved for baselines.

The asymmetric conclusion still holds: the divide is not which of Claude or GPT is stronger. It is whether you can make the review entry a hard constraint. Get one key through a single ocr review first, then add scan and a second model. When you need an execution plane, move the process off the sleeping laptop onto a cloud Mac. Upgrade the entry, the credentials, and the node—not another Review Skill.

If you remember one sequence, remember this one. Classify the question (diff versus baseline). Install the CLI and prove Git. Attach one complete triple and stop if ocr llm test fails. Produce one line-numbered comment on a real change. Only then talk about GPT versus Claude, Delegation Mode, or a merge gate. Teams that invert that sequence spend a week comparing prose and never get a replayable file list. Teams that keep it spend an afternoon and then have something CI can hold. That is the whole product, described without a launch video.