OpenCodeReview 教程 2026：阿里開源 AI Code Review CLI 怎麼安裝？Git Diff、程式掃描與 Claude/GPT 實測

為什麼「再下一個 Review Skill」解決不了審查

2026 年多數團隊的痛點不是「沒有 AI 審查」，而是審查入口綁在通用 Agent 上。你對 Claude Code 說「幫我 review 這個 PR」，它會讀一部分檔案、漏掉另一部分，評語行號偶發漂移，下次換一句提示詞，品質又抖一次。官方 README 把這類痛點寫得很直白：涵蓋不全、位置漂移、純自然語言 Skill 難除錯。

根因不是模型不夠聰明，而是純語言驅動的架構對審查過程沒有硬性約束。檔案該不該進這次審查、相關檔案要不要綁在一起、規則該落到哪一類檔案，這些步驟「絕不能錯」，卻被丟給同一次聊天。換 GPT 或換 Claude，只是換成另一種會漏檔案的方式。

非對稱結論是：分水嶺不在 Claude 或 GPT 誰比較強，而在審查入口是不是「確定性工程 + Agent」——檔案挑選、分束、規則比對由工程保證，模型只負責動態取證。 該升級的是入口（ocr review / ocr scan / CI），不是再裝一個更厚的 Review Skill。站內對「harness 是什麼」的概念拆解，見 Omnigent Agent Harness 完全搞懂；本篇只解決「怎麼把 OpenCodeReview 裝上、把 Git Diff 和掃描跑通、把 Claude 與 GPT 接上」。

OpenCodeReview 是什麼：Git Diff 與全量掃描

先歸類，再談指令。OpenCodeReview 不是又一個聊天視窗，而是同一套審查迴圈的兩種開啟方式。分類維度仍是入口、執行、上下文與適合人群。

官網與 npm 套件說明 把理念寫得很直白：確定性工程負責不該錯的步驟——精準選檔案、把相關檔案綁成一束（例如 message_en.properties 與 message_zh.properties）、依檔案特徵比對規則、再用外部定位與反思模組校正行號和內容。Agent 只做動態決策和動態取證：讀完整檔案、搜倉庫、看同一次變更裡的其他檔案。官方基準用 50 個開源倉庫、200 個真實 PR、10 種語言交叉標註，相對通用 Agent（含 Claude Code）宣稱更高 Precision / F1、約 1/9 token、更快完成，但 Recall 更低——這是刻意用精準度換雜訊，不是漏檢就等於失敗。

OCR vs Claude Code / Copilot / 人工

選型時若先問「Claude 強還是 GPT 強」，會錯過真正差異。把 OpenCodeReview、通用 Agent Skill、IDE 內建審查和人工放在同一張表上，按入口、執行、上下文與適合人群對齊。

多模型 coding harness 怎麼裝金鑰，見 Pi Coding Agent 安裝與多模型接入。那篇回答的是「怎麼換後端寫程式」；本篇回答的是「怎麼把審查入口從聊天框拆成可重現的 CLI」。

怎麼安裝與設定 LLM

前置條件

官方硬性要求 Git ≥ 2.41：diff 產生、程式搜尋和倉庫操作都走 Git。先 git --version，舊發行版升級後再裝 CLI。Node 不是唯一安裝路徑，但 npm 是文件推薦的預設。

npm install -g @alibaba-group/open-code-review
ocr version
ocr --help
which ocr

裝完 ocr 應在 PATH 裡。若回報 command not found，檢查 npm 全域 bin 是否進了 PATH，不要把「裝成功」理解成「已經能審查」——沒有 LLM 設定時，除 Delegation Mode 外會直接失敗。

其他安裝方式

CI 基礎映像和無頭環境可以用安裝腳本（封裝 GitHub Release 二進位檔，帶校驗）：

curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh
# OCR_INSTALL_DIR=/usr/local/bin（默认）
# OCR_VERSION=v1.2.3   # 可选：钉某个 release

不想裝 Node 時，從 GitHub Releases 拉靜態二進位檔；要改 OCR 本身再從原始碼建置（Go ≥ 1.25 + Make）。平台細節以 安裝指南 為準，版本號會變，指令形態比「某月某日的模型名」更穩。

先設定模型，再談審查

設定寫在 ~/.opencodereview/config.json。互動式最省事：ocr config provider 選內建或自訂供應商、填金鑰、選模型，然後自動跑連通性測試；之後用 ocr config model 換模型。腳本和 CI 用非互動 ocr config set。

ocr config provider    # 选 anthropic / openai / 自定义
ocr config model       # 为当前供应商选模型
ocr llm test           # 再测一次连通性
ocr llm providers      # 列出内置供应商

Git Diff 三種審查模式實測

安裝驗收不是 ocr version，而是在一個真實倉庫裡跑出第一條帶行號的意見。三種入口涵蓋本機改動、分支比對和單次提交。

cd your-project

# 工作区：暂存 + 未暂存 + 未跟踪
ocr review

# 分支：相对 merge-base 审 feature 相对 main 的变更
ocr review --from main --to feature-branch

# 单个 commit
ocr review --commit abc123

# 中断后续跑
ocr session list
ocr review --from main --to feature-branch --resume <session-id>

# 给宿主 Agent 或 CI 落盘
ocr review --format json --output result.json

工作區模式適合「改完還沒開 PR，先自己罵一遍」。分支模式適合 CI：base 用預設分支，head 用 PR 頭。單 commit 適合重播一次有問題的提交。大變更被拆成多個 bundle，每個 bundle 是隔離上下文的子 Agent，官方用這套分治壓住超大 changeset 的漏審。

第一次跑若回報 no valid LLM endpoint configured，說明設定鏈沒湊齊 (URL, token, model)。依官方 FAQ：寫 ~/.opencodereview/config.json，或匯出 OCR_LLM_URL / OCR_LLM_TOKEN / OCR_LLM_MODEL，或沿用已有 Claude Code 的 ANTHROPIC_*。OCR 取第一組完整三元組，不是最後一組——設定檔齊了，環境變數會被忽略。

ocr scan 全量掃描怎麼用

ocr review 回答「這次改了什麼」；ocr scan 回答「這個目錄現在安不安全 / 好不好懂」。沒有有意義的 diff 時——剛 clone 的陌生倉庫、要從零建立審查基準線、目錄幾乎沒提交——不要硬造一個空 commit 去騙 review。

ocr scan                          # 扫描整个仓库
ocr scan --path internal/agent    # 目录或具体文件
ocr scan --resume <session-id>    # 中断后恢复

掃描比 diff 貴：token 和時間都按「整份檔案」計，不是按「改了幾行」。預設先掃你真正要接手的子樹，而不是一上來掃整個倉庫的 vendor/ 和產生物。規則與路徑過濾見官方 Review Rules；先排除相依套件和產物，再談模型。

Claude 與 GPT 怎麼接、怎麼讀結果

內建供應商裡，anthropic 走 https://api.anthropic.com，金鑰環境變數 ANTHROPIC_API_KEY；openai 走 https://api.openai.com/v1，金鑰環境變數 OPENAI_API_KEY。未寫 providers.*.api_key 時回退到對應環境變數。已有 Claude Code 環境時，OCR 也會拾取 ANTHROPIC_*。

# Claude
ocr config set provider anthropic
ocr config set model claude-opus-4-6
ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY"
ocr llm test

# GPT（OpenAI）
ocr config set provider openai
ocr config set model gpt-4o
ocr config set providers.openai.api_key "$OPENAI_API_KEY"
ocr llm test

# 自定义 OpenAI 兼容网关
ocr config set provider my-gateway
ocr config set custom_providers.my-gateway.url https://gateway.internal.com/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.model llama-3-70b
ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY"

模型 ID 會隨供應商目錄變。官方範例裡出現過 claude-opus-4-6、gpt-4o；落地時以 ocr config model 列出的可選項為準，不要把部落格快照寫進正式環境。401 / 403 時先核對通訊協定：Anthropic 走 /v1/messages，OpenAI 相容走 /v1/chat/completions，llm.protocol / use_anthropic 必須和 URL 同一家族。

同一倉庫、同一 diff，換後端讀什麼

實測不要比「誰句子更長」。固定一個小 PR：一處空指標風險、一處明顯的測試缺失、一處風格雜訊。分別用 Claude 與 GPT 跑 ocr review --from main --to HEAD --format json --output out.json，看三件事：該報的缺陷有沒有行號對上、風格雜訊有沒有被壓住、token 與牆上時鐘是否進得了 CI 預算。官方基準的取向是高精度、低雜訊、低 token；若 GPT 更便宜但多報三倍 nit，CI 裡的人會關掉整條管線。

- name: Open Code Review
  uses: alibaba/open-code-review@main
  with:
    provider: openai
    model: gpt-4o
    api-key: ${{ secrets.OPENAI_API_KEY }}

也支援 GitLab CI、Gerrit、GitFlic。金鑰進倉庫 Secrets，不要寫進工作流程檔案。自建 macOS runner 與雲端 Mac 的分層，見 GitHub Actions macOS 自建 Runner 與雲端 Mac。

場景怎麼選

真正該問的不是「要不要裝 OpenCodeReview」，而是第一約束：要可重現的 diff 審查、要稽核沒有 diff 的目錄，還是只要聊天視窗裡的口頭意見。

推薦組合

允許工具疊加。OpenCodeReview 解決的是「可重現的審查入口」；它不負責給你一台不合上蓋的 Mac，也不負責替你付 Claude 或 GPT 的帳單。

• 個人日常組合：全域 ocr + ANTHROPIC_API_KEY 或 OPENAI_API_KEY + 工作區 ocr review。開 PR 前先跑一遍，規則檔案進倉庫。
• PR / CI 組合：ocr review --from base --to head --format json + 官方 GitHub Action + Secrets。失敗策略先「評論不阻斷」，誤報率穩定後再當硬門禁。
• 基準線稽核組合：第一次接手用 ocr scan --path 建問題清單，之後只對增量跑 review。不要每個 PR 整個倉庫掃描。
• 已有 Coding Agent 組合：本機繼續 Claude Code / Cursor 寫程式，審查走 ocr delegate 或 OCR 自管模型。寫與審分開，金鑰也可以分開。
• 最小驗證組合：只裝 CLI，只設一把金鑰，在一個小倉庫跑 ocr review 和工作區改動。四拍跑通（安裝→憑證→一次 review→一次 scan）再進 CI。

常見迷思

• 把 OCR 理解成 Claude Code 的免費克隆。它刻意把選檔案和行號從模型手裡拿走。你要的是審查涵蓋，不是又一個會改檔案的聊天視窗。
• 沒設 LLM 就怪「裝壞了」。除 Delegation Mode 外，必須有完整端點三元組。ocr llm test 不過，不要開始調 Git 參數。
• 用 scan 代替每一次 PR 審查。全量掃描貴，且會把歷史雜訊重新報一遍。增量用 review，基準線用 scan。
• 把部落格裡的模型 ID 寫死進 Action。目錄會變。Action 裡的 model 當成可改輸入，先在本機 ocr config model 驗證。
• 個人訂閱金鑰提交進 CI。CI 用倉庫 Secrets 或機器級 config.json（權限收緊）。公司程式不要指向未稽核閘道。
• 在會休眠的筆電上跑整個倉庫 scan。工作階段能 --resume，但牆上時鐘和帳單會很難看。長時間掃描放到常開節點。

落地步驟

1. 寫清不可妥協項：只要本機自審、只要 CI 評論，還是兩條都要；第一週是否必須同時接 Claude 與 GPT；CI 先評論還是直接阻斷。
2. 安裝 CLI 並做一次空跑：npm install -g @alibaba-group/open-code-review，ocr version，確認 PATH 與 Git ≥ 2.41。
3. 只接一把金鑰：ocr config provider 或 ocr config set，ocr llm test 通過再往下。
4. 在真實小 PR 上跑 ocr review：工作區或 --from/--to。驗收標準是「行號對得上、該報的報了」，不是「評語更長」。
5. 補一次 ocr scan --path：只掃你要接手的子樹，確認和 review 的分工：基準線 vs 增量。
6. 再決定第二家模型或 Delegation：同一 diff 換 Claude / GPT 對比誤報與費用；已有宿主 Agent 就試 ocr delegate。
7. 選定執行環境後進 CI：本機試用可以；夜間掃描與門禁放到常開雲端 Mac 或自建 runner，日誌去識別化，金鑰不進成品。

FAQ

OpenCodeReview 和 Claude Code 是什麼關係？

Claude Code 是 Anthropic 的官方 coding 工作流程，寫程式和口頭審查可以在同一個視窗。OpenCodeReview 是阿里開源的審查 CLI，模型可換成 Claude、GPT 或相容端點。它不替代「官方深度改檔案」，它替代的是「審查涵蓋和行號全靠提示詞」。

必須同時設定 Claude 和 GPT 嗎？

不必。一把金鑰就能跑通安裝驗收。第二把金鑰的意義是：同一套選檔案與規則，按費用和誤報換後端。沒有第二家帳單時，先不要為「對比評測」增加維運面。

ocr review 和 ocr scan 可以互相替代嗎？

不能當同一條指令用。review 吃 Git Diff，適合 PR 與本機改動；scan 吃整份檔案，適合無 diff 的稽核。用錯入口，不是模型不夠聰明，是你讓工程層看錯了輸入。

Windows 和無頭雲端 Mac 能裝嗎？

能。npm 全域套件跨平台；安裝腳本涵蓋 darwin / linux 的 amd64 與 arm64，Windows 用 Release 二進位檔或 npm。無頭機器用非互動 ocr config set 和 --format json，不要依賴 TUI。雲端 Mac 上更該先固化 Git、PATH 與 ~/.opencodereview 權限。

為什麼還要雲端 Mac？本機裝 npm 不夠嗎？

本機夠用來學指令。不夠用來跑夜間全量掃描、合上蓋後的 PR 門禁，以及和 Xcode / 簽名同一套環境的 CI。ocr 把模型解耦了，但 Git 與檔案工具仍然綁在那台正在跑行程的機器上。

總結

OpenCodeReview 的安裝教程，表面上是 npm、環境變數和 ocr review / ocr scan；真正要落地的是一條分層：確定性工程與模型分開，Git Diff 入口與全量掃描入口分開，互動設定與 CI 設定分開。2026 年 9 月能站得住的用法，是本機一把金鑰跑通 review，規則進倉庫，CI 用 Secrets 落地 JSON，scan 只用在基準線。

非對稱結論仍然成立：分水嶺不在 Claude 或 GPT 誰比較強，而在你能不能把審查入口做成硬性約束。先跑通一把金鑰的一次 ocr review，再加 scan 和第二家模型；需要執行面時，再把行程從會休眠的筆電挪到雲端 Mac。該升級的是入口、憑證與節點，不是再下一個 Review Skill。