DeepSeek Harnessのインストールとバージョンエラー対処法

DeepSeek Harness のインストールの実態

DeepSeek Harness のインストールは、npx @deepseek-ai/dsh web という 1 つのコマンドだけです。インストーラーはなく、設定するサービスもありません。多くの場合、問題の原因はインストールではありません。バージョン解決が原因です。つまり、@deepseek-ai/dsh の npx がその時点で実行するビルドと、使用している Node.js のバージョンで実行できるかどうかが問題になります。起動すると表示されるアドレスは localhost にバインドされます。Web UI が 127.0.0.1:3080 でしか応答しない理由は、このページで扱う問題とは別です。

以下の内容を左右する重要な点は 2 つあります。1 つ目は、これまで npm に公開された @deepseek-ai/dsh のすべてのバージョンが prerelease であることです。大半は release candidate（-rc.N）で、30 August 2026 以降は alpha build（-alpha.N）も公開されています。latest タグは release candidate を指します。6 October 2026 時点では 0.2.0-rc.2 で、29 September 2026 に公開されています。2 つ目は、プロジェクトの README に、harness は developer preview 段階であり、頻繁に更新され、互換性を壊す変更が行われると記載されていることです。先週動作したフラグが、今週はなくなっている可能性があります。これを基盤に何かを構築する前に、バージョンを固定してください。

まず用語を説明します。dsh は DeepSeek Harness のコマンドラインツールです。Node.js は、このツールが必要とする JavaScript ランタイムです。npx は npm（node package manager）に付属するパッケージランナーで、パッケージを恒久的にインストールせず、必要なときに取得して実行します。この文脈で harness という言葉の意味が分かりにくい場合は、agent harness はモデルを取り囲むプログラムです。ループ、ツール、権限、セッション状態を管理するため、選択していないバージョン番号によって agent の動作が変わることがあります。

dsh にはどの Node.js バージョンが必要ですか？

リポジトリのルートにある package.json では、"engines": {"node": "^22.19.0 || >=24.0.0"} が宣言されています。これは、リポジトリのバージョンが 0.2.1-alpha.1 だった 2026 年 10 月 6 日時点の内容です。そのため、Node 22 系では Node 22.19.0 以降、または Node 24 以降が必要です。Node 20 は対象外です。

何よりも先に、現在の環境を確認してください。

node -v
npm -v

ここが分かりにくい点です。公開された @deepseek-ai/dsh パッケージには、独自の engines フィールドがありません。宣言されているのは monorepo のルートだけで、そのルートファイルは npm に公開されません。したがって npm には確認する情報がなく、EBADENGINE 警告も表示せず、インストールも拒否しません。Node 20 ではインストールが成功したように見えますが、問題は後で発生します。読み込まれたコードが、実行環境にない構文や API に触れた時点で失敗します。どのモジュールが先に読み込まれるかによって最初に失敗する行が変わるため、安定したエラーメッセージはありません。クラッシュの内容ではなく、node -v を確認してください。

Node が古すぎる場合、VPS では nvm (node version manager) が最も影響の少ない解決方法です。ホームディレクトリ内にインストールされるため、システムの Node には影響しません。

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 で、v24. から始まるバージョンが表示されるはずです。シェルがまだ古いバージョンを報告する場合は、nvm のシェル関数が読み込まれていません。新しい login shell を開いて、もう一度実行してください。2026 年 10 月 6 日時点では、Node 24 が active LTS (long term support) 系列であり、その日時点での最新リリースは 24.21.0 です。以下で説明する別の理由からも、Node 24 を選ぶ方が適しています。

毎日異なるバージョンで npx が実行されるのはなぜですか？

npx @deepseek-ai/dsh web ではバージョンを指定していないため、npx はレジストリに対して、latest タグが現在指しているバージョンを要求します。このタグは頻繁に移動します。0.1.0-rc.8 は 2026 年 8 月 19 日にリリースされました。0.1.0-rc.7 の 2 日後です。2026 年 10 月 6 日までに、latest はすでに 0.2.0-rc.2 を指していました。タグが移動するたびに、メモに記載したコマンドは、確認プロンプトも変更履歴も表示せずに、異なるコードを実行し始めます。

コマンドラインから、変動する各要素を確認できます。

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

dist-tags を実行すると、latest が現在どこを指しているかを確認できます。2026 年 10 月 6 日には、latest と next の両方が 0.2.0-rc.2 を指していました。また、3 番目のタグである alpha は 0.2.1-alpha.1 を指していました。これらのどれも、切り替え先にできる安定したチャネルではありません。versions の一覧のほうが重要です。この一覧には欠落があります。2026 年 10 月 6 日には、0.0.1-rc.1 から 0.2.1-alpha.1 までの 30 個のバージョンが含まれていました。0.0.1 系列は -rc.2 から -rc.5 へ飛んでいます。0.1.0 系列は -rc.3 から -rc.6 へ飛んでいます。アルファビルドは 0.1.2-alpha.2 と 0.1.3-alpha.2 から始まり、0.1.4 は存在しません。番号が欠けているのは、一部のビルドが公開されなかったためです。また、アルファビルドとリリース候補版が同じ一覧に混在しています。デプロイスクリプト内の次の -rc.N を推測すると失敗するため、番号を順に数えるのではなく、一覧を確認してください。

npx が古いバージョンを実行し続けるのはなぜですか？

これは先ほどとは逆の問題です。実行している npm のバージョンによって、どちらも起こります。

npx は tarball キャッシュとは別に、独自のパッケージディレクトリを使用します。このディレクトリは npm キャッシュ内の _npx というフォルダーにあります。パスを表示して確認してください。

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

長年、npx はパッケージ名だけを指定した場合、そこに見つかったものを再利用し、レジストリへ再度問い合わせることはありませんでした。npm 11.2.0 でこの動作が変わりました。指定が名前だけ、またはバージョン範囲の場合、npx はマニフェストを取得します。そのうえで、解決された tarball がレジストリから返されたものと一致する場合にだけ、キャッシュ済みのコピーを再利用します。

どちらの動作になるかは、Node のリリースによって決まります。Node には特定の npm が同梱されているためです。

• Node 20.20.2 には npm 10.8.2 が同梱されています。
• Node 22.19.0 には npm 10.9.3 が同梱されています。
• Node 22.23.3 には npm 10.9.9 が同梱されています。これは 6 October 2026 時点での最新の 22 リリースです。
• Node 24.19.0 には npm 11.17.0 が同梱されています。
• Node 24.21.0 には npm 11.19.0 が同梱されています。これは 6 October 2026 時点での最新の 24 リリースです。

つまり、harness が公式にサポートする Node 22 系列全体には、11.2.0 より古い npm が同梱されています。Node 22 では、名前だけを指定した npx @deepseek-ai/dsh web が、数週間前にキャッシュされた release candidate を実行し続けます。同じコマンドを Node 24 で実行すると、毎回再解決されます。1 つのコマンドに 2 つの動作があり、どちらの場合も警告は表示されません。実行中のツールに確認してください。

npx @deepseek-ai/dsh --version

npx キャッシュを消去する

npm 11.2.0 以降には専用のサブコマンドがあります。

npm cache npx ls
npm cache npx rm --force

--force を指定しない場合、npm はすべてを消去せず、Please use --force to remove entire npx cache を表示します。すべてではなくキーで 1 つのエントリを削除する場合は、先に npm cache npx ls を使用してください。

npm 10 にはこれらのサブコマンドがないため、ディレクトリを自分で削除します。

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

npm cache clean --force はここでは役に立ちません。これは tarball ストアである _cacache を消去するだけで、_npx はそのまま残します。この分離があるため、後から npm に npm cache npx サブコマンドが追加されました。_npx を消去しても恒久的に失われるものはありません。ここにはダウンロードしたパッケージだけが保存され、harness の状態は $DSH_HOME/profiles/<name> に保存されていて影響を受けないためです。

正確なリリース候補を固定するにはどうすればよいですか？

-rc.Nの部分を含む完全なバージョン文字列を指定します。

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

このページの例では 0.1.0-rc.7を使用しています。実際にテストしたビルドに置き換えてください。2026年10月6日時点で、latestタグは 0.2.0-rc.2を指していました。

スクリプトでは --yesが重要です。指定しない場合、npxは未確認のパッケージをインストールする前にプロンプトを表示し、返ってこない入力を待ち続けるためです。

正確なバージョンを指定する方法は、処理も高速です。npxは入力した仕様文字列を基にキャッシュディレクトリを決めます。正確なバージョンの場合、その文字列をそこにすでにインストールされているパッケージ IDと比較し、レジストリへアクセスせずに実行します。npm 11.2.0以降では、名前だけを指定すると、起動するたびにマニフェストの取得が発生します。

グローバルインストールでも同じ方法でバージョンを固定でき、短いコマンドで実行できます。

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

@deepseek-ai/dsh@^0.1.0 に一致するバージョンが見つかりません

キャレットまたはチルダの範囲指定は、このパッケージでは失敗します。npm install -g @deepseek-ai/dsh@^0.1.0はエラーコード ETARGETと、次の行 No matching version found for @deepseek-ai/dsh@^0.1.0.を返します。レジストリに問題はありません。これは semver のルールによるものです。バージョン範囲自体にプレリリースが指定されていない限り、バージョン範囲はプレリリースバージョンに一致しません。このパッケージで公開されているビルドはすべてプレリリースで、-rc.Nまたは -alpha.Nのいずれかです。そのため、^0.1.0は何にも一致しません。正確なバージョンを指定してください。

このルールには有用な副作用もあります。範囲指定によって新しいリリース候補へ移行することがないため、中途半端に固定された状態を考慮する必要がありません。正確なバージョンを使用しているか、更新されるタグを使用しているかのどちらかです。

npx と dsh のグローバルインストールはどちらを使うべきですか？

まず試すなら npx を使います。残るのは、削除方法が分かっているキャッシュディレクトリだけだからです。VPS 上で稼働させ続ける コーディングエージェント など、再起動後も動作する必要があるものには、バージョンを固定したグローバルインストールを使います。

両方を使ったことがある環境では、結果が一致しない場合があります。比較してください。

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

which dsh グローバルインストールが成功した直後に何も見つからない場合、ほとんどは npm のグローバル bin ディレクトリが PATH に含まれていないことが原因です。npm prefix -g を実行して root を表示します。バイナリは、その下の bin フォルダにあります。

セキュリティ上の注意点があります。npx は新しいものを解決するたびに registry からコードを取得して実行します。サーバーでは、これは理論上の問題ではなく、現実の攻撃リスクです。バージョン固定は対策の一部です。残りの対策については、npm のサプライチェーン攻撃がサーバーに到達する経路を参照してください。

再現性における開発者プレビューの意味

0.1.0-rc.6は2026年8月13日に公開され、0.1.0-rc.7は2026年8月17日に公開されました。4日しか空いていません。その後もペースは落ちていません。2026年8月19日から10月3日までの間に、さらに23個のバージョンが公開されました。2026年9月28日の0.2.0-rc.1や、その翌日の0.2.0-rc.2も含まれます。このペースでは、1か月前に書いた手順が、すでに存在しないコマンドラインを説明している可能性があります。このページも例外ではありません。自分のメモを含め、バージョンに関する記述にはすべて日付を付けてください。

プレビュー版を安定して使うには、2つの習慣が役立ちます。すべてのコマンドとスクリプトで正確なバージョンを固定してください。これにより、サーバーを再構築しても同じハーネスを生成できます。次に、ガイドではなく、固定したビルドのヘルプ出力を確認してください。

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

再現性のもう半分はプロファイルです。dsh --profile <name>は$DSH_HOME/profiles/<name>に保存されたプロファイルを起動時に読み込みます。webプロファイルとheadlessプロファイルは、初回使用時に同梱テンプレートから自動的に作成されます。このディレクトリには、API key、model、endpoint の設定も保存されます。そのため、バージョンの固定と、動作する設定の用意は別々に対処する必要があります。同梱バンドルは、現在実行中の dsh のインストールから解決されます。つまり、固定するバージョンを変更すると、これらのバンドルも変わります。

外部プラグインは動作が異なります。プラグインはプロファイルディレクトリに置かれ、dsh plugin --profile <name> add <package>は引数を pnpm に渡してインストールします。そのため、PATHに pnpm が必要です。pnpm がない場合は、dsh がそのことを明確に示します。追加したプラグインはそれぞれ、agent と同じ権限で実行されます。インストール前にプラグインがアクセスできる範囲を確認することを推奨します。これらのプラグインを固定するのは、プロファイル内のpackage.jsonです。したがって、完全な固定には1つではなく2つのファイルが必要です。

この分離は、サーバー上で Python ツールを分離環境に置いてきた場合には理解しやすいはずです。ツール本体と追加するものは、別々の場所で固定します。ハーネスが起動したら、次に問題になるのは通常、バージョンではなくネットワークです。そこで、リモート VPS から dsh Web UI に接続する方法と、詳しい手順を説明するVPS への DeepSeek Harness のインストールを確認します。

実際に表示される引数エラー

これらは CLI 独自のパーサーが出力するエラーで、それぞれ具体的な問題を示します。文言はビルド間でおおむね維持されていますが、完全に同じではありません。そのため、以下のメッセージは 2026 年 10 月 6 日に 0.2.0-rc.2 を使って確認したものです。

error: --profile <name> is required

サブコマンドも profile も指定せずに npx @deepseek-ai/dsh を実行しました。サブコマンドなしのコマンドは profile を起動するため、名前が必要です。dsh web は --profile なしで動作します。パーサーが先頭の単独の単語を profile 名として解釈するため、同梱の web profile を起動します。

error: --patch needs a path

--patch の後に何も指定していません。このフラグは複数回指定でき、指定するたびに 1 つのファイルパスを受け取ります。

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

どちらか 1 つを選択してください。2026 年 10 月 6 日に 0.2.0-rc.2 が参照したビルド latest では、他の 2 つに --dump-config-schema も加わったため、メッセージに 3 つ目のフラグが含まれ、error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive と表示されます。--dump-config-schema は profile エントリと patch の JSON Schema を出力します。--dump-default-config は同梱された bundle の各レイヤーを出力し、--patch は受け付けません。--dump-config は profile に対して合成された設定を出力します。これらはすべて出力後に終了し、harness を起動しません。そのため、新しいリリース候補によって既存の構成がどのように変わったかを確認する安全な方法です。

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

転送する内容を指定せずに dsh plugin --profile <name> を実行しました。このサブコマンドは profile が存在しない場合に初期化し、その後、コマンドラインの残りを pnpm に渡します。そのため、add @scope/dsh-plugin-example のような引数が必要です。

FAQ

DeepSeek Harness に必要な Node.js のバージョンはどれですか？

リポジトリのルートにある package.json には ^22.19.0 || >=24.0.0 が宣言されています。これは、リポジトリがバージョン 0.2.1-alpha.1 だった 2026 年 10 月 6 日時点の内容です。そのため、Node 22 系では Node 22.19.0 以降、または Node 24 以降が必要です。Node 20 は動作しません。公開 npm パッケージには独自の engines フィールドがないため、npm は警告もインストールの阻止も行わず、実行時に失敗します。最初に node -v を確認してください。Node 24 のほうが適しています。npm 11 が同梱されており、npx によるバージョンの再利用に関する問題が修正されているためです。

キャッシュされたものではなく、最新の dsh を npx に使わせるにはどうすればよいですか？

npm 11.2.0 以降では、npx @deepseek-ai/dsh により、パッケージ名だけを指定した場合も実行のたびにレジストリが再確認されます。Node 22 のすべてのリリースに同梱される npm 10 では再確認されません。npm 11 では npm cache npx rm --force で npx のキャッシュを削除してください。npm 10 では rm -rf "$(npm config get cache)/_npx" でフォルダーを削除します。その後、npx @deepseek-ai/dsh --version で確認してください。npm cache clean --force は別のディレクトリを削除するため、この問題は解決しません。

@deepseek-ai/dsh@^0.1.0 のインストールが失敗するのはなぜですか？

npm はエラーコード ETARGET と、No matching version found for @deepseek-ai/dsh@^0.1.0. という行を返します。公開済みのビルドはすべて 0.2.0-rc.2 や 0.2.1-alpha.1 のようなプレリリースです。semver の範囲指定は、その範囲自体にプレリリースが指定されていない限り、プレリリースのバージョンに一致しません。サフィックスを含む正確なバージョン文字列を指定してインストールしてください。存在するバージョンを確認するには npm view @deepseek-ai/dsh versions --json を実行してください。公開されなかったビルドがあるため、バージョン系列には欠番があります。

dsh はグローバルにインストールすべきですか。それとも npx 経由で実行すべきですか？

まず試すだけなら npx が適しています。キャッシュディレクトリ以外には何も残らないためです。継続的に動作させる必要がある場合は、npm install -g @deepseek-ai/dsh@0.1.0-rc.7 のようにバージョンを固定してグローバルにインストールする方法が適しています。バージョンは自分で変更するまで変わらないためです。グローバルインストール後に dsh コマンドが見つからない場合は、npm のグローバル bin ディレクトリが PATH に含まれていません。npm prefix -g を実行すると、そのディレクトリが含まれるルートを確認できます。

DeepSeek Harness は基盤として使えるほど安定していますか？

プロジェクト自身の説明によれば、まだ安定していません。README には、開発者向けプレビュー段階にあり、開発が急速に進んでいて、互換性を壊す変更が発生すると記載されています。リリース候補の 0.1.0-rc.6 と 0.1.0-rc.7 は 2026 年 8 月に 4 日間隔で公開され、0.2.0-rc.1 と 0.2.0-rc.2 は 2026 年 9 月に 1 日間隔で公開されました。正確なバージョンを固定し、その固定したビルドの --help を確認してください。ガイドではなく、固定したビルドの内容を参照します。自分のメモには日付を付けてください。どの程度古くなったかを判断できるようにするためです。