Hướng dẫn DeepSeek Harness: Bắt đầu với Agent AI mã nguồn mở phổ biến nhất

Vì sao DeepSeek Harness được ưa chuộng?

DeepSeek Harness thu hút sự chú ý rất nhanh, đạt hơn 160.000 sao trên GitHub và 18.000 lần fork tại thời điểm xuất bản bài viết này. 

Một lý do lớn là các nhà phát triển nhận thấy nó có thể cho ra kết quả mạnh mẽ từ nhiều mô hình khác nhau, không chỉ DeepSeek. Người dùng Reddit thường xuyên báo cáo sử dụng thành công với các mô hình như Qwen3.8-27b, đặc biệt cho việc viết mã và các tác vụ agent nhiều bước.

Lý do khác là tính tự chủ và linh hoạt. Người dùng cho biết Harness có thể tiếp tục làm việc qua các tác vụ nhiều bước, phục hồi sau lỗi, quản lý ngữ cảnh dài, và tiếp diễn mà không cần can thiệp liên tục. Thiết kế dựa trên plugin cũng giúp dễ dàng hoán đổi mô hình, thêm công cụ, và tùy chỉnh quy trình agent thay vì bị khóa vào một thiết lập cố định.

Nếu bạn đang cân nhắc Harness so với các công cụ mà nó muốn cạnh tranh, hướng dẫn của chúng tôi về các lựa chọn thay thế Claude Code so sánh bảy phương án chính cạnh nhau.

Tính năng chính của DeepSeek Harness

Dưới đây là một số tính năng chính:

• Kiến trúc dựa trên plugin: Hầu hết các phần của agent có thể được mở rộng hoặc thay thế thông qua plugin, giúp việc tùy chỉnh thiết lập của bạn dễ dàng hơn.

• Web UI cục bộ: Chạy dsh web cung cấp cho bạn giao diện trên trình duyệt nơi bạn có thể quản lý mô hình, phiên, không gian làm việc, cài đặt và agent.

• Python SDK: deepseek-harness-sdk cho phép bạn chạy các agent Harness trực tiếp từ ứng dụng, script, bài kiểm thử và quy trình tự động hóa bằng Python.

• Nhiều nhà cung cấp mô hình: Bạn không bị giới hạn ở các mô hình của DeepSeek. Bạn có thể dùng các nhà cung cấp như OpenAI và Anthropic, hoặc kết nối endpoint tương thích của riêng bạn.

• Gọi công cụ: Agent có thể gọi công cụ để thực hiện hành động thay vì chỉ tạo văn bản.

• Công cụ tệp và terminal: Harness bao gồm công cụ đọc, tìm kiếm, và chỉnh sửa tệp, cùng với Bash trên Linux và macOS và PowerShell trên Windows.

• Tìm kiếm web tích hợp: Nhà cung cấp tìm kiếm web của DeepSeek được bao gồm trong cấu hình mặc định và dùng cùng khóa API DeepSeek như mô hình.

• Chế độ Code: Harness có thể phơi bày công cụ thông qua chế độ thực thi dựa trên mã, cho agent nhiều quyền kiểm soát hơn về cách kết hợp và chạy các lệnh gọi công cụ.

• Trajectory: Chế độ xem Trajectory cho phép bạn kiểm tra agent đang làm gì theo từng bước, gồm phản hồi của mô hình, lệnh gọi công cụ, hoạt động lồng nhau của công cụ, thời gian, và mức sử dụng token.

• Preset agent: Bạn có thể tạo các thiết lập agent khác nhau với bộ công cụ và prompt riêng, rồi dùng chúng trong nhiều phiên khác nhau.

• Thống kê phiên: Harness theo dõi thông tin hữu ích như lượt trao đổi, bước, thời gian mô hình, thời gian công cụ, thời gian đến token đầu tiên, và thời gian giải mã.

• Subagent: Một agent chính có thể giao phó một phần nhiệm vụ cho các agent con, hữu ích cho quy trình phức tạp hơn.

• Plugin cộng đồng: Plugin bên thứ ba có thể bổ sung khả năng mà mô hình gốc không có. Trong hướng dẫn này, chúng tôi dùng ModLens để thêm hỗ trợ thị giác.

• Giấy phép MIT: DeepSeek Harness là mã nguồn mở và phát hành theo giấy phép MIT linh hoạt.

Ưu điểm chính là bạn không bị ràng buộc vào một mô hình, một bộ công cụ, hay một kiểu agent. Bạn có thể bắt đầu với thiết lập mặc định và dần dần thêm hoặc thay thế thành phần khi thử nghiệm các quy trình khác nhau.

Cách thiết lập DeepSeek Harness

Hãy bắt đầu bằng cách cài đặt DeepSeek Harness và thiết lập mọi thứ cần cho phần còn lại của hướng dẫn. Chúng ta sẽ cài Node.js, DeepSeek Harness, và pnpm, sau đó thêm khóa API.

Cài đặt Node.js

DeepSeek Harness chạy trên Node.js. Vì ta cũng sẽ dùng ModLens cho thị giác sau này, tôi khuyến nghị dùng Node.js 22.19 hoặc mới hơn.

Nếu bạn dùng Ubuntu hoặc Debian, bạn có thể cài Node.js bằng:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

Sau khi cài xong, kiểm tra cả Node.js và npm hoạt động ổn:

node --version
npm --version

Trên máy tôi, kết quả là:

v24.19.0
11.17.0

Bạn không cần đúng y hệt phiên bản này. Chỉ cần bạn chạy một phiên bản Node.js đủ mới là ổn.

Cài đặt DeepSeek Harness

Tiếp theo, hãy cài chính DeepSeek Harness.

Hướng dẫn nhanh chính thức dùng npx, nhưng tôi thích cài toàn cục để ta có thể đơn giản dùng lệnh dsh xuyên suốt hướng dẫn.

Chạy:

npm install -g @deepseek-ai/dsh

Rồi kiểm tra cài đặt thành công:

dsh --version

Tại thời điểm tôi thử hướng dẫn này, tôi dùng:

0.1.0-rc.7

Cài đặt pnpm

Chúng ta cũng cần pnpm. DeepSeek Harness dùng nó khi thêm hoặc gỡ plugin. Cài toàn cục:

npm install -g pnpm

Thiết lập khóa API

Trong bài này, ta chỉ cần hai khóa API:

• Khóa DeepSeek API: dùng cho mô hình DeepSeek và tìm kiếm web tích hợp của nó.
• Khóa Gemini API: được ModLens dùng cho hiểu hình ảnh.

Chúng ta sẽ thiết lập khóa DeepSeek trước, vì đó là tất cả những gì cần cho viết mã và tìm kiếm web, và thêm khóa Gemini sau khi bổ sung thị giác với ModLens.

Với DeepSeek, bạn cần tạo tài khoản DeepSeek, tạo khóa API, và nạp tiền vào tài khoản. Với hướng dẫn này, tôi khuyến nghị nạp ít nhất $2, đủ để thử các ví dụ mà không cần nạp quá nhiều từ đầu.

Khi đã có khóa API, hãy thêm nó vào môi trường của bạn.

Trên Linux hoặc macOS:

export DEEPSEEK_API_KEY="your_deepseek_api_key"

Trên Windows PowerShell:

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

Điều hay là ta không cần API tìm kiếm web riêng. DeepSeek Harness đã tích hợp nhà cung cấp tìm kiếm web của DeepSeek và dùng cùng DEEPSEEK_API_KEY.

Bạn cũng có thể thêm khóa API DeepSeek sau này từ Settings → Models trong Web UI.

Cách khởi động DeepSeek Harness

Giờ mọi thứ đã cấu hình xong, ta có thể khởi động DeepSeek Harness và mở Web UI. Chỉ cần chạy dsh web, lệnh này khởi chạy giao diện trình duyệt trên cổng 3080 theo mặc định.

Bạn có thể thấy giao diện khi mở địa chỉ http://127.0.0.1:3080 trong trình duyệt.

Từ đây, tạo một workspace mới hoặc chọn workspace sẵn có, bắt đầu phiên mới, và chọn mô hình DeepSeek bạn muốn dùng. 

Khi phiên đã sẵn sàng, ta có thể bắt đầu kiểm thử viết mã, tìm kiếm web, thị giác, và hỗ trợ mô hình bên thứ ba. 

Cách dùng DeepSeek Harness cho viết mã

Giờ DeepSeek Harness đã chạy, ta có thể kiểm thử các năng lực chính của thiết lập. Bắt đầu với một bài tập viết mã đơn giản: 

Create a simple Python calculator with a command-line interface.

DeepSeek Harness có thể làm việc trực tiếp với tệp và terminal, vì vậy nó có thể tạo tệp Python, chỉnh sửa mã, và chạy lệnh trong workspace.

Sau khi hoàn thành, bạn sẽ thấy tệp được tạo và hướng dẫn chạy nó.

Để khai thác nhiều hơn từ các mô hình DeepSeek vận hành Harness, hướng dẫn DeepSeek V4 API của chúng tôi trình bày các chế độ lập luận V4 và tham số API trong Python.

Cách dùng DeepSeek Harness cho tìm kiếm web

Tiếp theo, hãy kiểm thử tìm kiếm web. Không cần thiết lập thêm vì DeepSeek Harness đã tích hợp sẵn nhà cung cấp tìm kiếm web của DeepSeek.

Thử một prompt như:

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

Agent sẽ tìm kiếm web và trả về bản tóm tắt kèm nguồn. 

Trong lúc nó làm việc, mở tab Trajectory. Bạn sẽ thấy các lệnh gọi công cụ như SUBTOOL: web_search.

Điều này cho thấy agent thực sự đang dùng công cụ tìm kiếm web thay vì chỉ dựa vào kiến thức sẵn có của mô hình. Theo mặc định, tìm kiếm này do nhà cung cấp deepseek-official xử lý và dùng cùng DEEPSEEK_API_KEY mà ta đã cấu hình trước đó. 

Cách dùng DeepSeek cho tác vụ thị giác

Mô hình chat của DeepSeek trong Harness chỉ hỗ trợ văn bản, nên không thể tự hiểu hình ảnh tải lên. Để thêm hỗ trợ thị giác, chúng ta sẽ dùng ModLens, hoạt động như cầu nối giữa DeepSeek và một mô hình có khả năng thị giác.

Cài đặt plugin ModLens

Khi bạn tải lên hình ảnh, ModLens xử lý bằng một mô hình thị giác, trích xuất thông tin hình ảnh hữu ích, rồi chuyển lại cho DeepSeek để suy luận về hình ảnh.

Bắt đầu bằng cách cài plugin ModLens vào hồ sơ web:

dsh plugin --profile web add @liustack/modlens@3.20.0

Sau khi cài, ModLens thêm công cụ modlens_read_image và tạo các tùy chọn mô hình như ``DeepSeek-V4-Flash (modlens vision)`.

Các biến thể mô hình này cho phép bạn tải ảnh lên trong khi vẫn dùng DeepSeek làm mô hình suy luận chính.

Đăng ký backend thị giác của bạn

Trong hướng dẫn này, chúng ta sẽ dùng Gemini API làm backend thị giác, nên chúng ta cần một khóa Gemini API. Bạn có thể bắt đầu với Free Tier của Gemini API. Google cung cấp quyền truy cập miễn phí vào các mô hình Gemini được hỗ trợ trong giới hạn Free Tier, vì vậy bạn không cần thêm thông tin thanh toán chỉ để thử thiết lập thị giác trong hướng dẫn này.

Khi đã có khóa, thêm nó vào môi trường của bạn.

Trên Linux hoặc macOS:

export GEMINI_API_KEY="your_gemini_api_key"

Trên Windows PowerShell:

$env:GEMINI_API_KEY="your_gemini_api_key"

Cài đặt và cấu hình ModLens CLI

Tiếp theo, cài ModLens CLI:

npm install -g @liustack/modlens

Sau đó cấu hình bằng khóa Gemini API.

Trên Linux hoặc macOS:

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

Trên Windows PowerShell:

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

Cuối cùng, kiểm tra mọi thứ hoạt động ổn:

modlens doctor

Bạn sẽ thấy gemini-api được chọn là nhà cung cấp và ở trạng thái sẵn sàng.

Kiểm thử DeepSeek Harness với ModLens

Giờ hãy kiểm thử khả năng hiểu hình ảnh.

Trong bộ chọn mô hình, chọn một trong các mô hình có (modlens vision) trong tên, ví dụ DeepSeek-V4-Flash (modlens vision).

Dán hoặc tải lên một hình ảnh, rồi hỏi: Giải thích nội dung hiển thị trong hình này.

Như trong ví dụ trên, DeepSeek giờ có thể mô tả và suy luận về hình ảnh đã tải lên.

Ở hậu trường, ModLens gửi ảnh tới Gemini để hiểu thị giác và chuyển thông tin đã trích xuất lại cho DeepSeek. Điều này nghĩa là ta vẫn giữ DeepSeek làm mô hình suy luận chính, còn Gemini chỉ dùng cho phần thị giác.

Cách dùng DeepSeek Harness với mô hình bên thứ ba

Cuối cùng, hãy thử một mô hình từ nhà cung cấp khác. Mở Settings → Models.

Tại đây, bạn có thể thêm các nhà cung cấp như OpenAI và Anthropic, hoặc cấu hình một nhà cung cấp mô hình được hỗ trợ khác bằng thông tin xác thực API của bạn. 

Bạn cũng có thể thêm nhà cung cấp tùy chỉnh nếu muốn kết nối mô hình tự lưu trữ hoặc endpoint tương thích khác. Điều này cho phép cấu hình chi tiết như ID nhà cung cấp, base URL, loại API, thông tin xác thực, và tên mô hình. 

Khi đã thêm nhà cung cấp, quay lại phiên của bạn và chọn mô hình mới từ bộ chọn mô hình.

Ví dụ, thử prompt sau:

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

Ví dụ trên sử dụng mô hình Kimi-K3 của bên thứ ba để hoàn thành tác vụ viết mã, cho thấy DeepSeek Harness không bị giới hạn ở các mô hình của DeepSeek.

Bạn có thể chuyển đổi giữa các mô hình đã cấu hình trực tiếp từ bộ chọn mô hình, và thay đổi sẽ áp dụng cho yêu cầu tiếp theo mà không cần khởi động lại máy chủ Harness.

Kết luận

Sau khi thử DeepSeek Harness, tôi vẫn ưu tiên Pi Coding Agent và OpenCode cho quy trình làm việc của riêng mình.

DeepSeek Harness khiến tôi liên tưởng nhiều đến Pi Coding Agent vì cả hai đều xây dựng quanh hệ sinh thái plugin. Bạn có thể cài các tiện ích mở rộng khác nhau và bổ sung khả năng cho trợ lý lập trình tùy theo nhu cầu. Sự linh hoạt đó hữu ích, nhưng trong quá trình thử, tôi vẫn chưa thực sự hiểu sự cường điệu quanh DeepSeek Harness. Trải nghiệm tổng thể khá bình thường so với các agent viết mã khác tôi đã dùng.

Tôi cũng gặp vài vấn đề gây khó chịu. Đôi khi agent dừng giữa chừng mà không nói lý do, và tôi phải gõ continue để nó chạy tiếp. Việc cài và cấu hình plugin cũng là điểm đau. Khá khó nếu bạn chưa biết chính xác mình đang làm gì, và tài liệu hiện tại chưa giúp được nhiều.

Tuy vậy, DeepSeek Harness vẫn là sản phẩm rất mới, nên những vấn đề này có thể hiểu được. Tôi kỳ vọng trải nghiệm, tài liệu, và hệ sinh thái plugin sẽ cải thiện đáng kể theo thời gian. Cũng có thể DeepSeek đang xây dựng một harness hoạt động đặc biệt tốt với các mô hình của chính họ, và đó có thể là một phần lý do cho sự hào hứng.