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 là ứng dụng Agent Canvas, một trung tâm điều khiển tự host cho OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode và agent tương thích ACP. Bạn có thể chạy cục bộ, trong Docker hoặc kết nối backend từ xa để giao việc lập trình và tự động hoá. Cài bằng gói npm khá nhanh, nhưng cần Node.js 24 trở lên và uv; Docker phù hợp hơn nếu muốn cô lập agent.
OpenHands/OpenHands là ứng dụng Agent Canvas, một trung tâm điều khiển tự host cho coding agent và các quy trình tự động hoá. Bạn có thể dùng nó để mở cuộc trò chuyện với agent, cho agent làm việc trên dự án, kết nối nhiều backend và chuyển qua lại giữa các môi trường chạy.
Repo phù hợp với lập trình viên, nhóm kỹ thuật và người muốn thử nhiều agent trong cùng một giao diện. Người làm kinh doanh hoặc văn phòng cũng có thể dùng nếu cần tự động tạo báo cáo, kết nối Slack, GitHub, Notion hoặc chạy tác vụ theo lịch. Điểm đáng giá nhất là bạn có thể chạy tại máy riêng, trong Docker, trên máy ảo hoặc kết nối hạ tầng cloud mà vẫn điều khiển từ một Agent Canvas.
Repo hiện có khoảng 93.402 sao và 12.494 fork. Mã nguồn dùng giấy phép MIT. README mô tả Agent Canvas là một hệ thống self-hosted, có thể chạy OpenHands và dùng thêm Claude Code, Codex, Gemini CLI, Pi, OpenCode hoặc agent tương thích Agent-Client Protocol.
OpenHands/OpenHands
Agent Canvas biến OpenHands và nhiều coding agent thành trung tâm tự host để lập trình, tự động hoá và kết nối công cụ.
I.OpenHands làm được gì
A.Gom nhiều coding agent vào một giao diện
Agent Canvas chạy OpenHands ngay từ đầu và cho phép dùng thêm Claude Code, Codex, Gemini CLI, Pi, OpenCode hoặc agent tương thích ACP. Bạn không phải mở một giao diện riêng cho từng agent. Việc chuyển backend cũng có thể thực hiện từ cùng một nơi.
Điều này hữu ích khi mỗi công cụ có thế mạnh khác nhau. Bạn có thể dùng một agent để sửa mã nguồn, agent khác để xem xét thay đổi, rồi giữ các cuộc trò chuyện trong cùng hệ thống.
B.Chạy agent tại máy hoặc trên hạ tầng riêng
Bạn có thể chạy agent trực tiếp trên laptop, trên một máy chuyên dụng như Mac Mini, trong Docker, trên máy ảo hoặc trong hạ tầng công ty. Agent Canvas kết nối đến nhiều Agent Server và cho phép chuyển đổi giữa backend cục bộ, từ xa và cloud.
Nhóm kỹ thuật có thể đặt Agent Server trên máy dùng chung cho công việc review mã nguồn hoặc cập nhật dependency. Đồng thời, mỗi thành viên vẫn có thể chạy agent cá nhân trên laptop.
C.Tạo tự động hoá cho công việc lặp lại
Agent Canvas hỗ trợ tạo automation và workflow tích hợp với Slack, GitHub, Linear và các dịch vụ khác. Automation có thể chạy theo lịch hoặc phản hồi sự kiện webhook.
Ví dụ, một workflow có thể nhận sự kiện từ GitHub, phân rã issue thành các task rồi chuyển cho agent xử lý. Một workflow khác có thể tạo báo cáo và gửi lên Slack. README không cung cấp cú pháp chi tiết cho từng automation, nên phần cấu hình cụ thể cần xem trong tài liệu và giao diện của dự án.
D.Dùng mô hình ngôn ngữ bạn chọn
README ghi rõ Agent Canvas có thể dùng với bất kỳ LLM nào. Vì vậy, bạn có thể chọn mô hình phù hợp với chi phí, tốc độ, chính sách dữ liệu hoặc yêu cầu kỹ thuật của mình.
Tư liệu được cung cấp không nêu danh sách API key, tên biến môi trường của từng nhà cung cấp LLM hay mức giá. Bạn cần cấu hình thông tin mô hình trong phần cài đặt của ứng dụng hoặc tài liệu tương ứng.
E.Tách phần giao diện và phần chạy agent
Bạn có thể chạy toàn bộ stack bằng một lệnh, hoặc tách riêng frontend và backend. Chế độ frontend chỉ chạy giao diện tĩnh và ingress. Chế độ backend chạy Agent Server, Automation Backend và ingress.
Cách tách này phù hợp khi giao diện và agent nằm ở hai nơi khác nhau, hoặc khi bạn muốn kiểm soát từng thành phần trong môi trường phát triển.
F.Lưu trạng thái và workspace khi dùng Docker
Với Docker, một named volume lưu settings, secrets và conversations. Các project được mount vào đường dẫn /projects. Khi container bị xoá rồi tạo lại, bạn có thể dùng lại volume để giữ trạng thái.
Khi chạy nhiều Docker sandbox, mỗi conversation có container, Agent Server và công cụ riêng. Workspace và lịch sử conversation được giữ qua việc thay thế container. Tuy nhiên, các conversation dùng chung một workspace trên máy chủ vẫn có thể sửa cùng file, nên cần tách thư mục hoặc worktree để tránh xung đột.
II.Cần chuẩn bị gì
Nếu cài bằng npm hoặc chạy từ source, bạn cần Node.js 24 trở lên. Bản chạy từ source còn yêu cầu npm 11.12.1 theo pin của repository và uv để chạy Agent Server qua uvx.
Nếu dùng Docker, bạn cần Docker Desktop trên macOS hoặc Windows, hoặc Docker Engine/Docker Desktop trên Linux. Với chế độ nhiều Docker sandbox, README cũng yêu cầu Node.js 24 trở lên, uv và Docker đang chạy. Người khởi động Canvas phải chạy được lệnh docker.
Nếu chạy không có sandbox, agent-server chạy trực tiếp trên máy cài đặt và agent có toàn quyền truy cập filesystem của máy đó. Đây là điểm cần cân nhắc trước khi cho agent làm việc trên dữ liệu thật.
Nếu dùng Docker trên Linux, người dùng có UID 10001 bên trong container phải đọc và ghi được workspace cùng các file hiện có. Docker Desktop trên macOS và Windows thường tự xử lý quyền bind mount.
README không bắt buộc một loại GPU cụ thể. Tư liệu cũng không nói rằng bạn phải có GPU. Về tài khoản hoặc API key, README nói ứng dụng có màn hình nhập API key trong một số cách triển khai và có thể dùng bất kỳ LLM nào, nhưng không liệt kê cụ thể từng key cần tạo.
III.Cài đặt từng bước
- Chọn cách chạyChọn npm trực tiếp, Docker sandbox, nhiều Docker sandbox hoặc chạy từ source
- Chuẩn bị công cụCài Node.js 24 trở lên, uv và Docker nếu chọn Docker
- Cài Agent CanvasCài gói npm hoặc lấy mã nguồn và cài dependency
- Khởi độngChạy agent-canvas, npm run dev hoặc docker run
- Mở giao diệnTruy cập địa chỉ localhost được README chỉ định và thêm backend nếu cần
A.Chọn cách chạy phù hợp
Có bốn lựa chọn chính. Cách npm trực tiếp đơn giản nhất nhưng agent có toàn quyền trên filesystem. Docker tạo ranh giới sandbox rõ hơn. Nhiều Docker sandbox phù hợp khi muốn chạy nhiều conversation song song. Chạy từ source phù hợp cho người phát triển hoặc muốn kiểm tra mã nguồn.
Nếu bạn mới bắt đầu và chỉ thử trên máy cá nhân, có thể dùng npm. Nếu agent sẽ đụng vào nhiều project hoặc dữ liệu quan trọng, hãy cân nhắc Docker và đọc phần tự host, bảo mật của dự án.
B.Cài và chạy không có sandbox
Mở Terminal hoặc PowerShell ở bất kỳ thư mục nào bạn muốn dùng để chạy ứng dụng. Cách này cài gói phát hành toàn cục bằng npm:
npm install -g @openhands/agent-canvas
agent-canvasLệnh đầu tiên cài package @openhands/agent-canvas. Lệnh thứ hai khởi động full local stack theo mặc định. Khi ứng dụng chạy, mở http://localhost:8000.
Bạn cũng có thể chạy từng phần riêng:
agent-canvas --frontend-only # static frontend + ingress only
agent-canvas --backend-only # agent server + automation backend + ingress only--frontend-only chỉ chạy frontend tĩnh và ingress. --backend-only chạy Agent Server, Automation Backend và ingress. Người mới thường nhầm rằng cài package là ứng dụng đã tự chạy; bạn vẫn cần gọi agent-canvas sau khi cài.
C.Chạy với một Docker sandbox
Cài và khởi động Docker trước. Cách dưới đây dành cho macOS và Linux. README có hướng dẫn PowerShell riêng cho Windows trong README.windows.md, nhưng nội dung được cung cấp ở đây chưa có các lệnh Windows đó.
Trước tiên, tạo thư mục chứa các project:
export PROJECTS_PATH="$HOME/projects" # directory containing your project folders
mkdir -p "$PROJECTS_PATH"PROJECTS_PATH là đường dẫn trên máy chủ. mkdir -p tạo thư mục nếu chưa có. Hãy giữ thư mục này riêng với ~/.openhands và dữ liệu nhạy cảm khác.
Trên Linux Docker Engine, nếu container báo không có quyền đọc hoặc ghi, README đưa ra hai lệnh sau cho một workspace mà bạn chấp nhận chia sẻ với mọi người dùng cục bộ:
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 truy cập rộng cho workspace. Không áp dụng cách này cho thư mục chứa key hoặc trạng thái riêng tư. Trên SELinux, bind mount có thể cần nhãn :z hoặc :Z, tuỳ hệ thống.
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 đó mở http://localhost:8000/canvas. Named volume openhands-state giữ settings, secrets và conversations khi container bị xoá. Bạn có thể kiểm tra volume bằng:
docker volume inspect openhands-stateLệnh trên chỉ kiểm tra thông tin volume. README khuyến cáo giữ user mặc định của container. Nếu tự đổi user, thư mục cấu hình trình duyệt có thể không truy cập được; khi đó phải cấu hình XDG_CONFIG_HOME có quyền ghi và bảo đảm state cùng workspace mount đúng quyền.
Container sẽ dừng với exit code 1 nếu Agent Server không trả lời kiểm tra /alive trong khoảng 30 giây. Nếu muốn tự khởi động lại, README khuyên dùng restart policy thay cho --rm, nhưng không đưa lệnh Docker Compose đầy đủ trong tư liệu được cung cấp.
D.Chạy nhiều Docker sandbox
Cách này tạo container riêng cho mỗi conversation. Trên macOS hoặc Linux, cài package rồi đặt biến môi trường trước khi khởi động:
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvasMở http://localhost:8000 và bắt đầu conversation mới. Mỗi container có workspace và state được lưu riêng theo conversation. Các conversation dùng chung cùng một workspace trên host vẫn có thể sửa cùng file, nên hãy dùng thư mục hoặc worktree riêng khi chạy song song.
Thiết lập này cô lập phần thực thi conversation. Nó không chuyển toàn bộ Canvas hoặc Automation Service vào sandbox. Người dùng Windows cần xem README.windows.md để biết cách chạy tương ứng.
E.Chạy từ source
Lấy mã nguồn và chuyển vào thư mục repo:
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHandsREADME yêu cầu Node.js 24 trở lên, npm 11.12.1 theo pin của repo và uv. Kiểm tra phiên bản npm trước khi cài dependency:
npm --versionCài đúng dependency theo lockfile rồi khởi động môi trường phát triển:
npm ci
npm run devnpm ci dùng lockfile đã commit để cài dependency. README nói bộ lọc release-age bảy ngày cần npm từ 11.10 trở lên; yêu cầu npm này dành cho việc resolve dependency của contributor, không phải việc cài package Canvas đã phát hành.
Sau khi chạy từ source, mở http://localhost:8000. Listener local của npx hoặc npm run dev chỉ bind 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 muốn nghe trên mọi interface, README cho phép dùng --host 0.0.0.0 hoặc đặt OH_BIND_HOST, nhưng session key sẽ không được tự chèn và giao diện sẽ yêu cầu nhập API key như chế độ --public.
IV.Kiểm tra đã chạy được chưa
Với npm hoặc source, mở http://localhost:8000. Với Docker image trong quickstart, mở http://localhost:8000/canvas. Nếu thấy giao diện Agent Canvas và có thể bắt đầu conversation, phần khởi động cơ bản đã thành công.
Trong giao diện, bạn có thể thêm backend bổ sung. Agent Canvas được thiết kế để kết nối nhiều Agent Server, nên việc nhìn thấy phần chọn hoặc thêm backend là dấu hiệu đúng với kiến trúc của ứng dụng.
Nếu Docker chạy được nhưng giao diện trả lỗi, xem log container và kiểm tra /alive. README cho biết entrypoint sẽ dừng container nếu Agent Server không trả lời khoảng 30 giây. Nếu gặp Permission denied, kiểm tra đường dẫn được nêu trong lỗi, quyền của workspace và quyền của các file state.
Với Docker, kiểm tra volume state bằng lệnh sau:
docker volume inspect openhands-stateNếu muốn kiểm tra API key được tạo trong container, README đưa ra lệnh sau:
docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"'Chỉ dùng key này đúng phạm vi cần thiết. Nếu publish Docker lên mạng LAN hoặc Internet, không bật AGENT_CANVAS_ALLOW_LAN_SESSION_KEY; hãy nhập API key trong giao diện và đặt LOCAL_BACKEND_API_KEY thành giá trị mạnh.
V.Dùng vào việc thật
A.Lập trình viên xử lý issue trong repository
Một lập trình viên có thể mở conversation mới, chọn Agent Server phù hợp rồi giao cho agent đọc project, phân tích issue và đề xuất thay đổi. Agent Canvas cho phép chạy OpenHands hoặc các agent khác như Claude Code, Codex, Gemini CLI, Pi và OpenCode trong cùng trung tâm điều khiển.
Cách làm cụ thể là mount thư mục project vào workspace, mở conversation và đưa yêu cầu rõ ràng, chẳng hạn: “Đọc issue này, xác định các file liên quan, lập kế hoạch thay đổi, sau đó chạy kiểm tra phù hợp và tóm tắt kết quả”. Kết quả phụ thuộc agent và backend bạn chọn; README không quy định một prompt hay bộ kiểm thử cụ thể.
B.Nhóm kỹ thuật dùng backend chung cho review mã nguồn
Một nhóm có thể chạy Agent Server trên máy dùng chung hoặc máy ảo. Thành viên thêm backend đó vào Canvas, chuyển qua lại giữa backend chung và backend cá nhân rồi giao các công việc như review mã nguồn hoặc cập nhật dependency.
Điểm thuận tiện là giao diện vẫn là một nơi duy nhất dù agent chạy ở nhiều máy. Cần thiết lập quyền truy cập và bảo mật hạ tầng theo môi trường của bạn; README nhấn mạnh cần xem hướng dẫn self-hosting và hardening khi đưa hệ thống lên cloud hoặc Internet.
C.Nhân viên văn phòng tạo báo cáo gửi lên Slack
Một nhân viên có thể tạo automation để agent tổng hợp thông tin thành báo cáo rồi publish lên Slack. README nêu rõ Agent Canvas có thể tích hợp automation với Slack và chạy theo lịch hoặc theo webhook.
Quy trình thực tế là kết nối dịch vụ cần dùng, định nghĩa workflow trong phần automation, chọn lịch hoặc sự kiện kích hoạt rồi kiểm tra kết quả. Tư liệu được cung cấp chưa có mẫu cấu hình hoặc prompt báo cáo cụ thể, nên cần dùng tài liệu và giao diện của dự án để hoàn thiện.
D.Chủ shop hoặc quản lý theo dõi yêu cầu qua GitHub
Khi đội ngũ ghi nhận yêu cầu trên GitHub, automation có thể phản hồi sự kiện, phân rã issue thành các task rồi chuyển cho agent. Đây là cách biến một yêu cầu lớn thành các phần việc nhỏ hơn để nhóm dễ theo dõi.
Bạn nên bắt đầu bằng workspace thử nghiệm, giới hạn quyền của token và kiểm tra đầu ra trước khi cho phép agent sửa project thật. Agent Canvas hỗ trợ kết nối GitHub trong workflow, nhưng README không mô tả chi tiết quyền token hoặc mẫu webhook.
Agent Canvas biến nhiều coding agent và backend thành một trung tâm điều khiển có thể chạy theo cách của bạn.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js thấp hơn phiên bản yêu cầu
Nếu cài hoặc khởi động thất bại, kiểm tra Node.js trước. README yêu cầu Node.js 24 trở lên. Với chạy từ source, kiểm tra thêm npm bằng npm --version và dùng npm 11.12.1 theo pin của repository.
B.Agent không có quyền đọc hoặc ghi workspace
Lỗi Permission denied thường liên quan đến quyền bind mount trên Linux. Kiểm tra đúng đường dẫn trong thông báo lỗi, bảo đảm UID 10001 trong container có quyền với workspace và các file hiện có. Không cấp quyền ghi rộng cho thư mục chứa key hoặc state.
C.Container chạy nhưng giao diện trả lỗi 502
Kiểm tra Agent Server có còn trả lời /alive hay không. Entrypoint sẽ dừng container nếu kiểm tra này thất bại khoảng 30 giây. Nếu muốn tự phục hồi, cấu hình restart policy như unless-stopped theo hướng dẫn của README.
D.Không giữ được conversation sau khi xoá container
Khi dùng Docker, cần giữ lại named volume openhands-state. Nếu tạo volume mới, nó không có dữ liệu ~/.openhands cũ. Dùng docker volume inspect openhands-state để kiểm tra volume đang được gắn đúng.
E.Dùng chung workspace khi chạy nhiều agent
Các conversation cùng mount một workspace có thể sửa cùng file và gây xung đột. Hãy dùng thư mục hoặc worktree riêng cho từng conversation. Việc tạo worktree cụ thể không được README cung cấp, nên bạn cần thực hiện theo quy trình Git quen thuộc của 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 cục bộ và từ xa, hoặc muốn kết hợp agent với workflow Slack, GitHub, Linear và các dịch vụ khác. Repo có giao diện Agent Canvas, hỗ trợ nhiều cách triển khai và cho phép chọn LLM theo nhu cầu.
Điểm mạnh là mô hình triển khai linh hoạt: chạy trực tiếp, chạy từ source, chạy một Docker sandbox hoặc chạy nhiều sandbox. Gói npm giúp bắt đầu nhanh. Mã nguồn dùng MIT và repository vẫn còn được cập nhật.
Giới hạn lớn nhất là độ phức tạp tăng nhanh khi bạn dùng backend từ xa, automation, nhiều container hoặc triển khai trên Internet. Chạy không sandbox cho agent quyền truy cập toàn bộ filesystem. Docker cũng cần xử lý volume, quyền file, API key và bảo mật mạng cẩn thận.
Nếu bạn chỉ cần một chatbot hỏi đáp mã nguồn đơn giản, Agent Canvas có thể nhiều tính năng hơn nhu cầu. Nếu bạn cần môi trường cô lập, tự động hoá theo lịch, nhiều agent và khả năng kết nối hạ tầng riêng, đây là lựa chọn phù hợp. Khi chạy production hoặc public, hãy đọc tài liệu self-hosting, hardening và các hướng dẫn Windows tương ứng trước khi mở quyền truy cập ra ngoài máy cá nhân.
Câu hỏi thường gặp
OpenHands/OpenHands có miễn phí không?
Repo dùng giấy phép MIT. Tuy nhiên, tư liệu được cung cấp không nêu chi phí của các mô hình LLM, OpenHands Cloud, OpenHands Enterprise hoặc dịch vụ bên thứ ba. Chi phí thực tế có thể phụ thuộc backend và LLM bạn chọn.
Có cần GPU để chạy không?
README không yêu cầu GPU và cũng không nêu phần cứng GPU bắt buộc. Tư liệu chỉ nêu Node.js, uv và Docker trong các cách chạy tương ứng.
Có chạy được trên Windows không?
Repo có file `README.windows.md` và README nói người dùng Windows có thể theo PowerShell quickstart. Nội dung được cung cấp chưa có các lệnh PowerShell chi tiết, nên cần xem file đó trong repo.
Dữ liệu có an toàn không?
Có thể chạy cục bộ hoặc tự host, nhưng mức an toàn phụ thuộc cách triển khai. Chạy không sandbox cho agent toàn quyền trên filesystem; khi dùng Docker cần bảo vệ workspace, state, secrets và API key.
Có dùng được Claude Code, Codex và Gemini không?
Có. README nêu Agent Canvas có thể chạy OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode hoặc agent tương thích ACP.
Có thể chạy nhiều conversation cùng lúc không?
Có thể dùng chế độ nhiều Docker sandbox để mỗi conversation có container, Agent Server và công cụ riêng. Các conversation vẫn có thể xung đột nếu dùng chung workspace trên host.
Tôi có cần tạo API key trước khi cài không?
README nói một số cách triển khai dùng API key và giao diện có màn hình nhập key, nhưng không liệt kê đầy đủ key cần tạo cho từng LLM. Bạn cần xem phần cài đặt và cấu hình của backend hoặc mô hình mình chọn.


