Hướng dẫn Agent Autoloop: để các Agent dòng lệnh như Claude Code, Codex tự động nhận việc và liên tục theo dõi ở chế độ nền

Agent Autoloop là gì?

Agent dòng lệnh như Claude Code, Codex thường yêu cầu người dùng liên tục tương tác bên cạnh terminal: nhập tác vụ, chờ thực thi, trả lời câu hỏi rồi cho Agent tiếp tục. Nếu terminal bị đóng hoặc người dùng tạm rời đi, quy trình thường sẽ bị gián đoạn.

Agent Autoloop là một nền tảng tự động hóa nhẹ dành cho Agent dòng lệnh. Công cụ đưa việc lập lịch tác vụ vào một lõi không phụ thuộc runtime, đồng thời tách nguồn sự kiện, Agent, kênh thông báo và quy trình phân phối thành các plugin có thể thay thế. Công cụ có thể chạy trên máy Mac hoặc Linux cục bộ, không cần mua máy chủ đám mây và không yêu cầu mở cổng công khai.

Cách thức hoạt động cốt lõi là: sau khi sự kiện đi vào, hệ thống phân công sự kiện cho Agent theo quy tắc; Agent hoàn thành một lượt rồi thoát; chỉ khi gặp thao tác không chắc chắn như xóa dữ liệu, khởi động lại dịch vụ, chi tiền hoặc gửi tin nhắn ra bên ngoài, hệ thống mới gửi thẻ thông báo để bạn quyết định. Sau khi bạn trả lời, hệ thống tiếp tục phiên ban đầu và hoàn thành phần việc còn lại.

Tính năng chính

• Chạy cục bộ: chỉ cần một máy macOS hoặc Linux để triển khai, không cần máy chủ đám mây riêng.
• Dễ tích hợp Agent: mọi công cụ dòng lệnh có thể nhận prompt và xuất câu trả lời cuối cùng đều có thể tích hợp thông qua plugin lệnh chung.
• Không tiêu tốn Agent khi tạm dừng: khi chờ người dùng trả lời, tiến trình Agent thoát hoàn toàn và không tiếp tục tiêu tốn Token; trạng thái chờ được lưu trong cơ sở dữ liệu.
• Điều khiển bằng quy tắc: dùng rules.json để mô tả sự kiện nào giao cho Agent nào và thực thi trong thư mục nào, không cần viết mã kết nối.
• Thông báo theo nhu cầu: hỗ trợ thông báo trên máy tính, Feishu, cùng các mẫu Webhook cho DingTalk, WeCom, Slack và Discord.
• Tiếp tục phiên: sau khi người dùng trả lời, có thể tiếp tục cuộc hội thoại ban đầu thay vì lặp lại tác vụ từ đầu.
• Có thể truy vết: trạng thái được tính từ nhật ký chỉ ghi nối tiếp, cho phép tra cứu nguyên nhân kích hoạt và kết quả xử lý của từng lượt tác vụ.
• Kiến trúc plugin: nguồn sự kiện, Agent, kênh thông báo và quy trình phân phối CI/CD đều có thể mở rộng hoặc thay thế.

Chuẩn bị trước khi cài đặt

Trước khi bắt đầu, hãy xác nhận hệ thống là macOS hoặc Linux và đã cài đặt các công cụ sau:

• Node 24
• Git
• curl
• Ít nhất một Agent dòng lệnh đã cài đặt và đăng nhập, chẳng hạn Claude Code hoặc Codex

Không cần tài khoản GitHub để cài đặt và chạy thử cục bộ. Agent Autoloop sẽ gọi trực tiếp các công cụ dòng lệnh có sẵn trên máy của bạn, không đọc hoặc chuyển tiếp thông tin đăng nhập của các công cụ đó.

Bước 1: Cài đặt Agent Autoloop

Chạy script cài đặt chính thức trong terminal:

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

Nếu muốn kiểm tra chi tiết cài đặt trước, bạn có thể đọc hướng dẫn cài đặt của dự án. README cũng khuyến nghị giao hướng dẫn này cho Agent trên máy để Agent hỗ trợ hoàn tất cài đặt.

Bước 2: Hoàn tất lần chạy thử tương tác đầu tiên

Sau khi cài đặt xong, hãy chạy:

agent-autoloop try

Lệnh này dùng Agent trên máy để minh họa toàn bộ quy trình: gửi tác vụ, Agent đặt câu hỏi, thoát và chờ, nhận quyết định của bạn rồi tiếp tục phiên để hoàn thành tác vụ.

Trong quá trình chạy thử, bạn sẽ thấy kết quả tương tự như sau:

Sự kiện đã được gửi, Agent bắt đầu xử lý……

Agent đã kết thúc lượt này và đặt một câu hỏi cho bạn. Hiện tại Agent không chiếm tiến trình và không tiêu tốn Token.

【Chờ bạn quyết định】#1 Chạy thử: chọn một màu
Đây chỉ là lần chạy thử, chọn màu nào cũng được.
  1. Xanh dương
  2. Xanh lá

Trong terminal tương tác, bạn có thể nhập trực tiếp số lựa chọn rồi nhấn Enter. Trong terminal không tương tác, có thể trả lời rõ ràng thẻ số 1 và chọn lựa chọn số 2:

agent-autoloop answer 1 2

Sau đó, truy vấn trạng thái tổng thể:

agent-autoloop status

Nếu quy trình hoạt động bình thường, bạn sẽ thấy Agent tiếp tục phiên ban đầu và xác nhận kết quả lựa chọn. Lệnh trạng thái cũng hiển thị số lượt chạy, Token và thống kê chi phí trong ngày và 7 ngày gần nhất.

Bước 3: Hiểu cách tác vụ tự động vận hành

1. Sự kiện đi vào: tác vụ định kỳ, GitHub Issue hoặc lỗi từ hệ thống nghiệp vụ được chuyển thành sự kiện tiêu chuẩn.
2. Khớp quy tắc: lõi dựa trên quy tắc cục bộ để quyết định dùng Agent nào và thực thi trong thư mục làm việc nào.
3. Thực thi một lượt: Agent xử lý tác vụ, nêu kết quả trong câu trả lời cuối cùng rồi thoát tiến trình.
4. Yêu cầu khi cần: nếu có thao tác cần con người phán đoán, nền tảng gửi thẻ thông báo và lưu trạng thái chờ.
5. Tiếp tục sau khi trả lời: sau khi bạn gửi lựa chọn, hệ thống khôi phục cuộc hội thoại ban đầu và tiếp tục hoàn thành tác vụ.

Đối với tác vụ không cần con người tham gia, Agent có thể kết thúc trực tiếp hoặc lên lịch kiểm tra lại sau. Hệ thống cũng gộp các tin nhắn mới nhận về cùng một việc trong thời gian xếp hàng để xử lý tập trung trong một lượt tác vụ.

Bước 4: Viết quy tắc tự động hóa đầu tiên

Cấu hình hằng ngày nằm tại:

~/.agent-autoloop/rules.json

Mỗi quy tắc ít nhất phải nêu rõ khi nào kích hoạt, giao cho ai và làm việc trong thư mục nào. Trong đó, to phải tham chiếu đến một tên đã tồn tại trong agents của cấu hình.

Ví dụ: tạo bản tin buổi sáng lúc 9 giờ mỗi ngày

{
  "name": "Bản tin buổi sáng",
  "when": { "cron": "0 9 * * *" },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "Tổng hợp ghi chú và các lần commit của hôm qua, viết bản tin buổi sáng hôm nay."
}

Quy tắc này giao tác vụ cho Agent có tên codex lúc 9 giờ mỗi ngày và yêu cầu Agent tổng hợp ghi chú cùng các lần commit Git trong thư mục ~/notes.

Ví dụ: xử lý GitHub Issue mới tạo

Cấu trúc quy tắc cho sự kiện bên ngoài tương tự, nhưng trước tiên cần đăng ký nguồn sự kiện tương ứng trong sources. Quy tắc sau theo dõi sự kiện issues.opened của GitHub:

{
  "name": "Xử lý issue",
  "when": {
    "source": "github",
    "types": ["issues.opened"]
  },
  "to": "codex",
  "cwd": "~/code/app",
  "skill": "handle-issue",
  "parallel": 3
}

skill chỉ định Skill cần thiết để xử lý tác vụ, còn parallel đặt số lượng chạy song song là 3. Cách đăng ký nguồn sự kiện cần tuân theo sổ tay cấu hình của dự án.

Sau khi lưu, quy tắc sẽ tự động có hiệu lực trong vài giây. Bạn nên chạy kiểm tra ngay:

agent-autoloop check

Nếu quy tắc mới có lỗi, hệ thống sẽ tiếp tục chạy bằng quy tắc cũ và thông báo vấn đề cụ thể qua thẻ, tránh để cấu hình sai làm gián đoạn hoạt động tự động hiện tại.

Bước 5: Để Agent yêu cầu con người quyết định

Quy ước chính của Agent Autoloop đối với Agent là: nêu kết quả trong câu trả lời cuối cùng. Nếu tác vụ đã hoàn tất, chỉ cần xuất kết luận bình thường; nếu cần người dùng lựa chọn, hãy thêm một khối mã phản hồi agent-autoloop ở cuối câu trả lời.

Đơn hàng đã được kiểm tra, hàng tồn kho đủ.

```agent-autoloop
{
  "ask": [{
    "title": "Giao hàng thế nào?",
    "text": "Cả hai phương thức đều có thể gửi hôm nay.",
    "options": ["Chuyển phát", "Tự nhận"],
    "key": "shipping"
  }]
}
```

Ở đây, ask sẽ tạo một thẻ quyết định gồm hai lựa chọn. Ngoài đặt câu hỏi, phản hồi còn hỗ trợ các hành động sau:

• notice: gửi thông báo.
• resolve: đóng thẻ đã được giải quyết.
• later: lên lịch kiểm tra lại vào một thời điểm trong tương lai.
• events: kích hoạt sự kiện mới.

Nếu JSON do Agent xuất ra không hợp lệ, nền tảng chỉ yêu cầu Agent viết lại phần phản hồi cuối cùng trong phiên ban đầu, không thực thi lại các thao tác nghiệp vụ đã hoàn tất. Nếu việc viết lại vẫn thất bại, hệ thống sẽ giữ nguyên kết luận ban đầu và thông báo cho bạn rằng phản hồi chưa có hiệu lực.

Sử dụng các mẫu kịch bản có sẵn

Dự án cung cấp nhiều mẫu bao gồm quy tắc, Skill tác vụ và hướng dẫn kích hoạt, có thể dùng làm điểm khởi đầu cho cấu hình thực tế:

• Bản tin buổi sáng hằng ngày: tổng hợp ghi chú cục bộ và các lần commit Git rồi ghi vào tệp đặt tên theo ngày.
• Theo dõi GitHub Issue: định kỳ kiểm tra Issue mới, sửa mã cục bộ và thông báo để bạn xem; mặc định không commit, không push và không trả lời Issue.
• Điều tra cảnh báo trực tuyến: tiếp nhận lỗi và đối chiếu mã để phân tích nguyên nhân; khi gặp thao tác khởi động lại, trước tiên yêu cầu phê duyệt.
• Xử lý phản hồi người dùng: kiểm tra trạng thái phản hồi, sửa vấn đề, xác minh việc bàn giao và chuẩn bị câu trả lời; khi cần quyết định, hỏi qua Feishu.
• Kiểm tra website: định kỳ kiểm tra trạng thái và nội dung quan trọng, tránh gửi thông báo lặp lại do lỗi kéo dài, đồng thời cập nhật thẻ ban đầu sau khi hệ thống khôi phục.
• Báo cáo tuần Feishu và tóm tắt nghiệp vụ: đọc báo cáo và bảng được chỉ định theo quyền hạn, lưu bản tóm tắt đầy đủ cục bộ, chỉ gửi nội dung ngắn gọn tới Feishu.
• Phân phối PR tự động: bắt đầu từ kiểm tra mã, chờ CI, merge PR, chờ triển khai rồi kiểm tra phiên bản trực tuyến.

Khi kích hoạt mẫu, cần đặt Skill tác vụ vào thư mục skills của Agent đang dùng, hợp nhất quy tắc mẫu vào ~/.agent-autoloop/rules.json, thay thế đường dẫn và tên máy, sau đó chạy agent-autoloop check.

README đặc biệt lưu ý: dữ liệu mẫu trong phần xử lý phản hồi, kiểm tra website và tóm tắt Feishu là dữ liệu hư cấu; các script và phản hồi liên quan chỉ được xác minh qua HTTP cục bộ và CLI Feishu mô phỏng, chưa hoàn tất kiểm thử nghiệp vụ đầy đủ trên tài khoản thực.

Tích hợp các Agent và kênh thông báo khác nhau

Plugin Agent tích hợp sẵn

Dự án tích hợp sẵn các plugin Claude Code, Codex, ACP và lệnh chung. Claude Code, Codex và bộ điều hợp Codex ACP chính thức đã hoàn tất nhiều vòng kiểm thử hỏi đáp và tiếp tục phiên qua các tiến trình.

Tích hợp Agent khác qua lệnh chung

Với các Agent dòng lệnh khác, có thể đặt use: "command" và cung cấp một mảng lệnh. Placeholder {prompt} được truyền vào dưới dạng tham số độc lập và không bị thực thi như mã Shell.

README liệt kê các ví dụ lệnh như DeepSeek Harness, pi, OpenClaw, Hermes, Cursor và WorkBuddy／CodeBuddy theo tài liệu chính thức của từng công cụ, nhưng cũng nêu rõ các lệnh này chưa được kiểm thử riêng từng cái. Vì vậy, trước khi sử dụng chính thức, cần xác minh tham số, định dạng đầu ra và hành vi phiên trong một thư mục biệt lập.

Cài đặt plugin bên thứ ba

Plugin bên thứ ba có thể được cài đặt qua địa chỉ Git:

agent-autoloop add <địa chỉ git>

Nếu cần tự phát triển plugin, có thể bắt đầu từ các mẫu plugin Agent, kênh và sự kiện tối thiểu do dự án cung cấp, đồng thời tham khảo hướng dẫn phát triển plugin.

Chọn kênh thông báo

Thông báo trên máy tính được bật mặc định. Feishu đã được kiểm thử thực tế với việc gửi, callback của nút và cập nhật thẻ. DingTalk, WeCom, Slack và Discord hiện sử dụng các mẫu Webhook, mới chỉ được xác minh trên dịch vụ mô phỏng cục bộ.

Các kênh văn bản này gửi quyết định thông qua liên kết trả lời, vì vậy bắt buộc phải cấu hình hub.publicUrl thành địa chỉ mà điện thoại hoặc máy tính có thể truy cập. Việc có cần truy cập công khai hay không phụ thuộc vào kênh và môi trường mạng bạn chọn, không phải bản thân việc chạy cục bộ cơ bản.

Kỹ thuật nâng cao và thiết kế độ tin cậy

Tra cứu lý do một vòng tác vụ được thực thi

Sử dụng lệnh why để xem sự kiện kích hoạt, phiên bản quy tắc, người nhận và kết quả cuối cùng của vòng được chỉ định:

agent-autoloop why 1

Điều này đặc biệt hữu ích khi kiểm tra các quy tắc lỗi, sự kiện trùng lặp hoặc việc phân công tác vụ ngoài ý muốn.

Tìm hiểu bốn cơ chế cốt lõi

• Tạm dừng không tiêu tốn tài nguyên: Khi chờ câu trả lời của con người, tiến trình Agent thoát và trạng thái được lưu trong cơ sở dữ liệu; sau khi có câu trả lời, phiên làm việc ban đầu sẽ được tiếp tục.
• Truy nguyên sự kiện: Mọi trạng thái đều được tính từ nhật ký chỉ ghi thêm. Nhật ký và chỉ mục được ghi vào đĩa trong cùng một giao dịch; khi định dạng thay đổi, có thể tái dựng trạng thái từ nhật ký.
• Tách biệt chỉ thị và dữ liệu: Nội dung bên ngoài như tiêu đề và nội dung Issue được lưu làm tài liệu, không được ghép trực tiếp vào prompt. Agent, thư mục làm việc và quyền hạn chỉ do quy tắc trên máy cục bộ quyết định; các trường cwd, agent, access trong sự kiện sẽ bị từ chối.
• Cầu chì giới hạn số bước: Các sự kiện mới do Agent kích hoạt sẽ cộng dồn số tầng; câu hỏi của con người và việc kiểm tra định kỳ không đặt lại số tầng. Sau khi vượt quá 8 tầng, hệ thống chỉ ghi nhận mà không tiếp tục phân công tác vụ, đồng thời gửi thẻ cho người dùng.

Chạy mô phỏng và kiểm thử hiệu năng

Truy cập thư mục chương trình:

cd ~/.agent-autoloop/app

Sau đó có thể chạy các lệnh xác minh được cung cấp trong README:

node sim/random.ts 24301 200000
node sim/crash.ts 1000 12648430
npm run benchmark

Lệnh đầu tiên mô phỏng mất kết nối mạng, mất gói tin, sự cố và gửi trùng lặp; lệnh thứ hai liên tục buộc tiến trình kết thúc để kiểm tra các bản ghi đã xác nhận có bị mất hay không; lệnh thứ ba chạy kiểm thử hiệu năng. Các ngưỡng đạt trong README dựa trên Apple M5 Pro, bộ nhớ 24 GB và Node 24.21.0; các máy khác có thể hiển thị chưa đạt do khác biệt phần cứng.

Khi nhật ký lịch sử tăng lên, việc tổng hợp trạng thái sẽ chậm hơn, đồng thời nhật ký và chỉ mục cũng tiếp tục chiếm dung lượng đĩa. Lần khởi động đầu tiên sau khi định dạng dữ liệu thay đổi có thể cần tái dựng toàn bộ, vì vậy khi chạy dài hạn cần chú ý đến dung lượng đĩa và thời gian khởi động.

Phạm vi sử dụng của quy trình bàn giao

Agent Autoloop cung cấp plugin delivery. Sau khi thêm nhãn deliver vào GitHub PR, hệ thống có thể liên tục theo dõi theo trình tự “review code, chờ CI, hợp nhất PR, chờ triển khai, đối chiếu phiên bản trực tuyến”.

Cấu hình review và bàn giao chỉ được đọc từ nhánh main, đồng thời không checkout hoặc chạy mã trong PR trên máy tính nhận tác vụ. Việc xếp hàng, xử lý đồng thời và thử lại sử dụng cùng một bộ cơ chế lõi. Trước khi chính thức kích hoạt, nên đọc tài liệu về ranh giới bảo mật kết hợp với quyền hạn của kho mã và quy trình phát hành.

Khuyến nghị về mức sử dụng và tuân thủ

Chi phí gọi mô hình được tính vào tài khoản của bạn; hạn mức và phạm vi sử dụng chịu sự điều chỉnh của điều khoản dịch vụ từ nhà cung cấp mô hình tương ứng. README lưu ý rằng các kịch bản tự động hóa tần suất cao thường phù hợp hơn với API Key; hạn mức gói đăng ký cá nhân chủ yếu dành cho tương tác thủ công hằng ngày. Nếu sử dụng công cụ này để cung cấp dịch vụ ra bên ngoài, nên dùng API Key và tự xác nhận các điều khoản dịch vụ cũng như yêu cầu tuân thủ.

Agent Autoloop là một dự án mã nguồn mở độc lập, không trực thuộc hoặc được Anthropic, OpenAI hay các nhà cung cấp mô hình khác chứng thực.

Kết luận

Trọng tâm của Agent Autoloop không phải là giữ Agent trực tuyến liên tục, mà là giúp tác vụ có thể tạm dừng, chờ và tiếp tục một cách đáng tin cậy. Bạn có thể bắt đầu bằng agent-autoloop try để xác minh vòng tương tác khép kín, sau đó viết quy tắc từ bản tin buổi sáng hằng ngày hoặc mẫu GitHub Issue. Sau khi xác nhận quy trình cục bộ ổn định, hãy từng bước tích hợp Feishu, Webhook, sự kiện bên ngoài và quy trình bàn giao PR.

Khi cần cấu hình thêm, có thể tham khảo sổ tay cấu hình quy tắc và bàn giao, giao thức liên lạc đầy đủ và tài liệu phát triển plugin.