alibaba/open-code-review: review code chính xác — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
alibaba/open-code-review là CLI review code bằng AI, kết hợp pipeline xác định với agent LLM để phân tích diff và tạo nhận xét đến từng dòng. Công cụ hỗ trợ nhiều ngôn ngữ, các nhóm lỗi như NPE, thread-safety, XSS và SQL injection. Cài bản CLI khá đơn giản bằng npm, nhưng bạn cần Git và cấu hình model hoặc dùng Delegation Mode.
alibaba/open-code-review là công cụ CLI dùng AI để review code trong repository. Công cụ đọc Git diff, gửi các file thay đổi đến model LLM đã cấu hình, sau đó tạo nhận xét có cấu trúc và trỏ chính xác đến dòng code liên quan.
Điểm đáng giá là repo không giao toàn bộ quy trình cho model. Phần chọn file, gom nhóm file, áp dụng rule và định vị nhận xét được xử lý bằng các thành phần xác định. Agent được dùng cho việc cần suy luận và đọc thêm ngữ cảnh. Vì vậy, công cụ phù hợp với dev muốn giảm cảnh báo sai, review changeset lớn ổn định hơn và đưa kiểm tra code vào quy trình làm việc hoặc CI/CD.
Repo hiện có khoảng 50193 sao và 3726 fork. Dự án dùng Go, phát hành CLI npm với tên @alibaba-group/open-code-review, và có giấy phép Apache-2.0.
alibaba/open-code-review
Công cụ CLI dùng AI để review code theo diff hoặc quét toàn bộ file, tạo nhận xét chính xác đến từng dòng.
I.Open Code Review làm được gì
A.Review thay đổi theo nhiều cách
Bạn có thể review toàn bộ thay đổi đang có trong workspace, review khoảng thay đổi giữa hai branch hoặc review một commit cụ thể. Cách này phù hợp với cả công việc hằng ngày của một dev lẫn việc kiểm tra một pull request trước khi gửi cho nhóm.
Khi chạy ở workspace mode, công cụ xem các thay đổi đã stage, chưa stage và file chưa được theo dõi. Bạn không phải tự gom danh sách file trước khi bắt đầu.
B.Nhận xét đến cấp dòng
Kết quả review được tạo theo dạng nhận xét có cấu trúc và gắn với vị trí cụ thể trong code. Điều này giúp bạn mở đúng file, đúng dòng để kiểm tra và sửa lỗi, thay vì phải đọc một báo cáo chung chung rồi tự tìm vị trí vấn đề.
C.Đọc thêm ngữ cảnh trong repository
Agent có thể đọc toàn bộ nội dung file, tìm kiếm trong codebase, kiểm tra các file thay đổi khác và dùng ngữ cảnh đó để đưa ra review sâu hơn. Công cụ không chỉ nhìn vài dòng diff rồi đoán ý định của code.
Đây là điểm hữu ích khi một lỗi chỉ lộ ra khi nhìn cả hàm, class, module hoặc file cấu hình liên quan.
D.Quét cả file hoặc thư mục không có diff
Lệnh ocr scan cho phép review toàn bộ file, không phụ thuộc vào lịch sử Git hay diff. Bạn có thể quét cả repository, một thư mục hoặc một số file cụ thể.
Tính năng này phù hợp khi bạn tiếp nhận một codebase cũ, muốn audit một thư mục chưa có thay đổi hoặc cần kiểm tra nhanh một file hoàn chỉnh.
E.Kết hợp pipeline xác định với agent
Công cụ dùng logic xác định để chọn đúng file cần review, lọc file và gom các file liên quan thành từng nhóm. Mỗi nhóm có thể được xử lý như một sub-agent với ngữ cảnh riêng.
Thiết kế này giúp changeset lớn dễ kiểm soát hơn. Ví dụ, các file bản dịch liên quan có thể được gom chung để model không xem từng file một cách rời rạc.
F.Tập trung vào rule phù hợp
Open Code Review có ruleset đa ngôn ngữ tích hợp, bao gồm các nhóm lỗi như null pointer exception, thread-safety, XSS và SQL injection. Rule được ghép với đặc điểm của file để giảm thông tin thừa và giúp model tập trung hơn.
Mô tả dự án cũng nêu khả năng tương thích với endpoint OpenAI và Anthropic. Bạn cần cấu hình provider và model trước khi dùng chế độ OCR gọi model.
G.Tiết kiệm token và giảm nhiễu
Theo benchmark được README mô tả, công cụ ưu tiên precision hơn recall. So với agent đa dụng dùng cùng model, Open Code Review được mô tả là đạt precision và F1 cao hơn, dùng khoảng một phần chín số token và hoàn thành review nhanh hơn; đổi lại recall thấp hơn.
Ý nghĩa thực tế là báo cáo có thể ít cảnh báo sai hơn, nhưng bạn không nên xem đây là cam kết tìm được mọi lỗi trong code.
H.Có chế độ Delegation
Trong Delegation Mode, host coding agent thực hiện review bằng model và thông tin xác thực mà host đã cấu hình. OCR vẫn phụ trách chọn file và phân giải rule, nhưng bạn không cần cấu hình LLM riêng trong OCR.
Chế độ này hữu ích nếu bạn đã dùng một coding agent có sẵn model và muốn tận dụng cấu hình hiện tại.
II.Cần chuẩn bị gì
Bạn cần Git phiên bản 2.41 trở lên. README nói Open Code Review dùng Git để tạo diff, tìm kiếm code và thực hiện các thao tác trên repository.
Bản CLI được cài qua npm. Dữ liệu package được cung cấp cho repo yêu cầu Node.js từ phiên bản 14 trở lên. Bạn cũng cần npm để chạy lệnh cài đặt global.
Nếu dùng chế độ OCR-managed, bạn cần một LLM provider và model đã cấu hình. Lệnh cấu hình có giao diện tương tác để chọn provider, nhập API key và chọn model. Yêu cầu xác thực cụ thể phụ thuộc provider.
Nếu dùng provider tùy chỉnh, endpoint, biến môi trường hoặc cấu hình nâng cao, README chỉ dẫn xem tài liệu Configuration của dự án. Phần tư liệu được cung cấp chưa liệt kê tên biến môi trường hay giá trị cụ thể, nên không nên tự đoán.
Nếu dùng Delegation Mode, bạn cần host coding agent đã có model và thông tin xác thực. Theo README, chế độ này không cần cấu hình LLM hoặc credential riêng trong OCR.
README chưa ghi yêu cầu GPU hay phần cứng đặc biệt. Tư liệu cũng chưa xác nhận chi tiết các hệ điều hành được hỗ trợ. Repo có install.ps1 và install.sh, nhưng chỉ riêng tên file chưa đủ để kết luận mọi phiên bản Windows hoặc Linux đều được hỗ trợ.
API key và thông tin xác thực model có thể phát sinh chi phí theo provider.
Chỉ nhập key vào giao diện hoặc cấu hình của provider mà bạn tin cậy.
Không đưa key vào source code, diff hoặc file chia sẻ cùng repository.
III.Cài đặt từng bước
- Kiểm tra môi trườngĐảm bảo có Git >= 2.41, Node.js >= 14 và npm
- Cài CLICài gói @alibaba-group/open-code-review ở phạm vi global
- Cấu hình modelChọn provider, nhập key và chọn model bằng lệnh ocr config
- Review lần đầuChạy ocr review trong một project Git có thay đổi
- Đọc kết quảXem nhận xét theo dòng hoặc lưu kết quả dạng JSON
A.Kiểm tra công cụ cần thiết
Mở Terminal hoặc PowerShell. Bạn nên chạy các lệnh từ cửa sổ terminal của máy mình, không chạy trong trình nhập code của ứng dụng khác. Trước hết, kiểm tra Git và Node.js đã có chưa.
git --version
node --version
npm --versionGit cần đạt phiên bản 2.41 trở lên. Node.js cần đạt phiên bản 14 trở lên theo yêu cầu của package. Nếu một lệnh không tồn tại, hãy cài công cụ tương ứng trước khi tiếp tục. README được cung cấp không ghi lệnh cài Git hoặc Node.js cho từng hệ điều hành.
B.Cài Open Code Review
Cài package npm ở phạm vi global để lệnh ocr có thể gọi từ mọi thư mục.
npm install -g @alibaba-group/open-code-reviewSau khi cài xong, README cho biết lệnh ocr sẽ có sẵn trên hệ thống. Nếu terminal báo không tìm thấy ocr, thường là thư mục chứa npm global chưa nằm trong PATH hoặc terminal đang mở chưa nhận thay đổi PATH. Hãy kiểm tra lại cách npm cấu hình executable trên máy của bạn và mở terminal mới.
README cũng nêu các cách cài khác như install script, binary từ GitHub Release và cài từ source. Tuy nhiên, phần tư liệu được cung cấp không chép các lệnh cụ thể cho những cách đó. Bạn cần xem mục Installation trong tài liệu của dự án hoặc các file install.sh, install.ps1, Makefile và go.mod trong repo.
C.Cấu hình provider và model
Nếu để OCR trực tiếp gọi model, hãy chạy hai lệnh sau.
ocr config provider
ocr config modelLệnh thứ nhất mở giao diện chọn một provider tích hợp hoặc thêm provider tùy chỉnh. Giao diện sẽ hướng dẫn bạn nhập API key nếu provider yêu cầu. Lệnh thứ hai dùng để chọn model cho provider đang hoạt động.
Sau khi cấu hình, giao diện sẽ tự kiểm tra kết nối. Nếu chưa có key, chọn nhầm provider hoặc model không thuộc provider đang hoạt động, bước kiểm tra kết nối có thể thất bại. Hãy đọc kỹ tên provider và model trước khi xác nhận.
Có một điểm dễ nhầm: ocr review, lệnh /open-code-review:review và skill open-code-review dùng cấu hình provider riêng của OCR. Chúng không dùng thông tin đăng nhập Team hoặc Pro của Claude Code.
Nếu muốn để coding agent hiện tại tự gọi model, hãy dùng Delegation Mode. Theo README, chế độ này dùng model và xác thực của host agent nên không cần cấu hình LLM riêng trong OCR.
D.Chạy review workspace đầu tiên
Đi vào thư mục project Git có thay đổi rồi chạy review.
cd your-project
ocr reviewyour-project chỉ là tên minh họa. Bạn cần thay bằng đường dẫn hoặc tên thư mục project thật trên máy. Workspace mode sẽ review các thay đổi đã staged, chưa staged và file chưa được theo dõi.
Nếu bạn muốn review một khoảng branch, dùng merge-base mode.
ocr review --from main --to feature-branchLệnh này review các thay đổi của feature-branch kể từ lúc branch này tách khỏi main. Hãy thay tên branch bằng tên thực tế trong repository.
Để review một commit cụ thể, dùng mã commit.
ocr review --commit abc123abc123 là ví dụ. Bạn cần thay bằng mã commit muốn kiểm tra.
E.Quét toàn bộ file hoặc lưu kết quả
Khi không có diff đáng kể hoặc muốn audit code hiện có, dùng ocr scan.
ocr scan
ocr scan --path internal/agentLệnh đầu tiên quét toàn bộ repository. Lệnh thứ hai quét thư mục hoặc file theo path được chỉ định. Tư liệu nói không cần Git history cho full-file scan, nên đây là lựa chọn phù hợp khi bạn muốn kiểm tra nội dung hiện tại thay vì chỉ xem thay đổi.
Nếu muốn đưa kết quả cho một AI host agent hoặc xử lý tiếp bằng công cụ khác, lưu kết quả dạng JSON.
ocr review --format json --output result.jsonLệnh này tạo file result.json trong thư mục làm việc hiện tại theo ví dụ của README. Hãy chú ý file kết quả có thể chứa nội dung code hoặc thông tin nhạy cảm; chỉ chia sẻ nó với nơi được phép.
F.Tiếp tục một phiên bị gián đoạn
Nếu review khoảng branch hoặc full-file scan bị gián đoạn, xem danh sách session trước.
ocr session list
ocr review --from main --to feature-branch --resume <session-id>
ocr scan --resume <session-id>Thay <session-id> bằng ID thật được hiển thị từ lệnh đầu tiên. Không gõ nguyên dấu ngoặc nhọn. Resume giúp tiếp tục phiên thay vì bắt đầu lại toàn bộ tác vụ.
G.Dùng Delegation Mode
Nếu bạn đã có coding agent được cấu hình model, xem trước rule và các file được chọn bằng các lệnh sau.
ocr delegate preview
ocr delegate rule src/main.go src/handler.goocr delegate preview giúp bạn xem kế hoạch hoặc phạm vi delegation. Lệnh ocr delegate rule cho phép kiểm tra rule áp dụng cho các file được nêu. README không cung cấp mẫu đầu ra chi tiết, vì vậy hãy đối chiếu những gì terminal hiển thị với file và rule bạn mong muốn.
IV.Kiểm tra đã chạy được chưa
Cài đặt được xem là đúng khi lệnh ocr có thể gọi sau khi npm cài xong. Dấu hiệu rõ nhất là các lệnh ocr config provider, ocr config model, ocr review hoặc ocr scan mở được giao diện hay bắt đầu xử lý thay vì báo không tìm thấy command.
Với cấu hình OCR-managed, bước cấu hình thành công khi giao diện cho phép chọn provider, nhập API key, chọn model và tự kiểm tra kết nối. Sau đó, chạy ocr review trong project có thay đổi. Kết quả mong đợi là các nhận xét review có cấu trúc và vị trí dòng cụ thể.
Với full-file scan, ocr scan phải bắt đầu quét repository hoặc path được chọn. Với output JSON, kiểm tra file result.json đã được tạo và có kết quả review.
Nếu review bị ngắt, ocr session list phải hiển thị session để bạn lấy ID và chạy lại bằng --resume. Nếu dùng Delegation Mode, hãy kiểm tra preview và rule trước khi để host agent thực hiện review.
V.Dùng vào việc thật
A.Dev muốn kiểm tra thay đổi trước khi gửi pull request
Một dev vừa sửa nhiều file trên branch tính năng. Trước khi gửi review cho đồng đội, bạn mở terminal tại project rồi chạy:
cd your-project
ocr reviewCông cụ sẽ xem các thay đổi staged, unstaged và untracked trong workspace. Bạn dùng các nhận xét theo dòng để sửa lỗi logic, lỗi bảo mật hoặc vấn đề về tính an toàn luồng trước khi commit hoặc mở pull request.
B.Nhóm muốn so sánh branch tính năng với main
Một nhóm phát triển đã hoàn thành branch feature-branch và muốn kiểm tra toàn bộ phần khác biệt so với main. Người phụ trách chạy:
ocr review --from main --to feature-branchKết quả tập trung vào phần thay đổi kể từ lúc branch tách khỏi main. Cách này phù hợp hơn việc chỉ review file đang mở, vì công cụ có thể chọn và gom các file liên quan trong cả khoảng thay đổi.
C.Dev nhận một repository cũ cần audit
Một dev mới tiếp quản codebase không có diff hữu ích hoặc chưa biết phần nào có rủi ro. Thay vì tạo thay đổi giả để lấy diff, bạn có thể quét toàn bộ repository:
ocr scanNếu đã xác định module cần xem trước, giới hạn phạm vi bằng:
ocr scan --path internal/agentKết quả giúp lập danh sách vấn đề cần đọc kỹ hơn trong codebase. Đây là review toàn file, không phải lời khẳng định rằng mọi lỗi đều được phát hiện.
D.Nhóm muốn lưu báo cáo để xử lý tiếp
Một nhóm cần chuyển kết quả review cho hệ thống nội bộ hoặc cho AI host agent. Người phụ trách chạy:
ocr review --format json --output result.jsonFile JSON giúp lưu kết quả theo định dạng máy đọc được. Nhóm có thể dùng nó làm đầu vào cho bước xử lý tiếp theo, đồng thời dễ lưu lại kết quả của một lần review. Trước khi chia sẻ, hãy kiểm tra file có chứa source code, secret hoặc dữ liệu nội bộ hay không.
Review tốt là tìm đúng vấn đề, đúng dòng và đủ ngữ cảnh để sửa.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Terminal báo không tìm thấy lệnh ocr
Nguyên nhân thường là package chưa được cài global thành công hoặc thư mục binary global của npm chưa có trong PATH. Chạy lại lệnh cài đặt, kiểm tra npm không báo lỗi và mở một terminal mới. README xác nhận sau khi cài, command ocr phải có sẵn globally.
B.Git không đủ phiên bản hoặc không ở trong repository
Open Code Review yêu cầu Git từ 2.41 trở lên và dựa vào Git để tạo diff. Nếu Git cũ, hãy nâng cấp Git; nếu chạy lệnh ở sai thư mục, hãy dùng cd để vào project Git trước khi chạy ocr review.
C.Chưa cấu hình provider hoặc model
ocr review cần LLM configuration trừ khi bạn dùng Delegation Mode. Chạy ocr config provider, chọn provider và nhập thông tin được yêu cầu, sau đó chạy ocr config model để chọn model. Nếu không muốn cấu hình riêng trong OCR, dùng host agent đã có model và Delegation Mode.
D.Kiểm tra kết nối model thất bại
Hãy kiểm tra provider, API key, model đang chọn và endpoint tùy chỉnh nếu bạn dùng provider riêng. Giao diện cấu hình có bước tự kiểm tra kết nối, nên hãy đọc thông báo tại bước này trước khi chạy review. Không đưa API key vào command, source code hoặc file kết quả nếu không cần.
E.Review bị dừng giữa chừng
Xem các session bằng ocr session list. Với review branch, chạy lại lệnh có --resume <session-id>; với full-file scan, dùng ocr scan --resume <session-id>. Nếu dùng sai ID hoặc để nguyên dấu ngoặc nhọn, lệnh sẽ không tiếp tục được.
VII.Có nên dùng không
Nên dùng nếu bạn cần một CLI review code có thể chạy trên diff, branch, commit hoặc toàn bộ file; muốn nhận xét đến cấp dòng; và muốn kết hợp rule xác định với khả năng suy luận của LLM. Các nhóm làm nhiều ngôn ngữ cũng có lợi từ ruleset tích hợp cho NPE, thread-safety, XSS và SQL injection. Khả năng xuất JSON, resume session và Delegation Mode giúp công cụ phù hợp với workflow tự động hóa.
Điểm mạnh lớn nhất là cách thiết kế hybrid. Pipeline đảm nhiệm việc chọn file, gom ngữ cảnh và định vị bình luận; agent đảm nhiệm việc đọc, tìm kiếm và suy luận. Benchmark trong README cũng cho thấy dự án ưu tiên precision, ít nhiễu và chi phí token thấp hơn trong điều kiện so sánh được mô tả.
Giới hạn là công cụ vẫn phụ thuộc vào LLM provider hoặc host coding agent, nên chất lượng và chi phí còn phụ thuộc cấu hình model. Recall thấp hơn agent đa dụng theo benchmark của README, vì vậy không nên coi kết quả là kiểm định bảo mật tuyệt đối. Tư liệu được cung cấp cũng chưa nêu chi tiết hỗ trợ từng hệ điều hành, chi phí provider, yêu cầu GPU hay toàn bộ cách cài từ source.
Bạn nên chọn công cụ khác nếu cần một trình phân tích tĩnh hoàn toàn không dùng model, cần bảo đảm mọi lỗi đều được phát hiện, hoặc tổ chức không thể gửi source code đến endpoint LLM. Với trường hợp đó, hãy cân nhắc công cụ static analysis nội bộ hoặc pipeline đã được phê duyệt. Nếu nhóm đã có coding agent và muốn tránh cấu hình thêm API key, hãy thử Delegation Mode trước.
Câu hỏi thường gặp
Open Code Review có miễn phí không?
Repo dùng giấy phép Apache-2.0. Tuy nhiên, README không cung cấp thông tin đầy đủ về chi phí sử dụng các LLM provider. API key của provider có thể phát sinh chi phí theo chính sách của provider đó.
Có cần GPU để chạy không?
Tư liệu được cung cấp không nêu yêu cầu GPU hay phần cứng đặc biệt. Công cụ gọi model qua provider hoặc dùng model của host coding agent, nên chưa có cơ sở để khẳng định cần GPU cục bộ.
Có chạy được trên Windows không?
Repo có file `install.ps1`, nhưng README được cung cấp không xác nhận đầy đủ các hệ điều hành được hỗ trợ. Vì vậy chưa thể kết luận mọi phiên bản Windows đều chạy được; bạn nên xem tài liệu Installation và file cài đặt trong repo.
Có cần API key riêng không?
Nếu dùng chế độ OCR-managed với `ocr review`, bạn cần cấu hình provider, model và thông tin xác thực theo yêu cầu của provider. Nếu dùng Delegation Mode, README nói không cần credential riêng trong OCR vì host coding agent dùng model và xác thực đã có.
Open Code Review có hỗ trợ OpenAI và Anthropic không?
Mô tả của tác giả nêu công cụ tương thích với OpenAI và Anthropic. README cũng cho phép chọn provider tích hợp hoặc thêm provider tùy chỉnh, nhưng không liệt kê chi tiết mọi endpoint hay model.
Công cụ có review được cả repository không có diff không?
Có. Lệnh `ocr scan` review toàn bộ file và không cần Git history. Bạn có thể quét toàn repository hoặc giới hạn bằng `ocr scan --path`.
Kết quả review có bảo đảm tìm được mọi lỗi không?
Không. README mô tả benchmark của công cụ ưu tiên precision hơn recall, nghĩa là giảm cảnh báo sai nhưng có thể bỏ sót một số vấn đề. Bạn vẫn nên kết hợp kết quả AI với review của con người và các kiểm tra phù hợp khác.


