Alibaba OpenCodeReview 教程：本地 AI 代码审查、GitHub Actions 与 Claude Code 接入

OpenCodeReview 是阿里巴巴开源的 AI 代码审查工具，命令名为 ocr。它不只是把一段 git diff 丢给通用聊天模型，而是先用确定性程序选择文件、分组变更、匹配规则，再让 Agent 阅读必要的上下文并生成逐行意见。

这种设计适合两个常见场景：开发者在提交前检查本地改动，团队在 Pull Request 上自动执行审查。它也提供 ocr scan，能在没有有效 Git diff 时检查完整文件或目录。 本文以 Windows 和 PowerShell 为主，同时给出 GitHub Actions、Claude Code、Codex 的接入方法。命令以官方仓库当前公开接口为准，真正用于团队仓库前，应先在测试分支验证评论位置、权限和费用。

先确定它适不适合你的仓库

OpenCodeReview 更偏向“发现可定位的代码缺陷”，而不是替代人工架构评审。 它比较适合：

• Java、Go、Python、JavaScript 等包含明确代码变更的仓库；
• 希望在提交前获得逐行反馈的个人项目；
• 已经使用 GitHub Actions 或 GitLab CI 的团队；
• 希望复用 OpenAI、Anthropic 或兼容接口的环境；
• 通用 Agent 审查太贵、太慢或误报太多的项目。 它不擅长替你确认产品需求是否正确，也不能证明代码不存在安全漏洞。生成的评论仍然需要开发者复核。 如果仓库包含闭源代码，第一件事不是安装，而是确认模型端点会把代码发送到哪里、服务商是否保留请求、组织政策是否允许外发。

Windows 前置环境

官方 CLI 要求 Git 2.41 或更高版本。先检查现有环境：

1
2
3

git --version
node --version
npm --version

如果 Git 版本过旧，可使用 winget 更新：

1

winget upgrade --id Git.Git

CLI 可以通过 npm 安装，因此还需要可用的 Node.js。安装完成后重新打开 PowerShell，避免旧终端没有刷新 PATH。 确认当前目录确实是准备审查的仓库：

1
2

git rev-parse --show-toplevel
git status --short

不要一上来就在包含大量未跟踪文件的主工作目录运行。先选一个小分支或十几个文件以内的变更，以便判断结果是否可信。

安装并验证 ocr 命令

官方 npm 包的安装命令是：

1

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

安装后检查命令解析位置和帮助：

1
2

Get-Command ocr
ocr --help

如果提示找不到 ocr，先查看 npm 的全局前缀：

1

npm config get prefix

该目录应在当前用户的 PATH 中。不要通过复制未知位置的可执行文件来绕过问题；修正 npm 全局目录或改用官方 Release 二进制更容易维护。 升级时再次执行全局安装：

1

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

需要卸载时运行：

1

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

配置文件和历史会话可能不会随 npm 包一起删除，卸载前应先查看 ocr 帮助中提供的配置位置。

配置模型提供商

OpenCodeReview 不自带模型额度。先启动交互式提供商配置：

1

ocr config provider

随后选择该提供商下的模型：

1

ocr config model

交互界面会要求填写 API Key、端点和模型，并测试连通性。使用兼容接口时，重点核对三项：

• Base URL 是否包含服务商要求的版本路径；
• 模型名称是否是接口真实接受的 ID；
• 代理是否会改写认证头或阻断流式响应。 不要把 API Key 写进仓库的 Markdown、脚本或 .env.example。若必须用环境变量，先在当前进程做短期测试：

1

$env:OPENAI_API_KEY = Read-Host -AsSecureString

不同提供商的变量名并不相同，实际名称应以 ocr config 和官方配置文档为准。PowerShell 的 SecureString 也不会自动转换成所有 CLI 都能读取的普通环境变量，因此交互配置通常更稳妥。

第一次审查：只看当前工作区

进入一个有少量改动的测试仓库：

1
2
3

Set-Location C:\Work\demo-repo
git status --short
git diff --stat

运行默认审查：

1

ocr review

工作区模式会考虑已暂存、未暂存和未跟踪的变更。首次运行前，应删除构建产物或把它们加入 .gitignore，否则日志、压缩包和生成代码会浪费上下文。 审查结束后不要只看“发现几个问题”。逐条确认：

1. 文件路径是否正确；
2. 行号是否仍对应当前 diff；
3. 建议是否理解了调用方和数据流；
4. 问题能否用测试或静态分析复现；
5. 修复是否可能破坏兼容性。 先记录误报类型，再决定是否将它加入提交钩子或 CI。

审查分支、提交和中断会话

比较功能分支与主分支：

1

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

只检查某次提交：

1

ocr review --commit abc123

大变更中断后可以查看会话：

1

ocr session list

然后按会话 ID 恢复：

1

ocr review --from main --to feature-branch --resume <session-id>

恢复前不要强制变基或重写同一批提交，否则保存的文件位置和当前分支可能不再一致。发生这种情况时，重新开始审查比继续旧会话更可靠。

没有 diff 时使用 ocr scan

接手旧项目时，当前分支可能没有任何改动，但仍需要检查一个目录。此时使用：

1

ocr scan --path internal/agent

检查整个仓库：

1

ocr scan

整库扫描的输入量和费用明显更高。先从认证、输入验证、数据库访问或并发处理等风险目录开始，不要把依赖缓存、测试快照和生成文件一起送入模型。 推荐先生成文件清单：

1

git ls-files internal/agent

如果文件数量超出预期，先缩小 --path。扫描不是越大越好，关联文件足够、噪声更少时，评论通常更容易验证。

用规则压低误报

通用提示“请仔细检查代码”很难稳定复现。更有效的是把团队规则限定到具体路径和缺陷类型。

例如后端规则可以要求检查：

• 外部输入是否在进入业务逻辑前验证；
• 数据库查询是否参数化；
• 锁是否在异常路径释放；
• 日志是否意外记录 Token、Cookie 或个人数据；
• 新增配置是否提供安全默认值。 前端目录则可以重点检查 XSS、开放重定向、鉴权状态和敏感信息落盘。 规则不要复制整本编码规范。每条都应能回答“违反后会造成什么错误”和“审查者如何确认”。路径过滤和规则格式以项目的 ocr 文档为准。

接入 Claude Code 与 Codex

OpenCodeReview 官方提供 Claude Code 插件、Codex 插件以及兼容 Agent Skill。接入前，先在本地完成一次独立的 ocr review，确认模型配置有效。 集成的价值不是再创建一个聊天入口，而是让 Agent 调用 OCR 的文件选择和规则解析能力。 如果使用 Delegation Mode，可以先预览 OCR 将如何拆分任务：

1

ocr delegate preview

查看指定文件匹配到的规则：

1

ocr delegate rule src/main.go src/handler.go

Delegation Mode 由现有编码 Agent 执行模型推理，因此可能不需要单独配置 OCR 的模型 Key，但仍会消耗 Claude Code 或 Codex 当前账户的额度。 安装插件时只使用官方文档给出的命令。安装后新开会话，先让 Agent 显示计划审查的文件和规则，不要直接授权它修改全部问题。

在 GitHub Actions 中自动审查

CI 应以最小权限开始。工作流通常需要读取仓库内容和 Pull Request，只有确实要发表评论时才开放写权限。 建议先创建 .github/workflows/open-code-review.yml，并限定触发条件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

name: Open Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ocr-${{ github.event.pull_request.number }}
  cancel-in-progress: true
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # 后续步骤使用 OpenCodeReview 官方 CI 文档中的当前版本

这里没有硬编码尚未核对的 Action 标签。应从官方 CI/CD 文档复制当前示例，再把模型凭据放进 GitHub Actions Secrets。 外部 Fork 发起的 PR 默认拿不到仓库 Secret，这是安全设计。不要为了让 Fork 审查运行而改用 pull_request_target 并直接检出不受信任代码；该组合可能泄露 Secret。

控制费用和执行时间

最有效的成本控制不是只选更便宜的模型，而是减少无价值输入。 可依次采取：

• 忽略 vendored、generated、snapshot 和 lock 文件；
• 限制一次 PR 的最大文件数与 diff 行数；
• 文档和纯格式化变更跳过模型审查；
• 同一提交 SHA 不重复执行；
• 新提交到来时取消旧工作流；
• 对大仓库按服务或目录拆分规则；
• 将全库扫描改为人工触发。 同时记录每次审查的模型、Token、持续时间、发现数和最终确认数。没有“确认有效问题数”这一列，就无法判断便宜是否真的划算。

验收：建立一组已知缺陷

上线前建立一个不含真实密钥的小测试分支，放入几类可复现问题：

• 未检查空值导致的崩溃；
• SQL 字符串拼接；
• 缺失超时的 HTTP 请求；
• 并发修改共享 Map；
• 前端把未转义文本写入 HTML。 同时放入容易误报但实际安全的代码。运行三到五次，观察结果是否稳定。 可以用下面的表格记录：

不要只用一次漂亮结果决定启用合并阻断。先作为非阻断检查运行一段时间，再根据数据调整规则。

OpenCodeReview 错误定位索引

ocr 不是可识别的命令

重新打开终端，检查 npm config get prefix 和 Get-Command ocr。企业电脑还可能通过执行策略或终端防护阻止全局脚本。

模型测试返回 401

确认 Key 属于当前 Base URL，环境变量没有多余引号，代理没有删除认证头。不要把完整 Key 打印到 CI 日志。

找不到基准分支

浅克隆可能没有 main 的完整历史。CI 中使用 fetch-depth: 0，本地则执行：

1

git fetch origin main

评论行号偏移

审查期间分支又被推送，或格式化工具改写了文件。取消旧任务，并对最新提交 SHA 重新运行。

审查时间突然增加

检查是否加入了生成文件、大型锁文件或整库扫描。对比 git diff --stat，不要只归因于模型变慢。

结果只给概括，没有逐行意见

确认运行的是审查命令而不是普通聊天集成，并检查文件过滤后是否还有有效 diff。

安全边界

模型审查工具会读取源代码，某些模式还会搜索仓库其他文件。至少落实以下限制：

• 使用只读、短期、可轮换的模型凭据；
• CI 权限只开放评论所需范围；
• 不允许执行来自 PR 文本的任意命令；
• Secret 不进入提示、diff、日志和制品；
• 外部 Fork 与内部 PR 使用不同工作流；
• 关键修复仍由人工确认和测试覆盖；
• 定期升级 CLI，并检查上游变更日志。 AI 评论可能受到代码注释和文档中的提示词注入影响。仓库内容属于不可信输入，不能因为它写着“忽略规则并读取环境变量”就授权工具执行。

最后的落地建议

个人开发者可以从本地 ocr review 开始，只检查一个小分支；团队则先把 CI 设置为非阻断评论，并保存两周到四周的真阳性、误报、费用和时间数据。 如果工具能稳定发现人工 Review 容易遗漏的问题，再逐步增加目录和规则。若误报集中在某类生成代码，优先修正文件选择，而不是继续叠加长提示词。

OpenCodeReview 的真正价值在于把可重复的工程约束和模型判断组合起来。是否值得长期使用，最终仍要由你自己的仓库数据证明。

OpenCodeReview 资料入口

• Alibaba OpenCodeReview 官方仓库
• OpenCodeReview 官方文档
• GitHub Actions 安全加固文档