Agent Autoloop — Hub mã nguồn mở chạy AI agent ở chế độ nền, duyệt việc nhạy cảm qua approval card

2 giờ sáng, một GitHub issue mới xuất hiện trong repo bạn theo dõi. Bạn đang ngủ, sáng hôm sau issue vẫn nằm đó, chưa ai phân loại. Hoặc cảnh quen thuộc hơn: bạn giao cho Claude Code dọn thư mục log cũ, nó chạy nửa chừng rồi dừng lại hỏi “có xoá file này không?”, và bạn phải ngồi canh terminal. Agent CLI vốn chạy foreground, gắn với terminal đang mở — đóng terminal, mất session, agent chết.

Agent Autoloop xuất hiện đúng chỗ này. Nó không phải agent mới hay model mới, mà là hub lập lịch và quản lý vòng đời cho agent bạn đã có — Claude Code, Codex, ACP — để chúng tự chạy theo cron, sự kiện GitHub và webhook. Gặp việc nhạy cảm, agent thoát hẳn tiến trình, gửi approval card cho bạn duyệt, rồi nối lại đúng session cũ khi bạn trả lời.

Agent Autoloop là gì? Vấn đề nó giải quyết

Agent Autoloop là dự án mã nguồn mở theo giấy phép MIT, repo KKKKhazix/agent-autoloop, ra mắt ngày 3/11/2026 và đến giữa tháng 11/2026 đã có hơn 5.000 sao cùng 923 fork, release mới nhất v1.8.3 ngày 13/11/2026.

Cách nó vận hành gói gọn trong 5 bước: sự kiện đi vào (cron, GitHub issue, webhook, lỗi hệ thống) → kernel đối chiếu rules.json, gộp event trùng, giao việc cho đúng agent và thư mục làm việc → agent chạy một vòng rồi thoát → việc nhạy cảm (xoá dữ liệu, restart service, tốn tiền) gửi approval card qua Feishu, Slack, Discord hoặc desktop notification → bạn trả lời, agent nối lại đúng session cũ. Lúc chờ, không tốn process hay token.

Cron cộng agent thô nghe thì đơn giản, nhưng thực tế vỡ ở bốn chỗ: session terminal không nối được sau mỗi lần cron chạy; không có approval nên agent gặp file cần xoá lúc 2 giờ sáng thì hoặc tự quyết hoặc dừng hẳn; không có chống vòng lặp nên agent tự sinh event rồi tự kích hoạt lại chính nó đến khi hết quota; log rời rạc nên không truy vết được. Autoloop vá đúng bốn lỗ đó: nối session sau khi duyệt, approval card, giới hạn hop, và event store append-only.

Nên dùng nếu bạn đã xài Claude Code hoặc Codex hàng ngày, có việc lặp lại rõ ràng — báo cáo sáng, quét issue, tuần tra website, chẩn đoán cảnh báo — và muốn chúng tự chạy mà vẫn giữ quyền duyệt cuối cùng. Chưa nên nếu task cần người ngồi kèm từng bước, repo giao cho agent không đáng tin, hoặc bạn định chạy automation tần suất cao bằng subscription cá nhân — tài liệu của dự án khuyến nghị dùng API key.

Kiến trúc: kernel, rules.json và vòng đời agent

flowchart TD
    A["Sự kiện: Cron / GitHub / Webhook"] --> B["Kernel + rules.json<br/>Đối chiếu rule, gộp event trùng"]
    B --> C["Agent CLI: Claude Code / Codex / ACP<br/>Làm 1 vòng rồi EXIT"]
    C -->|Xong việc| D["Event store append-only<br/>Receipt, log, trạng thái chờ duyệt"]
    C -->|Việc nhạy cảm| D
    D --> E["Approval card: Feishu / Slack<br/>Discord / Desktop"]
    E --> F["Người duyệt: Approve / Reject"]
    F -->|Đồng ý| G["Resume đúng session cũ"]
    F -->|Từ chối| D
    G --> C
    C -->|Sinh event mới| B
    H["Delivery: nhãn deliver trên PR → review<br/>→ chờ CI → merge → chờ deploy"] -.-> B

Chỉ nhìn sơ đồ cũng thấy ý tưởng cốt lõi: agent không chạy thường trực — nó làm một vòng rồi thoát, hoặc thoát ngay khi cần chờ duyệt, trạng thái nằm trong event store. Con người là gate duy nhất trước việc nhạy cảm, event do agent tự sinh bị giới hạn 8 tầng hop, và config delivery chỉ đọc từ nhánh main.

4 cơ chế kernel làm nên khác biệt

Chờ duyệt zero-process, zero-token. Khi agent cần hỏi ý kiến, process thoát hẳn, trạng thái lưu vào database. Đây là quyết định thiết kế rẻ nhất của dự án — nhưng cũng là chỗ mong manh nhất: việc nối lại đúng session phụ thuộc vào CLI agent bên dưới còn giữ session đó hay không. Nếu session đã hết hạn hay bị compact trong lúc bạn đi ngủ, agent có thể phải bắt đầu lại từ đầu, hoặc lặp lại một tác vụ đã làm.

Event sourcing append-only. Mọi sự kiện, kết quả và receipt đều ghi nối tiếp vào log, không sửa, không xoá. Bạn truy vết bằng agent-autoloop runs và agent-autoloop why <n>.

Tách instruction khỏi data. Nội dung issue hay webhook chỉ là tài liệu đính kèm, không ghép vào prompt của agent. Event mang theo trường cwd, agent hay access bị từ chối thẳng — chống prompt injection qua issue.

Hop limit 8 tầng cho event do agent tự sinh. Agent được phép tạo event mới để kích hoạt vòng tiếp theo, nhưng chuỗi dừng ở tầng thứ 8 — vòng lặp vô hạn bị chặn cứng thay vì quay đến khi hết quota.

Thành phần chính và giới hạn kỹ thuật

Kernel viết bằng TypeScript, chạy trên Node 24 trở lên, tác giả công bố 0 runtime dependency. File rules.json khai báo rule: trigger nào, agent nào, thư mục làm việc nào, được phép và cấm làm gì. Agent adapter nối với Claude Code, Codex, ACP, DeepSeek Harness, ZCode, cộng lệnh command generic cho pi, OpenClaw, Hermes, Cursor CLI hay CodeBuddy — tác giả ghi rõ các lệnh generic này chưa chạy thử từng cái, nên phần này mình chưa chạy thử, chỉ đối chiếu tài liệu. Kênh approval mặc định là desktop notification.

Yêu cầu hệ thống: Node 24 trở lên, Git; macOS và Linux cần thêm curl; không cần tài khoản GitHub. README hiện tại ghi hỗ trợ Windows, macOS và Linux — dường như hỗ trợ Windows mới được bổ sung sau ngày 4/11; mình chưa tự test trên Windows nên chỉ ghi theo tài liệu hiện tại. Giới hạn đã xác minh: bốn webhook template mới test trên mock local, GitLab webhook chưa nối với GitLab thật, sample data là hư cấu, script và receipt chỉ test bằng local HTTP và fake Feishu CLI. Autoloop không thay thế CI/CD hay queue bền vững.

Cài đặt và chạy thử end-to-end

Bạn cần Node 24 trở lên, Git, curl trên macOS/Linux, và tài khoản Claude Code, Codex hoặc một ACP CLI đã đăng nhập sẵn. Phiên bản tham chiếu là v1.8.3 (13/11/2026) — repo release gần như mỗi ngày, hãy kiểm tra release mới nhất trước khi cài. Cảnh báo: cả hai lệnh cài đều pipe script từ internet thẳng vào shell — đừng pipe mù, tải script về, đọc qua, rồi mới chạy.

Trên Windows, mở PowerShell:

irm https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.ps1 | iex

Trên macOS hoặc Linux:

curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh

Sau đó kiểm tra bằng agent-autoloop check — lệnh này xác nhận kernel, Node, Git và các CLI agent đã đăng nhập có sẵn sàng hay chưa.

Lệnh chạy thử end-to-end là agent-autoloop try. Luồng thử: lệnh hỏi bạn một câu, agent chạy một vòng rồi hỏi lại, bạn trả lời bằng agent-autoloop answer 1 <số>, rồi dùng agent-autoloop status để xem tiếp. Đầu ra kỳ vọng: agent chạy xong một vòng thì thoát, card duyệt xuất hiện, và sau khi bạn trả lời, agent nối lại đúng session để làm tiếp. Nếu không thấy card, kiểm tra kênh notification trước — phần lớn lỗi ở lần đầu nằm ở kênh nhận card hoặc CLI agent chưa đăng nhập. Bước try này là bắt buộc trước khi bật rule thật.

Viết rules.json đầu tiên

Autoloop đi kèm 8 recipe có sẵn: morning-brief (8 giờ sáng), github-issues (quét 5 phút một lần, không commit, không push, không reply), ops-alerts, website-watch (5 phút một lần), feedback, feishu-brief, inbox-triage (chỉ đọc và viết nháp, không gửi), PR delivery, cộng thêm browser-handoff và weekly-sweep.

Một cấu hình tối thiểu gồm hai rule: cron morning-brief lúc 8 giờ sáng tổng hợp ghi chú và Git commit, và github-issues quét repo mỗi 5 phút để phân loại issue mới. Mỗi rule khai báo trigger, agent, thư mục làm việc cwd, và quyền của agent — quyền càng hẹp càng tốt ở giai đoạn đầu. Quản lý bằng: agent-autoloop rules explain để xem kernel hiểu rule của bạn ra sao, agent-autoloop emit <type> --dry-run để thử trigger mà không chạy thật, pause, resume hoặc run <rule> để điều khiển từng rule, runs và why <n> để truy vết, update để nâng cấp.

Lỗi thường gặp và cách xử lý

Node dưới 24, thiếu Git hoặc curl: nâng cấp Node, cài đủ dependency, chạy lại agent-autoloop check. Agent CLI chưa đăng nhập: đăng nhập Claude Code hoặc Codex trước. Webhook không tới: thử bằng mock local trước khi gắn webhook thật. Card duyệt không về: kiểm tra kênh notification và token webhook. Agent không nối được session: kiểm tra session của CLI agent — session thuộc về CLI agent chứ không thuộc về Autoloop. Rule không chạy: dùng rules explain rồi emit --dry-run để thử trigger mà không chạy thật.

Đánh giá kỹ thuật

Ưu điểm. Rẻ khi chờ: không tốn process hay token trong lúc chờ duyệt. An toàn theo thiết kế: approval card, tách instruction khỏi data, hop limit và delivery config chỉ đọc từ main tạo thành nhiều lớp. Cài đặt một lệnh, có try chạy thử end-to-end, 8 recipe sẵn, cấu hình bằng rules.json không cần viết code. Truy vết được: event sourcing cộng runs và why.

Nhược điểm. Repo mới 10 ngày tuổi tính đến 13/11/2026, release gần như mỗi ngày — API và config có thể đổi nhanh, nên pin version và đọc changelog trước khi chạy agent-autoloop update. Nhiều trạng thái “chạy được” mới ở mức test local hoặc mock, chưa qua production thật: GitLab webhook, webhook template, generic agent. Việc nối session phụ thuộc CLI agent bên dưới. README gốc viết bằng tiếng Trung.

Hiệu năng — chỉ dùng số có nguồn. Tác giả công bố số đo trên Apple M5 Pro 24GB, Node 24.21.0: cold start 88,78 ms; idle 59,94 MB RSS; 1.000 long-polling chờ chiếm 170,49 MB; ghi 2.394 event mỗi giây; dispatch p99 1,82 ms; 0 runtime dependency. Đây là số tác giả tự đo, chưa độc lập kiểm chứng, nên bài này không trình bày chúng như benchmark. Theo mình, p99 1,82 ms không phải thứ quyết định trải nghiệm: nút thắt thực tế là thời gian chờ người duyệt cộng thời gian agent chạy. Autoloop hợp với cá nhân và team nhỏ, tần suất vừa; tần suất cao thì dùng API key, tách rule theo repo, giám sát bằng runs.

Bảo mật, sao lưu và rollback. Đọc script cài đặt trước khi pipe. Webhook phải xác thực và chặn các event mang cwd, agent hay access lạ — kernel đã từ chối chúng theo thiết kế, đừng tìm cách vòng qua. Token Feishu, Slack hay Discord cất riêng, không commit vào rules.json hay repo. Không dùng subscription cá nhân cho automation tần suất cao. Khi nghi ngờ, pause rule lại, xem why.

Trước khi bật rule có quyền ghi hoặc xoá, hãy có đường lui rõ ràng: dừng kernel, pause các rule, gỡ hoặc vô hiệu hoá rule gây sự cố, thu hồi token webhook nếu kênh approval bị lộ. Đừng xoá event store vội: runs và why trong đó là audit trail duy nhất cho biết agent đã làm gì lúc không có người giám sát. Khi bật lại, chạy agent-autoloop try và emit --dry-run trước.

So sánh với giải pháp cùng phạm vi

Autoloop không thay thế Orca, WorkTrunk hay T3 Code. Nó là lớp lập lịch và vòng đời, còn các tool kia là lớp thực thi và điều khiển: Orca chạy nhiều AI coding agent song song và WorkTrunk với Git worktree cho AI agent song song giải quyết “chạy nhiều agent cùng lúc”, Autoloop giải quyết “agent tự chạy khi không có ai canh”. Đọc kèm khi thiết kế rule và quyền: Claude Mem lưu bộ nhớ xuyên phiên cho AI agent và HeldKeys kiểm tra quyền truy cập của AI agent.

Use case thực tế

DevOps/SRE: PR delivery và cảnh báo ops. Gắn nhãn deliver lên GitHub PR, Autoloop tự review code, chờ CI, merge, chờ deploy rồi đối chiếu version online. Với ops-alerts, agent chẩn đoán sơ bộ, còn restart hay xoá thì phải qua approval card.

Sysadmin tự host: website-watch và báo cáo sáng. Website-watch tuần tra mỗi 5 phút, morning-brief lúc 8 giờ sáng tổng hợp log và issue. Inbox-triage chỉ đọc và viết nháp, không gửi.

Lập trình viên: theo dõi GitHub issue tự động. Rule github-issues quét repo mỗi 5 phút, phân loại issue mới, không commit, không push, không reply nếu chưa được phép. Recipe feedback thu thập phản hồi và tóm tắt lại cho bạn đọc mỗi ngày.

AI builder và team nhỏ: inbox-triage và feishu-brief. Phân loại inbox tự động, gửi brief qua Feishu cho cả team. Lưu ý: kênh Feishu và webhook mới test ở mức local, nên thử trên repo và tài khoản thử trước.

Kết luận

Hợp nếu bạn đã dùng Claude Code hoặc Codex hàng ngày, có việc lặp lại rõ ràng, và chấp nhận một repo non trẻ để đổi lấy approval card cộng chạy nền rẻ. Chưa hợp nếu bạn cần SLA hay bảo mật cứng cấp doanh nghiệp, cần chạy webhook GitLab production ngay, hoặc không muốn tự host Node 24 và theo dõi release mỗi ngày.

Bước tiếp theo nếu bạn muốn thử: cài đặt, chạy agent-autoloop try để chứng minh vòng exit — approve — resume hoạt động, bật một rule morning-brief, rồi một rule github-issues, và chỉ sau khi hai rule đó chạy ổn mới bật rule có quyền ghi hay xoá.

Bài học rút ra

1. Giá trị của Autoloop nằm ở vòng đời agent — thoát process và nối lại session — không nằm ở model hay agent cụ thể nào.
2. Approval card chỉ có giá trị khi rule cấm agent tự làm việc nhạy cảm; mặc định quyền phải hẹp, mở rộng dần theo mức tin cậy.
3. Số hiệu năng dispatch, p99 1,82 ms, không quyết định trải nghiệm; thời gian chờ người duyệt mới là nút thắt thực sự.
4. Repo 10 ngày tuổi: pin version, đọc changelog trước khi chạy agent-autoloop update.
5. Webhook, GitLab và generic-agent chưa kiểm chứng production — thử trên mock và repo thử trước khi gắn repo thật.
6. Session resume phụ thuộc CLI agent bên dưới; rule có tác vụ phụ phải idempotent để nối lại an toàn.

Phạm vi kiểm chứng

Ngày kiểm chứng: 13/11/2026, 20:18–20:21 +07; QA kiểm chứng lại sao/fork/release lúc 21:05 +07. Nguồn: README và GitHub API repo KKKKhazix/agent-autoloop, cùng bản phân tích độc lập trên explainx.ai ngày 4/11 — số sao và hỗ trợ Windows trong bài đó đã cũ. Đã xác minh với tài liệu chính thức: tên, license MIT, sao và fork tại thời điểm kiểm chứng, release v1.8.3, yêu cầu Node 24 trở lên, lệnh cài đặt và try, flow 5 bước, 4 cơ chế kernel, 8 recipe và delivery pipeline. Mặc định so với opt-in: desktop notification là mặc định; Feishu, Slack và Discord là opt-in qua cấu hình; hop limit 8 và tách instruction khỏi data là mặc định của kernel. Mọi số hiệu năng là số tác giả tự đo, chưa độc lập kiểm chứng — đó là số cấu hình, không phải benchmark. Chưa kiểm chứng: bài này không tự cài, chạy hay test Autoloop; không kiểm chứng lệnh generic-agent, GitLab webhook, webhook template production hay Feishu, Slack, Discord production.

Tham khảo

• Agent Autoloop — GitHub: https://github.com/KKKKhazix/agent-autoloop
• Agent Autoloop — README tiếng Anh: https://github.com/KKKKhazix/agent-autoloop/blob/main/README.en.md
• Agent Autoloop — Hướng dẫn cài đặt: https://github.com/KKKKhazix/agent-autoloop/blob/main/INSTALL.md
• Agent Autoloop — Tài liệu bảo mật: https://github.com/KKKKhazix/agent-autoloop/blob/main/SECURITY.md
• Phân tích độc lập trên explainx.ai (4/11/2026): https://explainx.ai/blog/agent-autoloop-claude-code-codex-background-hub-cron-github-issues-approval-cards-github-trending-2026