代码审查总出问题？试试这款阿里开源的 AI 审查工具

你有没有经历过这样的场景：团队代码审查（Code Review）时，总有一些低级错误被漏掉；或者使用通用 AI 助手审查代码，结果它要么偷懒只看一半文件，要么报告的问题行号和实际代码对不上，甚至每次审查的效果都不稳定。

这些问题并非个例。如果你深度使用过 Claude Code 这类通用 AI 编程助手来做代码审查，很可能已经深有体会：变更稍大，AI 就开始选择性地“跳着看”；审查结果里的行号经常偏移，让你找半天才能定位到真正的问题；而且每一次审查，质量都像开盲盒。

为了解决这些痛点，阿里巴巴将其内部使用了两年、服务了数万开发者的 AI 代码审查助手进行了开源。这款工具叫做 Open Code Review（简称 OCR）。它不是一个通用的聊天机器人，而是一款专为代码审查场景设计的命令行工具（CLI），只需要配置好一个模型端点，就能在你本地的 Git 仓库中运行，生成带有行级精度的结构化审查意见。

下面，我们就来详细看看 Open Code Review 到底是什么，它如何工作，以及你怎样快速上手使用它。

为什么通用 AI 做不好代码审查？

在介绍 Open Code Review 之前，先简单分析一下为什么那些通用的 AI 编程助手在代码审查时总会出现各种问题。

你可能会遇到以下三种典型情况：

1. 覆盖不全：当你提交的代码变更较大时，AI 助手会倾向于“偷懒”，选择性地审查部分文件。比如一个功能改动涉及 20 个文件，它可能只仔细看了其中 10 个，其余的简单带过或直接忽略。这种遗漏在人工审查中很难被发现，却可能隐藏着严重的缺陷。

2. 位置漂移：AI 报告的问题中，提到的文件名或行号常常与实际代码对不上。比如它说“第 35 行有空指针风险”，但你翻到第 35 行发现是空行或者完全无关的代码。这通常是因为语言模型在理解 diff 格式和原始文件位置时产生了偏差。

3. 效果不稳定：基于自然语言提示词（Prompt）驱动的 AI 行为，其表现很大程度上取决于你如何描述需求。哪怕只是修改了几个词语，审查的深度、严格程度甚至输出格式都可能发生剧烈变化。这种不稳定性让你难以信任它的每次输出。

这些问题的根源在于：纯语言驱动的架构缺少对审查流程的强约束。AI 可以自由决定看哪些文件、不看哪些文件，也可以自由决定如何定位行号。而 Open Code Review 正是通过一种“确定性工程 × Agent 混合驱动”的设计，从工程层面解决了这些痛点。

Open Code Review 的核心设计：谁来做确定的事？

Open Code Review 的设计理念非常清晰：将那些“不能出错”的工作交给确定性工程逻辑来处理，而将动态决策和上下文召回这类“适合 AI 发挥”的工作交给 Agent。

确定性工程：负责强约束

以下这些环节，由代码逻辑而非语言模型来保证，从而从根本上避免了“偷懒”和“漂移”：

• 精准的文件筛选：通过规则明确哪些文件需要审查（比如 src/main/**/*.java）、哪些应当过滤（比如 **/generated/**）。这确保了每一次审查，重要文件的改动都不会被遗漏。
• 智能的文件打包：将相关联的文件归并为同一个审查单元。比如，message_en.properties 和 message_zh.properties 这两个国际化资源文件会被打包在一起，作为一个整体进行审查。每个包作为独立的 sub-agent 处理，上下文相互隔离。这种分治策略在处理超大型代码变更时，表现非常稳定，而且天然支持并发审查。
• 精细化规则匹配：针对不同文件的特征（比如 Java 文件、XML 配置文件、SQL 映射文件），自动匹配对应的审查规则。相比用自然语言在提示词里描述规则，这种基于模板引擎的规则匹配行为更稳定，结果更可预期。同时，它能帮助模型聚焦于当前文件的关键点，避免信息噪声干扰。
• 外挂的定位与反思组件：独立的评论定位模块和评论反思模块，会系统性地纠正 AI 反馈中的位置错误和内容错误。比如，当 AI 提出一个看似合理但实际位置错误的问题时，反思模块会进行二次校验，显著提升最终输出的准确性。

Agent：负责动态决策

在确定性工程划定的“框架”内，Agent 可以自由发挥它真正擅长的能力：

• 场景化提示词调优：针对代码审查这个特定场景，深度优化了提示词模板。这不仅提升了审查效果，还有效降低了 Token 消耗（也就是节省了 API 调用成本）。
• 场景化工具集沉淀：通过分析大量真实线上数据中的工具调用轨迹（比如哪些工具被高频使用、单一工具的重复调用率如何、新增工具对整体调用链路的影响等），对通用的 Agent 工具集进行了取舍与拆分。最终沉淀出一套在代码审查场景下更稳定、行为更可预期的专属工具集。这套工具集能让 Agent 更高效地读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而不是仅仅停留在表面。

如何安装 Open Code Review？

Open Code Review 是一个命令行工具，支持 macOS、Linux 和 Windows。你可以根据自己的习惯选择以下任意一种安装方式。

通过 NPM 安装（推荐）

如果你已经安装了 Node.js 环境，这是最简单的方式。在终端中运行以下命令：

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

安装完成后，ocr 命令就可以在全局使用了。

从 GitHub Release 下载二进制文件

你也可以直接下载对应你操作系统的二进制文件。

macOS (Apple Silicon 芯片，即 M1/M2/M3 等)

curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

macOS (Intel 芯片)

curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

Linux (x86_64)

curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

Linux (ARM64)

curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

Windows (x86_64)

curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe

然后将 ocr.exe 移动到你的 PATH 目录中（例如 C:\Windows\System32）。

Windows (ARM64)

curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe

从源码构建

如果你想从源代码编译，可以使用 make build：

git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr

配置 LLM：让 AI 为你工作

在使用 Open Code Review 审查代码之前，必须先配置好一个 LLM（大语言模型）。你不需要自己部署模型，只需要有一个支持标准 API 的模型端点即可，比如 Anthropic 的 Claude、OpenAI 的 GPT 系列，或者国内的通义千问（DashScope）、DeepSeek 等。

OCR 支持以下几种配置方式，你可以选择最顺手的一种。

方式一：交互式设置（推荐）

这是最简单直观的方法，适合初次使用。在终端中依次运行：

ocr config provider

这个命令会列出内置的模型供应商（如 anthropic、openai、dashscope、deepseek 等），并允许你选择其中一个，或者手动添加自定义供应商。

选择完供应商后，再运行：

ocr config model

这个命令会列出当前供应商支持的常用模型，你可以从中选择一个。交互式设置会自动帮你填写好对应的 API 地址和模型名称。

方式二：手动配置

如果你更喜欢手动操作，或者需要配置一个非标准端点，可以使用 ocr config set 命令。

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token your-api-key-here
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

配置文件会保存在 ~/.opencodereview/config.json 中。

关于认证头（auth_header）：对于 Anthropic 的 API，认证方式比较特殊。如果你使用的是标准的 sk-ant-* 格式的 API Key，需要将认证头设置为 x-api-key：

ocr config set llm.auth_header x-api-key

如果你使用的是其他兼容 OpenAI 协议的端点，通常使用默认的 authorization（Bearer Token）即可。

方式三：环境变量（优先级最高）

你还可以通过环境变量来配置。这种方式优先级最高，会覆盖配置文件中的设置。

export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=your-api-key-here
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

另外，OCR 也兼容 Claude Code 的环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL），如果你已经配置过 Claude Code，可能会更方便。

测试连通性

配置完成后，建议先测试一下 LLM 是否能够正常连通。

ocr llm test

如果配置正确，你会看到成功连接的提示。

第一次代码审查

假设你已经在一个 Git 仓库中（比如 cd your-project），并且已经配置好了 LLM。现在可以进行第一次审查了。

Open Code Review 支持三种常见的审查场景。

工作区模式（审查所有未提交的变更）

这是最常用的模式。它会审查你当前工作区中的所有暂存（staged）、未暂存（unstaged）和未跟踪（untracked）的变更。

ocr review

运行后，你会看到 OCR 开始分析变更文件，然后调用 LLM 进行审查，最后在终端输出行级的具体意见。

分支范围模式（比较两个分支）

如果你想要审查从 main 分支到 feature-branch 分支之间的所有差异，可以使用 --from 和 --to 参数。

ocr review --from main --to feature-branch

这个命令在 CI/CD 流水线中非常有用，比如在合并请求（Merge Request）触发时，自动审查两个分支之间的差异。

单个提交模式（审查某个 commit）

如果你只想审查某一次提交的内容，可以使用 --commit 参数。

ocr review --commit abc123

其中 abc123 是提交的哈希值（可以是短哈希）。

其他常用参数

参数	缩写	默认值	描述
--preview	-p	false	仅列出将被审查的文件，不实际调用 LLM
--format	-f	text	输出格式：text（人类可读）或 json（机器可读）
--concurrency	—	8	最大并发文件审查数量，可根据网络和 API 限制调整
--timeout	—	10	并发任务超时时间（分钟）
--audience	—	human	human 显示进度，agent 仅输出简洁摘要
--background	-b	—	提供需求或业务背景信息，帮助 AI 更聚焦地审查
--rule	—	—	自定义 JSON 审查规则文件的路径
--max-tools	—	内置默认	每个文件的最大工具调用轮次

示例：如果你希望以 JSON 格式输出审查结果，并提高并发数到 4：

ocr review --from main --to my-feature --concurrency 4 --format json

如果你有一些业务背景想提供给 AI（比如“为登录 API 添加了限流逻辑”）：

ocr review --background "为登录 API 添加限流"

将 Open Code Review 集成到你的 AI 编程助手

如果你日常在使用 Claude Code、Codex 这类 AI 编程助手，可以将 OCR 作为一条斜杠命令（Slash Command）或技能（Skill）集成进去，让助手在需要时直接调用它进行代码审查。

方式一：作为 Skill 安装（适用于支持 Skills 的 Agent）

使用 npx 将 OCR skill 安装到你的项目中：

npx skills add alibaba/open-code-review --skill open-code-review

这个命令会从技能注册表安装 open-code-review skill，教会你的编程 Agent 如何调用 ocr 进行审查、按优先级分类问题，甚至可选择性地自动修复。

方式二：作为 Claude Code 插件安装

如果你使用的是 Claude Code，可以通过以下命令安装插件：

/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

安装后，你就可以在 Claude Code 中使用 /open-code-review:review 命令来触发 OCR 审查，插件还会自动过滤和修复部分问题。

方式三：作为 Codex 插件安装

对于本地 Codex，可以添加此仓库作为插件市场：

codex plugin marketplace add alibaba/open-code-review
codex
/plugins

安装并启用 Open Code Review 后，在新的 Codex 对话中，你可以通过以下方式调用：

@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues

方式四：直接复制命令文件（无需包管理器）

如果你不想使用任何包管理器，可以直接下载命令文件到 Claude Code 的配置目录。

项目级（与团队共享，通过 git 提交）：

mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

用户级（个人全局使用，适用于所有项目）：

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

注意：所有集成方式都要求你已经在系统中安装并配置好了 ocr CLI。

在 CI/CD 流水线中使用（GitHub Actions / GitLab CI）

你可以在代码合并请求（Merge Request / Pull Request）触发时，自动运行 Open Code Review 并输出结果。这对于保证代码质量非常实用。

CI 集成的核心命令如下：

ocr review \
  --from "origin/main" \
  --to "origin/feature-branch" \
  --format json

使用 --format json 参数，OCR 会输出结构化的 JSON 数据，便于 CI 脚本解析和处理。

具体的集成示例，可以参考项目中的 examples/ 目录：

• github_actions/ — GitHub Actions 集成示例
• gitlab_ci/ — GitLab CI 集成示例

命令速查表

命令	别名	描述
ocr review	ocr r	开始代码审查
ocr rules check <file>	—	预览某个文件路径会生效哪些审查规则
ocr config provider	—	交互式供应商设置
ocr config model	—	交互式选择当前供应商的模型
ocr config set <key> <value>	—	直接设置配置项
ocr llm test	—	测试 LLM 连通性
ocr llm providers	—	列出所有内置 LLM 供应商
ocr viewer	ocr v	启动 WebUI 会话查看器（默认地址 localhost:5483）
ocr version	—	显示版本信息

评审规则：如何让 AI 按照你的规范审查？

Open Code Review 允许你通过 JSON 文件来定义审查规则。规则系统采用四层优先级，每层采用“首次匹配”原则。

优先级	来源	路径	描述
1（最高）	--rule 参数	用户指定的路径	临时覆盖，适合一次性特殊审查
2	项目配置	<repoDir>/.opencodereview/rule.json	可提交到 git，团队共享
3	全局配置	~/.opencodereview/rule.json	个人偏好，适用于所有项目
4（最低）	系统默认	内嵌 system_rules.json	覆盖常见语言和文件类型的内置规则

规则文件格式

规则文件是一个 JSON 对象，包含一个 rules 数组。每个规则由 path（文件匹配模式）和 rule（具体的审查要求）组成。

{
  "rules": [
    {
      "path": "force-api/**/*.java",
      "rule": "所有新方法必须对必填参数进行空值校验"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "检查 SQL 注入风险、参数错误和缺少闭合标签"
    }
  ]
}

• path 支持 ** 递归匹配和 {java,kt} 大括号展开。
• 在每一层内，规则按声明顺序评估——先匹配到的规则生效。
• 如果规则文件不存在，会被静默跳过。

路径过滤：哪些文件需要审查？

除了 rules 数组，规则文件还可以包含 include 和 exclude 字段，用于控制审查范围。

{
  "rules": [
    {"path": "**/*.java", "rule": "检查空值安全"}
  ],
  "include": ["src/main/**/*.java", "lib/**/*.kt"],
  "exclude": ["**/generated/**", "vendor/**"]
}

过滤决策的优先级如下（从高到低）：

步骤	条件	结果
1	文件为二进制文件	排除
2	路径匹配用户 exclude 模式	排除
3	文件扩展名不在支持列表中	排除
4	配置了 include 且路径匹配	纳入审查（跳过步骤 5）
5	路径匹配内置默认排除模式（测试文件等）	排除
6	以上均不满足	纳入审查

需要了解的关键点：

• include 和 exclude 遵循与评审规则相同的优先级链（--rule > 项目配置 > 全局配置），取最高优先级中配置了 include/exclude 的那一层整体生效，不会跨层合并。
• exclude 始终优先于 include —— 同时匹配两者的文件会被排除。
• include 的作用是绕过内置默认排除模式（如测试文件），而非限制审查范围。也就是说，未匹配 include 的文件仍会正常进入后续的默认过滤判断。

内置默认排除模式（用于过滤测试文件，可通过 include 覆盖）：

**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
**/src/test/java/**/*.java, **/src/test/**/*.kt,
**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**

配置文件完整参考

全局配置文件位于 ~/.opencodereview/config.json，你可以手动编辑它。

键	类型	示例
provider	string	anthropic | openai | dashscope | deepseek | z-ai
providers.<name>.api_key	string	供应商 API 密钥
providers.<name>.url	string	供应商 Base URL 覆盖
providers.<name>.protocol	string	anthropic | openai
providers.<name>.model	string	供应商模型名称
providers.<name>.auth_header	string	x-api-key | authorization
custom_providers.<name>.*	—	与 providers.<name>.* 相同的字段
llm.url	string	https://api.openai.com/v1/chat/completions
llm.auth_token	string	sk-xxxxxxx
llm.auth_header	string	仅 Anthropic：x-api-key | authorization
llm.model	string	claude-opus-4-6
llm.use_anthropic	boolean	true | false
language	string	English | Chinese（默认：Chinese）
telemetry.enabled	boolean	true | false
telemetry.exporter	string	console | otlp
telemetry.otlp_endpoint	string	OTLP 采集器地址
telemetry.content_logging	boolean	在遥测数据中包含提示词（慎用）

环境变量的优先级高于配置文件。

环境变量列表

变量	用途
OCR_LLM_URL	LLM API 端点 URL
OCR_LLM_TOKEN	API 密钥 / 认证令牌
OCR_LLM_AUTH_HEADER	Anthropic 认证头（x-api-key 或 authorization）
OCR_LLM_MODEL	模型名称
OCR_USE_ANTHROPIC	true = Anthropic 协议，false = OpenAI 协议

遥测（Telemetry）：了解工具运行情况

Open Code Review 内置了 OpenTelemetry 集成，用于收集 spans 和 metrics 数据，方便你监控工具的运行状态。默认情况下，遥测是关闭的。

如果你需要开启：

ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp          # 或 console
ocr config set telemetry.otlp_endpoint localhost:4317

如果设置 telemetry.content_logging 为 true，遥测数据中会包含 LLM 的提示词和响应内容（请注意隐私风险）。

常见问题解答（FAQ）

问：Open Code Review 支持哪些编程语言？

答：它没有硬性限制，理论上支持任何文本文件。内置的默认规则覆盖了 Java、Go、Rust、Python、Ruby、JavaScript/TypeScript 等常见语言，以及 XML、SQL、Properties 等配置文件。你可以通过自定义规则扩展对其他语言的支持。

问：我必须要使用 Anthropic 的 Claude 模型吗？

答：不一定。OCR 支持多种内置供应商（OpenAI、DashScope 通义千问、DeepSeek、Z-AI 等），也支持你手动添加任何兼容 OpenAI 或 Anthropic 协议的自定义端点。你只需要一个有效的 API 密钥即可。

问：审查一次代码大概会消耗多少 Token？

答：这取决于变更文件的大小和数量。OCR 通过场景化提示词调优和分治策略，已经尽力降低 Token 消耗。一次中等规模的变更（比如 10-20 个文件）可能消耗几千到几万 Token。你可以先使用 --preview 参数查看将要审查的文件列表，评估大致成本。

问：我可以让 OCR 只审查特定的几个文件吗？

答：可以。通过规则文件中的 include 和 exclude 字段，你可以精确控制审查范围。或者你也可以直接使用 Git 的暂存区功能：只将你想要审查的文件 git add，然后运行 ocr review（工作区模式会审查暂存和非暂存变更）。如果你只想审查已暂存的文件，目前可以通过 git diff --cached 配合脚本实现，但 OCR 本身没有专门参数。

问：审查结果中，AI 说的问题位置还是不对，怎么办？

答：首先，OCR 内置的定位与反思模块已经大幅降低了位置漂移的概率。如果仍然出现，建议检查你的代码文件是否在审查过程中发生了未提交的修改。另外，可以尝试使用 --max-tools 参数增加每个文件的工具调用轮次，让 AI 有机会多次核对位置。你也可以在规则文件中针对特定文件类型添加更严格的定位要求。

问：我能在团队内统一审查规则吗？

答：完全可以。将规则文件放在项目根目录的 .opencodereview/rule.json 中，并提交到 Git 仓库。这样团队成员使用 ocr review 时，会自动加载项目级规则。注意，--rule 参数的优先级最高，如果某人在命令行指定了自定义规则，会覆盖项目规则。

问：Open Code Review 和现有的 SonarQube、CodeClimate 等静态分析工具是什么关系？

答：它们是互补关系。静态分析工具基于固定的规则集（如代码规范、复杂度检查）进行确定性扫描，速度快、无遗漏，但难以理解业务逻辑和上下文。OCR 基于 LLM，能够理解代码意图、检测逻辑错误、提出架构建议，但成本较高、速度相对慢。你可以将 OCR 作为静态分析工具的上层补充，专门用于审查那些难以通过规则表达的深层次问题。

问：它能否自动修复发现的问题？

答：目前的版本主要定位是“审查并报告”，不会直接修改你的代码。但是，在与 Claude Code 或 Codex 集成时（例如通过 Skill 方式），编程 Agent 可以读取 OCR 输出的审查意见，并尝试自动生成修复补丁。如果你希望完全自动化修复，可以编写脚本解析 --format json 的输出，然后调用其他工具或 LLM 进行修复。

总结

Open Code Review 是一款从阿里内部大规模实践走出来的 AI 代码审查工具。它通过确定性工程与Agent的混合架构，解决了通用 AI 助手在代码审查场景中常见的覆盖不全、位置漂移、效果不稳定等问题。

无论你是一名独立开发者，还是属于大型团队，都可以快速上手：安装 CLI、配置一个 LLM 端点、然后运行 ocr review。它支持工作区审查、分支对比、单次提交审查等多种模式，还可以集成到 Claude Code、Codex 等编程助手，以及 GitHub Actions、GitLab CI 等自动化流水线中。

更重要的是，它的规则系统灵活且强大，允许你定义项目级、全局级甚至临时的审查规则，并精细控制哪些文件进入审查范围。这对团队统一代码规范、沉淀最佳实践非常有帮助。

如果你正在寻找一个更可靠、更可控的 AI 代码审查方案，不妨试试 Open Code Review。

---

项目地址：https://github.com/alibaba/open-code-review
许可证：Apache-2.0