# Doop: canvas thiết kế để người và AI agent cùng vẽ — hướng dẫn cài đặt và dùng

> Doop là công cụ thiết kế trên canvas mã nguồn mở, thay thế Paper.design, cho phép người và AI agent cùng chỉnh một bản thiết kế trực tiếp. Agent như Claude Code, Codex, Cursor kết nối qua MCP server có sẵn. Chạy thử trên máy chỉ cần ba lệnh với bun, không cần cấu hình; cũng có bản dùng sẵn trên mạng nếu bạn không muốn cài.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-24 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/doop-canvas-thiet-ke-nguoi-va-ai-agent-cung-ve

Doop là một canvas thiết kế mã nguồn mở, nơi người và AI agent cùng vẽ chung một bản thiết kế, xem nhau làm theo thời gian thực. Tác giả định vị nó là bản mã nguồn mở thay thế cho Paper.design. Mỗi bản thiết kế nằm trên một Canvas có đường dẫn chia sẻ được, bên trong có các Frame, tức là các khung màn hình hiển thị HTML thật.

Nếu bạn đang dùng Claude Code, Codex, ChatGPT hay Cursor và muốn agent đó vẽ giao diện ngay trên một tấm canvas bạn nhìn thấy, Doop dành cho bạn. Bạn cũng có thể dùng nó nếu làm việc nhóm và muốn góp ý, bình luận, duyệt màn hình ngay trên bản thiết kế. Nó hợp với người làm sản phẩm, chủ shop cần dựng nhanh trang giới thiệu, và lập trình viên mới muốn thấy agent làm việc ra sao.

Điểm đáng giá nhất: Doop không buộc bạn vào một hãng AI nào. Agent nào hỗ trợ MCP đều vào vẽ được, và còn có sẵn Doop Agent chạy bằng tài khoản mô hình bạn tự kết nối. Hiện repo có khoảng 1987 sao và 245 fork, giấy phép AGPL-3.0. Bạn có thể xem video ngắn bên dưới để thấy nó chạy.

```repo
- repo | kgoedecke/doop
- kind | Ứng dụng
- desc | Doop là canvas thiết kế mã nguồn mở, nơi bạn và AI agent (Claude Code, Codex, Cursor…) cùng thiết kế theo thời gian thực, có sẵn MCP server.
- stars | 2k
- lang | TypeScript
- license | AGPL-3.0
```

```video
- youtube | https://youtube.com/shorts/o8JkcvyS07k
- facebook | https://www.facebook.com/reel/1087784370747233
- title | Video giới thiệu doop
```

## Doop làm được gì

Dưới đây là những tính năng chính, kèm lợi ích thực tế.

- **Agent vẽ ngay trước mắt bạn.** Bạn kết nối Claude Code (hoặc bất kỳ MCP client nào) một lần. Sau đó bạn thấy agent phác thảo, đẩy thiết kế lên canvas và tự xem lại, ngay cạnh con trỏ của bạn. Không cần cứ viết prompt rồi tải lại trang.
- **Doop Agent có sẵn.** Bạn xếp một thẻ việc hoặc gõ @ nhắc một vai trò, agent sẽ tự thiết kế. Nó chạy bằng tài khoản mô hình mà mỗi người dùng kết nối: gói ChatGPT, hoặc khóa của OpenAI, Claude, Gemini, DeepSeek, Kimi, OpenRouter.
- **Nhiều trang trong một canvas.** Bạn chia các frame thành các trang có tên trong bảng Layers, kéo để sắp xếp lại, đổi tên, hoàn tác. Mỗi trang có thể có màu nền riêng.
- **Prototype bấm được.** Bạn nối phần tử này sang frame khác (bấm, rê chuột, phím, hẹn giờ), rồi bấm Play để thử luồng. Bạn cũng có thể chia sẻ đường dẫn dạng `/c/<id>/proto` cho người khác xem.
- **Trình chỉnh sửa canvas thật sự.** Vẽ frame, hình, đường pen, chữ; chỉnh màu, kiểu chữ, bố cục flex; thước và đường gióng; zoom từ 8% đến 1600%.
- **Nhiều người cùng làm.** Con trỏ trực tiếp, chế độ đi theo người khác, hoàn tác/làm lại, bình luận theo luồng và dòng hoạt động, tất cả qua một phòng WebSocket.
- **Bộ nhớ thiết kế.** Bạn ghim frame mẫu, ghi lại quyết định, để hệ thống đề xuất các quy tắc phong cách mà mọi agent đều tuân theo.
- **Riêng tư mặc định.** Bạn mời người khác qua email hoặc chia sẻ link chỉ xem, chỉ bình luận hay được sửa. Agent chỉ có đúng quyền của người đã kết nối nó.
- **Xuất và nhập.** Xuất PNG, JPG, PDF vector. Nhập từ website, ứng dụng đang chạy hoặc repo GitHub. Mỗi frame còn có ảnh trực tiếp tại `/i/<frameId>.png?scale=2`, dùng làm ảnh og:image được.
- **Duyệt màn hình để giao cho dev.** Bạn đánh dấu frame là đã duyệt. Nếu sau đó HTML hay kích thước đổi, frame chuyển sang trạng thái cần xem lại.

Có một giới hạn cần biết: tích hợp Figma, Canva và nhập/xuất Photoshop (PSD) hiện chỉ có ở Doop Cloud, không nằm trong bản mã nguồn mở.

## Cần chuẩn bị gì

Theo README, bạn cần:

- **bun**: Doop cài đặt và build bằng bun (file khóa duy nhất là `bun.lock`). Bạn cài bun từ trang bun.sh.
- **Node.js**: server chạy trên Node. Lệnh `bun run dev` và `bun run build` còn đóng gói tiện ích Claude Desktop bằng một script Node, nên Node phải nằm trong `PATH`. README không ghi số phiên bản cụ thể, bạn xem thêm trong `package.json`.
- **Git** để tải mã nguồn về.
- **Docker** nếu bạn chọn cách chạy bản production bằng `docker compose`.
- **Khóa hoặc tài khoản mô hình**: chỉ cần nếu muốn dùng Doop Agent có sẵn. Agent bạn tự kết nối qua MCP (Claude Code, Codex…) thì README nói không cần khóa.

README không ghi yêu cầu phần cứng như GPU, và cũng không nói riêng về hệ điều hành. Lệnh Docker mẫu trong README viết theo kiểu shell Unix, nên trên Windows bạn nên chạy trong Git Bash hoặc WSL cho chắc.

Không cần cấu hình gì thêm để chạy thử: dữ liệu lưu vào Postgres nhúng (PGlite) trong thư mục `data/pg`. Các tích hợp tùy chọn như email SMTP, ảnh stock, lưu trữ object, phân tích sẽ tự tắt cho đến khi bạn điền biến tương ứng trong `.env.example`.

## Cài đặt từng bước

```steps
- Cài công cụ nền | Có bun, Node và git trên máy
- Tải mã nguồn | git clone repo Doop rồi vào thư mục
- Cài thư viện | bun install
- Chạy chế độ dev | bun run dev, mở web ở cổng 4300
- Kết nối agent | Dùng Connect AI trên thanh trên cùng
- Hoặc chạy bằng Docker | docker compose up -d cho bản production
```

### Cài công cụ nền

Bạn cài bun theo hướng dẫn ở trang bun.sh, và chắc chắn Node đã nằm trong `PATH`. README chưa ghi lệnh cài bun, nên bạn làm theo trang chủ của bun. Sau đó mở một cửa sổ terminal mới để máy nhận lệnh `bun`.

### Tải mã nguồn

Mở terminal ở thư mục bạn muốn đặt dự án (ví dụ thư mục Documents), rồi chạy lệnh trong README:

```bash
git clone https://github.com/kgoedecke/doop && cd doop
```

Lệnh đầu tải mã nguồn về, phần sau `&&` đưa bạn vào thư mục `doop`. Người mới hay quên bước vào thư mục, nên các lệnh sau báo không tìm thấy gì. Nếu terminal của bạn không hiểu `&&`, bạn chạy hai lệnh `git clone` và `cd doop` riêng.

### Cài thư viện

```bash
bun install
```

Lệnh này tải các gói mà Doop cần. Lần đầu có thể mất vài phút tùy mạng.

### Chạy chế độ dev

```bash
bun run dev
```

Sau khi chạy, bạn có hai địa chỉ:

- Ứng dụng web: `http://localhost:4300`
- API, WebSocket và MCP server: `http://localhost:4400` (cổng web chuyển tiếp các đường dẫn như `/api`, `/ws`, `/mcp` sang đây)

Bạn mở trình duyệt vào `http://localhost:4300`. Đừng đóng terminal này, vì đóng là ứng dụng dừng.

### Kết nối agent

Sau khi đăng nhập, bạn bấm **Connect AI** ở thanh trên cùng. Màn hình này hướng dẫn từng agent. Theo README:

- Claude Code kết nối bằng `claude mcp add` rồi đăng nhập OAuth trong trình duyệt.
- Codex (CLI và desktop) dùng `codex mcp add`, cũng đăng nhập OAuth.
- Claude (web và desktop) có nút **Add to Claude**.
- Cursor có nút **Add to Cursor**.
- ChatGPT dùng một MCP server tùy chỉnh, có hướng dẫn trong **Connect AI → ChatGPT**.
- Agent chạy ngầm (n8n, Mastra, CI) dùng agent key làm bearer header.

README phần này không ghi đầy đủ tham số của `claude mcp add` và `codex mcp add`. Bạn hãy copy đúng lệnh hiển thị trong Connect AI, đừng tự đoán.

### Hoặc chạy bằng Docker

Muốn chạy bản production, README đưa lệnh:

```bash
BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d   # app + Postgres on :4400
```

Lệnh này tạo một chuỗi bí mật ngẫu nhiên cho `BETTER_AUTH_SECRET`, rồi dựng ứng dụng cùng Postgres ở cổng 4400. Cách khác không dùng Docker:

```bash
bun run build && bun run start
```

Lệnh này chạy một server duy nhất ở cổng 4400. Nếu muốn dùng Postgres thật, bạn đặt biến `DATABASE_URL`.

```note
Chuỗi BETTER_AUTH_SECRET là bí mật. Đừng đưa lên chỗ công khai và đừng commit vào git. Nếu dùng khóa API của mô hình (OpenAI, Claude…), bạn cũng giữ kín như mật khẩu, vì khóa đó tính tiền theo mức dùng của bạn.
```

## Kiểm tra đã chạy được chưa

Cách kiểm tra đơn giản nhất:

- Terminal sau `bun run dev` chạy liên tục, không báo lỗi đỏ.
- Mở `http://localhost:4300` thấy giao diện Doop và đăng nhập được.
- Trang Home cho bạn mô tả điều muốn làm, Doop sẽ tạo canvas và xếp sẵn các thẻ việc cho Doop Agent.
- README nói canvas đầu tiên có màn trình diễn chào mừng chạy theo kịch bản, không cần khóa hay tài khoản mô hình. Nếu bạn thấy màn này chạy, phần giao diện đã ổn.
- Với agent: sau khi kết nối từ Connect AI, agent hiện trên canvas với con trỏ, trạng thái và tác vụ riêng.

Nếu bạn chạy bằng Docker, hãy mở `http://localhost:4400` thay vì cổng 4300.

## Dùng vào việc thật

README không đưa prompt mẫu cụ thể, nên các tình huống dưới đây chỉ dựa trên những khả năng nó có. Câu lệnh mẫu là gợi ý của mình, bạn tự chỉnh theo việc của mình.

### Chủ shop dựng nhanh trang giới thiệu sản phẩm

Bạn bán đồ handmade và cần vài màn hình mẫu để xem trước khi nhờ người làm web. Bạn vào Home, mô tả bằng tiếng thường, ví dụ: "Trang chủ cho shop nến thơm, tông kem và nâu, có phần sản phẩm nổi bật". Doop tạo canvas và xếp thẻ việc cho Doop Agent. Bạn nhận về các frame là HTML thật, chỉnh màu và chữ trực tiếp trong tab Design, rồi bấm Play ở chế độ Prototype để thử luồng bấm.

> Agent không còn là hộp chat ở xa, nó ngồi cạnh con trỏ của bạn trên cùng một canvas.
>
> — Ông T

### Dev dùng Claude Code vẽ giao diện trên canvas

Bạn đang làm một ứng dụng và muốn agent phác giao diện trước khi viết code. Bạn kết nối Claude Code qua Connect AI, rồi giao việc cho nó. Agent đọc canvas bằng `get_canvas`, tạo và sửa frame, còn bạn xem trực tiếp. Khi ưng một màn, bạn bật **Mark as approved** để đánh dấu sẵn sàng cho dev. Nếu sau đó ai đó sửa HTML, màn chuyển sang "Needs review", nên bạn không lỡ giao nhầm bản cũ.

### Nhóm văn phòng góp ý trực tiếp trên bản thiết kế

Bạn là nhân viên marketing, cần sếp và đồng nghiệp duyệt banner. Bạn mời họ qua email hoặc chia sẻ link chỉ bình luận. Mọi người ghim bình luận lên đúng phần tử. Muốn nhờ AI sửa, bạn gõ @ nhắc vai trò agent (README lấy ví dụ `@doop`) trong bình luận, thẻ việc sẽ được xếp và câu trả lời quay lại ngay trong luồng đó. Xong, bạn xuất PDF hoặc PNG gửi đi.

### Người tự host dùng ảnh frame làm ảnh chia sẻ

Bạn viết tài liệu hoặc bài blog và cần ảnh minh họa luôn khớp bản thiết kế mới nhất. Mỗi frame có ảnh trực tiếp tại `/i/<frameId>.png?scale=2`, tự vẽ lại khi thiết kế đổi. Bạn dán đường dẫn đó vào thẻ `og:image` hoặc tài liệu, không phải xuất ảnh thủ công mỗi lần sửa.

## Lỗi hay gặp và cách xử lý

**Lệnh `bun` không được nhận.** Thường do bạn chưa cài bun hoặc chưa mở terminal mới sau khi cài. Cài bun từ trang bun.sh, đóng và mở lại terminal rồi thử lại.

**`bun run dev` báo lỗi liên quan Node.** README nói lệnh này cần Node trong `PATH` để đóng gói tiện ích Claude Desktop. Kiểm tra `node --version` có chạy không. Nếu không, cài Node rồi chạy lại.

**Mở web thấy trang trống hoặc không vào được.** Kiểm tra bạn đang vào đúng cổng: 4300 khi chạy dev, 4400 khi chạy Docker hay bản production. Cũng kiểm tra terminal còn chạy, và không có chương trình khác chiếm cổng.

**Doop Agent không làm gì.** README nói Doop Agent chạy khi người dùng kết nối một tài khoản mô hình trong Settings, hoặc dùng `ANTHROPIC_API_KEY` của server nếu bạn nâng `RESIDENT_TASK_LIMIT` (mặc định là không có tác vụ miễn phí). Vào Settings và kết nối tài khoản trước.

**Agent bên ngoài không kết nối được.** Dùng đúng lệnh hiển thị trong Connect AI, hoàn tất bước OAuth trên trình duyệt. Nếu vẫn lỗi, xem hướng dẫn trong thư mục `docs/` của repo thay vì đoán tham số.

**Lệnh Docker báo lỗi trên Windows.** Dòng `BETTER_AUTH_SECRET=$(openssl rand -hex 32) docker compose up -d` viết theo kiểu shell Unix, PowerShell không hiểu. Bạn chạy nó trong Git Bash hoặc WSL.

## Có nên dùng không

**Điểm mạnh:** mã nguồn mở, tự host được, chạy thử không cần cấu hình. Agent nào hỗ trợ MCP đều vào làm được. Có đủ phần cộng tác như con trỏ, bình luận, quyền truy cập, và có prototype, xuất PDF, duyệt cho dev. Dự án còn được cập nhật trong vài tháng gần đây.

**Giới hạn:** giấy phép AGPL-3.0 có yêu cầu riêng nếu bạn chạy dịch vụ cho người khác, nên người làm sản phẩm thương mại nên đọc kỹ file `LICENSE`. Figma, Canva và PSD chỉ có ở Doop Cloud. Muốn dùng Doop Agent bạn phải có tài khoản hoặc khóa mô hình. Cài bằng dòng lệnh đòi hỏi bạn quen mở terminal, còn README không nói rõ về hỗ trợ Windows.

**Khi nào chọn cách khác:** nếu bạn không muốn cài gì, README nói doop.design là bản chạy sẵn trên mạng. Nếu cần nhập/xuất Figma hay Photoshop, hãy xem bản Doop Cloud. Nếu bạn chỉ cần vẽ tay đơn giản, một công cụ thiết kế quen thuộc có thể đủ và gọn hơn.

## Câu hỏi thường gặp

### Doop có miễn phí không?

Mã nguồn mở theo giấy phép AGPL-3.0, bạn tự chạy trên máy được. Doop Agent có sẵn cần tài khoản hoặc khóa mô hình của bạn, và chi phí theo nhà cung cấp đó. README cũng nói có bản chạy sẵn trên mạng, nhưng chưa nêu giá.

### Cần GPU không?

README không nhắc yêu cầu GPU hay phần cứng riêng. Các mô hình AI chạy qua tài khoản hoặc khóa của nhà cung cấp, không chạy trên máy bạn.

### Chạy trên Windows được không?

README chưa nói rõ về hệ điều hành. Lệnh Docker mẫu viết theo kiểu shell Unix, nên trên Windows bạn nên dùng Git Bash hoặc WSL. Cần bun và Node trên máy.

### Có phải điền API key mới dùng được không?

Chạy thử không cần cấu hình gì. Agent bạn tự kết nối qua MCP (như Claude Code, Codex) cũng không cần khóa theo README. Chỉ Doop Agent có sẵn mới cần bạn kết nối tài khoản mô hình trong Settings.

### Dữ liệu của tôi lưu ở đâu, có an toàn không?

Khi chạy dev, dữ liệu lưu vào Postgres nhúng trong thư mục data/pg trên máy bạn. Bản production có thể dùng Postgres thật qua DATABASE_URL. Canvas riêng tư mặc định, và agent chỉ có quyền bằng đúng người đã kết nối nó.

### Doop khác gì Paper.design?

README giới thiệu Doop là bản mã nguồn mở thay thế Paper.design, tự host được và dùng được với nhiều agent qua MCP. README không so sánh chi tiết từng tính năng giữa hai công cụ.

### Tôi có thể nhập thiết kế từ Figma không?

Nhập/xuất Figma, Canva và Photoshop hiện chỉ có ở Doop Cloud, không nằm trong bản mã nguồn mở. Bản tự host cho nhập từ website, ứng dụng đang chạy và repo GitHub.
