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 安全加固文件