Sửa lỗi cài DeepSeek Harness và chọn đúng version

DeepSeek Harness thực sự được cài như thế nào

Cài DeepSeek Harness chỉ gồm một lệnh: npx @deepseek-ai/dsh web. Không có installer và cũng không có service nào cần cấu hình. Phần lớn vấn đề mọi người gặp phải thực ra không liên quan đến việc cài đặt. Đó là việc phân giải phiên bản: hôm nay npx quyết định chạy build nào của @deepseek-ai/dsh, và phiên bản Node.js của bạn có chạy được build đó hay không. Khi khởi động, công cụ in ra một địa chỉ bind vào localhost. Lý do Web UI chỉ phản hồi trên 127.0.0.1:3080 là một vấn đề riêng, không liên quan đến các vấn đề trên trang này.

Hai thực tế chi phối toàn bộ nội dung bên dưới. Thứ nhất, mọi phiên bản của @deepseek-ai/dsh được publish lên npm cho đến nay đều là prerelease. Phần lớn là release candidate (-rc.N), và từ 30 August 2026 đã có thêm các alpha build (-alpha.N). Tag latest trỏ đến một release candidate. Tính đến 6 October 2026, đó là 0.2.0-rc.2, được publish vào 29 September 2026. Thứ hai, README của project cho biết harness đang ở giai đoạn developer preview, được phát triển nhanh và sẽ có các thay đổi phá vỡ tính tương thích. Một flag hoạt động trong tuần trước có thể đã bị xóa trong tuần này. Hãy pin phiên bản trước khi xây dựng bất kỳ thứ gì dựa trên nó.

Trước hết, cần làm rõ một số thuật ngữ. dsh là công cụ dòng lệnh DeepSeek Harness. Node.js là JavaScript runtime mà công cụ này cần. npx là package runner đi kèm npm (node package manager). Nó fetch package khi cần thay vì cài package vĩnh viễn. Nếu từ harness trong câu này chưa quen thuộc, agent harness là chương trình bao quanh model, quản lý vòng lặp, tools, permissions và session state. Vì vậy, một version number mà bạn không tự chọn vẫn có thể thay đổi cách agent hoạt động.

dsh cần phiên bản Node.js nào?

File root package.json của repository khai báo "engines": {"node": "^22.19.0 || >=24.0.0"}, được đọc vào ngày 6 October 2026, khi repository đang ở phiên bản 0.2.1-alpha.1. Vì vậy, cần Node 22.19.0 hoặc mới hơn trong dòng 22, hoặc Node 24 trở lên. Node 20 không được hỗ trợ.

Trước tiên, hãy kiểm tra phiên bản hiện có.

node -v
npm -v

Đây là phần thường gây bất ngờ. Package @deepseek-ai/dsh đã publish không có field engines riêng. Chỉ root của monorepo khai báo field này, nhưng file root đó không được publish lên npm. Vì vậy, npm không có gì để kiểm tra, không in cảnh báo EBADENGINE và cũng không từ chối cài đặt. Trên Node 20, quá trình cài đặt trông như đã thành công. Lỗi chỉ xuất hiện sau đó, khi code được load chạm vào syntax hoặc API mà runtime không có. Không có một chuỗi lỗi duy nhất và ổn định để tìm kiếm, vì dòng lỗi đầu tiên phụ thuộc vào module nào được load trước. Hãy đọc node -v thay vì chỉ đọc crash.

Nếu Node quá cũ, nvm (node version manager) là cách ít ảnh hưởng nhất để sửa trên VPS. nvm được cài trong home directory của bạn và không thay đổi Node của hệ thống.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v lúc này phải in ra phiên bản bắt đầu bằng v24.. Nếu shell vẫn báo phiên bản cũ, shell function của nvm chưa được load. Hãy mở một login shell mới rồi thử lại. Node 24 là dòng LTS (long term support) hiện hành vào ngày 6 October 2026. Bản release mới nhất vào ngày đó là 24.21.0. Đây là target phù hợp hơn vì một lý do khác được đề cập bên dưới.

Vì sao npx chạy một version khác mỗi ngày?

npx @deepseek-ai/dsh web không chỉ định version, nên npx hỏi registry xem tag latest hiện trỏ đến version nào. Tag đó thay đổi, và thường xuyên thay đổi. 0.1.0-rc.8 được phát hành vào ngày 19 August 2026, hai ngày sau 0.1.0-rc.7, và đến ngày 6 October 2026, latest đã chuyển sang 0.2.0-rc.2. Mỗi lần tag thay đổi, command trong ghi chú của bạn bắt đầu chạy code khác mà không hỏi xác nhận và không hiển thị changelog.

Bạn có thể kiểm tra từng thành phần thay đổi từ CLI.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags cho biết hiện tại latest đang trỏ đến đâu. Vào ngày 6 October 2026, cả latest và next đều trỏ đến 0.2.0-rc.2, còn tag thứ ba, alpha, trỏ đến 0.2.1-alpha.1. Không tag nào trong số đó là channel ổn định để chuyển sang. Danh sách versions đáng chú ý hơn vì có các version bị thiếu. Vào ngày 6 October 2026, danh sách này có 30 version, từ 0.0.1-rc.1 đến 0.2.1-alpha.1. Dòng 0.0.1 nhảy từ -rc.2 sang -rc.5, dòng 0.1.0 nhảy từ -rc.3 sang -rc.6, các alpha build bắt đầu tại 0.1.2-alpha.2 và 0.1.3-alpha.2, và hoàn toàn không có 0.1.4. Các số bị thiếu vì một số build chưa từng được publish, đồng thời alpha build và release candidate được xếp xen kẽ trong cùng danh sách. Việc đoán -rc.N tiếp theo trong deploy script sẽ thất bại, vì vậy hãy đọc danh sách thay vì tăng số tuần tự.

Vì sao npx vẫn chạy phiên bản cũ?

Đây là phàn nàn ngược lại, và cả hai trường hợp đều có thể đúng, tùy bạn đang chạy npm phiên bản nào.

npx có thư mục package riêng, tách khỏi tarball cache, nằm trong thư mục có tên _npx bên trong npm cache. In đường dẫn đó ra và kiểm tra.

npm config get cache
ls "$(npm config get cache)/_npx"

Trong nhiều năm, npx dùng lại mọi thứ tìm thấy ở đó khi nhận package name không kèm spec, và không hỏi lại registry. npm 11.2.0 đã thay đổi hành vi này. Khi spec là một tên đơn hoặc một version range, npx giờ sẽ lấy manifest rồi chỉ dùng lại bản trong cache khi tarball đã resolve khớp với tarball mà registry vừa trả về.

Hành vi bạn nhận được phụ thuộc vào bản Node, vì Node tích hợp sẵn một phiên bản npm cụ thể:

• Node 20.20.2 tích hợp npm 10.8.2.
• Node 22.19.0 tích hợp npm 10.9.3.
• Node 22.23.3, bản phát hành 22 mới nhất tính đến ngày 6 October 2026, tích hợp npm 10.9.9.
• Node 24.19.0 tích hợp npm 11.17.0.
• Node 24.21.0, bản phát hành 24 mới nhất tính đến ngày 6 October 2026, tích hợp npm 11.19.0.

Vì vậy, toàn bộ dòng Node 22, được harness hỗ trợ chính thức, đều tích hợp npm cũ hơn 11.2.0. Trên Node 22, npx @deepseek-ai/dsh web không kèm spec sẽ tiếp tục chạy release candidate đã được cache từ nhiều tuần trước. Cùng lệnh đó trên Node 24 sẽ resolve lại trong mỗi lần chạy. Một lệnh, hai hành vi, và không hành vi nào cảnh báo bạn. Hãy yêu cầu tool cho biết nó đang dùng gì:

npx @deepseek-ai/dsh --version

Xóa npx cache

Trên npm 11.2.0 trở lên, có các subcommand riêng cho việc này.

npm cache npx ls
npm cache npx rm --force

Nếu không có --force, npm sẽ từ chối xóa toàn bộ và in Please use --force to remove entire npx cache. Hãy dùng npm cache npx ls trước nếu bạn muốn xóa một entry theo key thay vì xóa tất cả.

Trên npm 10, các subcommand này không tồn tại, nên hãy tự xóa thư mục.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force không giúp ích trong trường hợp này. Nó xóa _cacache, tức tarball store, nhưng vẫn giữ nguyên _npx. Việc tách riêng này chính là lý do npm sau đó bổ sung các subcommand npm cache npx. Xóa _npx cũng không làm mất dữ liệu vĩnh viễn: thư mục này chỉ chứa các package đã tải xuống, còn state của harness nằm dưới $DSH_HOME/profiles/<name> và không bị ảnh hưởng.

Làm thế nào để ghim chính xác một release candidate?

Ghi đầy đủ chuỗi version, bao gồm cả phần -rc.N.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

Các ví dụ trên trang này sử dụng 0.1.0-rc.7. Hãy thay bằng build bạn đã thực sự kiểm thử. Vào ngày 6 October 2026, tag latest trỏ đến 0.2.0-rc.2.

--yes rất quan trọng trong script, vì nếu không có nó, npx sẽ in prompt trước khi cài một package mà nó chưa từng thấy và chờ câu trả lời không bao giờ xuất hiện.

Version chính xác cũng là cách nhanh nhất. npx dùng chuỗi spec bạn nhập để xác định cache directory. Với version chính xác, npx so sánh chuỗi đó với package id đã được cài trong cache rồi chạy package mà không cần gọi registry lần nào. Trên npm 11.2.0 trở lên, chỉ dùng tên package sẽ khiến npx fetch manifest ở mỗi lần khởi động.

Global install cũng ghim version theo cách tương tự và cho bạn một command ngắn hơn.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

Không tìm thấy version phù hợp cho @deepseek-ai/dsh@^0.1.0

Range dạng caret hoặc tilde không khớp với package này. npm install -g @deepseek-ai/dsh@^0.1.0 trả về error code ETARGET và dòng No matching version found for @deepseek-ai/dsh@^0.1.0. Registry vẫn hoạt động bình thường. Đây là quy tắc semver: version range không khớp với prerelease version nếu bản thân range không ghi rõ prerelease. Mọi build đã publish của package này đều là prerelease, có dạng -rc.N hoặc -alpha.N, nên ^0.1.0 không khớp với version nào. Hãy ghi version chính xác.

Quy tắc này có một tác dụng phụ hữu ích. Vì range không thể tự chuyển sang một release candidate mới, bạn không phải xử lý trạng thái ghim một phần. Bạn hoặc đang dùng một version chính xác, hoặc đang dùng một tag có thể thay đổi.

Tôi nên dùng npx hay cài dsh trên toàn hệ thống?

Dùng npx để xem thử lần đầu, vì không có gì bị bỏ lại ngoài một thư mục cache mà bạn đã biết cách xóa. Dùng bản cài global có phiên bản được pin cho mọi thứ cần tiếp tục hoạt động sau khi reboot, chẳng hạn như một coding agent bạn duy trì chạy trên VPS.

Hai cách này có thể cho kết quả khác nhau trên máy đã dùng cả hai, vì vậy hãy so sánh chúng.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh không tìm thấy gì ngay sau khi cài global thành công gần như luôn có nghĩa là thư mục global bin của npm không có trong PATH của bạn. Chạy npm prefix -g để in root, rồi tìm các binary trong thư mục bin bên dưới đó.

Một lưu ý về bảo mật. npx tải và thực thi code từ registry mỗi khi resolve một package mới. Trên server, đây là một điểm phơi nhiễm thực tế chứ không chỉ là rủi ro trên lý thuyết. Pin phiên bản là một phần của giải pháp. Phần còn lại nằm trong cách các cuộc tấn công vào supply chain của npm tiếp cận server.

Ý nghĩa của developer preview đối với khả năng tái lập

0.1.0-rc.6 được phát hành vào ngày 13 tháng 8 năm 2026 và 0.1.0-rc.7 vào ngày 17 tháng 8 năm 2026. Hai phiên bản cách nhau 4 ngày. Tốc độ này không chậm lại: có thêm 23 phiên bản được phát hành từ ngày 19 tháng 8 đến ngày 3 tháng 10 năm 2026, trong đó có 0.2.0-rc.1 vào ngày 28 tháng 9 và 0.2.0-rc.2 vào ngày hôm sau. Với tốc độ đó, hướng dẫn được viết từ một tháng trước có thể mô tả một command line không còn tồn tại, và trang này cũng vậy. Hãy ghi ngày cho mọi nhận định về phiên bản, kể cả trong ghi chú của bạn.

Hai thói quen giúp dùng preview ổn định hơn. Pin chính xác phiên bản trong mọi command và script để khi rebuild server, harness tạo ra vẫn giống nhau. Sau đó, hãy đọc output của lệnh help từ build đã pin thay vì đọc từ một hướng dẫn bất kỳ.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

Nửa còn lại của khả năng tái lập là profile. dsh --profile <name> khởi động profile được lưu tại $DSH_HOME/profiles/<name>, còn các profile web và headless tự tạo từ các template đi kèm trong lần sử dụng đầu tiên. Đây cũng là thư mục nơi harness đọc API key, model và endpoint settings của nó, nên pin phiên bản và cấu hình hoạt động là hai việc riêng biệt cần làm đúng. Các bundle tích hợp được lấy từ bản dsh đang chạy hiện tại, nên khi thay đổi phiên bản đã pin, bạn cũng thay đổi các bundle đó. Plugin ngoài cây mã nguồn hoạt động khác. Chúng nằm trong thư mục profile, còn dsh plugin --profile <name> add <package> chuyển các argument của chúng cho pnpm để cài đặt. Vì vậy, pnpm phải có trong PATH của bạn; dsh sẽ báo rõ khi không có. Mỗi plugin bạn thêm vào chạy với cùng quyền như agent, nên hãy kiểm tra plugin có thể truy cập những gì trước khi cài đặt. package.json riêng của profile dùng để pin các plugin đó, vì vậy một cấu hình pin đầy đủ bao gồm 2 file, không phải 1 file.

Sự tách biệt này sẽ quen thuộc nếu bạn từng giữ các công cụ Python trong môi trường cô lập trên server: tool và những thành phần bạn thêm vào được pin ở các vị trí riêng. Khi harness đã khởi động, câu hỏi tiếp theo thường liên quan đến network thay vì phiên bản. Khi đó, truy cập Web UI của dsh trên VPS từ xa và hướng dẫn chi tiết hơn trong cài đặt DeepSeek Harness trên VPS sẽ tiếp tục phần này.

Các lỗi argument bạn thực sự sẽ gặp

Các lỗi này đến từ parser của CLI và mỗi lỗi đều nêu chính xác vấn đề. Cách diễn đạt nhìn chung ổn định giữa các bản build, nhưng không hoàn toàn giống nhau. Vì vậy, các thông báo dưới đây đã được kiểm tra với 0.2.0-rc.2 vào ngày 6 October 2026.

error: --profile <name> is required

Bạn đã chạy npx @deepseek-ai/dsh mà không có subcommand và profile. Lệnh không có đối số sẽ boot một profile, nên cần có tên profile. dsh web vẫn chạy được mà không có --profile vì parser đọc từ đầu tiên đứng riêng làm tên profile. Do đó, nó boot profile web được đóng gói sẵn cho bạn.

error: --patch needs a path

Bạn đã truyền --patch nhưng không có gì theo sau. Flag này có thể lặp lại, và mỗi lần xuất hiện cần một đường dẫn đến file.

error: --dump-config and --dump-default-config are mutually exclusive

Chọn một trong hai. Trong 0.2.0-rc.2, bản build mà latest trỏ tới vào ngày 6 October 2026, thông báo này nêu thêm một flag thứ ba và có nội dung error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive vì --dump-config-schema, vốn in JSON Schema cho các mục profile và patch, đã được thêm vào cùng hai flag kia. --dump-default-config in các layer của bundle được đóng gói sẵn và không nhận --patch. --dump-config in cấu hình đã ghép của một profile. Tất cả các lệnh này đều in kết quả rồi thoát mà không khởi động harness. Đây là cách an toàn để xem một release candidate mới đã thay đổi gì trong cấu hình của bạn.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name> không được cung cấp đối số nào để truyền tiếp. Khi thiếu subcommand, lệnh này sẽ khởi tạo profile, sau đó chuyển phần còn lại của command line cho pnpm. Vì vậy, nó cần các đối số như add @scope/dsh-plugin-example.

FAQ

DeepSeek Harness cần phiên bản Node.js nào?

Repository khai báo ^22.19.0 || >=24.0.0 trong package.json ở thư mục gốc. Thông tin này được đọc vào ngày 6 October 2026, khi repository đang ở phiên bản 0.2.1-alpha.1. Vì vậy, cần Node 22.19.0 trở lên trong dòng 22, hoặc Node 24 trở lên. Node 20 sẽ không hoạt động. npm package đã publish không có field engines riêng, nên npm không cảnh báo và cũng không chặn quá trình cài đặt. Lỗi chỉ xuất hiện khi runtime chạy. Trước tiên, hãy kiểm tra node -v. Dù sao Node 24 vẫn là lựa chọn tốt hơn vì đi kèm npm 11, phiên bản sửa lỗi tái sử dụng version của npx.

Làm cách nào để buộc npx dùng dsh mới nhất thay vì bản trong cache?

Trên npm 11.2.0 trở lên, npx @deepseek-ai/dsh đã kiểm tra lại registry cho package name không kèm version trong mỗi lần chạy. Trên npm 10, phiên bản đi kèm mọi bản phát hành Node 22, cơ chế này không hoạt động. Xóa npx cache bằng npm cache npx rm --force trên npm 11, hoặc xóa thư mục bằng rm -rf "$(npm config get cache)/_npx" trên npm 10. Sau đó xác nhận bằng npx @deepseek-ai/dsh --version. Lưu ý rằng npm cache clean --force xóa một thư mục khác nên không sửa được lỗi này.

Vì sao cài đặt @deepseek-ai/dsh@^0.1.0 bị lỗi?

npm trả về error code ETARGET cùng dòng No matching version found for @deepseek-ai/dsh@^0.1.0.. Mọi build đã publish đều là prerelease, chẳng hạn 0.2.0-rc.2 hoặc 0.2.1-alpha.1. Một semver range không khớp với prerelease version, trừ khi chính range đó chỉ rõ một prerelease version. Hãy cài exact version string, bao gồm cả suffix. Chạy npm view @deepseek-ai/dsh versions --json để xem các version đang tồn tại, vì chuỗi version có những khoảng trống do một số build chưa từng được publish.

Nên cài dsh global hay chạy qua npx?

npx phù hợp để dùng thử lần đầu vì ngoài một cache directory thì không có gì được lưu lại. Một global install đã pin version, chẳng hạn npm install -g @deepseek-ai/dsh@0.1.0-rc.7, phù hợp với mọi thứ cần tiếp tục hoạt động vì version chỉ thay đổi khi bạn tự thay đổi. Nếu không tìm thấy command dsh sau khi global install, global bin directory của npm chưa có trong PATH. npm prefix -g sẽ in ra root nơi thư mục đó nằm.

DeepSeek Harness đã đủ ổn định để xây dựng trên đó chưa?

Theo mô tả của chính dự án thì chưa. README nêu rằng dự án đang ở giai đoạn developer preview, được phát triển lặp nhanh và sẽ có các thay đổi phá vỡ tính tương thích. Release candidate 0.1.0-rc.6 và 0.1.0-rc.7 được publish cách nhau 4 ngày trong August 2026. 0.2.0-rc.1 và 0.2.0-rc.2 được publish cách nhau 1 ngày trong September 2026. Hãy pin một exact version và đọc --help từ build đã pin đó thay vì lấy từ một guide bất kỳ. Ghi ngày vào các ghi chú của bạn để biết chúng đã cũ đến mức nào.