OpenCodeReview 教程 2026：阿里开源 AI Code Review CLI 怎么安装？Git Diff、代码扫描与 Claude/GPT 实测

为什么「再下一个 Review Skill」解决不了审查

2026 年多数团队的痛苦不是「没有 AI 审查」，而是审查入口绑在通用 Agent 上。你对 Claude Code 说「帮我 review 这个 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 个开源仓、200 个真实 PR、10 种语言交叉标注，相对通用 Agent（含 Claude Code）宣称更高 Precision / F1、约 1/9 token、更快完成，但 Recall 更低——这是故意用精度换噪音，不是漏检就等于失败。

OCR vs Claude Code / Copilot / 人工

选型时若先问「Claude 强还是 GPT 强」，会错过真正差异。把 OpenCodeReview、通用 Agent Skill、IDE 内置审查和人工放在同一张表上，按入口、执行、上下文与适合人群对齐。

多模型 coding harness 怎么装钥匙，见 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 头。单 commit 适合回放一次有问题的提交。大变更被拆成多个 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 的陌生仓、要从零建审查基线、目录几乎没提交——不要硬造一个空 commit 去骗 review。

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

扫描比 diff 贵：token 和时间都按「整文件」计，不是按「改了几行」。默认先扫你真正要接手的子树，而不是一上来扫整仓的 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，看三件事：该报的缺陷有没有行号对上、风格噪音有没有被压住、token 与墙钟是否可进 CI 预算。官方基准的取向是高精度、低噪音、低 token；若 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 runner 与云 Mac 的分层，见 GitHub Actions macOS 自建 Runner 与云 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 参数。
• 用 scan 代替每一次 PR 审查。全量扫描贵，且会把历史噪音重新报一遍。增量用 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 或自建 runner，日志脱敏，钥匙不进制品。

FAQ

OpenCodeReview 和 Claude Code 是什么关系？

Claude Code 是 Anthropic 的官方 coding 工作流，写代码和口头审查可以在同一个窗口。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。