OpenHands: trung tâm điều khiển coding agent — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về OpenHands/OpenHands — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: OpenHands: trung tâm điều khiển coding agent — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
OpenHands/OpenHands cung cấp Agent Canvas, một trung tâm điều khiển tự host để chạy OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode và các agent tương thích ACP. Bạn có thể chạy cục bộ, trong Docker, trên máy từ xa hoặc dịch vụ đám mây; cách cài đơn giản nhất là cài gói npm toàn cục, nhưng cần Node.js 24 trở lên và uv.
OpenHands/OpenHands là repo mã nguồn mở cung cấp Agent Canvas, một trung tâm điều khiển tự host cho coding agent và các quy trình tự động hóa. Bạn có thể dùng nó để bắt đầu cuộc trò chuyện với agent, kết nối nhiều máy chạy agent, hoặc để agent xử lý công việc theo lịch và sự kiện.
Điểm đáng giá nhất là Agent Canvas không khóa bạn vào một agent duy nhất. OpenHands được tích hợp sẵn, đồng thời có thể làm việc với Claude Code, Codex, Gemini CLI, Pi, OpenCode và agent tương thích Agent-Client Protocol (ACP). Bạn cũng có thể chọn chạy trực tiếp trên máy, trong Docker, trên máy ảo hoặc kết nối tới hạ tầng của công ty.
Repo phù hợp với lập trình viên, nhóm kỹ thuật, người muốn tự quản lý dữ liệu và doanh nghiệp cần tự động hóa các việc như chia nhỏ issue GitHub, tạo báo cáo gửi Slack, cập nhật mã nguồn hoặc chạy tác vụ trên máy chủ. Repo hiện có khoảng 93.402 sao và 12.494 fork, dùng giấy phép MIT.
OpenHands/OpenHands
OpenHands Agent Canvas là trung tâm tự host để chạy coding agent, kết nối nhiều backend và tự động hóa công việc kỹ thuật.
I.OpenHands làm được gì
A.Điều khiển nhiều coding agent trong một giao diện
Agent Canvas là nơi bạn bắt đầu cuộc trò chuyện và quản lý các agent. OpenHands chạy được ngay từ đầu, nhưng bạn có thể chuyển sang Claude Code, Codex, Gemini CLI, Pi, OpenCode hoặc một agent khác tương thích ACP.
Lợi ích thực tế là bạn không phải mở nhiều công cụ riêng cho từng agent. Bạn có thể chọn agent phù hợp với từng việc, chẳng hạn dùng một agent để sửa mã nguồn và một agent khác để kiểm tra hoặc phân tích vấn đề.
B.Kết nối backend cục bộ, từ xa và đám mây
Agent Canvas có thể kết nối tới backend chạy trên laptop, Docker, máy ảo, máy chủ riêng hoặc hạ tầng doanh nghiệp. Bạn có thể chuyển đổi giữa các backend mà không cần đổi giao diện làm việc.
Cách này phù hợp khi bạn muốn chạy việc nhẹ trên máy cá nhân, nhưng đưa tác vụ dài hoặc tác vụ cần chạy liên tục lên máy chủ. Agent vẫn có thể tiếp tục làm việc khi laptop đã đóng nếu backend được đặt trên máy chủ đám mây.
C.Tạo automation theo lịch hoặc webhook
Bạn có thể tạo workflow kết nối với Slack, GitHub, Linear và các dịch vụ khác. Automation có thể chạy theo lịch hoặc bắt đầu khi nhận webhook.
Ví dụ, một issue GitHub mới có thể được phân tích và chia thành các task. Một agent cũng có thể tạo báo cáo định kỳ rồi gửi kết quả vào Slack. Những việc lặp lại như vậy không cần nhân viên phải mở giao diện và chạy thủ công mỗi lần.
D.Dùng mô hình ngôn ngữ bạn chọn
Agent Canvas hỗ trợ dùng mô hình ngôn ngữ do bạn chọn thông qua phần cấu hình. Tài liệu gọi khả năng này là “bring your own model”, tức bạn có thể kết nối với bất kỳ LLM nào phù hợp.
Tư liệu không nêu danh sách đầy đủ các nhà cung cấp, giá hoặc cấu hình API cụ thể cho từng mô hình. Vì vậy, khi dùng một LLM cụ thể, bạn cần xem phần cài đặt LLM profiles và tài liệu tương ứng trong dự án.
E.Chạy local hoặc nhiều sandbox Docker
Bạn có thể chạy toàn bộ stack local, trong đó agent-server chạy trực tiếp trên máy. Bạn cũng có thể dùng một Docker sandbox cho workspace, hoặc tạo container riêng cho từng cuộc trò chuyện.
Mỗi cuộc trò chuyện trong chế độ nhiều sandbox có Agent Server và công cụ riêng. Workspace và lịch sử cuộc trò chuyện được lưu lại khi container bị thay thế. Tuy nhiên, các cuộc trò chuyện dùng chung một thư mục trên máy chủ vẫn có thể sửa cùng một file, nên bạn cần dùng thư mục hoặc worktree tách biệt nếu làm nhiều việc song song.
F.Tự host và kiểm soát dữ liệu
Agent Canvas chạy local theo mặc định. Bạn có thể giữ cài đặt, secrets, cuộc trò chuyện và workspace trong môi trường do mình quản lý.
Đây là điểm phù hợp với nhóm không muốn đưa toàn bộ mã nguồn hoặc lịch sử làm việc vào một dịch vụ bên ngoài. Dù vậy, quyền của agent phụ thuộc vào cách bạn triển khai. Nếu chạy không sandbox, agent-server có toàn quyền truy cập filesystem của máy cài đặt.
II.Cần chuẩn bị gì
- Node.js phiên bản 24 trở lên.
uvnếu chạy local bằng gói npm hoặc dùng source. README mô tảuvdùng để chạy agent server quauvx.- npm nếu cài gói toàn cục hoặc chạy từ source. Khi cài từ source, repo yêu cầu npm 11.12.1 theo lockfile.
- Docker Desktop trên macOS hoặc Windows, hoặc Docker Engine/Docker Desktop trên Linux nếu chọn Docker sandbox.
- Quyền chạy lệnh Docker nếu dùng nhiều Docker sandbox.
- Một thư mục workspace riêng nếu muốn agent làm việc với các dự án.
- API key hoặc thông tin cấu hình LLM/backend khi backend hoặc mô hình bạn chọn yêu cầu. Tư liệu được cung cấp không nêu tên biến API key cụ thể cho từng LLM.
Trên Windows, README có nhắc tới PowerShell quickstart và có file README.windows.md trong repo. Phần tư liệu được cung cấp không chép nội dung chi tiết của file Windows, nên mình không tự thêm lệnh Windows chưa được xác nhận.
Bạn không được yêu cầu GPU trong phần quickstart. Tư liệu cũng không nói Agent Canvas có bắt buộc GPU hay không. Với Docker, máy cần cài Docker Desktop hoặc Docker Engine tương ứng.
III.Cài đặt từng bước
- Chọn cách chạyChọn npm local, Docker sandbox, nhiều Docker sandbox hoặc chạy từ source
- Chuẩn bị môi trườngCài Node.js 24 trở lên, uv và Docker nếu cần
- Cài và khởi độngChạy đúng lệnh của phương án đã chọn
- Mở giao diệnTruy cập địa chỉ localhost được README chỉ định
- Cấu hình backendThêm backend, agent và thông tin LLM trong giao diện
A.Chọn cách chạy phù hợp
Có bốn phương án chính. Nếu bạn muốn thử nhanh trên máy cá nhân, dùng npm không sandbox. Nếu muốn cô lập workspace bằng container, dùng Docker sandbox. Nếu cần chạy nhiều cuộc trò chuyện đồng thời, dùng nhiều Docker sandbox. Nếu muốn chỉnh sửa repo hoặc phát triển chính Agent Canvas, chạy từ source.
Phương án không sandbox dễ bắt đầu nhưng agent-server chạy thẳng trên máy và có toàn quyền truy cập filesystem. Phương án Docker an toàn hơn cho workspace theo mô hình container, nhưng bạn cần hiểu quyền mount thư mục và cách lưu state.
B.Cài bản npm không sandbox
Đảm bảo đã cài Node.js 24 trở lên và uv, sau đó mở terminal. Bạn có thể đứng ở bất kỳ thư mục nào vì lệnh cài gói toàn cục không phụ thuộc vào thư mục dự án.
npm install -g @openhands/agent-canvas
agent-canvasLệnh đầu tiên cài gói @openhands/agent-canvas trên toàn hệ thống. Lệnh thứ hai khởi động full local stack theo mặc định.
Nếu muốn tách frontend và backend thành các tiến trình riêng, dùng một trong hai lệnh sau:
agent-canvas --frontend-only # static frontend + ingress only
agent-canvas --backend-only # agent server + automation backend + ingress only--frontend-only chạy frontend tĩnh và ingress. --backend-only chạy agent server, automation backend và ingress. Người mới thường nên bắt đầu bằng agent-canvas để giảm số tiến trình cần theo dõi.
C.Chạy với một Docker sandbox
Cài Docker Desktop trên macOS hoặc Windows, hoặc Docker Engine/Docker Desktop trên Linux. Các lệnh dưới đây là quickstart cho macOS và Linux.
Trước tiên, tạo workspace chứa các thư mục dự án:
export PROJECTS_PATH="$HOME/projects" # directory containing your project folders
mkdir -p "$PROJECTS_PATH"PROJECTS_PATH là đường dẫn trên máy host. Docker sẽ mount đường dẫn này vào /projects trong container. Hãy dùng một thư mục riêng, không dùng chung với dữ liệu nhạy cảm.
Trên Linux Docker Engine, user có UID 10001 trong container phải đọc và ghi được workspace. README đưa ra lựa chọn cấp quyền rộng như sau:
find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} +
find "$PROJECTS_PATH" -type f -exec chmod a+rw {} +Hai lệnh này cấp quyền cho mọi user trên máy đối với workspace. Chỉ dùng khi bạn hiểu rõ rủi ro và workspace không chứa dữ liệu nhạy cảm. Docker Desktop trên macOS và Windows thường tự xử lý quyền bind mount nên thường không cần hai lệnh trên.
Khởi động Agent Canvas bằng Docker:
docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v openhands-state:/home/openhands/.openhands \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.40.0 # x-release-please-versionSau khi container chạy, mở http://localhost:8000/canvas. Volume có tên openhands-state giữ settings, secrets và conversations khi container bị xóa. Nếu cần kiểm tra volume, README dùng lệnh:
docker volume inspect openhands-stateKhông nên đổi user mặc định trong container nếu chưa cấu hình đầy đủ. README cảnh báo việc override user có thể làm thư mục cấu hình trình duyệt không truy cập được. Nếu đổi user, cần cấu hình XDG_CONFIG_HOME có thể ghi và bảo đảm state cùng workspace được mount đúng quyền.
Trên Linux dùng SELinux, nếu thấy Permission denied, hãy kiểm tra xem bind mount có cần nhãn :z hoặc :Z không. Nếu mount state ~/.openhands hiện có thay vì named volume, UID 10001 cũng cần quyền với thư mục, file key và automation database.
D.Chạy nhiều Docker sandbox
Phương án này yêu cầu Node.js 24 trở lên, uv, Docker Desktop đang chạy trên macOS hoặc Docker Engine/Docker Desktop trên Linux. User khởi động Canvas phải chạy được lệnh docker.
Cài Agent Canvas nếu chưa cài:
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvasMỗi cuộc trò chuyện mới sẽ có container, Agent Server và công cụ riêng. Mở http://localhost:8000 rồi bắt đầu cuộc trò chuyện mới.
Các file workspace và lịch sử cuộc trò chuyện được lưu qua quá trình thay container. Tuy nhiên, hai cuộc trò chuyện dùng cùng host workspace vẫn chia sẻ file. Nếu chúng có thể sửa cùng một mã nguồn, hãy chọn thư mục hoặc worktree riêng để tránh xung đột.
README chỉ dẫn người dùng Windows xem README.windows.md cho phương án này. Không nên tự đổi cú pháp biến môi trường sang PowerShell nếu chưa kiểm tra file đó.
E.Chạy từ source
Phương án này phù hợp với contributor hoặc người muốn sửa chính repo. Repo yêu cầu Node.js 24 trở lên, npm 11.12.1 theo lockfile và uv. Trước khi cài dependency, kiểm tra phiên bản npm.
npm --version
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm ci
npm run devnpm --version giúp bạn phát hiện npm quá cũ trước khi resolve dependency. git clone tải repo, cd OpenHands đi vào thư mục dự án, npm ci cài đúng dependency theo lockfile, còn npm run dev khởi động bản development.
README nói bộ lọc release-age bảy ngày cần npm từ 11.10 trở lên, nhưng yêu cầu npm 11.12.1 là pin của repo khi chạy từ source. README cũng nhấn mạnh yêu cầu npm này dành cho contributor dependency resolution, không áp dụng cho việc cài package Canvas đã publish.
Sau khi khởi động, bản npm và source dùng địa chỉ http://localhost:8000. Bản Docker dùng http://localhost:8000/canvas.
IV.Kiểm tra đã chạy được chưa
Nếu chạy npm hoặc source, mở:
http://localhost:8000Nếu chạy image Docker theo quickstart, mở:
http://localhost:8000/canvasMàn hình Agent Canvas xuất hiện là dấu hiệu frontend đã chạy. Từ giao diện, bạn có thể thêm backend khác. README mô tả local listeners của npx hoặc npm run dev chỉ bind vào loopback 127.0.0.1, nên session key tự chèn không bị máy khác trong mạng truy cập.
Nếu dùng Docker, container có thể dừng với exit code 1 khi Agent Server không trả lời kiểm tra /alive trong khoảng 30 giây. Đây là dấu hiệu startup, crash hoặc hang cần kiểm tra log. Nếu muốn tự khởi động lại, README khuyên dùng restart policy unless-stopped thay cho --rm, hoặc dùng restart: unless-stopped trong Docker Compose.
Trong giao diện, hãy thử tạo một cuộc trò chuyện mới và thêm backend. Nếu agent có thể nhận yêu cầu, truy cập workspace và trả kết quả, stack đã sẵn sàng cho công việc thực tế.
V.Dùng vào việc thật
A.Chủ shop muốn tạo báo cáo vận hành
Một chủ shop có dữ liệu hoặc project nằm trong workspace có thể chạy agent để tổng hợp báo cáo theo mẫu. Khi đã cấu hình backend và LLM, bạn có thể đưa yêu cầu như:
Đọc các file báo cáo trong workspace, tổng hợp doanh thu và các vấn đề nổi bật, rồi tạo một bản báo cáo ngắn cho người quản lý.Agent xử lý file trong workspace theo quyền của backend. Nếu muốn báo cáo chạy định kỳ và gửi tới Slack, hãy tạo automation kết nối Slack, chọn lịch chạy và thiết lập workflow tương ứng. Tư liệu xác nhận Canvas hỗ trợ automation với Slack nhưng không cung cấp mẫu cấu hình cụ thể, nên phần chi tiết cần xem tài liệu automation trong repo.
B.Nhân viên văn phòng muốn theo dõi issue và chia việc
Nhân viên phụ trách dự án có thể kết nối GitHub và dùng automation để xử lý issue mới. Một yêu cầu phù hợp là:
Khi có issue mới, tóm tắt mục tiêu, xác định các phần việc cần làm và đề xuất thứ tự ưu tiên.Kết quả mong đợi là issue được phân tích thành các task rõ ràng hơn. Canvas có thể kích hoạt workflow từ webhook hoặc chạy theo lịch. Tư liệu không nói agent tự động được phép ghi ngược vào GitHub trong mọi cấu hình, vì vậy hãy kiểm tra quyền tích hợp trước khi cho phép thay đổi dữ liệu.
C.Lập trình viên muốn sửa lỗi trong workspace
Dev có thể chạy bản local hoặc Docker, mount project vào workspace rồi yêu cầu agent điều tra lỗi:
Đọc project trong workspace, tìm nguyên nhân lỗi đang được mô tả, đề xuất cách sửa và liệt kê các file sẽ thay đổi trước khi chỉnh sửa.Nếu cần nhiều agent thử các hướng khác nhau, dùng nhiều Docker sandbox. Mỗi cuộc trò chuyện có môi trường riêng, nhưng hãy dùng workspace hoặc worktree riêng để các agent không ghi đè file của nhau.
D.Nhóm kỹ thuật muốn chạy agent liên tục trên máy chủ
Nhóm có thể đặt backend trên máy chủ hoặc máy ảo để agent tiếp tục chạy khi laptop tắt. Canvas trên máy cá nhân có thể chuyển sang backend từ xa. Với công việc như kiểm tra dependency, code review hoặc tạo báo cáo định kỳ, đây là cách tận dụng backend luôn bật.
Bạn nên bảo vệ session key, API key và automation database. Nếu công khai Docker ra LAN hoặc Internet, README khuyên bỏ AGENT_CANVAS_ALLOW_LAN_SESSION_KEY, nhập API key trong giao diện và đặt LOCAL_BACKEND_API_KEY thành giá trị mạnh. Với hệ thống hướng ra Internet, cần đọc hướng dẫn self-hosting và security hardening.
Agent Canvas biến coding agent thành một đội kỹ thuật luôn sẵn sàng, nhưng quyền của đội đó chỉ an toàn khi workspace và key được giới hạn đúng cách.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Agent có quyền quá rộng khi chạy local
Đây không hẳn là lỗi cài đặt mà là rủi ro thiết kế. Khi chạy không sandbox, agent-server có toàn quyền truy cập filesystem của máy cài đặt.
Cách xử lý là dùng Docker sandbox cho workspace cần cô lập, hoặc chạy local trong một máy và thư mục dành riêng. Không đặt các file chứa dữ liệu nhạy cảm trong workspace nếu agent không cần đọc chúng.
B.Docker báo Permission denied
Trên Linux Docker Engine, UID 10001 trong container phải đọc và ghi được workspace. Kiểm tra quyền của đường dẫn trong thông báo lỗi; nếu dùng SELinux, kiểm tra nhu cầu nhãn :z hoặc :Z cho bind mount.
Nếu mount state hiện có, cần cấp quyền phù hợp cho thư mục, key và automation database. Không biến thư mục state thành writable cho mọi user vì user khác trên máy có thể thay session key.
C.Container khởi động nhưng không truy cập được giao diện
Kiểm tra lệnh publish port và mở đúng địa chỉ. Docker quickstart dùng 127.0.0.1:8000:8000 và giao diện ở /canvas, nên địa chỉ là http://localhost:8000/canvas.
Nếu Agent Server không trả lời /alive khoảng 30 giây, entrypoint sẽ dừng container với exit code 1. Hãy xem log để xác định crash hoặc hang trước khi thêm restart policy.
D.Nhiều cuộc trò chuyện sửa cùng file
Trong chế độ nhiều Docker sandbox, các cuộc trò chuyện dùng chung host workspace vẫn chia sẻ file. Vì vậy, hai agent có thể ghi đè hoặc tạo xung đột.
Hãy dùng thư mục riêng hoặc worktree riêng cho từng công việc. Lịch sử cuộc trò chuyện được giữ lại không có nghĩa là các file trong cùng workspace được tự động tách biệt.
E.Mở Canvas từ mạng nhưng session key không hoạt động như mong đợi
Local npx hoặc npm run dev chỉ bind loopback và tự chèn session key. Nếu dùng --host 0.0.0.0 hoặc OH_BIND_HOST, session key không được tự chèn và UI dùng màn hình nhập API key như --public.
Với Docker publish ra LAN hoặc giao diện công khai, không dùng AGENT_CANVAS_ALLOW_LAN_SESSION_KEY. Hãy nhập API key trong UI và đặt LOCAL_BACKEND_API_KEY thành giá trị mạnh.
VII.Có nên dùng không
OpenHands/OpenHands đáng dùng nếu bạn muốn một trung tâm tự host cho nhiều coding agent, cần chuyển đổi giữa backend local và remote, hoặc muốn kết hợp agent với Slack, GitHub, Linear, lịch chạy và webhook. Gói npm giúp thử nhanh, còn Docker phù hợp hơn khi cần cô lập workspace.
Điểm mạnh là phạm vi tích hợp rộng, hỗ trợ nhiều agent, có khả năng chạy liên tục trên máy chủ và cho phép bạn chọn mô hình ngôn ngữ. Repo dùng MIT, có mã TypeScript chính và có sẵn cấu hình cho package, test, Docker, Windows và source development.
Giới hạn cần cân nhắc là việc tự host vẫn đòi hỏi hiểu Node.js, npm, uv, Docker, quyền filesystem và bảo mật key. Chạy không sandbox có thể cho agent toàn quyền với máy. Chạy nhiều sandbox giúp cô lập cuộc trò chuyện nhưng không tự tách các cuộc trò chuyện nếu chúng cùng mount một workspace.
Nếu bạn chỉ cần một chatbot hỏi đáp mã nguồn đơn giản, Agent Canvas có thể lớn hơn nhu cầu. Nếu bạn cần nền tảng agent chạy lâu dài, nhiều backend và automation có kiểm soát, đây là lựa chọn phù hợp. Với triển khai Internet-facing hoặc dữ liệu nhạy cảm, hãy đọc thêm hướng dẫn self-hosting, cấu hình backend và hardening bảo mật trước khi mở quyền truy cập.
Câu hỏi thường gặp
OpenHands/OpenHands có miễn phí không?
Repo có giấy phép MIT. Tư liệu không nêu chi phí sử dụng các mô hình, backend, OpenHands Cloud hoặc hạ tầng máy chủ, nên tổng chi phí phụ thuộc vào cách bạn triển khai và dịch vụ bạn kết nối.
Có cần GPU để chạy OpenHands Agent Canvas không?
Phần quickstart không yêu cầu GPU. Tư liệu được cung cấp chưa xác nhận cụ thể GPU có cần cho mọi backend hoặc mô hình hay không.
Có chạy được trên Windows không?
Có dấu hiệu hỗ trợ Windows: README yêu cầu Docker Desktop trên Windows cho Docker sandbox và repo có file `README.windows.md`. Tuy nhiên, phần tư liệu được cung cấp không có toàn bộ lệnh PowerShell chi tiết.
Agent có truy cập được toàn bộ máy tính không?
Nếu chạy agent-server trực tiếp trên máy không sandbox, agent có toàn quyền truy cập filesystem của máy cài đặt. Dùng Docker sandbox và workspace riêng để giới hạn phạm vi tốt hơn.
Có thể dùng Claude Code, Codex hoặc Gemini không?
Có. Agent Canvas chạy OpenHands tích hợp sẵn và có thể dùng Claude Code, Codex, Gemini CLI, Pi, OpenCode hoặc agent tương thích Agent-Client Protocol.
Dữ liệu và API key có an toàn không?
Agent Canvas có thể chạy local và lưu state trong named Docker volume, nhưng an toàn phụ thuộc vào quyền mount, session key, API key và cách mở mạng. Không nên dùng quyền writable rộng cho thư mục state; khi publish Docker ra LAN hoặc Internet, hãy bỏ tùy chọn cho phép chèn LAN session key và đặt API key mạnh.
Có thể chạy nhiều agent cùng lúc không?
Có. Chế độ nhiều Docker sandbox tạo container, Agent Server và công cụ riêng cho từng cuộc trò chuyện. Các cuộc trò chuyện vẫn có thể xung đột nếu cùng dùng một host workspace, nên dùng thư mục hoặc worktree riêng.


