什么是 Open Code Review？
Open Code Review 是一款由 AI 驱动的代码审查 CLI 工具。它最初是阿里巴巴集团内部的官方 AI 代码审查助手——在过去两年中，它为数万名开发者提供服务，并识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化成一个面向社区的开源项目。只需配置一个模型端点即可开始使用。
它能读取 Git 差异（diff），通过一个具备工具调用能力的智能体将变更文件发送给可配置的大语言模型，并生成具有行级精度的结构化审查意见。该智能体可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而不仅仅是表面层次的差异反馈。
为什么选择 Open Code Review？
通用型智能体存在的问题
如果你曾使用过像 Claude Code 结合技能（Skills）这类通用型智能体进行代码审查，很可能遇到过以下痛点：
- 覆盖不完整——在较大的变更集上，智能体倾向于“偷工减料”，只选择性审查部分文件而遗漏其他文件。
- 位置偏移——报告的问题经常与实际代码位置不符，行号或文件引用出现偏移。
- 质量不稳定——自然语言驱动的技能难以调试，审查质量会因提示词的微小变化而显著波动。
根本原因：纯粹的语言驱动架构缺乏对审查过程的硬性约束。
核心设计：确定性工程 × 智能体混合架构
Open Code Review 的核心理念是将确定性工程与智能体相结合，各自处理其最擅长的部分。
确定性工程——硬约束
对于绝不能出错的审查步骤，由工程逻辑（而非语言模型）来保证正确性：
- 精确的文件选择——准确判定哪些文件需要审查、哪些应被过滤，确保不遗漏任何重要变更。
- 智能文件打包——将相关文件分组到单个审查单元中（例如，`message_en.properties` 和 `message_zh.properties` 会被打包在一起）。每个打包单元作为一个拥有独立上下文的子智能体运行——这是一种分而治之的策略，能在非常大的变更集上保持稳定，并天然支持并发审查。
- 细粒度规则匹配——将审查规则与每个文件的特性相匹配，使模型的注意力高度集中，从源头消除信息噪声。与纯语言驱动的规则引导相比，基于模板引擎的规则匹配更加稳定和可预测。
- 外部定位与反思模块——独立的评论定位模块和评论反思模块，系统性地提升了 AI 反馈的位置准确性和内容准确性。
智能体——动态决策
该智能体的优势集中在最关键的地方——动态决策和动态上下文检索：
- 场景调优提示词——为代码审查深度优化的提示词模板，在提升效果的同时减少模型 token 消耗。
- 场景调优工具集——基于对大规模生产数据中工具调用轨迹的深度分析提炼而成，分析内容包括调用频率分布、每个工具的重复率以及新工具对整体调用链的影响——最终形成一套专为代码审查打造的工具集，比通用智能体工具包更稳定、更可预测。
使用方法
命令行界面
安装
通过 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) — move ocr.exe to a directory in your PATH curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe # Windows (ARM64) — move ocr.exe to a directory in your 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. 配置大语言模型
在审查代码之前，你必须配置一个大语言模型。
选项 A：交互式设置（推荐）
ocr config provider # Select a built-in provider or add a custom one ocr config model # Pick a model for the active provider
选项 B：手动配置
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 时，哪个 HTTP 头部承载 API 密钥。如果省略，默认为 `authorization`（Bearer token）。如果你使用标准的 `sk-ant-*` API 密钥，必须将其设置为 `x-api-key`：
ocr config set llm.auth_header x-api-key 支持的值：`x-api-key`、`authorization`（别名：`bearer`）。其他值将被拒绝并报错。
选项 C：环境变量（最高优先级）
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
它还与 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 # Workspace mode — review all staged, unstaged, and untracked changes ocr review # Branch range — compare two refs ocr review --from main --to feature-branch # Single commit ocr review --commit abc123
与编码智能体集成
OCR 可以作为斜杠命令无缝集成到 AI 编码智能体中，让你能够在智能体工作流中直接进行代码审查。
选项 1：作为技能安装
使用 npx 将 OCR 技能安装到你的项目中：
npx skills add alibaba/open-code-review --skill open-code-review
这会从技能注册表中安装 `open-code-review` 技能，该技能会教会你的编码智能体如何调用 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
对于本地检出或分支：
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 技能：
ocr review --audience agent
此集成不会更改 OCR 的内部大语言模型后端，也不需要为 Codex 配置 OpenAI Responses API 端点。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”。
CI/CD 集成
OCR 可以集成到 CI/CD 流水线中，以自动对合并请求/拉取请求进行代码审查。
CI 集成的核心命令：
ocr review \ --from "origin/main" \ --to "<commit_sha>" \ --format json
`--from` 标志接受一个分支引用（例如 `origin/main`）或提交 SHA 作为基准，而 `--to` 则接受一个提交 SHA 或分支引用作为目标头。在 CI 环境中，建议对 `--to` 使用提交 SHA，以便正确处理源分支在原始远程仓库中不存在的复刻 PR/MR。
`--format 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` | 在 localhost:5483 上启动 WebUI 会话查看器 |
| `ocr version` | — | 显示版本信息 |
`ocr review` 标志
| 标志 | 简写 | 默认值 | 描述 |
|---|---|---|---|
| `--repo` | — | 当前目录 | Git 仓库根目录 |
| `--from` | — | — | 源引用（例如 main） |
| `--to` | — | — | 目标引用（例如 feature-branch） |
| `--commit` | `-c` | — | 要审查的单个提交 |
| `--preview` | `-p` | false | 预览哪些文件将被审查，而不实际运行 LLM |
| `--format` | `-f` | text | 输出格式：text 或 json |
| `--concurrency` | — | 8 | 最大并发文件审查数 |
| `--timeout` | — | 10 | 并发任务超时时间（分钟） |
| `--audience` | — | human | human（显示进度）或 agent（仅摘要） |
| `--background` | `-b` | — | 审查的可选需求/业务上下文；使用 `--commit` 时会从提交信息中自动填充 |
| `--rule` | — | — | 自定义 JSON 审查规则的路径 |
| `--max-tools` | — | built-in | 每个文件的最大工具调用轮数；仅当大于模板默认值时生效 |
| `--max-git-procs` | — | built-in | 最大并发 Git 子进程数 |
| `--tools` | — | — | 自定义 JSON 工具配置的路径 |
示例
# Interactive provider and model setup ocr config provider ocr config model ocr llm providers # Preview which files will be reviewed (no LLM calls) ocr review --preview ocr review -c abc123 -p # Review workspace changes with default settings ocr review # Review branch diff with higher concurrency ocr review --from main --to my-feature --concurrency 4 # Review a specific commit with verbose JSON output ocr review --commit abc123 --format json --audience agent # Provide requirement context for more targeted review ocr review --background "Adding rate limiting to the login API" # Use custom review rules ocr review --rule /path/to/my-rules.json # Preview which rule applies to a file ocr rules check src/main/java/com/example/Foo.java ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml # View review session history in browser ocr viewer ocr viewer --addr :3000
查看器安全性
该查看器通过 HTTP 提供会话 JSONL 内容（大语言模型请求消息和响应）。它对每个请求强制执行 Host 头允许列表：回环名称（localhost、127.0.0.0/8、::1）和具体的绑定主机始终被允许。通配符绑定（`--addr :3000`、`--addr 0.0.0.0:3000`）以及其他非回环主机名必须通过 `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": "All new methods must validate required parameters for null values"
},
{
"path": "**/*mapper*.xml",
"rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
}
]
} - `path` 支持 `**` 递归匹配和 `{java,kt}` 花括号扩展。
- 在每一层内，规则按声明顺序评估——首次匹配生效。
- 如果规则文件不存在，则静默跳过。
路径过滤
规则文件还支持 `include` 和 `exclude` 字段，用于控制哪些文件进入审查范围：
{
"rules": [
{"path": "**/*.java", "rule": "Check for null safety"}
],
"include": ["src/main/**/*.java", "lib/**/*.kt"],
"exclude": ["**/generated/**", "vendor/**"]
} 过滤决策优先级（从高到低）：
| 步骤 | 条件 | 结果 |
|---|---|---|
| 1 | 文件是二进制文件 | 排除 |
| 2 | 路径匹配用户排除模式 | 排除 |
| 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
| 键 | 类型 | 示例 |
|---|---|---|
| provider | 字符串 | anthropic | openai | dashscope | deepseek | z-ai |
| providers.<name>.api_key | 字符串 | 特定提供商的 API 密钥 |
| providers.<name>.url | 字符串 | 提供商基础 URL 覆盖 |
| providers.<name>.protocol | 字符串 | anthropic | openai |
| providers.<name>.model | 字符串 | 该提供商的模型名称 |
| providers.<name>.auth_header | 字符串 | x-api-key | authorization |
| custom_providers.<name>.* | — | 与 providers.<name>.* 相同的字段 |
| llm.url | 字符串 | https://api.openai.com/v1/chat/completions |
| llm.auth_token | 字符串 | sk-xxxxxxx |
| llm.auth_header | 字符串 | 仅限 Anthropic：x-api-key | authorization |
| llm.model | 字符串 | claude-opus-4-6 |
| llm.use_anthropic | 布尔值 | true | false |
| language | 字符串 | English | Chinese（默认：Chinese） |
| telemetry.enabled | 布尔值 | true | false |
| telemetry.exporter | 字符串 | console | otlp |
| telemetry.otlp_endpoint | 字符串 | OTLP 收集器地址 |
| telemetry.content_logging | 布尔值 | 在遥测数据中包含提示词 |
环境变量优先级高于配置文件。
环境变量
| 变量 | 用途 |
|---|---|
| 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 |
遥测
用于可观测性的 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 提示词和响应。
贡献指南
请参阅 CONTRIBUTING.md 了解开发环境搭建、编码规范以及如何提交拉取请求。
Star 历史
许可证
Apache-2.0 — 版权所有 2026 Alibaba
关于
开源且免费——已在阿里巴巴规模下经受实战检验。混合架构代码审查工具：确定性流水线 + 大语言模型智能体，精确到行级的注释，内置经过微调的规则集（空指针异常、线程安全、跨站脚本攻击、SQL注入），兼容 OpenAI 与 Anthropic。
alibaba.github.io/open-code-review/
发布版本 51 个
v1.3.11
贡献者
编程语言
- Go 76.3%
- TypeScript 13.2%
- JavaScript 3.2%
- CSS 3.1%
- Shell 2.0%
- HTML 1.8%
- Makefile 0.4%
What is Open Code Review?
Open Code Review is an AI-powered code review CLI tool. It originated as Alibaba Group's internal official AI code review assistant — over the past two years, it has served tens of thousands of developers and identified millions of code defects. After thorough validation at massive scale, we incubated it into an open source project for the community. Simply configure a model endpoint to get started.
It reads Git diffs, sends changed files to a configurable LLM via an agent with tool-use capabilities, and generates structured review comments with line-level precision. The agent can read full file contents, search the codebase, inspect other changed files for context, and produce deep reviews — not just surface-level diff feedback.
Why Open Code Review?
The Problem with General-Purpose Agents
If you've used general-purpose agents like Claude Code with Skills for code review, you've likely encountered these pain points:
- Incomplete coverage — On larger changesets, agents tend to "cut corners," selectively reviewing only some files and missing others.
- Position drift — Reported issues frequently don't match the actual code location, with line numbers or file references drifting off target.
- Unstable quality — Natural-language-driven Skills are hard to debug, and review quality fluctuates significantly with minor prompt variations.
The root cause: a purely language-driven architecture lacks hard constraints on the review process.
Core Design: Deterministic Engineering × Agent Hybrid
Open Code Review's core philosophy is to combine deterministic engineering with an agent, each handling what it does best.
Deterministic Engineering — Hard Constraints
For review steps that must not go wrong, engineering logic — not the language model — guarantees correctness:
- Precise file selection — Determines exactly which files need review and which should be filtered, ensuring no important change is missed.
- Smart file bundling — Groups related files into a single review unit (e.g.,
message_en.propertiesandmessage_zh.propertiesare bundled together). Each bundle runs as a sub-agent with isolated context — a divide-and-conquer strategy that stays stable on very large changesets and naturally supports concurrent review. - Fine-grained rule matching — Matches review rules to each file's characteristics, keeping the model's attention sharply focused and eliminating information noise at the source. Compared to purely language-driven rule guidance, template-engine-based rule matching is more stable and predictable.
- External positioning and reflection modules — Independent comment-positioning and comment-reflection modules systematically improve both the location accuracy and content accuracy of AI feedback.
Agent — Dynamic Decision-Making
The agent's strengths are concentrated where they matter most — dynamic decisions and dynamic context retrieval:
- Scenario-tuned prompts — Prompt templates deeply optimized for code review, improving effectiveness while reducing token consumption.
- Scenario-tuned toolset — Distilled from deep analysis of tool-call traces in large-scale production data — including call frequency distributions, per-tool repetition rates, and the impact of new tools on the overall call chain — resulting in a purpose-built toolset that is more stable and predictable for code review than a generic agent toolkit.
How to Use
CLI
Install
Via NPM (Recommended)
npm install -g @alibaba-group/open-code-review
After installation, the ocr command is available globally.
From GitHub Release
Download the latest binary from 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) — move ocr.exe to a directory in your PATH curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe # Windows (ARM64) — move ocr.exe to a directory in your PATH curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe
From Source
git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr Quick Start
1. Configure LLM
You must configure an LLM before reviewing code.
Option A: Interactive setup (Recommended)
ocr config provider # Select a built-in provider or add a custom one ocr config model # Pick a model for the active provider
Option B: Manual config
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
Config is stored in ~/.opencodereview/config.json.
auth_header (optional): Controls which HTTP header carries the API key when using Anthropic. Defaults to authorization (Bearer token) if omitted. If you use a standard sk-ant-* API key, you must set it to x-api-key:
ocr config set llm.auth_header x-api-key Supported values: x-api-key, authorization (alias: bearer). Other values are rejected with an error.
Option C: Environment variables (highest priority)
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
It is also compatible with Claude Code environment variables (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL) and parses ~/.zshrc / ~/.bashrc for those exports.
Note for CC-Switch Users: If you are using CC-Switch with routing service enabled, you can point
llm.urlto the CC-Switch proxy address without additional configuration:
- For Claude provider: set
llm.urltohttp://127.0.0.1:15721- For Codex provider: set
llm.urltohttp://127.0.0.1:15721/v1- Set
llm.modelaccording to your provider settingsllm.auth_tokencan be any valueextra_bodysettings still apply
2. Test Connectivity
ocr llm test 3. Review
cd your-project # Workspace mode — review all staged, unstaged, and untracked changes ocr review # Branch range — compare two refs ocr review --from main --to feature-branch # Single commit ocr review --commit abc123
Integrate with Coding Agents
OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow.
Option 1: Install as a Skill
Use npx to install the OCR skill into your project:
npx skills add alibaba/open-code-review --skill open-code-review
This installs the open-code-review skill from the skills registry, which teaches your coding agent how to invoke ocr for code review, classify issues by priority, and optionally apply fixes.
Option 2: Install as a Claude Code Plugin
For Claude Code, install the command plugin through the following command in Claude Code:
/plugin marketplace add alibaba/open-code-review /plugin install open-code-review@open-code-review
This registers the /open-code-review:review slash command, which runs OCR and automatically filters and fixes issues.
Option 3: Install as a Codex Plugin
For local Codex, install the Open Code Review plugin from this repository:
codex plugin marketplace add alibaba/open-code-review codex /plugins
For a local checkout or fork:
codex plugin marketplace add .
codex
/plugins Install and enable Open Code Review, then start a new Codex thread and invoke it explicitly:
@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues
This registers a Codex skill that runs the local OCR CLI:
ocr review --audience agent
This integration does not change OCR's internal LLM backend and does not require configuring an OpenAI Responses API endpoint for Codex. OCR itself still requires the ocr CLI to be installed and configured as described in the CLI setup section.
Korean guide: plugins/open-code-review/CODEX.ko-KR.md
Option 4: Copy the Command File Directly
For a quick setup without any package manager, simply copy the command file to use the /open-code-review slash command in Claude Code.
Project-level (shared with team via 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
User-level (personal global use across all projects):
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
Prerequisite: All integration methods require the
ocrCLI to be installed and an LLM configured. See Install and Configure LLM above.
CI/CD Integration
OCR can be integrated into CI/CD pipelines to automate code review on Merge Requests / Pull Requests.
The core command for CI integration:
ocr review \ --from "origin/main" \ --to "<commit_sha>" \ --format json
The --from flag accepts a branch ref (e.g., origin/main) or commit SHA as the base, while --to accepts a commit SHA or branch ref as the head. In CI environments, using commit SHA for --to is recommended to correctly handle fork PRs/MRs where the source branch doesn't exist on the origin remote.
The --format json flag outputs machine-readable results suitable for parsing in CI scripts.
See the examples/ directory for integration examples:
github_actions/— GitHub Actions integration examplegitlab_ci/— GitLab CI integration example
Commands
| Command | Alias | Description |
|---|---|---|
ocr review | ocr r | Start a code review |
ocr rules check <file> | — | Preview which review rule applies to a file path |
ocr config provider | — | Interactive provider setup (built-in, custom, or manual) |
ocr config model | — | Interactive model selection for the active provider |
ocr config set <key> <value> | — | Set configuration values |
ocr llm test | — | Test LLM connectivity |
ocr llm providers | — | List built-in LLM providers |
ocr viewer | ocr v | Launch WebUI session viewer on localhost:5483 |
ocr version | — | Show version info |
ocr review Flags
| Flag | Shorthand | Default | Description |
|---|---|---|---|
--repo | — | current dir | Git repository root |
--from | — | — | Source ref (e.g., main) |
--to | — | — | Target ref (e.g., feature-branch) |
--commit | -c | — | Single commit to review |
--preview | -p | false | Preview which files will be reviewed without running the LLM |
--format | -f | text | Output format: text or json |
--concurrency | — | 8 | Max concurrent file reviews |
--timeout | — | 10 | Concurrent task timeout in minutes |
--audience | — | human | human (show progress) or agent (summary only) |
--background | -b | — | Optional requirement/business context for the review; auto-filled from commit message when using --commit |
--rule | — | — | Path to custom JSON review rules |
--max-tools | — | built-in | Max tool call rounds per file; only takes effect when greater than template default |
--max-git-procs | — | built-in | Max concurrent git subprocesses |
--tools | — | — | Path to custom JSON tools config |
Examples
# Interactive provider and model setup ocr config provider ocr config model ocr llm providers # Preview which files will be reviewed (no LLM calls) ocr review --preview ocr review -c abc123 -p # Review workspace changes with default settings ocr review # Review branch diff with higher concurrency ocr review --from main --to my-feature --concurrency 4 # Review a specific commit with verbose JSON output ocr review --commit abc123 --format json --audience agent # Provide requirement context for more targeted review ocr review --background "Adding rate limiting to the login API" # Use custom review rules ocr review --rule /path/to/my-rules.json # Preview which rule applies to a file ocr rules check src/main/java/com/example/Foo.java ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml # View review session history in browser ocr viewer ocr viewer --addr :3000
Viewer security
The viewer serves session JSONL contents (LLM request messages and responses) over HTTP. It enforces a Host-header allowlist on every request: loopback names (localhost, 127.0.0.0/8, ::1) and the concrete bind host are always allowed. Wildcard binds (--addr :3000, --addr 0.0.0.0:3000) and other non-loopback Hostnames must be added via the OCR_VIEWER_ALLOWED_HOSTS environment variable (comma-separated):
OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000
This blocks DNS-rebinding attacks against the local viewer.
Review Rules
OCR resolves review rules using a four-layer priority chain. Each layer uses first-match-wins: if a file path matches a pattern, that rule is used; otherwise it falls through to the next layer.
| Priority | Source | Path | Description |
|---|---|---|---|
| 1 (highest) | --rule flag | User-specified path | CLI explicit override |
| 2 | Project config | <repoDir>/.opencodereview/rule.json | Per-project rules, can be committed to git |
| 3 | Global config | ~/.opencodereview/rule.json | User-wide personal preferences |
| 4 (lowest) | System default | Embedded system_rules.json | Built-in rules covering common languages and file types |
Rule File Format
Layers 1–3 share the same JSON format:
{
"rules": [
{
"path": "force-api/**/*.java",
"rule": "All new methods must validate required parameters for null values"
},
{
"path": "**/*mapper*.xml",
"rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
}
]
} pathsupports**recursive matching and{java,kt}brace expansion.- Within each layer, rules are evaluated in declaration order — the first match wins.
- If a rule file does not exist, it is silently skipped.
Path Filtering
Rule files also support include and exclude fields to control which files enter the review scope:
{
"rules": [
{"path": "**/*.java", "rule": "Check for null safety"}
],
"include": ["src/main/**/*.java", "lib/**/*.kt"],
"exclude": ["**/generated/**", "vendor/**"]
} Filter decision priority (highest to lowest):
| Step | Condition | Result |
|---|---|---|
| 1 | File is binary | Excluded |
| 2 | Path matches user exclude pattern | Excluded |
| 3 | File extension not in supported list | Excluded |
| 4 | include is configured and path matches | Reviewed (skips step 5) |
| 5 | Path matches built-in default exclude pattern (test files, etc.) | Excluded |
| 6 | None of the above | Reviewed |
How it works:
includeandexcludefollow the same priority chain as review rules (--rule> project config > global config). The highest-priority layer that has include/exclude configured takes effect as a whole — patterns are not merged across layers.excludealways wins overinclude— a file matching both is excluded.includeacts as a bypass for built-in default exclude patterns (e.g., test files), not as an exclusive allowlist — files not matching anyincludepattern still proceed through the default filter checks normally.- Pattern syntax: supports
**recursive matching,*single-segment matching, and{a,b}brace expansion. Matching is case-insensitive.
Built-in default exclude patterns (filters test files, etc. — can be overridden with 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/**
Configuration Reference
Config file: ~/.opencodereview/config.json
| Key | Type | Example |
|---|---|---|
provider | string | anthropic | openai | dashscope | deepseek | z-ai |
providers.<name>.api_key | string | Provider-specific API key |
providers.<name>.url | string | Provider base URL override |
providers.<name>.protocol | string | anthropic | openai |
providers.<name>.model | string | Model name for the provider |
providers.<name>.auth_header | string | x-api-key | authorization |
custom_providers.<name>.* | — | Same fields as providers.<name>.* |
llm.url | string | https://api.openai.com/v1/chat/completions |
llm.auth_token | string | sk-xxxxxxx |
llm.auth_header | string | Anthropic only: x-api-key | authorization |
llm.model | string | claude-opus-4-6 |
llm.use_anthropic | boolean | true | false |
language | string | English | Chinese (default: Chinese) |
telemetry.enabled | boolean | true | false |
telemetry.exporter | string | console | otlp |
telemetry.otlp_endpoint | string | OTLP collector address |
telemetry.content_logging | boolean | Include prompts in telemetry |
Environment variables take precedence over the config file.
Environment Variables
| Variable | Purpose |
|---|---|
OCR_LLM_URL | LLM API endpoint URL |
OCR_LLM_TOKEN | API key / auth token |
OCR_LLM_AUTH_HEADER | Anthropic auth header (x-api-key or authorization) |
OCR_LLM_MODEL | Model name |
OCR_USE_ANTHROPIC | true = Anthropic, false = OpenAI |
Telemetry
OpenTelemetry integration for observability (spans, metrics). Disabled by default.
ocr config set telemetry.enabled true ocr config set telemetry.exporter otlp ocr config set telemetry.otlp_endpoint localhost:4317
Set telemetry.content_logging to include LLM prompts and responses in exported data.
Contributing
See CONTRIBUTING.md for development setup, coding guidelines, and how to submit pull requests.
Star History
License
Apache-2.0 — Copyright 2026 Alibaba
About
Open-source & free — Battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in fine-tuned ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.
alibaba.github.io/open-code-review/
Releases 51
v1.3.11