阿里开源代码审查工具

alibaba/open-code-review

二〇二六年七月十五日·★ 5,011·⑂ 246·Go·Apache-2.0 ·最新发布 v1.2.4 · 2026-06-07 · GitHub 原仓库

摘要

阿里巴巴开源了Open Code Review，一个基于AI的代码审查CLI工具。它读取Git diff，通过具备工具调用能力的agent将变更文件发送给可配置的LLM，生成行级精度的结构化审查意见。该工具采用确定性工程与agent混合架构，包含精确文件选择、智能文件打包、细粒度规则匹配及外部定位与反思模块。它支持CLI、CI/CD集成，并可安装为编码agent（如Claude Code、Codex）的插件或斜杠命令。

什么是 Open Code Review？

Open Code Review 是一个基于 AI 的代码审查 CLI 工具。它起源于阿里巴巴集团内部的官方 AI 代码审查助手——在过去两年中，它为数万名开发者提供服务，并识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化成一个面向社区的开源项目。只需配置一个模型 endpoint 即可开始使用。

它读取 Git diff，通过一个具备工具调用能力的 agent 将变更文件发送给可配置的 LLM，并生成具有行级精度的结构化审查意见。该 agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而生成深度审查——而不仅仅是表面层次的 diff 反馈。

Highlights

为什么选择 Open Code Review？

通用 Agent 的问题

如果你曾使用过像 Claude Code 结合 Skills 这样的通用 agent 进行代码审查，你很可能遇到过以下痛点：

覆盖不完整——在较大的变更集上，agent 倾向于"偷工减料"，只选择性地审查部分文件而遗漏其他文件。
位置偏移——报告的问题常常与实际代码位置不匹配，行号或文件引用出现偏差。
质量不稳定——自然语言驱动的 Skills 难以调试，审查质量会因 prompt 的微小变化而大幅波动。

根本原因：纯语言驱动的架构缺乏对审查过程的硬约束。

核心设计：确定性工程 × Agent 混合

Open Code Review 的核心理念是将确定性工程与 agent 相结合，各自处理其最擅长的部分。

确定性工程——硬约束

对于绝不能出错的审查步骤，由工程逻辑（而非语言模型）来保证正确性：

精确的文件选择——准确判断哪些文件需要审查、哪些应被过滤，确保不遗漏任何重要变更。
智能文件打包——将相关文件分组到单个审查单元中（例如，message_en.properties 和 message_zh.properties 被打包在一起）。每个包作为一个子 agent 运行，拥有独立的上下文——这是一种分治策略，在非常大的变更集上也能保持稳定，并自然支持并发审查。
细粒度规则匹配——将审查规则与每个文件的特性相匹配，使模型的注意力高度集中，从源头消除信息噪声。与纯语言驱动的规则引导相比，基于模板引擎的规则匹配更加稳定和可预测。
外部定位与反思模块——独立的评论定位模块和评论反思模块，系统性地提高了 AI 反馈的位置准确性和内容准确性。

Agent——动态决策

Agent 的优势集中在最重要的地方——动态决策和动态上下文检索：

场景调优的 prompt——针对代码审查深度优化的 prompt 模板，在提高效果的同时减少 token 消耗。
场景调优的工具集——基于对大规模生产数据中工具调用轨迹的深入分析（包括调用频率分布、每个工具的重复率以及新工具对整个调用链的影响）提炼而成，从而形成一个比通用 agent 工具包更稳定、更可预测的专用工具集。

如何使用

CLI

安装

通过 NPM（推荐）

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

安装后，ocr 命令即可全局使用。

从 GitHub Release 下载

从 GitHub Releases 下载最新二进制文件：

# macOS (Apple Silicon)
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) — 将 ocr.exe 移动到 PATH 中的目录
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe

# Windows (ARM64) — 将 ocr.exe 移动到 PATH 中的目录
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe

从源码构建

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

快速开始

1. 配置 LLM

在审查代码之前，你必须配置一个 LLM。

# 选项 A：交互式配置
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

# 选项 B：环境变量（优先级最高）
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

配置存储在 ~/.opencodereview/config.json 中。

它也兼容 Claude Code 的环境变量（ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL），并会解析 ~/.zshrc / ~/.bashrc 中的这些导出项。

CC-Switch 用户注意：如果你使用启用了路由服务的 CC-Switch，可以将 llm.url 指向 CC-Switch 代理地址，无需额外配置：

对于 Claude 提供商：将 llm.url 设置为 http://127.0.0.1:15721

对于 CodeX 提供商：将 llm.url 设置为 http://127.0.0.1:15721/v1

根据你的提供商设置配置 llm.model

llm.auth_token 可以是任意值

extra_body 设置仍然适用

2. 测试连接

ocr llm test

3. 审查

cd your-project

# 工作区模式——审查所有已暂存、未暂存和未跟踪的变更
ocr review

# 分支范围——比较两个 ref
ocr review --from main --to feature-branch

# 单个提交
ocr review --commit abc123

与编码 Agent 集成

OCR 可以作为斜杠命令无缝集成到 AI 编码 agent 中，从而在你的 agent 工作流中直接进行代码审查。

选项 1：安装为 Skill

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

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

这会从 skills 注册表安装 open-code-review skill，该 skill 会教会你的编码 agent 如何调用 ocr 进行代码审查、按优先级对问题进行分类，并可选择性地应用修复。

选项 2：安装为 Claude Code 插件

对于 Claude Code，通过以下命令在 Claude Code 中安装命令插件：

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

这会注册 /open-code-review:review 斜杠命令，该命令运行 OCR 并自动过滤和修复问题。

选项 3：安装为 Codex 插件

对于本地 Codex，从此仓库安装 Open Code Review 插件：

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

对于本地检出或 fork：

codex plugin marketplace add .
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

这会注册一个运行本地 OCR CLI 的 Codex skill：

ocr review --audience agent

此集成不会更改 OCR 的内部 LLM 后端，也不需要为 Codex 配置 OpenAI Responses API endpoint。OCR 本身仍然需要按照 CLI 设置部分所述安装和配置 ocr CLI。

韩语指南：plugins/open-code-review/CODEX.ko-KR.md

选项 4：直接复制命令文件

为了快速设置而无需任何包管理器，只需复制命令文件即可在 Claude Code 中使用 /open-code-review 斜杠命令。

项目级别（通过 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 并配置 LLM。请参阅上面的安装和配置 LLM。

CI/CD 集成

OCR 可以集成到 CI/CD 流水线中，以自动化 Merge Request / Pull Request 上的代码审查。

CI 集成的核心命令：

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

--format json 标志输出机器可读的结果，适合在 CI 脚本中解析。

有关集成示例，请参阅 examples/ 目录：

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

命令

命令	别名	描述
`ocr review`	`ocr r`	开始代码审查
`ocr rules check <file>`	—	预览哪个审查规则适用于某个文件路径
`ocr config set <key> <value>`	—	设置配置值
`ocr llm test`	—	测试 LLM 连接
`ocr viewer`	`ocr v`	在 `localhost:5483` 上启动 WebUI 会话查看器
`ocr version`	—	显示版本信息

`ocr review` 标志

标志	简写	默认值	描述
`--repo`	—	当前目录	Git 仓库根目录
`--from`	—	—	源 ref（例如 `main`）
`--to`	—	—	目标 ref（例如 `feature-branch`）
`--commit`	`-c`	—	要审查的单个提交
`--preview`	`-p`	`false`	预览哪些文件将被审查，而不运行 LLM
`--format`	`-f`	`text`	输出格式：`text` 或 `json`
`--concurrency`	—	`8`	最大并发文件审查数
`--timeout`	—	`10`	并发任务超时时间（分钟）
`--audience`	—	`human`	`human`（显示进度）或 `agent`（仅摘要）
`--rule`	—	—	自定义 JSON 审查规则的路径
`--max-tools`	—	内置	每个文件的最大工具调用轮数；仅在大于模板默认值时生效
`--max-git-procs`	—	内置	最大并发 git 子进程数
`--tools`	—	—	自定义 JSON 工具配置的路径

示例

# 预览哪些文件将被审查（无 LLM 调用）
ocr review --preview
ocr review -c abc123 -p

# 使用默认设置审查工作区变更
ocr review

# 以更高并发度审查分支差异
ocr review --from main --to my-feature --concurrency 4

# 审查特定提交，输出详细 JSON
ocr review --commit abc123 --format json --audience agent

# 使用自定义审查规则
ocr review --rule /path/to/my-rules.json

# 预览哪个规则适用于某个文件
ocr rules check src/main/java/com/example/Foo.java
ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml

# 在浏览器中查看审查会话历史
ocr viewer
ocr viewer --addr :3000

查看器安全性

查看器通过 HTTP 提供会话 JSONL 内容（LLM 请求消息和响应）。它对每个请求强制执行 Host 头允许列表：回环名称（localhost、127.0.0.0/8、::1）和具体的绑定主机始终允许。通配符绑定（--addr :3000、--addr 0.0.0.0:3000）和其他非回环 Hostname 必须通过 OCR_VIEWER_ALLOWED_HOSTS 环境变量（逗号分隔）添加：

OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000

这可以阻止针对本地查看器的 DNS 重新绑定攻击。

审查规则

OCR 使用四层优先级链来解析审查规则。每一层采用"首次匹配即获胜"原则：如果文件路径匹配某个模式，则使用该规则；否则，它会回退到下一层。

优先级	来源	路径	描述
1（最高）	`--rule` 标志	用户指定的路径	CLI 显式覆盖
2	项目配置	`<repoDir>/.opencodereview/rule.json`	每个项目的规则，可以提交到 git
3	全局配置	`~/.opencodereview/rule.json`	用户范围的个人偏好
4（最低）	系统默认	内嵌的 `system_rules.json`	涵盖常见语言和文件类型的内置规则

规则文件格式

第 1-3 层共享相同的 JSON 格式：

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

path 支持 ** 递归匹配和 {java,kt} 花括号扩展。
在每一层内，规则按声明顺序评估——第一个匹配的获胜。
如果规则文件不存在，则静默跳过。

路径过滤

规则文件还支持 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 模式的文件仍会正常通过默认过滤器检查。
模式语法：支持 ** 递归匹配、* 单段匹配和 {a,b} 花括号扩展。匹配不区分大小写。

内置默认排除模式（过滤测试文件等——可通过 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

键	类型	示例
`llm.url`	string	`https://api.openai.com/v1/chat/completions`
`llm.auth_token`	string	`sk-xxxxxxx`
`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	在遥测中包含 prompt

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

环境变量

变量	用途
`OCR_LLM_URL`	LLM API endpoint URL
`OCR_LLM_TOKEN`	API 密钥 / 认证令牌
`OCR_LLM_MODEL`	模型名称
`OCR_USE_ANTHROPIC`	`true` = Anthropic, `false` = OpenAI

遥测

用于可观测性（span、指标）的 OpenTelemetry 集成。默认禁用。

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

设置 telemetry.content_logging 以在导出的数据中包含 LLM prompt 和响应。

贡献

请参阅 CONTRIBUTING.md 了解开发设置、编码指南以及如何提交 pull request。

Star 历史

许可证

译自 GitHub · 项目涌现 · 录于二〇二六年七月十五日