Clawpatch: Code review tự động bằng AI Agent với vòng lặp fix có kiểm soát

Tóm tắt nhanh:

• Clawpatch là một CLI mã nguồn mở thuộc tổ chức OpenClaw, tự động map repository thành các feature slice ngữ nghĩa, review từng slice bằng AI provider và lưu lại các finding để bạn xử lý từng cái một.
• Hỗ trợ đa ngôn ngữ và framework: Node/TypeScript, Next.js, React, Go, Java/Kotlin, Ruby, Rust, C/C++, Python, Swift, Laravel/PHP, kèm cả Nx và Turborepo monorepo.
• Tích hợp linh hoạt với nhiều provider AI: Codex CLI, Claude / Gemini / Pi qua ACPx, Grok Build CLI, OpenCode CLI và provider mock cho testing.
• Triết lý an toàn: review không sửa file, fix chỉ chạy khi bạn chỉ định finding ID, không tự commit/push/mở PR – luôn yêu cầu human review cuối cùng.
• Cài đặt cực nhanh chỉ với một dòng pnpm add -g clawpatch, state lưu cục bộ trong thư mục .clawpatch/ để có thể resume và audit.

Trong khi các công cụ AI code review thông thường thường rơi vào hai thái cực – hoặc quá sơ sài kiểu “comment chung chung”, hoặc quá tự tin đến mức tự ý sửa code mà không hỏi – Clawpatch chọn một con đường khác: thay vì cố làm thay developer, nó đóng vai trò một reviewer kỷ luật với vòng lặp fix tường minh và có thể kiểm soát.

Clawpatch là gì

Clawpatch là một CLI mã nguồn mở được phát triển bởi OpenClaw. Slogan của dự án rất ngắn gọn: “Automated code review that lands fixes”. Tuy nhiên, cách Clawpatch triển khai ý tưởng này lại rất khác biệt so với các trợ lý lập trình AI thông thường.

Thay vì hoạt động như một chatbot trong terminal, Clawpatch coi mỗi repository như một tập hợp các feature slice ngữ nghĩa. Mỗi slice là một đơn vị công việc bền vững (durable work unit), được review độc lập, lưu finding vào một database cục bộ, và có thể được sửa từng cái một thông qua một vòng lặp fix tường minh.

Hiện tại dự án đang ở giai đoạn early CLI: phần review, report, state đã hoàn thiện; phần patching đã có nhưng vẫn yêu cầu developer review thủ công các thay đổi trong worktree.

Vì sao Clawpatch lại đáng chú ý

Mô hình feature slicing thay vì file-by-file

Đa số công cụ review AI hoạt động theo từng file hoặc từng diff. Clawpatch nâng cấp tư duy này lên cấp độ ngữ nghĩa: nó tự động phát hiện các package, route, command, test suite, semantic role trong repo của bạn và coi mỗi nhóm như một feature slice. Điều này có hai lợi ích lớn:

• Provider AI nhận được context đầy đủ hơn cho mỗi lần review, giảm hiện tượng “review tù mù”
• Bạn có thể review song song nhiều slice mà không lo trùng lặp hay bỏ sót

Hỗ trợ đa ngôn ngữ và framework thực sự rộng

Clawpatch hiện đã map được rất nhiều loại dự án:

• Node/TypeScript: package bins, scripts (start, build, test, lint, typecheck, format), workspace pattern apps/*, packages/*, extensions/*, plugins/*
• Frontend: Next.js app//pages/ routes, React Router routes, React components
• Monorepo: metadata từ Nx project.json, task của Turborepo
• Backend & system: Go packages từ go list ./..., Rust với crates và bins, C/C++ với CMake và autotools, Ruby với RSpec/Minitest
• JVM: Gradle source groups, semantic role từ annotation, import, supertype trong Java và Kotlin (kể cả Kotlin Android với ViewModels, DI, Metro)
• Python: console scripts, source groups, pytest suites, route Flask/FastAPI
• Mobile & Web: SwiftPM targets, Laravel/PHP với composer, artisan, controllers, jobs, services, migrations

Đây là một trong những danh sách hỗ trợ ngôn ngữ rộng nhất mà mình từng thấy trong một CLI review AI.

Tích hợp nhiều provider AI khác nhau

Clawpatch không khoá bạn vào một mô hình AI duy nhất. Các provider được hỗ trợ hiện tại:

• codex: local Codex CLI (mặc định)
• acpx: bất kỳ coding agent nào tương thích ACP, bao gồm Codex, Claude, Pi, Gemini
• grok: local Grok Build CLI
• opencode: local OpenCode CLI
• mock và mock-fail: provider giả lập cho testing

Mọi cuộc gọi tới provider đều dùng JSON schema nghiêm ngặt, đảm bảo output có thể parse được và không bị “ảo giác” cấu trúc.

Hướng dẫn cài đặt Clawpatch

Cài đặt nhanh qua pnpm

Cách đơn giản nhất là cài global thông qua pnpm:

pnpm add -g clawpatch

Sau đó kiểm tra phiên bản:

clawpatch --version

Cài từ source

Nếu bạn muốn theo sát bản phát triển mới nhất hoặc đóng góp cho dự án:

git clone https://github.com/openclaw/clawpatch.git
cd clawpatch
pnpm install
pnpm build
pnpm link --global

Kiểm tra provider hoạt động

Clawpatch mặc định dùng local Codex CLI. Trước khi chạy, hãy đảm bảo bạn đã có Codex (hoặc provider bạn chọn) sẵn sàng:

codex --version
clawpatch doctor

Lệnh clawpatch doctor sẽ kiểm tra mọi provider đã được cấu hình và báo lỗi cụ thể nếu binary nào chưa sẵn sàng.

Workflow sử dụng Clawpatch

Phần này là điểm sáng nhất của Clawpatch: workflow được thiết kế rõ ràng, có thể resume và audit. Dưới đây là chu trình hoàn chỉnh từ khi mở một repo lần đầu tới khi sửa xong một finding.

Bước 1: Khởi tạo và map repository

clawpatch init
clawpatch map

Lệnh init tạo thư mục .clawpatch/ chứa config và state cục bộ. Lệnh map quét repo, phát hiện feature slice và lưu thành các file JSON trong .clawpatch/features/.

Bước 2: Chạy review song song

clawpatch review --limit 3 --jobs 3

Tham số --limit giới hạn số feature mỗi lần review, --jobs cho phép chạy song song để tận dụng nhiều worker. Quá trình này hoàn toàn read-only – không có file nào trong source bị thay đổi.

Bước 3: Xem báo cáo và pick finding

clawpatch report
clawpatch next
clawpatch show --finding <id>

report xuất ra báo cáo Markdown tổng hợp toàn bộ finding. next cho bạn finding tiếp theo cần xử lý. show hiển thị chi tiết một finding kèm evidence và lệnh validation đề xuất.

Bước 4: Triage hoặc Fix

Nếu bạn quyết định finding này không cần xử lý:

clawpatch triage --finding <id> --status false-positive --note "covered by tests"

Nếu muốn AI thử fix:

clawpatch fix --finding <id>

Lệnh fix này quan trọng cần lưu ý:

• Chỉ chạy trên một finding ID cụ thể, không bao giờ chạy hàng loạt mặc định
• Không commit, không push, không mở PR
• Từ chối chạy nếu source worktree đang dirty (đảm bảo bạn có thể rollback)
• Sau khi chạy xong, kết quả patch được lưu vào .clawpatch/patches/ để bạn review thủ công

Bước 5: Revalidate

Sau khi fix, kiểm tra lại finding:

clawpatch revalidate --finding <id>
clawpatch revalidate --all --status open

Bạn có thể chạy revalidate cho một finding hoặc tất cả finding đang ở trạng thái open.

Cấu trúc state cục bộ

Toàn bộ state của Clawpatch được lưu trong thư mục .clawpatch/ ngay trong repo, mặc định không bị Git ignore (bạn nên thêm vào .gitignore hoặc commit để chia sẻ theo team tuỳ chiến lược):

.clawpatch/
  config.json
  project.json
  features/*.json
  findings/*.json
  patches/*.json
  reports/*.md
  runs/*.json

Mỗi feature record là một work unit bền vững. Mỗi finding và patch attempt đều liên kết ngược về feature, cho phép resume các chu trình dài và audit chi tiết.

Các flag hữu ích trong vận hành thực tế

Clawpatch cung cấp nhiều flag rất tinh tế:

• --root <path> và --state-dir <path>: cho phép chạy trên monorepo lớn hoặc cấu hình CI/CD
• --source <heuristic|auto|agent>: chọn chiến lược mapping
• --provider <name> và --model <name>: override provider và model cụ thể
• --reasoning-effort <none|minimal|low|medium|high|xhigh>: cân bằng giữa tốc độ và chất lượng phân tích
• --json / --plain: format output cho pipeline tự động hoặc cho con người
• --dry-run: xem trước hành động mà không thực thi
• --force: bỏ qua các check an toàn (dùng cẩn trọng)

Một điểm rất hay: Clawpatch fail-fast với unknown flags, tránh được những lỗi typo âm thầm.

Triết lý an toàn của Clawpatch

Đây là phần mà mình đánh giá cao nhất ở Clawpatch. Trong khi nhiều công cụ AI hiện nay muốn “tự động hoá tất cả”, Clawpatch tự đặt ra ranh giới rõ ràng:

• Review không bao giờ sửa file
• Fix tường minh, phải chỉ định finding ID
• Từ chối worktree dirty để bạn có thể rollback dễ dàng
• Không bao giờ commit, push, mở PR hay land changes – tất cả phụ thuộc vào con người
• Symlink và build output bị skip trong quá trình map
• Provider output parse qua schema nghiêm ngặt, tránh ảo giác cấu trúc

Triết lý này phù hợp với những team coi code review là một hoạt động trí tuệ chứ không phải khâu bottleneck cần loại bỏ.

Đối tượng nên dùng Clawpatch

Clawpatch phát huy giá trị tốt nhất trong các tình huống sau:

• Team mid-to-large muốn AI hỗ trợ review nhưng vẫn giữ quyền kiểm soát
• Maintainer dự án mã nguồn mở có nhiều contributor, cần một lớp review sơ bộ trước khi reviewer chính nhìn
• Solo developer trên các dự án lớn, dùng Clawpatch như một “second pair of eyes” trước khi merge
• Người làm CI/CD muốn tích hợp một bước review tự động với output JSON sạch

Clawpatch không cố trở thành Cursor hay Claude Code phiên bản OSS. Thay vào đó, nó chiếm lĩnh một mảnh đất riêng: một code reviewer AI có kỷ luật, tôn trọng human-in-the-loop và minh bạch về mọi hành động. Với hỗ trợ đa ngôn ngữ rộng, thiết kế state có thể audit, và triết lý an toàn rõ ràng, đây là công cụ rất đáng đưa vào toolbox của bất cứ developer chuyên nghiệp nào.

Hãy thử ngay bằng cách ghé thăm repository Clawpatch trên GitHub và chạy pnpm add -g clawpatch trong terminal. Chỉ vài phút sau, bạn đã có một code reviewer AI thực thụ ngồi bên cạnh, sẵn sàng map repo và soi từng feature một cách kỷ luật mà không bao giờ vội vàng commit thay bạn.