Alibaba Open Code Review

1. Open Code Review là gì?

Open Code Review (lệnh gõ tắt là ocr) là công cụ dùng AI để "soát lỗi" code. Bạn vừa sửa code xong, chạy một lệnh, nó đọc phần bạn thay đổi, gửi cho một mô hình AI và trả về danh sách nhận xét chỉ đúng từng dòng: chỗ nào có thể gây lỗi, chỗ nào có nguy cơ bảo mật. Công cụ này vốn là trợ lý soát code nội bộ của Alibaba, sau đó được mở mã nguồn theo giấy phép Apache-2.0.

Nói thẳng: đây là công cụ dòng lệnh cho lập trình viên. Nó không có cửa sổ bấm chuột, và chỉ có ích khi bạn có code nằm trong Git (công cụ quản lý phiên bản code). Phần mềm miễn phí; tiền (nếu có) là tiền gọi mô hình AI mà bạn tự cấu hình. Có một ngoại lệ: "Delegation Mode" cho phép dùng luôn gói thuê bao của trợ lý lập trình bạn đang có (Claude Code, Codex, Cursor…) mà không cần khóa API riêng.

Hợp với bạn nếu:

• Bạn viết code và muốn có người soát lại trước khi gửi cho đồng đội.
• Bạn đang dùng Claude Code, Codex, Cursor hoặc Kimi Code và muốn thêm bước review chặt chẽ hơn.
• Bạn cần soát lỗi tự động trong quy trình CI/CD (hệ thống tự kiểm tra code khi đẩy lên).

Chưa hợp nếu:

• Bạn không lập trình. Công cụ này không viết app thay bạn và không dùng được nếu không có code.
• Dự án của bạn không dùng Git. Tài liệu ghi rõ các hệ quản lý khác như SVN, Mercurial chưa được hỗ trợ.
• Bạn muốn một công cụ tìm được mọi lỗi: dự án tự nhận họ ưu tiên ít báo sai hơn là bắt hết lỗi.

2. Cần chuẩn bị gì?

Hệ điều hành: Windows, macOS và Linux đều được, cả máy chip Intel/AMD lẫn ARM.

Phần mềm cần có trước:

• Git bản 2.41 trở lên: công cụ quản lý phiên bản code; Open Code Review dựa vào Git để biết bạn đã đổi gì. Tải tại https://git-scm.com.
• Node.js bản 18 trở lên: nền tảng chạy JavaScript, đi kèm lệnh npm dùng để cài. Tải tại https://nodejs.org. Nếu không muốn cài Node.js, bạn có thể dùng cách cài bằng script ở Bước 2B.

Khóa API của một mô hình AI: là chuỗi ký tự bí mật để gọi mô hình. Open Code Review có sẵn cấu hình cho nhiều nhà cung cấp, trong đó có Anthropic, OpenAI, OpenRouter, Gemini, DeepSeek, DashScope và một số nhà cung cấp khác; bạn chỉ cần dán khóa. Khóa API thường tính tiền theo lượng dùng, giá do nhà cung cấp quyết định. Không cần khóa nếu:

• bạn dùng Delegation Mode bên trong một trợ lý lập trình đã có gói thuê bao, hoặc
• bạn chạy mô hình ngay trên máy bằng Ollama (xem mục 7).

3. Cài đặt từng bước

Bước 1: Kiểm tra Git và Node.js

git --version
node --version

Thấy gì là đúng: Git hiện số từ 2.41 trở lên, Node.js hiện số từ v18 trở lên. Nếu một trong hai báo không tìm thấy lệnh, cài từ link ở mục 2 rồi mở lại cửa sổ dòng lệnh.

Bước 2A: Cài bằng npm (cách được khuyên dùng)

Lệnh này giống nhau trên Windows, macOS và Linux:

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

Thấy gì là đúng: npm chạy xong không có dòng lỗi màu đỏ. Từ giờ bạn có lệnh ocr dùng ở mọi thư mục.

Bước 2B: Cài không cần Node.js (tùy chọn)

Nếu không muốn cài Node.js, dùng script cài chính thức. Script tải file chạy từ trang Releases và có kiểm tra mã checksum.

Windows (PowerShell 5.1 trở lên):

irm https://open-codereview.ai/install.ps1 | iex

Trên Windows, chương trình được đặt vào %LOCALAPPDATA%\Programs\ocr.

macOS và Linux:

curl -fsSL https://open-codereview.ai/install.sh | sh

Trên macOS và Linux, mặc định đặt vào /usr/local/bin. Người dùng macOS/Linux có Homebrew cũng có thể chạy:

brew install open-code-review

Bước 3: Xác nhận đã cài

ocr version

Thấy gì là đúng: hiện số phiên bản, mã commit và ngày build. Bản mới nhất lúc viết bài là v1.12.11, phát hành ngày 29/9/2026.

Bước 4: Khai báo mô hình AI

Bỏ qua bước này nếu bạn dùng Delegation Mode.

ocr config provider

Một giao diện chọn bằng phím mũi tên hiện ra: chọn nhà cung cấp, dán khóa API, chọn mô hình. Công cụ lưu lại cấu hình rồi tự thử kết nối một lần. Muốn đổi mô hình về sau:

ocr config model

Bước 5: Thử kết nối

ocr llm test

Thấy gì là đúng: dòng báo kết nối thành công. Nếu báo 401 hoặc 403 thì khóa API sai hoặc hết hạn.

4. Dùng lần đầu

Bước 1: Vào một thư mục dự án có Git

cd duong-dan-toi-du-an

Thay duong-dan-toi-du-an bằng thư mục thật của bạn. Thư mục này phải là một kho Git, và nên có vài thay đổi bạn chưa commit.

Bước 2: Xem trước cái gì sẽ được soát (không tốn tiền)

ocr review --preview

Lệnh này không gọi mô hình AI. Nó liệt kê các file sẽ được soát, và file nào bị bỏ qua thì ghi kèm lý do.

Bước 3: Chạy soát lỗi thật

ocr review

Mặc định nó soát mọi thay đổi trong thư mục làm việc: phần đã đưa vào hàng chờ commit, phần chưa, và file mới. Kết quả là danh sách nhận xét, mỗi nhận xét gắn với file và dòng cụ thể.

Hai cách chạy khác hay dùng:

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

Dòng đầu so sánh một nhánh với nhánh main. Dòng sau soát riêng một commit (thay abc123 bằng mã commit thật). Ngoài ra ocr scan soát nguyên cả file thay vì chỉ phần thay đổi, dùng khi bạn muốn kiểm tra một kho code lạ.

Bước 4: Xem lại kết quả trên trình duyệt

ocr viewer

Một trang web cục bộ mở tại localhost:5483, liệt kê các lần soát trước. Ở mỗi nhận xét bạn có thể bấm Fixed hoặc Ignored để đánh dấu đã xử lý. Nhấn Ctrl+C trong cửa sổ dòng lệnh để tắt.

Tùy chọn: đổi ngôn ngữ nhận xét

Cấu hình language quyết định nhận xét được viết bằng ngôn ngữ nào. Ví dụ trong tài liệu:

ocr config set language English

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ ocr báo "command not found" hoặc "not recognized"	Thư mục cài chưa nằm trong PATH (danh sách nơi máy tìm lệnh)	Đóng và mở lại cửa sổ dòng lệnh. Nếu vẫn lỗi, kiểm tra thư mục cài đã có trong PATH chưa
no valid LLM endpoint configured	Chưa khai báo đủ ba thứ: địa chỉ, khóa, tên mô hình	Chạy ocr config provider, sau đó ocr llm test
ocr llm test trả về 401 hoặc 403	Khóa API sai, hết hạn, hoặc chọn nhầm nhà cung cấp so với khóa	Tạo khóa mới và chạy lại ocr config provider
not a git repository	Bạn đang đứng ở thư mục không phải kho Git	cd vào đúng thư mục dự án, hoặc thêm --repo kèm đường dẫn
Lặp lại "No tool calls parsed" rồi "Max tool requests reached", không có nhận xét nào	Mô hình (thường là mô hình chạy trên máy) không hỗ trợ gọi công cụ	Đổi sang mô hình có hỗ trợ tool calling. Tài liệu nêu deepseek-r1 là ví dụ không chạy được, qwen3 là ví dụ chạy được
Một file không được soát	File bị bộ lọc loại: file nhị phân, nằm trong node_modules hay vendor, hoặc quá lớn	Chạy ocr review --preview để đọc lý do của từng file
Cảnh báo "prompt tokens exceed 80% of max_tokens"	Phần thay đổi của một nhóm file quá lớn	Tách thành các commit nhỏ hơn, hoặc loại file sinh tự động ra

Các lỗi khác có trong trang FAQ chính thức: https://open-codereview.ai/docs/faq

6. Gỡ cài đặt / cập nhật

Cập nhật

Nếu cài bằng npm, ocr tự kiểm tra bản mới mỗi lần chạy và tự nâng cấp ngầm; bạn không cần làm gì. Muốn tắt tự cập nhật, đặt biến môi trường OCR_NO_UPDATE thành một giá trị bất kỳ, ví dụ trên macOS/Linux:

export OCR_NO_UPDATE=1

Nếu cài bằng script, chạy lại lệnh cài ở Bước 2B để lấy bản mới nhất. Nếu cài bằng Homebrew:

brew upgrade open-code-review

Gỡ cài đặt

Cài bằng npm:

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

Cài bằng script trên macOS/Linux:

sudo rm /usr/local/bin/ocr

Cài bằng script trên Windows: xóa thư mục %LOCALAPPDATA%\Programs\ocr.

Cuối cùng, để xóa cấu hình, khóa API đã lưu và lịch sử các lần soát, xóa thư mục .opencodereview trong thư mục người dùng của bạn. Trên macOS/Linux:

rm -rf ~/.opencodereview

Tài liệu cho biết công cụ không ghi dữ liệu ra ngoài thư mục này, nên xóa nó là gỡ sạch.

7. Câu hỏi hay gặp

Có mất tiền không?

Công cụ miễn phí, mã nguồn mở. Phần tốn tiền là gọi mô hình AI qua khóa API của bạn. Muốn rẻ hơn, thêm --effort low khi chạy: mức này chỉ soát một vòng thay vì hai vòng như mặc định.

Code của tôi có bị gửi đi đâu không?

Có, nhưng chỉ tới đúng nơi bạn cấu hình. Theo tài liệu, công cụ gửi phần thay đổi trong code (và vài đoạn file nó cần đọc thêm) tới mô hình AI bạn đã khai báo. Lịch sử soát và file quy tắc chỉ nằm trên máy bạn.

Chạy hoàn toàn trên máy, không gửi code ra ngoài được không?

Được, bằng cách trỏ tới một mô hình chạy cục bộ qua Ollama như một nhà cung cấp tùy chỉnh. Điều kiện là mô hình đó phải hỗ trợ gọi công cụ. Cách khai báo có trong https://open-codereview.ai/docs/configuration.

Tôi đã trả tiền Claude Code hoặc Cursor, có cần mua thêm khóa API không?

Không bắt buộc. Delegation Mode để chính trợ lý lập trình của bạn làm phần suy luận, còn ocr chỉ lo chọn file và quy tắc. Hướng dẫn: https://open-codereview.ai/docs/delegate.

Nó có bắt được hết lỗi không?

Không. Dự án nói rõ họ chọn ưu tiên độ chính xác (ít báo sai) và chấp nhận bỏ sót nhiều hơn so với trợ lý đa năng. Hãy coi nó là người soát thêm, không thay cho việc tự kiểm tra.