TLDR DeepSeek Harness (dsh) là môi trường chạy agent mã nguồn mở của DeepSeek AI, phát hành ở giai đoạn developer preview khoảng ngày 13 tháng 8 năm 2026 theo giấy phép MIT. Nó tuân theo nguyên tắc “Model + Harness = Agent”, với mọi năng lực (models, tools, sessions, sandboxes, loops, UI) được triển khai dưới dạng plugin Cordis có thể hoán đổi.
Cách nhanh nhất để chạy cục bộ là npx @deepseek-ai/dsh web (yêu cầu Node.js ^22.19 hoặc ≥24), lệnh này khởi động Web UI tại http://127.0.0.1:3080. Bạn cung cấp khóa API DeepSeek (hoặc tương thích OpenAI) và một workspace. Cũng có sẵn bản dựng từ mã nguồn, ứng dụng desktop, Docker, Python SDK và tích hợp Ollama. Để truy cập đa mô hình cấp độ sản xuất, tăng độ tin cậy và kiểm soát chi phí khi sử dụng harness, hãy định tuyến yêu cầu thông qua endpoint hợp nhất tương thích OpenAI của CometAPI.
Key Takeaways
- DeepSeek Harness không phải là một model — đây là runtime/orchestrator cục bộ cho phép các model thao tác với tệp, shell, công cụ và phiên.
- One-liner chính thức:
npx @deepseek-ai/dsh web→ mở Web UI cục bộ trên cổng 3080. - Yêu cầu Node.js nghiêm ngặt: ^22.19.0 hoặc ≥24.x.
- Hỗ trợ các model chính thức của DeepSeek (deepseek-v4-flash, deepseek-v4-pro), các cổng tương thích OpenAI tùy chỉnh và model cục bộ thông qua plugins/Ollama.
- Kiến trúc hoàn toàn dựa trên plugin (Cordis kernel); các chế độ gồm Standard, Minimal, Code và Creator.
- Được đón nhận nhanh chóng: từ hàng chục nghìn đến vượt 100k sao GitHub trong vài ngày sau khi ra mắt.
- Khuyến nghị cho power users: kết hợp với CometAPI (https://www.cometapi.com/) như một nhà cung cấp tùy chỉnh để truy cập 500+ model, tiết kiệm 20–40% chi phí và dùng một khóa API duy nhất.
- Luôn dùng workspace cách ly; agent có thể sửa đổi tệp và chạy lệnh.
- Trạng thái developer preview có nghĩa là có thể có thay đổi phá vỡ — hãy pin phiên bản cho các thử nghiệm giống sản xuất.
What Is DeepSeek Harness and Why It Matters in 2026
DeepSeek Harness (dsh) là một agent runtime mã nguồn mở do DeepSeek AI phát triển. Phát hành theo giấy phép MIT ở giai đoạn developer preview, nó nhấn mạnh tính composable: mọi năng lực — model adapters, tools, skills, sessions, sandboxes, storage, agent loops, scheduling và UI — đều tồn tại dưới dạng plugin Cordis có thể gắn, tháo, hoán đổi hoặc tái hợp thông qua cấu hình. Về cơ bản không có “lõi đặc quyền” nào cần vá.
Các nguyên tắc thiết kế chính gồm:
- Agent = Model + Harness.
- Luồng sự kiện có thể truy vết hỗ trợ resume, fork, search và replay.
- Nhiều chế độ runtime (bộ công cụ đầy đủ tiêu chuẩn, chế độ code/orchestration, chế độ tối giản để benchmark, các chế độ creator/experimental).
- Web UI local-first cho sử dụng tương tác cùng với các tùy chọn headless và SDK để tự động hóa.
Nguồn chính thức:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- Product/landing: https://www.deepseek.com/harness/en/ (và phiên bản tiếng Trung)
- Các trang hướng dẫn cài đặt và mirror cộng đồng củng cố cùng các lệnh cốt lõi.
Lưu ý thuật ngữ quan trọng: “triển khai cục bộ” có thể mang hai nghĩa khác nhau. DeepSeek Harness trong hướng dẫn này chạy cục bộ trên máy của bạn, nhưng dự án
deepseek-harnesstiêu chuẩn kết nối tới DeepSeek V4-Pro hoặc V4-Flash qua API. Điều đó nghĩa là harness, cấu hình, phiên, xác thực và logic client có thể cục bộ, trong khi suy luận model thường được thực hiện bởi API của DeepSeek. Nếu bạn cần suy luận ngoại tuyến thực sự với trọng số model trên GPU của chính bạn, đó là một kiến trúc triển khai khác.
Prerequisites and System Requirements
Trước khi cài đặt, hãy xác minh:
- Hệ điều hành: Windows 10+, macOS 10.15+, Linux phổ biến (x64 hoặc arm64). Python SDK có ràng buộc bổ sung (Linux x64/arm64 hoặc macOS 14+ arm64).
- Node.js: Bắt buộc cho tuyến Web UI chính. Phạm vi mục tiêu là ^22.19.0 || ≥24.0.0. Kiểm tra bằng node --version. Các phiên bản lẻ ngoài phạm vi này không được hỗ trợ.
- Trình quản lý gói: npm/npx (đi kèm Node). Bản dựng từ nguồn cần pnpm (cài bằng npm install -g pnpm).
- Git: Bắt buộc để clone mã nguồn.
- Python (tùy chọn): 3.10+ cho Python SDK chính thức.
- API key / endpoint: Khóa API DeepSeek từ platform.deepseek.com, hoặc bất kỳ endpoint tương thích OpenAI + key + tên model.
- Phần cứng: Không cần GPU cho bản thân harness — suy luận model diễn ra từ xa (hoặc qua nhà cung cấp cục bộ bạn cấu hình). Tài nguyên laptop thông thường là đủ cho Web UI và orchestration.
- Mạng: Cần trong lần chạy đầu để tải gói; sau đó UI có thể hoạt động chỉ với các cuộc gọi API model.
- Workspace: Chuẩn bị một thư mục cách ly. Agent có thể đọc, ghi và thực thi lệnh trong workspace được cấu hình — không bao giờ trỏ vào dữ liệu sản xuất hoặc cá nhân nếu không có biện pháp bảo vệ.
Nguồn cho yêu cầu hệ thống: README chính thức và nhiều hướng dẫn cài đặt độc lập được đăng ngay sau khi ra mắt.
Method 1: Official One-Liner with npx (Recommended for Most Users)
Đây là cách nhanh nhất và được khuyến nghị chính thức.
- Đảm bảo Node.js đáp ứng yêu cầu phiên bản.
- Mở terminal và chạy:
Bash
npx @deepseek-ai/dsh web
- Gói sẽ được tải (hoặc dùng cache), khởi động cấu hình Web UI và in địa chỉ lắng nghe — mặc định http://127.0.0.1:3080.
- Mở URL đó trong trình duyệt. Chấp nhận thông báo developer preview nếu xuất hiện.
- Lần đầu sử dụng, cấu hình nhà cung cấp model (Settings → Models) bằng cách dán khóa API của bạn và chọn một model như deepseek-v4-flash hoặc deepseek-v4-pro.
- Chọn hoặc tạo một thư mục workspace.
- Bắt đầu giao nhiệm vụ.
Để dùng cổng khác:
Bash
npx @deepseek-ai/dsh web --port 8080
Các one-liner theo nền tảng đảm bảo Node đã có cũng được cung cấp bởi cộng đồng (PowerShell trên Windows với winget, Homebrew trên macOS, NodeSource trên Debian/Ubuntu, v.v.).
Ưu điểm: Không để lại dấu vết cài đặt lâu dài ngoài cache npm; luôn kéo phiên bản phát hành mới; onboarding đơn giản nhất. Nhược điểm: Phụ thuộc mạng cho lần tải gói đầu; kém thuận tiện cho việc đọc sâu mã nguồn hoặc build tùy chỉnh.
Method 2: Install and Run from Source
Dùng khi bạn muốn đọc plugin Cordis, pin một commit, phát triển preset tùy chỉnh hoặc đóng góp.
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
Web UI tương tự sẽ xuất hiện ở cổng mặc định. Các bản build developer preview có thể phá vỡ giữa các commit, vì vậy hãy xem đây là tuyến thử nghiệm.
Method 3: Desktop Applications (Zero Node Setup)
Các wrapper desktop từ cộng đồng và bên thứ ba đóng gói runtime để người dùng tránh phải cài Node/pnpm:
- Client nhẹ dựa trên Tauri khởi động một runtime Node kèm theo và đồng bộ harness upstream mới nhất khi khởi động. Chúng chạy trên 127.0.0.1:3080, giữ dữ liệu cục bộ và đăng ký lệnh dsh.
- Đóng gói dựa trên Electron với các phụ thuộc được pin.
Tải bộ cài từ trang GitHub Releases tương ứng (tìm “deepseek-harness-desktop”). Lần khởi chạy đầu sẽ tải các thành phần lõi (vài trăm MB). Chúng tiện lợi cho người không kỹ thuật nhưng không phải sản phẩm chính thức của DeepSeek — hãy xem xét repository và checksum SHA.
Method 4: Docker / Container Deployment
Các image Docker và compose file cộng đồng tồn tại để chạy Web UI trong container, thường với kết thúc HTTPS qua nginx và hỗ trợ các cổng tương thích OpenAI tùy ý. Quy trình điển hình:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # set API key / public host
docker compose up -d --build
Hữu ích cho truy cập LAN, máy chủ hoặc môi trường không muốn cài Node trên host. Một số thiết lập hỗ trợ settings.yaml tùy chỉnh cho các nhà cung cấp không phải DeepSeek.
Method 5: Python SDK for Programmatic / Headless Use
Dành cho agent không giám sát hoặc tích hợp vào pipeline Python:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
Thiết lập biến môi trường:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash
Sau đó chạy các ví dụ đã check-in hoặc dùng lớp DeepSeekHarness trong mã của bạn đối với một workspace và thư mục session cách ly. SDK đóng gói runtime của riêng nó và không yêu cầu Node.js hệ thống.
Method 6: Ollama Integration
Ollama cung cấp trình khởi chạy tiện lợi:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
Ollama có thể cài gói nếu cần và lưu cài đặt khởi chạy riêng. Tìm kiếm web và hỗ trợ tool phụ thuộc vào model đã chọn và truy cập đám mây của Ollama.
Configuring Models and Providers (Including CometAPI)
Trong Web UI, vào Settings → Models.
- Đối với DeepSeek chính thức: dán khóa từ platform.deepseek.com. Các model điển hình là deepseek-v4-flash và deepseek-v4-pro.
- Đối với các nhà cung cấp catalog (Anthropic, OpenAI, v.v.): dùng luồng “Add provider”.
- Đối với endpoint tùy chỉnh/tự host/aggregator: chọn “Add a custom provider”. Cung cấp Provider ID cố định, base URL, protocol (thường là openai-completions), tham chiếu hoặc giá trị khóa API và ít nhất một model ID.
Khuyến nghị CometAPI (được đề xuất mạnh cho nhiều workflow gần sản xuất) CometAPI là nền tảng hạ tầng AI hợp nhất cung cấp 500+ model (bao gồm các biến thể DeepSeek, GPT, Claude, Gemini, Grok và nhiều model khác) qua một endpoint tương thích OpenAI duy nhất: https://api.cometapi.com/v1.
Lợi ích khi dùng với DeepSeek Harness:
- Một khóa API thay vì quản lý nhiều thông tin xác thực nhà cung cấp.
- Giá cạnh tranh (được báo cáo tiết kiệm 20–40% so với mức giá trực tiếp của nhiều nhà cung cấp).
- Độ sẵn sàng cao (mục tiêu SLA 99,9%), độ trễ trung vị thấp và thanh toán theo mức dùng.
- Dễ chuyển model để A/B testing hoặc tối ưu chi phí mà không cần thay đổi cấu hình harness ngoài model ID.
- Tương thích drop-in: các mẫu SDK OpenAI hiện có hoạt động sau khi chỉ đổi base_url và key.
Trong biểu mẫu custom-provider của harness:
- Base URL:
https://api.cometapi.com/v1 - Protocol: openai-completions (hoặc tùy chọn tương đương được hỗ trợ)
- API key: khóa CometAPI của bạn
- Model ID: bất kỳ chuỗi model nào được hỗ trợ trong catalog model của CometAPI
Kết hợp này giữ runtime agent cục bộ mạnh mẽ trong khi cung cấp khả năng truy cập model đa nhà cung cấp linh hoạt, tiết kiệm chi phí. Người dùng mới thường nhận được tín dụng thử miễn phí. Tài liệu: https://apidoc.cometapi.com/.
Khóa được lưu ở trạng thái chỉ ghi (ví dụ, dưới $DSH_HOME/.credentials.yaml); UI chỉ hiển thị mô tả bị che.
Troubleshooting DeepSeek Harness
DEEPSEEK_API_KEY not found
Kiểm tra:
echo $DEEPSEEK_API_KEY
Trên Windows:
echo $env:DEEPSEEK_API_KEY
Nếu trống, hãy cấu hình lại.
400 reasoning_content error
Điều này thường chỉ ra việc xử lý vòng đời reasoning không chính xác.
Đảm bảo ứng dụng của bạn bảo toàn thông tin reasoning liên quan của assistant trong các yêu cầu thinking/tool-call nhiều lượt.
Đây là một trong những vấn đề cốt lõi mà harness được thiết kế để xử lý.
Context-length error
Kiểm tra:
input tokens + max_tokens
Giới hạn cứng được ghi nhận là:
1,048,576 tokens
Giảm ngữ cảnh đầu vào hoặc kích thước completion yêu cầu.
Tool calls trở nên sai định dạng trong quá trình streaming
Đừng giả định các mảnh stream đến theo thứ tự tool.
Hợp nhất các deltas của tool-call theo tool_call.index, như hợp đồng harness khuyến nghị.
Các yêu cầu bất ngờ đắt
Kiểm tra:
- thinking mode
- output length
- cache-hit rate
- prompt prefix stability
- model choice
- current API pricing
Một cải thiện đơn giản thường là chuyển các tác vụ thường kỳ từ Pro sang Flash.
Comparison of Installation and Deployment Methods
| Method | Ease of Use | Node Required | Best For | Persistence / Control | Typical Port / Access | Notes |
|---|---|---|---|---|---|---|
| npx one-liner | Cao nhất | Có | Thử nhanh, hầu hết người dùng | Tạm thời (chỉ cache) | 3080 (có thể cấu hình) | Khuyến nghị chính thức |
| Source (pnpm) | Trung bình | Có | Phát triển, plugin, pinning | Kiểm soát mã nguồn đầy đủ | 3080 | Cần pnpm + build |
| Desktop (Tauri/Electron) | Cao | Không (bundled) | Người dùng không kỹ thuật | Hồ sơ cục bộ & auto-update | 3080 (nội bộ) | Gói từ cộng đồng |
| Docker | Trung bình | Không (container) | Máy chủ, LAN, HTTPS | Volume container | Tùy chỉnh / 443 | Image cộng đồng |
| Python SDK | Trung bình | Không (bundled) | Headless, tự động hóa, pipeline | Phiên theo chương trình | N/A (không UI mặc định) | SDK chính thức |
| Ollama launch | Cao | Tùy chọn | Thử nghiệm model cục bộ | Cài đặt của Ollama | 3080 | Tích hợp với Ollama |
Dữ liệu tổng hợp từ tài liệu chính thức và các hướng dẫn sau khi ra mắt (tháng 8/2026).
Conclusion and Next Steps
DeepSeek Harness mang đến một agent runtime thiết kế sạch, hoàn toàn dựa trên plugin cho máy cục bộ, với gần như không có ma sát nhờ one-liner npx. Kết hợp với định tuyến model linh hoạt — đặc biệt thông qua một nền tảng hợp nhất như CometAPI — bạn có cả sức mạnh của các workflow lập trình agent hiện đại và kiểm soát thực tế về chi phí, lựa chọn model và tính cục bộ dữ liệu.
Bắt đầu ngay với:
npx @deepseek-ai/dsh web
Cấu hình khóa DeepSeek hoặc CometAPI, trỏ đến một workspace an toàn và khám phá chế độ Standard. Sau đó thử nghiệm chế độ Minimal cho benchmark, nhà cung cấp tùy chỉnh để tối ưu chi phí hoặc Python SDK cho tự động hóa.
Để có hướng dẫn chính thức mới nhất, luôn ưu tiên repository GitHub và doc. Để có độ tin cậy đa mô hình và lợi thế về giá khi chạy harness, hãy khám phá CometAPI và tài liệu tại https://apidoc.cometapi.com/.


