OpenHands Agent Canvas: bảng điều khiển tự lưu trữ cho coding agent
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
OpenHands năm 2026: repository này giờ là bảng điều khiển, không còn là lõi agent
Ai nhớ OpenHands như một agent lập trình nên đọc lại README tại commit nghiên cứu: repository nay giới thiệu Agent Canvas, được mô tả là trung tâm điều khiển tự lưu trữ dành cho các coding agent, tức agent AI viết và sửa mã, cùng các tác vụ tự động hóa. Nó chạy agent OpenHands mã nguồn mở theo mặc định nhưng cũng điều khiển được Claude Code, Codex, Gemini CLI, Pi, OpenCode hoặc bất kỳ agent nào hỗ trợ giao thức ACP. Huy hiệu trạng thái ghi beta. [1]
Phần thực thi agent không nằm ở đây. README nêu rõ Agent Canvas là giao diện và lớp điều phối, còn Agent Server, SDK, công cụ và API chuẩn thuộc repository software-agent-sdk; lịch chạy và webhook thuộc repository automation. [1] Đánh giá OpenHands vì thế phải nhìn cả hệ, chứ không chỉ mã trong repository này.
Nên cân nhắc Agent Canvas khi một đội phát triển muốn gom nhiều agent và nhiều máy chạy về một giao diện, chạy agent trong container, và lên lịch các việc lặp lại như cập nhật phụ thuộc hay tóm tắt issue. Không nên dùng khi đội chưa sẵn sàng quản trị một dịch vụ có quyền đọc ghi mã nguồn và chạy lệnh shell, hoặc khi cần một sản phẩm ổn định lâu dài thay vì một bản beta thay đổi nhanh.
Khi mỗi lập trình viên chạy một agent riêng trên laptop
Cách dùng coding agent phổ biến vẫn là mỗi người mở một agent trên máy mình: agent dừng khi gập laptop, quyền truy cập rải rác, và việc lặp lại như rà phụ thuộc không có nơi chạy định kỳ.
README của Agent Canvas đặt vấn đề theo hướng ngược lại: biến coding agent thành một đội kỹ thuật tự lưu trữ, luôn bật. Cách mạnh nhất, theo README, là chạy trên máy chủ đám mây để agent tiếp tục làm việc khi laptop tắt và dễ được kích hoạt từ Slack, GitHub hay Datadog. Một Agent Server dùng chung cho cả đội có thể làm code review và cập nhật phụ thuộc, trong khi agent cá nhân vẫn chạy trên máy từng người. [1]
Vấn đề thứ hai là mỗi nhà cung cấp agent có CLI, cách đăng nhập và chọn mô hình riêng; Agent Canvas dùng Agent Client Protocol để đặt chúng sau cùng một giao diện. [4] Câu hỏi cho doanh nghiệp là sự tập trung này có làm bề mặt rủi ro tăng nhanh hơn lợi ích hay không.
Một frontend, nhiều Agent Server và một máy chủ tự động hóa
Tài liệu kiến trúc mô tả Agent Canvas là frontend React và TypeScript để chạy và theo dõi agent OpenHands trên môi trường cục bộ, từ xa và được lưu trữ. Nó chịu trách nhiệm hiển thị hội thoại, terminal, trình duyệt, tệp, cài đặt và giao diện tự động hóa; quản lý trạng thái frontend; và dịch thao tác người dùng thành lời gọi API tới Agent Server. [2]
Điều quan trọng không kém là danh sách những việc Agent Canvas không làm: không trực tiếp thực thi hành động của agent, không cung cấp lớp sandbox hay cô lập workspace, không giữ khóa nhà cung cấp mô hình ngoài backend đã cấu hình, và không tự chạy tác vụ theo lịch nếu thiếu backend tự động hóa. [2] Nói cách khác, ranh giới bảo mật thật nằm ở Agent Server và môi trường chạy nó.
Backend chính là OpenHands Agent Server, một REST API cho phép chạy nhiều agent trên một máy; mỗi Agent Server chạy trên một host và cổng, và Canvas có thể kết nối nhiều server rồi chuyển qua lại. Agent Server thường đi kèm Automation Server để chạy agent theo lịch hoặc theo sự kiện. [1] Các dịch vụ tùy chọn khác gồm ingress gom frontend, Agent Server và tự động hóa về một origin, cùng API của OpenHands Cloud cho sandbox được lưu trữ và quy trình tổ chức. [2] Gói npm @openhands/agent-canvas còn cung cấp entrypoint thư viện để nhúng từng phần giao diện vào ứng dụng khác. [2]
Bốn repository, một hệ thống: đọc đúng chỗ trước khi đánh giá
README dành hẳn một bảng để phân định trách nhiệm. OpenHands/OpenHands giữ frontend Agent Canvas, trung tâm điều khiển, việc chọn backend và điều phối stack cục bộ. software-agent-sdk giữ Python SDK, Agent Server, agent, công cụ, hội thoại, workspace, sự kiện và API chuẩn. typescript-client là client TypeScript cho API của Agent Server. automation giữ định nghĩa tự động hóa, lịch, webhook, lịch sử chạy và cơ chế phân phối. [1]
Hệ quả là phần lớn hành vi người dùng quan tâm, như agent chạy lệnh gì hay workspace cô lập ra sao, nằm ngoài repository được nghiên cứu; ngay cả danh sách nhà cung cấp ACP cũng lấy từ registry của SDK. [4]
Nhận định của bài viết về Agent Server, SDK hay automation chỉ dựa trên mô tả trong tài liệu Canvas. Đánh giá triển khai thật cần ghim phiên bản cả bốn thành phần, vì tài liệu ACP cho thấy Canvas yêu cầu phiên bản Agent Server tối thiểu cho một số tính năng. [4]
Từ cú nhấp trên giao diện tới tiến trình agent trong container
Khi tự lưu trữ trên máy ảo, lệnh khởi động ở chế độ public dựng bốn thành phần sau một ingress lắng nghe ở 127.0.0.1 cổng 8000: máy chủ tĩnh cho frontend, Agent Server, backend tự động hóa, và ingress định tuyến theo đường dẫn. Yêu cầu tới đường dẫn API và socket đi vào Agent Server, yêu cầu API tự động hóa đi vào backend tự động hóa, phần còn lại trả về tệp tĩnh. Nginx đứng trước để kết thúc TLS. [3]
Mỗi lời gọi API phải mang header X-Session-API-Key khớp với khóa LOCAL_BACKEND_API_KEY; ở chế độ public, khóa không được nhúng sẵn vào frontend mà người dùng phải nhập khi mở giao diện. [3] Sự kiện trực tiếp đi qua WebSocket hoặc SSE. [3]
Với agent ACP, luồng có thêm một tầng. Canvas ghi lựa chọn agent qua PATCH tới API cài đặt, gửi lượt hội thoại tới Agent Server, và Agent Server sinh tiến trình CLI của agent, nói chuyện bằng JSON-RPC qua stdio; chính agent bên ngoài gọi nhà cung cấp mô hình. Thông tin xác thực được lưu thành secret toàn cục mang đúng tên biến môi trường mà Agent Server xuất cho tiến trình con. [4]
Nếu bật chế độ nhiều sandbox, mỗi hội thoại mới chạy trong container riêng với Agent Server và công cụ riêng, gắn workspace và trạng thái của hội thoại đó. README lưu ý chế độ này cô lập việc thực thi hội thoại nhưng không đưa toàn bộ Canvas hay dịch vụ tự động hóa vào sandbox, và các hội thoại dùng chung thư mục trên máy chủ vẫn chia sẻ tệp. [1]
Năng lực được ghi nhận trong tài liệu tại commit 0f1b6f6
README liệt kê bốn cách cài: chạy thẳng trên máy, trong một container Docker gắn thư mục dự án, mỗi hội thoại một container, và từ mã nguồn; hai cách không sandbox kèm cảnh báo agent có toàn quyền hệ thống tệp. [1]
Về nhiều backend, đặc tả yêu cầu thêm backend thì tự chuyển sang nó, chuyển backend thì không bao giờ hiển thị dữ liệu cũ của backend trước, và xóa backend đang dùng thì quay về một backend cục bộ còn lại. [5]
Về agent bên ngoài, tài liệu ACP liệt kê lệnh mặc định cho Claude Code, Codex, Gemini CLI, Pi và OpenCode. Pi và OpenCode chỉ có trên backend cục bộ hoặc tự lưu trữ, còn OpenHands Cloud chỉ chạy Claude Code, Codex và Gemini CLI. Nếu CLI đã đăng nhập bằng tài khoản thuê bao trên cùng máy, đăng nhập đó được ưu tiên hơn khóa API. Mục Custom cho phép trỏ tới bất kỳ máy chủ ACP nào chạy qua stdio. [4]
Về tự động hóa, README mô tả việc tạo workflow tích hợp Slack, GitHub, Linear, Notion, chạy theo lịch hoặc khi có webhook, và cho phép dùng bất kỳ mô hình ngôn ngữ nào. [1] Về chất lượng phát hành, CI chạy kiểm tra kiểu, lint, kiểm thử đơn vị, build ứng dụng và thư viện; bản phát hành npm dùng trusted publishing kèm provenance. [2]
Đội phần mềm nhỏ có người quản trị hạ tầng là đối tượng hợp nhất
Đối tượng phù hợp nhất là đội phát triển từ vài người đến vài chục người, đã quen dùng coding agent và muốn chuẩn hóa nơi chạy. Họ được lợi từ việc một Agent Server chung xử lý các việc định kỳ, trong khi từng người vẫn giữ agent cá nhân. [1]
Điều kiện cần là có người hiểu quản trị Linux, tường lửa, TLS và bí mật. Tài liệu tự lưu trữ yêu cầu khóa tường lửa trước khi chạy Agent Server lần đầu và đối xử với máy ảo như một máy giữ thông tin xác thực production. [3] Thiếu năng lực đó thì nên bắt đầu bằng chế độ Docker trên máy cá nhân, giới hạn một thư mục dự án.
Nhóm thứ ba là nhà phát triển muốn nhúng giao diện agent vào sản phẩm riêng. [2] Bộ phận không viết mã như kế toán hay chăm sóc khách hàng không phải đối tượng, vì giao diện xoay quanh terminal, tệp, git và pull request.
Tình huống đề xuất: đội kỹ thuật của một nhà bán lẻ trực tuyến ở TP.HCM
Đây là tình huống giả định, không phải dự án đã triển khai. Một doanh nghiệp bán đồ gia dụng trực tuyến ở TP.HCM có website riêng và kết nối vài sàn thương mại điện tử. Đội kỹ thuật năm người duy trì website và dịch vụ đồng bộ tồn kho, thường tồn đọng việc nhỏ như nâng phiên bản thư viện hay viết rõ issue do bộ phận vận hành gửi.
Đề xuất là dựng một máy ảo Linux riêng chỉ cho Agent Canvas, theo đúng các bước trong hướng dẫn tự lưu trữ: chặn mọi cổng vào trừ SSH từ IP văn phòng, sinh khóa ngẫu nhiên cho LOCAL_BACKEND_API_KEY, chạy ở chế độ public sau nginx có TLS. [3] Mỗi hội thoại chạy trong container riêng để hai việc song song không giẫm lên nhau, và mỗi việc dùng một thư mục làm việc riêng như README khuyến nghị. [1]
Hai tự động hóa đầu tiên nên là việc ít rủi ro: mỗi tuần mở một pull request nâng phụ thuộc cho dịch vụ đồng bộ tồn kho, và mỗi khi có issue mới thì agent đề xuất cách tách thành các đầu việc nhỏ, đăng lại thành bình luận. README liệt kê Slack và GitHub là hai tích hợp có sẵn. [1] Tài liệu không nhắc đến Zalo hay Google Chat, nên nếu đội trao đổi chủ yếu qua các kênh đó, cần chấp nhận nhận báo cáo qua GitHub hoặc Slack, hoặc tự xây cầu nối.
Quy tắc riêng cho thương mại điện tử: dừng tự động hóa tạo pull request vài ngày trước các đợt khuyến mãi lớn như 11.11, không cấp cho agent khóa thanh toán hay cơ sở dữ liệu đơn hàng thật. Agent chỉ đề xuất; người trong đội review và merge.
Vận hành: cổng mạng, tiến trình nền và phiên bản các thành phần
Hướng dẫn tự lưu trữ đưa ra quy trình năm bước: cấp máy, khóa mạng, chạy Agent Canvas, tùy chọn gắn tên miền với nginx và Let's Encrypt, rồi tùy chọn đăng ký máy từ xa như một backend trong Canvas cục bộ. Các cổng nội bộ của ingress, Agent Server, backend tự động hóa và máy chủ tĩnh không được để lộ ra ngoài máy. [3]
Để dịch vụ chạy sau khi đóng phiên SSH, tài liệu gợi ý tmux cho cách nhanh và systemd cho triển khai lâu dài, kèm mẫu unit tự khởi động lại khi lỗi. [3] Một lưu ý vận hành: lệnh npx trong mẫu tải bản phát hành mới nhất, nên nếu cần ổn định, đội nên ghim phiên bản gói và ảnh Docker, vì README dùng ảnh có số phiên bản cụ thể trong ví dụ Docker. [1][3]
Tài liệu cho rằng máy 2 vCPU và 4 GB RAM là đủ cho một người dùng; đây là con số của tài liệu, chưa tính nhiều container chạy song song. [3]
Cuối cùng, nên nâng Canvas, Agent Server và dịch vụ tự động hóa cùng lúc trên môi trường thử, vì tài liệu ACP cho thấy có tính năng phụ thuộc phiên bản Agent Server tối thiểu. [4]
Ai nói chuyện được với agent server thì có quyền như agent
Câu cảnh báo trung tâm của tài liệu tự lưu trữ là Agent Canvas điều khiển một agent có thể đọc ghi hệ thống tệp, chạy lệnh shell và truy cập mạng, và bất kỳ ai nói chuyện được với Agent Server cũng làm được như vậy. [3] Hai lớp phòng thủ chính là tường lửa mạng và khóa API bắt buộc trên mọi lời gọi.
Có một điểm yếu được tài liệu thừa nhận công khai. Trình soạn thảo OpenVSCode đi kèm được phục vụ dưới một tiền tố đường dẫn trên cùng origin với Canvas, nên mã script chạy ở bất kỳ đâu trên origin đó, kể cả nội dung tiếp cận qua tiện ích mở rộng hay tài nguyên bị xâm phạm, có thể đọc localStorage, nơi giữ khóa phiên của mọi backend đã đăng ký trong trình duyệt. Vấn đề được theo dõi trong một issue riêng. [3] Doanh nghiệp nên coi đây là rủi ro đang mở khi đánh giá.
Về thông tin xác thực, tài liệu ACP lưu ý các hội thoại cùng nhà cung cấp trong một container dùng chung thư mục home nên có thể tranh chấp tệp xác thực và cấu hình, và tùy chọn cô lập theo hội thoại chưa được Canvas gửi đi. [4]
Về quyền riêng tư, Canvas có telemetry qua PostHog, phụ thuộc lựa chọn đồng ý của người dùng, nhưng sự kiện cài đặt được gửi một lần trước khi có đồng ý, kèm ID ẩn danh; đặt VITE_DO_NOT_TRACK bằng 1 sẽ tắt cấu hình mặc định. [6]
MIT cho Canvas; các thành phần còn lại cần kiểm tra riêng
Tệp LICENSE ở thư mục gốc tại commit nghiên cứu là giấy phép MIT, ghi bản quyền năm 2025 thuộc các cộng tác viên OpenHands. [7] Danh sách tệp tài liệu và giấy phép tại commit này không cho thấy thư mục nào mang tệp giấy phép khác, và repository không có tệp mô tả phạm vi giấy phép bổ sung.
Tuy vậy, MIT ở đây chỉ bao phủ mã trong repository OpenHands/OpenHands, tức frontend và bộ khởi chạy. Agent Server, SDK, client TypeScript và dịch vụ tự động hóa nằm ở các repository khác mà bài viết không đọc giấy phép. [1] Ảnh Docker dựng sẵn và gói npm có thể kéo theo phụ thuộc với giấy phép riêng.
Cần tách bạch phần mã nguồn mở với dịch vụ thương mại. README gọi OpenHands Cloud là sản phẩm thương mại và nhắc tới hạ tầng OpenHands Enterprise như lựa chọn tùy chọn. [1] Các CLI agent bên thứ ba như Claude Code, Codex hay Gemini CLI, cùng mô hình và tài khoản thuê bao đi kèm, chịu điều khoản của nhà cung cấp tương ứng; giấy phép MIT của Canvas không trao quyền gì với chúng.
Chi phí nằm ở thời gian quản trị và hóa đơn mô hình
Phần mềm Canvas miễn phí theo MIT, nên chi phí thực tế gồm bốn nhóm. Thứ nhất là máy chạy: một máy ảo đám mây hoặc máy chuyên dụng luôn bật; tài liệu xem cấu hình nhỏ là đủ cho một người, nhưng chế độ mỗi hội thoại một container sẽ cần thêm CPU, bộ nhớ và ổ đĩa tương ứng số việc chạy song song. [3]
Thứ hai là mô hình. Canvas cho phép mang mô hình của mình, còn agent ACP dùng khóa API hoặc tài khoản thuê bao của nhà cung cấp. [1][4] Cần đặt hạn mức theo dự án và theo tự động hóa, vì một tác vụ chạy theo lịch mỗi ngày tiêu tốn lặp lại mà không ai nhìn thấy nếu không theo dõi.
Thứ ba là công quản trị: vá hệ điều hành, gia hạn chứng chỉ, nâng phiên bản và rà nhật ký; bài viết giả định vài giờ mỗi tuần giai đoạn đầu, cần đo lại trong thí điểm.
Thứ tư là công review: mỗi pull request của agent vẫn cần người đọc, nên số tự động hóa phải tăng theo năng lực review chứ không theo khả năng sinh mã.
Bảng điều khiển tự lưu trữ, dịch vụ đám mây hay agent riêng lẻ
Cách thứ nhất là để mỗi lập trình viên tự dùng CLI agent trên máy mình. Đơn giản, không có máy chủ để bảo vệ, nhưng không có nơi chạy định kỳ và khó áp quy tắc chung. Đây là điểm xuất phát hợp lý cho đội chưa có nhu cầu tự động hóa.
Cách thứ hai là Agent Canvas tự lưu trữ. Đội giữ toàn quyền về nơi chạy, dữ liệu mã nguồn và mô hình, và có thể dùng nhiều loại agent sau một giao diện. [1][4] Đổi lại, đội tự chịu trách nhiệm bảo mật máy chủ, điều mà tài liệu nhấn mạnh nhiều lần. [3]
Cách thứ ba là dịch vụ lưu trữ sẵn như OpenHands Cloud, sản phẩm thương mại theo README, hoặc dịch vụ agent đám mây khác. [1] Bớt công vận hành nhưng mã nguồn đi qua hạ tầng bên ngoài; bài viết không so sánh giá hay chất lượng.
Cách thứ tư là tự ghép workflow CI với lời gọi mô hình cho từng việc, như bot nâng phụ thuộc truyền thống kèm tóm tắt bằng mô hình: kém linh hoạt nhưng dễ kiểm soát.
Những trường hợp nên đợi hoặc chọn cách khác
Trạng thái beta là giới hạn đầu tiên, và tài liệu ACP cho thấy có tính năng đã có ở SDK nhưng chưa được client và Canvas hỗ trợ. [1][4] Tổ chức cần ổn định giao diện và API trong thời gian dài nên chờ hoặc ghim phiên bản chặt.
Không nên chạy các chế độ không sandbox trên máy có dữ liệu nhạy cảm, vì README cảnh báo agent khi đó có toàn quyền hệ thống tệp. [1] Không nên mở Canvas ra Internet nếu chưa xử lý được rủi ro khóa phiên trong localStorage mà tài liệu đã nêu. [3]
Canvas cũng không bảo đảm chất lượng mã do agent tạo; nó chỉ điều phối. [2] Kho mã thiếu kiểm thử tự động thì agent tạo thay đổi nhanh hơn khả năng phát hiện lỗi.
Thí điểm sáu tuần, đo bằng pull request được merge
Giai đoạn một, tuần một và hai: dựng Canvas trên một máy ảo riêng theo hướng dẫn tự lưu trữ, bật chế độ public và mỗi hội thoại một container, chỉ gắn một kho mã không chứa bí mật. [1][3] Tiêu chí qua giai đoạn là kiểm tra từ bên ngoài không thấy cổng nội bộ nào, mọi lời gọi API không có khóa bị từ chối, và có nhật ký truy cập lưu ít nhất ba mươi ngày.
Giai đoạn hai, tuần ba và bốn: bật một tự động hóa nâng phụ thuộc hằng tuần và một tự động hóa tách issue. Đo bốn chỉ số: tỷ lệ pull request của agent được merge không cần sửa, tỷ lệ phải sửa nhiều, thời gian review trung bình mỗi pull request, và chi phí mô hình trên mỗi pull request được merge.
Giai đoạn ba, tuần năm và sáu: thử một agent ACP bên ngoài trên cùng việc và chạy hai việc song song để kiểm tra cô lập. Dừng và quay về agent cá nhân nếu tỷ lệ merge dưới ngưỡng đặt từ đầu, có sự cố lộ khóa, hoặc thời gian review vượt thời gian tiết kiệm.
Kết luận: tập trung hóa agent đòi hỏi tập trung hóa trách nhiệm
OpenHands tại thời điểm nghiên cứu là một hệ nhiều repository, trong đó repository mang tên dự án đã chuyển thành bảng điều khiển Agent Canvas. Giá trị chính là gom nhiều agent, nhiều máy và các tác vụ định kỳ về một nơi, với kiến trúc tách bạch giữa giao diện, máy chủ agent và máy chủ tự động hóa. [1][2]
Đổi lại, agent luôn bật trên máy chủ chung biến mạng, khóa và quyền truy cập thành trách nhiệm của đội vận hành; tài liệu dự án nói thẳng về các rủi ro này. [3]
Với một kho tri thức kỹ thuật, kiểu bộ não thứ hai mà phamvanthu.com hướng tới, ý tưởng đáng tham khảo là để agent đề xuất thay đổi qua pull request có người duyệt thay vì ghi thẳng. Đây là gợi ý của bài viết, không có nghĩa BDSG đang dùng OpenHands.
Cách chọn dự án, tệp đã đọc và điều bài viết không làm
OpenHands được chọn từ kho lưu trữ GitHub Trending cộng đồng, nơi dự án xuất hiện một lần, ngày 2026-06-15, ở vị trí 18 của danh sách Python. [8] Kho lưu trữ chỉ chứa danh sách Python, Go, JavaScript và Swift, thiếu ngày 2026-09-03 và 2026-10-12; loạt bài không phải bảng top 100 chính thức.
Bài viết phân tích commit 0f1b6f62507f1ccdb4e63f61cf3dc48356a0d4fa, ngày commit 2026-10-12, kiểm tra ngày 2026-10-12. Các tệp đã đọc gồm README, LICENSE, docs/architecture.md, docs/SELF_HOSTING.md, docs/ACP_AGENTS.md, đặc tả quản lý backend và hướng dẫn kiến trúc telemetry. [1][2][3][4][5][6][7] Mã nguồn của Agent Server, SDK và dịch vụ tự động hóa ở các repository khác không được đọc.
Đây là nghiên cứu tài liệu: không cài đặt, chạy, đo hay triển khai phần mềm. Con số cấu hình máy là của tài liệu dự án. Tình huống ở TP.HCM là đề xuất giả định. Bài viết không phải công bố khoa học đã qua bình duyệt.
Xem mã nguồn OpenHands trên GitHub