DeepSeek Harness plugins directoryDSH Pluginsdsh プラグイン ディレクトリ
ガイド一覧に戻る

DeepSeek Harness プラグイントラブルシューティング：インストールエラー・パッチ競合・バージョンロールバック（2026）

DeepSeek Harness（dsh）プラグインのエラー別対処法：pnpm workspace の allowlist、cordis.patch.yml の上書き順序、効かない profile、読み込まれないプラグイン、アップグレード後に壊れたときのバージョン固定とロールバック。

最終更新: 2026-10-07

このページを使うタイミング

「プラグインを見つけた」から「プラグインが動いている」までのどこかで問題が起きたときにお読みください。dsh plugin add の失敗、monorepo での pnpm-workspace allowlist エラー、cordis.patch.yml を変更しても反映されない、起動する Profile が想定と違う、といったケースを扱います。各セクションは「症状 → 原因 → 対処コマンド」の順でまとめています。

まだインストール作業に進んでいない場合は プラグインの安全なインストール から。どの設定レイヤーを編集しているのか分からない場合は 設定ガイド を先にお読みください。

その前にひとつだけ鉄則を：設定を変更したら必ず dsh を再起動してください。プラグインツリーは起動時に Cordis コンテナが組み立てるため、「何も起こらない」報告の半分は、設定変更後に再起動していなかっただけです。

1. インストール時にプラグインが見つからない

症状：dsh plugin add dsh-some-tool が解決エラーで失敗する、または正常終了したのにプラグインがどこにも現れない。

原因：CLI は npm レジストリから正確なパッケージ名で解決します。パッケージ名のタイポ、@scope/ プレフィックスの欠落、GitHub 限定配布（npm に存在しない）、または --profile <name> が起動時と食い違っていて別の Profile に入り込む、が主な原因です。

対処法：

  1. まず npm view dsh-some-tool でパッケージ名とスコープを確認します。プラグインの詳細ページとリポジトリの README に正しいインストールコマンドが記載されています（コミュニティプラグインの導入方法はプラグイン自身が管理しています）。
  2. GitHub 限定のプラグインはソースからブランチ・タグを指定してインストールします：dsh plugin add github:owner/repo#main
  3. フラグと起動方法を揃えます：dsh plugin --profile web add <package> で入れたなら dsh --profile web で起動します（dsh 単体ではダメです）。
  4. 開発中のプラグインはディレクトリを直接リンク：dsh plugin add ./path/to/my-dsh-plugin

2. インストールが止まる・失敗する：pnpm workspace allowlist

症状：pnpm monorepo 内でインストールがハングする、または pnpm-workspace allowlist・module not found・ESM & CJS 解決エラーで失敗する。特に git やローカルビルドから入れた場合に多い。

原因：pnpm は依存関係の境界を厳密にチェックします。GitHub から入れたプラグインは実質ワークスペースの一部になるため、パッケージが境界内に宣言されていないとリンクされず、実行時にモジュールを解決できません。

対処法：

  1. 境界内に宣言します：ワークスペースルートの package.json の dependencies（または pnpm-workspace.yaml の allowlist/catalog）にプラグインを追加し、ルートで pnpm install を実行します。
  2. プラグインを入れ直して再起動します：dsh plugin add <package> → 再起動して再構築されたツリーを読み込みます。
  3. npm に公開版があるならそちらを優先します。公開パッケージは依存を同梱しているため、境界問題を回避できます。
  4. ランタイムを確認します：node -v が 20.0.0 以上であることを確認してください。

3. cordis.patch.yml の競合（上書き順序の問題）

症状：2 つのプラグインが重複する（サイドバーが 2 つ、OCR エンジンが 2 つ、同一サービスの実装が 2 つ）、一方の設定が無視される、Profile patch collision / Override order issue が表示される。

原因：patch は bundle と profile の上に重ねる最上位のオーバーライド層であり、後ろに書いたエントリが優先されます。同じサービスや UI パネルを登録するエントリが複数ある場合、宣言順で決着が付きます。YAML のキー重複やインデントずれが、エントリの意味を静かに書き換えてしまうこともあります。

対処法：

  1. 実際に使っているファイルを開きます：cat ~/.dsh/profiles/<name>/cordis.patch.yml（ワークスペース内は <プロジェクトルート>/.dsh/cordis.patch.yml）。
  2. 順序を調整します：優先させたいプラグインを plugins: リストの末尾に移動します（後ろのエントリが前のエントリを上書きします）。
  3. 競合を止めたいだけなら共存させます：片方のエントリを enabled: false にします。
  4. 長期的にきれいなのは分離です：競合するプラグインを別の Profile に分け、dsh --profile <name> で起動します。
  5. 再起動前に YAML を検証します：インデント 1 つでエントリの意味が変わります。yq eval . cordis.patch.yml

4. dsh bundle 形式エラー

症状：dsh は起動するのにプラグイン構成がドキュメントとまったく違う、コピーした設定ファイルが競合エラーを出し続けて読み込まれない。

原因：3 つの設定レイヤーは役割が異なります。bundle は dsh に同梱される公式プラグインセット、profile は自分の「bundle + プラグイン」の組み合わせ、patch は単一のプラグイン項目に対する外科的なオーバーライドです。cordis.patch.yml が bundle 全体（数十のエントリと profile 層に属する設定）を再宣言していると形式が混ざり、bundle が提供する内容と上書きが衝突し始めます。

対処法：

  1. patch は最小限にします：プラグイン 1 つにつきエントリ 1 つ、enabled と options だけにしましょう。
# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'
  1. 一式まとめて有効化したいなら profile 層の仕事です。patch に全エントリを貼り付けるのではなく、profile の組み合わせとして定義します。
  2. 重複エントリを削除して保存し、dsh を再起動します。競合メッセージなしでプラグインのツール・パネルが読み込まれれば完了です。

5. Profile が反映されない

症状：cordis.patch.yml を編集して再起動したのに何も変わらない、特定の Profile 用に入れたプラグインがどこにもない。

原因：よくある 3 パターンのどれかです。① 間違ったファイルを編集している（設定ファイルは 2 箇所あり、プロジェクト側がグローバル側を上書きする）、② 起動時の Profile 名と編集したディレクトリ名が一致しない、③ そもそも再起動していない。

対処法：

  1. 2 箇所を確認します：ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null と、プロジェクトルートで ls .dsh/cordis.patch.yml 2>/dev/null
  2. 優先順位を思い出します：両方ある場合 <プロジェクトルート>/.dsh/cordis.patch.yml が ~/.dsh/profiles/<name>/cordis.patch.yml より優先されます。
  3. フラグとディレクトリを一致させます：~/.dsh/profiles/web/cordis.patch.yml を編集したなら dsh --profile web で起動します（dsh 単体や dsh --profile headless ではダメです）。
  4. 再起動して確認します：dsh --profile web でツール・パネルが現れるか確認してください。まだの場合は次のセクションへ。

6. インストール済みなのに読み込まれない（failed to register）

症状：インストールは成功、設定も正しいはずなのに、起動時に Plugin failed to register / Lifecycle timeout が出る、またはエラーなしで読み込まれない。

原因：ランタイムが古い（Node.js 20 未満）、依存が不足している（git インストールはビルドが必要）、宣言順が別のプラグインと衝突する、エントリが enabled: false のまま。もう一つのよくある原因がサンドボックスです。dsh はデフォルトで read-only のため、ディスクやネットワークにアクセスするプラグインは読み込み時に Permission denied / Sandbox security policy violation でブロックされます。

対処法：

  1. ランタイムを確認します：node -v —— 20.0.0 以上（推奨：Node 22 LTS）にアップグレードします。
  2. ソースインストールはビルドが必要です：プラグインディレクトリで pnpm install && pnpm build を実行してから再起動します。
  3. クリーンにインストールし直します：dsh plugin remove <package> → cordis.patch.yml のエントリを確認 → dsh plugin add <package>
  4. エントリが有効か確認します：dsh plugin add は enabled: true を書き込みますが、手編集した場合はそのまま残っているか確認してください。
  5. サンドボックスが原因で、プラグインが信頼できる場合は権限を上げて起動します：dsh --sandbox workspace-write（詳細はセキュリティガイド）。
  6. dsh-market の Web UI から入れた場合は Settings → Plugin Market でステータスを確認してください。バックエンドが設定を適用してホットリロードするため、失敗状態もそこに表示されます。

7. アップグレード後に遅くなる・パフォーマンスが落ちる

症状：dsh をアップグレードした後、古いセッションを開く・再開する・会話を続けるたびに明らかにのもたつきが出る。セッションが長いほど顕著です。以前のバージョンより全体的に遅くなったと感じる場合も。

原因：多くの場合、プラグインの問題ではありません。長時間セッションのもたつきは旧バージョンの既知の不具合で、初期のセッション データ保存形式が重く、メッセージが増えるほどオープン・再開・毎ターンの会話に余分なメモリと解析コストがかかっていました。

対処法：

  1. 結論を出す前にまず現在の安定系へアップグレード：長時間セッションのもたつきは v0.1.5 で修正済み（保存形式の最適化、メモリ使用量の削減）で、2026-09-29 時点で npm の latest は 0.2.0-rc.2 です。npm install -g @deepseek-ai/dsh@latest を実行して再起動し、同じ長いセッションで再確認してください。「アップグレードしたら遅くなった」報告の大半はこの既知問題に遡れ、更新で解決します。実験チャネルは latest に追いつきました——next も 0.2.0-rc.2、alpha は 0.1.7-alpha.2 を指します——が、速度問題の切り分けを alpha チャネルから始めるのは筋が悪いです。
  2. それでも遅い？超長コンテキストの場面では Minimal プロファイルで起動します（GitHub 議論 #5485 参照）：dsh --profile minimal なら永続ターミナルなどの基本ツールだけを読み込み、セッションに注入される内容を減らせます。普段は Standard、長丁場のセッションは Minimal に。
  3. それでも解決しない場合：ログを収集して報告を——dsh --version、起動コマンド、セッション規模（メッセージ数/ファイルサイズ）、コンソールのエラー、比較結果を添えて公式リポジトリに issue を立ててください。データが揃うほど特定は早まります。

8. アップグレード後にプラグインが動かなくなった（バージョン固定とロールバック）

症状：dsh が自己更新した、あるいは npm install -g @deepseek-ai/dsh@latest を実行したあと、昨日まで動いていたプラグインが読み込めない・パネルが消えた・登録エラーが出る。特定の profile でのみ再現するケースもあります。

原因：アップグレードで壊れる箇所は 2 つあります。ひとつはハーネス側がプラグインに求める契約が変わるケース。v0.1.6-alpha.2 の公式リリースノートではプラグインの依存解決が実行時の解決に変更され、実行時のアンロードが追加され、あわせてプラグイン開発者にロード／アンロード処理の見直し が明示的に求められています。旧前提で動いていたプラグインは、作者が追従するまで失敗します。もうひとつは自分の設定のズレで、起動しない profile にエントリが残っている、あるいは並び替え後に 2 つのエントリが衝突しています。バージョンの動きも現実の要因です。0.1.6 系は 2 日間で alpha を 2 回（09-15 と 09-17）公開し、安定系は 0.1.5-rc.3 のまま 09-28 の 0.1.7-rc.2 切り替えまで留まりました——同日の 0.2.0-rc.1 はプラグイン管理 UI を作り直しているため、0.2.0 プレビューには現実の互換性コストが伴います（次のセクション参照）。

対処法：

  1. まず切り分け——dsh かプラグインか：dsh --profile minimal で起動します。この profile は永続ターミナルなどの基本ツールだけを読み込むため、ここで症状が消えるなら原因はプラグイン側。何かを触る前に dsh --version と、--profile <name> を含めた起動コマンドを控えておいてください。
  2. 起動診断を読む：0.1.6-alpha.2（alpha 系）以降、起動に失敗するとエラーと待機中のサービスを分類して表示し、完全な診断内容をログファイルに保存します。何かを外す前に、まずそのファイルを読むのが先です。
  3. インストール全体が不安定ならハーネスを固定：npm install -g @deepseek-ai/dsh@0.1.5-rc.2——@latest にせず正確なバージョンを指定します。これがロールバックです。戻り先は、以前動いていた安定系のバージョンです。
  4. 特定のプラグインだけならプラグインを固定：dsh plugin remove <package> のあと、動くブランチではなくタグで再インストールします：dsh plugin add github:owner/repo#v1.2.3（#ref にはタグでもブランチでも可）。使えるタグが無い場合は削除せず、cordis.patch.yml の該当エントリを enabled: false にして再起動すれば、直ったときに設定をそのまま復旧できます。
  5. 触る前にバックアップ：cp ~/.dsh/profiles/<name>/cordis.patch.yml ~/dsh-profile-backup.yml。ロールバックのついでにプラグイン構成まで失うと、元の問題より悪い状態になります。
  6. 多重インスタンス衝突を確認：セッションが別の DSH インスタンスに占有されていると表示された場合、公式の案内はそのインスタンスを終了して再試行することです。サーバー常駐のインスタンスとローカルのインスタンスが同じ profile を共有しているときに起きがちです（サーバーに常駐させて使う参照）。
  7. 最後に再起動して検証。プラグインツリーは起動時に組み立てられるため、再起動するまで上記の対処はどれも検証済みになりません。

意図的に alpha 系に乗っているなら、この前提を受け入れてください。リリースノートは適配の責任をプラグイン作者に置いていて、エコシステムはプラグインごとに追従していきます。コミュニティプラグインが業務の要なら、alpha が落ち着くまでは latest に留まるのが得策です。

9. Windows サンドボックス権限：0xC0000142 とアクセス拒否

症状：Windows でサンドボックス化されたシェルコマンドがすべて 0xC0000142 (STATUS_DLL_INIT_FAILED) で失敗する。制限付きサンドボックスで子プロセスの出力を取得できない（Access is denied）。デスクトップアプリがサンドボックス付き PTY を起動できずに落ちる。あるいはプロビジョニング段階で SetNamedSecurityInfoW failed (Win32 5) がそのまま出る——報告はハーネスのアップグレード直後に集中しており、0.2.0-rc 系の間もディスカッションの新規報告は増え続けています。

原因：内蔵 Windows サンドボックスは起動時にディレクトリごとの ACL を供給（プロビジョニング）しますが、記録済みの障害形態は 3 系統に整理できます。0xC0000142 系：非昇格の起動で workspace-write の供給に失敗し、自己修復しない壊れた ACL が残る（#8115）。デスクトップで pwsh/cmd echo といった無害なコマンドまで 0xC0000142 で落ちる（#8208、#8295）。0.2.0-rc.1 では Electron ホスト下でサンドボックス子プロセスが 1 つも起動しない（#8193）。加えて初期からの記録として、デスクトップでの全面的な失敗（#8142、#8130）、CLI/Web（npx）での stdio 取得の確定的な失敗と間欠的な 0xC0000142（#8143、#8141）、minimal プリセットの PTY が終了コード 127 で落ちる件（#8158）。さらに 10 月初めには 24 時間ウィンドウで 4 件の新報告が集中する過去最多の記録——Win10 LTSC での起動（#8877）、no-console 起動（#8878）、confined pwsh 内での DLL 初期化失敗（#8890）、pwsh での workspace-write 供給失敗（#8897）。WRITE_OWNER 系：ワークスペースがデータドライブ（D:\... など）にあると、ドライブ既定の継承 ACL は WRITE_DAC を暗黙に与えるだけで、WRITE_DAC | WRITE_OWNER でルートを開こうとする grantWrite は Win32 5 で失敗します。以後そのセッション内のサンドボックス経由コマンドは、読み取り専用のものまで含めてすべて使用不能になり、一方でファイル読み書きツールは影響を受けません（#8232、#8272、#8275、#8282、および 10 月の WRITE_OWNER Win32 5 新報告 #8886）。リグレッション系：0.1.5 → 0.1.7-rc.2 で制限付き子プロセスが ConstrainedLanguage に落ち、許可済みの書き込みがすべて拒否される（#8219）。workspace-write は git for Windows も壊しました——MSYS バイナリが起動せず、schannel がキーストアに届かない（#8209）。そして 4 回目の波が 10 月 6〜7 日の 2 日で到着しました：パッケージ版デスクトップで workspace-write コマンドがすべて 3221225794/0xC0000142 で終了し（#9031）、confined pwsh の全コマンドが同じエラーで落ちて（#8991）、Win11 の pwsh ツール起動も同様に失敗（#8990）。#8971 は有用な対照実験も残しています——同じマシンで 0.1.5-rc.2 の workspace-write サンドボックスは問題なく動いたのです。

対処法：

  1. まず切り分け：障害形態を記録し（全コマンドか間欠か、デスクトップか npx か、システムドライブかデータドライブか）、dsh --version と起動診断ログを控えます。
  2. 0.2.0-rc.2 以降へ上げて、公式のワンショット修復を実行：rc.2 のリリースノートは Windows サンドボックス権限スクリプトを「許可を得て 1 回で診断と修復を完了し、変更前のバックアップと復元コマンドを保持する」形に統合したと説明しています。セッション内でエージェントにサンドボックス権限の診断を依頼し、手動の変更の前にまずこれを実行してください（rc.1 時代は診断と修復が別ステップで、#8272 にその隔たりが記録されています）。
  3. WRITE_OWNER 形態への個別対応：ワークスペースをユーザーディレクトリ配下へ戻すか、データドライブのルートでアカウントに明示的に WRITE_OWNER を許可します——アップグレード後のワンショット修復がやっているのはまさにこれで、バックアップ付きです。代替策として、昇格した（管理者）ターミナルから一度起動してプロビジョニングを完了させ、その後ふだんの（非管理者）ターミナルに戻って再テストします。
  4. 壊れた ACL が残る場合：前回失敗したプロビジョニングが作ったサンドボックス profile ディレクトリを削除し、次の起動で一から作り直させます（先に cordis.patch.yml をバックアップ——セクション 8 参照）。
  5. それでも失敗するなら：診断ファイルを添えて上記ディスカッション群に報告を追加してください——こうした詳細こそが障害形態の切り分けに使われています。

10. ネットワークと認証のエラー：プロキシ設定と「API key is invalid」

症状：社内プロキシ環境でリクエストだけがタイムアウト・ハングする（ブラウザは正常）。またはセッションが API key is invalid（401）、Insufficient Balance（402）、403 系の権限エラーを返す。

原因：dsh はその環境のネットワークを通ってプロバイダに到達します：npm が認識するプロキシを dsh プロセスが認識しない（またはその逆）だと、きれいなエラーではなくハングやタイムアウトとして現れます。キー無効エラーの大半は初歩的な原因です——貼り付け時に空白が混ざった、別のプロバイダのキーだった、違う profile の設定に入った、そして有名な「ログインパスワードが API Key 欄に自動入力される」ケース——0.1.7-rc.2 で特に対策されました。

対処法：

  1. まずプロキシ：dsh を起動するプロセスに標準変数 HTTP_PROXY / HTTPS_PROXY / NO_PROXY を設定し、dsh を再起動して再試行します。プラグインのダウンロードが遅いのは別経路なので、インストールガイドのミラー切り替えセクションへ。
  2. GUI が欲しければ：kanneiren/dsh-network-settings（★107）は dsh プロセスの実ネットワーク経路・DNS・最初の失敗点を診断し、kriskite/dsh-network-proxy（★8）は設定ページからシステム／手動／直接の各プロキシモードを管理します。
  3. API key is invalid が出たら：プロバイダの管理画面でキーを再生成し、空白や改行を含まない状態で貼り直し、Settings → Models で実際に選ばれているプロバイダと一致しているか確認します。
  4. 再試行の前にステータスコードを読む：401 はキーそのものが誤り（キーを作り直す）、402 は残高不足（チャージする——残高ガイド参照）、403 はキーは有効だがそのモデルやリージョンの利用が許可されていない（モデルかアカウントを変える）。

11. dsh: command not found

症状：ターミナルが dsh: command not found を返す。デスクトップアプリが PATH 上に dsh ランチャーを見つけられない（#8268）。昨日まで動いていた起動コマンドが、アップグレード後になくなる（#8242）。

原因：CLI は npm のグローバル領域に入るため、原因はほぼ次の 3 つのいずれかです。グローバル領域が PATH に載っていない（nvm/fnm/volta のようなバージョンマネージャーやカスタム prefix で典型）、インストールがそもそも完了していない、あるいは GUI から起動されたデスクトップアプリがシェルの PATH 追加分を一切引き継いでいない。web バリエーション——dsh web を実行したら zsh: command not found: dsh が返ってくるだけ——は、同じ問題を Web UI の入り口から見た姿です。CLI が起動できていないので、Web 側が失敗する段階にすら届いていません。

修正手順：

  1. まず実行体の場所を特定：npm prefix -g がグローバル prefix を出力し、dsh の実行ファイルはその下の bin ディレクトリにあります。このディレクトリを echo $PATH と突き合わせてください。
  2. 再インストールして新しいターミナルを開く（新しいシェルは PATH を読み直します）：npm install -g @deepseek-ai/dsh。
  3. macOS / Windows デスクトップアプリでは、0.2.0-rc.2 で追加されたメニューバーの 「Manage dsh command」 を使います。dsh コマンド（プラグイン込み）のインストールと管理を公式が代行し、Node.js や pnpm の別途導入は不要。シェル環境が見えない GUI 起動のケースもまとめて解決します。
  4. つなぎの手段として、npx @deepseek-ai/dsh web ならグローバルインストールなしで現行バージョンが動かせます。

12. デスクトップアプリ：全コマンドが 0xC0000142 でゼロ出力（解決済みケース）

症状：デスクトップアプリで実行したコマンドがすべて 0xC0000142 で落ち、出力がまったくない——エラーテキストすら表示されない。同じマシンの普通のターミナルで同じコマンドを実行すると正常に動く。この形状を特定した報告（#8395）は解決済みとマークされています。

原因：0xC0000142 は STATUS_DLL_INIT_FAILED——サンドボックス化された子プロセスが生成の段階で死ぬため、出力を吐く前に終わります。danger-full-access では制限付きトークンが適用されないため、同じコマンドが動く。「CLI では動く」のは矛盾ではなく、この形状の特徴です。#8336 の制御実験が、どの組み合わせで落ちるかを特定しました：制限付きトークン（WRITE_RESTRICTED + Low 整合性レベル）とコンソール分離フラグ（CREATE_NO_WINDOW / CREATE_NEW_CONSOLE）のいずれかが同時に存在すると子プロセスは必ず死に、どちらか単独なら生存できます。解決済みケースの変数はインストール先——デスクトップアプリが既定の場所ではなくカスタムディレクトリに入っていたことでした。

修正手順：

  1. まず形状の確認：CLI は動き、デスクトップは静かに死ぬ → このセクションです。何か変える前に dsh --version を記録してください。
  2. 実証済みの解決策（#8395）：デスクトップアプリをアンインストールし、既定のインストール先に入れ直す。セットアップでカスタムディレクトリを選ばないこと。
  3. 動けない間の公式の回避策：DSH_HOME を harness ホームに指定し、同じエントリポイントを ELECTRON_RUN_AS_NODE=1 で起動する——#8395 に記録された公式の一時的な方法です。
  4. 検証：workspace-write で無害なコマンドを実行し、出力が返ってくることを確認。まだ落ちるなら第 9 セクションに戻ってワンショット修復を。

13. workspace-write の許可が効かない：ACL の 3 つの欠陥（と ERROR_NONE_MAPPED 1332）

症状：workspace-write を許可したのに、ワークスペースのサブフォルダへの書き込みが拒否され続ける。デスクトップアプリが同じワークスペースで失敗を繰り返し、再起動するまで直らない。標準（非管理者）ユーザーがシステムドライブ以外にワークスペースを置くと grantWrite が Win32 5 で失敗。ACL を手で掃除しようとすると icacls /remove が ERROR_NONE_MAPPED (1332) を返す。

原因：ディスカッション #8409 が Windows ACL サンドボックスの 3 つの独立した認可欠陥を記録しています。1 つ目、保護付き DACL の下にあるサブディレクトリは許可を得られないため、ルートの認可が成功してもサブフォルダの書き込みは拒否され続けます。2 つ目、デスクトップアプリはルートの許可を一度だけ評価して結果をキャッシュし、再チェックしない——一度失敗した評価は失敗し続け、アプリの再起動で再評価されて回復します。3 つ目、標準ユーザーが非システムドライブに置いたワークスペースではドライブルートに WRITE_OWNER がなく、grantWrite が Win32 5 で失敗——第 9 セクションの WRITE_OWNER 系です。1332 は別物：機能 SID（capability SID）はアカウントにマッピングされないため、icacls は名前では削除できない——このエラーは「マッピング対象がない」であって「ACL が壊れた」ではありません。

修正手順：

  1. まず公式のワンショット修復を実行（第 9 セクションの手順 2）——サポートされている経路で、バックアップも残ります。
  2. 動くはずのワークスペースでデスクトップが繰り返し失敗する？アプリを再起動してキャッシュされたルート許可を再評価させる——#8409 に記録された自己回復の経路です。
  3. 標準ユーザー + データドライブ：ワークスペースをユーザーディレクトリの下へ戻す（またはドライブルートに WRITE_OWNER を付与——ワンショット修復が自動でやっているのはこれです）。
  4. icacls の ERROR_NONE_MAPPED 1332 と格闘しない：マッピングされない機能 SID は名前では削除できません。ACL は公式の修復スクリプトに任せる——手で剥がすと欠陥そのものより悪い状態になりかねません。
  5. 検証：ワークスペースのサブフォルダ内にファイルを 1 つ作らせる（欠陥 1 はルートより下で発生するため）、そのあとデスクトップを一度再起動して再テスト。

14. dsh がそもそも起動しない：Smart App Control とウイルス対策ソフトの TLS 検査

症状：dsh のバグに見えてそうではない、ホスト側の遮断が 2 種類。Windows 11 で Smart App Control が有効なマシンでは dsh が起動しない（#8377）。デスクトップアプリ（0.2.0-rc.2）で一部のウイルス対策ソフトが入っていると、ホストプロセスの HTTPS リクエストがすべて失敗し、UI には汎用エラーしか出ない——ログインが完了しない（#8448）。

原因：Smart App Control は未署名のネイティブモジュールを遮断します。dsh はいくつか抱えているため、こちら側のログが何も出る前に起動が失敗します。イベントビューアーの CodeIntegrity ログに 3077/3033 イベントが残るのが証拠。ウイルス対策ソフト側の失敗は TLS の再署名です。カスペルスキー系の「暗号化された接続の検査」が HTTPS を横取りして対策ソフト自身の証明書で再署名し、ホストプロセスがそのチェーンを拒否するため、すべての HTTPS 通信が汎用エラーの背後で止まります。

修正手順：

  1. Smart App Control：まずイベントビューアーで CodeIntegrity 3077/3033 を確認——この形状の指紋です。そのうえで Smart App Control をオフにすると起動が回復します（#8377）。SAC にはアプリ単位の許可リストがなく、dsh だけを許可リストに追加することはできません。
  2. ウイルス対策ソフトの TLS：dsh 関連ドメインを除外リストに追加するか、「暗号化された接続の検査」機能をオフにする——どちらでもホストの HTTPS が回復します（#8448）。
  3. 検証：変更後に一度起動（SAC）またはログイン（ウイルス対策）。まだ汎用エラー？ホストのログと dsh --version を集め、報告の前に第 10 セクションのプロキシ形状と見比べてください。

15. Web UI が「authentication required」を出す（またはポートが塞がっている）

症状：dsh web（または npx @deepseek-ai/dsh web）を起動したのに、ページが認証エラー（authentication required）を出す。またはポートが塞がっている。または dsh web と打つと zsh: command not found: dsh が出るだけ。検索エンジンはこの 3 つを同じ質問として扱います——答えは 3 つとも別です。

原因：Web UI の URL はコマンド自身が表示し、そこに今回の起動コンテキストが入っています——公式ドキュメントは「コマンドが URL を表示する」と明言しています。そのため、素の 127.0.0.1:3080 を手打ちすると、ダッシュボードではなく認証ゲートに当たることがあります。ポートが塞がっているのは、別の dsh インスタンス（または残存プロセス）がすでに 3080 を握っているから——第 8 セクションの多重インスタンス競合です。command not found は第 11 セクションの PATH の問題で、Web UI とは無関係です。しかもこのゲートは設計として組み込み済み：ディスカッション #5936（タイトルがまさに dsh web authentication required）は必須のトークン認証を任意にするよう要望していますが、実装されておらず、LAN 内デプロイでも同じ壁に当たります。

修正手順：

  1. 手打ちのアドレスではなく、dsh web が表示した完全な URL を開き直す——コマンドを再実行して自動で開かせるのが確実です。
  2. SSH 経由の起動でホスト URL だけが表示されるのは想定内。ポート転送を持つ側のマシンのブラウザで開いてください。
  3. ポートが塞がっている場合：セッションを握っている別インスタンスを終了させる（第 8 セクションの多重インスタンス処理）、または別ポートで起動：dsh --profile web --port 8080。
  4. command not found：先にインストールを直す（第 11 セクション——npm のグローバルパス、またはデスクトップの「Manage dsh command」）。
  5. ダッシュボードを本当にループバックの外へ出す（リバースプロキシ、共用 LAN サーバー）なら、トークンゲートはそこでも適用されます——任意にできます。コミュニティルートは hxy91819/dsh-auth（★6、2026-10-03 に GitHub API で再確認）：管理された Caddy forward_auth エッジと Argon2id ハッシュの管理者ログインを前面に置き、dsh 本体はループバック専用のまま（紹介スレッドは #3231）。機能はするものの初期段階です。Linux x64/ARM64 + systemd + Node 24.7+ が必須で、star 数から見てユーザーベースもまだ小さく、公開 URL の前面に置く前に README を必ず読んでください。
  6. さらに先へ：Web UI ガイドは画面全体をフレーム検証付きで解説。リモート・モバイルコレクションに dsh-pocket や dsh-web などのスマホ／リモートクライアントをまとめています。リモートアクセスは外部からダッシュボードへ戻るトンネルを扱います。
  7. 検証：表示された URL でダッシュボードが開き、ワークスペース選択後に入力欄が使えること。

16. API key is invalid（401）——キーそのものが原因とは限らない

症状：セッションやタスクが API key is invalid という文言のエラー（大抵は 401）や、403 系の権限エラーで止まる。ここにたどり着く検索は完全なエラー文そのものです——しかも記録されているケースでは、キーは無事だったこともあります。同じキーがある画面では動くのに別の画面では拒否される、あるいはキーが明らかに正しいのにエラーが出続ける、という形です。

原因：ありふれた 3 つのキーの問題が大多数を占めます。キーを貼り付けるときに前後の空白や改行が混ざった。キーが別の provider のもので、Settings → Models で選択中の provider と一致していない。あるいはキーが別の profile の設定に保存されていて、起動したプロファイルとずれている。その先では、ディスカッション #5794 が「画面の不一致」形を 2 件記録しています——Web UI と headless 実行は同じ保存済み認証情報を読んでいるとは限らず、片方だけが動く。さらに #3073 と #3222 は、provider アダプターが認証以外の失敗を API key is invalid として表面化させていた例を示します——エラー文だけではキーの不良と断定できません。

修正手順：

  1. 再試行の前にステータスコードを読む（第 10 セクションのトリアージ基準）：401 = キーそのものを拒否されたのでキーを直す。402 = 残高不足なので入金。403 = キーは有効だがそのモデル・地域の権限がないので、モデルかアカウントを変える。
  2. provider でキーを再発行し、空白や改行を混ぜずに貼り直す。そして Settings → Models で実際に選択している provider のキーであることを確認。
  3. 画面の不一致（#5794）：Web UI は動くのに dsh --profile headless が失敗する（またはその逆）なら、失敗している側が読む場所にキーを置きます——headless 実行は DEEPSEEK_API_KEY の環境変数かリポジトリールートの .env を読みます——そのうえで同じコマンドを再実行。
  4. キーが正しいことを確認したうえで、それでも画面をまたいでエラーが続くなら「誤分類の疑い」として扱います。エラー出力全体と dsh --version を取り、資格情報を再ローテーションする前に #3073/#3222 と突き合わせてください。
  5. プロキシーを通している？第 10 セクションのプロキシー形は、きれいな 401 ではなくハングやタイムアウトとして現れます。キーを疑う前にまずあちらで切り分けを。
  6. プロバイダー側でキーを誤削除し、dsh に新しいキーを設定できない？それは記録済みのギャップです（#8988。かつてクローズされた #7625 と同型）：デスクトップと Web UI には現状、保存済み認証情報を「更新」する、「削除して再設定」する入口がありません。つなぎとして：headless 実行は DEEPSEEK_API_KEY 環境変数から新しいキーを読めます（上のステップ 3 の経路）。Web/デスクトップには製品内リセットがまだなく、#8988 に事例を追加してスレッドをフォローしてください。ブランド付き検索 deepseek harness api key is invalid の着地点はこのセクションです。

17. Output token limit reached——上限は 2 種類あり、対処も 2 通り

症状：回答の途中で出力トークン上限のエラーで止まったり、長いターンが途切れたりする。検索される完全文は output token limit reached（未解決のディスカッション：#1166、#5970）。ブランド付きの検索形——deepseek harness token limit、deepseek harness output token limit——も同じ場所に着地します。関連だが別の失敗：圧縮の直後に CONTEXT_WINDOW_EXCEEDED が出るパターン。

原因：ここで混同される 2 つの上限があります。出力上限：すべてのモデル行には Max output tokens の値が付いており（カスタムモデル行のプレースホルダーは 32K）、1 回の返信がそれを超えると途切れます。コンテキスト上限：会話全体がウィンドウを使い切りそうになると、圧縮が履歴を折りたたむはずです——しかし #8498 は圧縮が空回りした末にセッションを CONTEXT_WINDOW_EXCEEDED と誤判定した例を、#8494 は大きな headroom 値の後に使用可能な余りが急減した例を記録しています。つまり「上限に達した」表示は、セッションが本当に大きいのではなく、圧縮機構の誤動作のことがあるのです。

修正手順：

  1. 制限するのはセッションではなく返信：Settings → Models でモデル行の Max output tokens を設定します（カスタムモデル行はこの欄を直接公開。プレースホルダーは 256K/32K。空欄なら provider の既定を継承）。長い回答を途中で切るモデルはここを引き上げます。
  2. セッションが本当に巨大化しているなら分割します：新しいセッションを開き、要約を持ち越す——コンテキスト圧縮ガイドで、dsh が履歴をどう折りたたむか、3 つの圧縮トリガーを解説しています。
  3. 圧縮の直後（または最中）に CONTEXT_WINDOW_EXCEEDED？それは #8498 の形です。dsh --version とセッションサイズを記録し、再起動して一度再試行、そのうえで診断情報を添えてディスカッションに報告を。
  4. 小さなタスクでも回答の途中で繰り返し切れるなら、それは dsh ではなく provider 側を指します。dsh 側の設定を変える前に、provider の利用状況ページで自分のプランの長さ・レート上限を確認してください。
  5. それでも再現する：dsh --version、起動コマンド、完全なエラー文を添えてディスカッション群（#1166、#5970）へ。この形はまさにそこで 1 件ずつ切り分けられています。

18. メモリ不足（OOM）——落ちるのはプロセスであってセッションではない

症状：Linux で dsh を実行していると、プロセスが途中で消えてターミナルには Killed の一言（または終了コード 137）。dsh web がしばらく動いた後に落ち、ログに OOM（Out of Memory）の記録が残ります。ユーザーがそのまま入力する語は dsh oom——まず 1 つ注意：検索結果を埋める DSH の医療・会計コンテンツ（Disproportionate Share Hospital、米国の医療保障制度の用語）はこのツールとは無関係です。実際の同類事例は GitHub ディスカッションにあります。

原因：OOM はOS レベルのメモリ枯渇です——dsh プロセス（またはそのコンテナ/cgroup）が上限を超えるメモリを要求し、カーネルがプロセスを kill します。セクション 17 の「上限」とは別物：コンテキストウィンドウの枯渇は CONTEXT_WINDOW_EXCEEDED のようなモデル側のエラーを返し、セッションは生きたままです。OOM はプロセスごと持っていきます。記録されている実例は 2 つ：npx でのその場実行で発生しやすい（GitHub 報告「Linux: OOM when running dsh via npx — use global install」、公式の対処はまさにグローバルインストールへの切り替え）、そして #8639 が記録した dsh web 常駐ケース——RSS がセッション数とともに増え、最後には 1GiB の cgroup 制限で OOM-kill されます。

修正手順：

  1. npx で長期実行しない：npm install -g @deepseek-ai/dsh でグローバル導入し、dsh で直接起動します。公式報告の処置そのもので、セクション 11 の command not found も同時に解消します。
  2. dsh web 常駐が落ちる（#8639 の形）：まず systemd/cgroup のユニットに 1GiB などのハード制限がないか確認——MemoryMax を引き上げるか解除し、RSS がセッション数に応じて増え続けるか観察します。メモリを食う使い方なら dsh web を定期的に再起動を。
  3. まず切り分け：エラー文に CONTEXT_WINDOW_EXCEEDED / token limit の文字 → セクション 17 とコンテキスト圧縮ガイドへ。Killed のみ＋dmesg に Out of memory: Killed process → このセクションの OOM です。
  4. コンテナや小さな VPS：dsh のコンテナに swap を追加するかメモリ上限を引き上げます。Web UI と複数セッションの同時実行なら 2GiB 以上の余裕を。
  5. それでも再現する：dsh --version、デプロイ形態（npx / グローバル / Docker / cgroup 制限値）、dmesg の該当行を添えてディスカッションへ——#8639 のスレッドがまさにこれらを収集しています。

19. デスクトップアプリが起動しない：9月末の起動障害ラッシュ

症状：2026 年 9 月末〜10 月初めの公式ディスカッションには、デスクトップ側の起動失敗が 4 形態で集中しています。Windows 11 で V8 スタートアップスナップショットの読み込みに失敗してアプリが落ちる（#8776）。管理者として起動すると exitCode 18 で終了する（#8787）。プラグイン id の競合でホストが 'prepare' is undefined でクラッシュし（#8822）、別のケースでは BOM 付きで保存された profile の package.json が壊れて resume 時に同じエラーが出る（#8837）。そしておなじみ 0xC0000142 が 3 件の報告として再発（#8771・#8772、背景の DACL capability SID 機構を #8775 が分析）。

形態ごとの原因と対処：

  1. V8 スナップショット読み込み失敗（#8776）：デスクトップバイナリのスナップショットが読み込めないパターン。更新の中断やインストール破損の後に起きがちです。古いインストールディレクトリを流用せず、新規ダウンロードで再インストールし、CLI 側の dsh --version でコア自体が正常かを確認してください。
  2. 管理者起動で exitCode 18（#8787）：昇格するとアプリが期待する環境（ユーザーディレクトリのリダイレクトや PATH）が変わります。まず通常ユーザーで起動してください。昇格が本当に必要なら、古いショートカットを右クリックではなく、昇格済みターミナルからクリーンな環境で起動します。
  3. 'prepare' is undefined（#8822・#8837）：ホスト側のクラッシュであり、プラグインサンドボックス内のエラーではありません。#8822 は 2 つのプラグインが id 競合して参照が空になったケース、#8837 は BOM 付き package.json で profile のパースが壊れ、resume 時に再発したケースです。原因のプラグインを外すか、ファイルを BOM なし UTF-8 で保存し直し、セッションを再開する前に一度コールドスタートしてください。10 月には 3 つ目の形も報告されています（#8924）：web profile がローカルの @deepseek-ai/dsh-tools コピーを持つ（ローカルプラグイン開発向けのデュアルパッケージ構成）と、テキストのみのターンは生き残る一方で、すべてのツール呼び出しが同じ reading 'prepare' エラーで落ちます——profile 内の重複コピーを外し、dsh-tools が 1 コピーだけに解決されるようにしてください。
  4. 0xC0000142 再発（#8771・#8772・#8775）：セクション 9・12 と同じ STATUS_DLL_INIT_FAILED 系の 3 度目の発生で、今回は中国語・英語双方で報告されました。#8775 の分析は子プロセスの DACL 内 capability SID を指しています。まずセクション 9 のワンクリック修復を実行してください——このファミリーに対する公式の対処法です。

20. アップグレード後に古いセッションが開かない：セッションフォーマットのコーデック

症状：新しい dsh に移行した後、これまで問題なく開けていたセッションが SessionFormatError 系のメッセージとともに開かなくなります。記録されているのは 2 形態です。v0→v1 コーデックは、0.1.0-rc.6 / 0.1.1-rc.2 が書き出したセッションを拒否します——subagent/descriptor イベントが version: 2 を持つのに対し、マイグレーションは version: 3 を要求するためです（#8868）。サブエージェントセッションを履歴に持つ環境は、このためにアップグレードがブロックされていました。v3→v4 コーデックは、system/message がログ全体の最初の surface ノードに来ていない合法なログを拒否します（#8888）。

原因：セッションログはバージョン付きで、各マイグレーションは厳格に検証します。v0→v1 はイベントバージョンを単一値に固定し、v3→v4 の foldSurface ガードは system/message が最初の surface ノードであることを仮定しました——両方の仮定が、旧リリースが正当に書き出したログを誤傷しています。

修正：

  1. まずエラーテキスト全文と dsh --version を記録します——どのマイグレーションが怒っているかで 2 形態を判別できます。
  2. アップグレード前は開けていたセッションなら、最速の実用路線は第 8 節のロールバックです：ログを書いたバージョンに dsh をピン留めし（npm install -g @deepseek-ai/dsh@<バージョン>）、セッションを開いて必要な内容をエクスポートします。
  3. 検証を通すためにセッションファイルを手で編集してはいけません——壊れた編集はログを恒久的に読めなくします。ファイルをバックアップし、エラーテキスト付きで #8868 / #8888 に報告を追加してください。フォローアップ修正はこの 2 つのスレッドに実装されます。

21. セキュリティ勧告：ローカルコントロールプレーン経由のサンドボックスエスケープ開示（#8887）

何が起きたか。公式ディスカッションの公開開示（#8887、重大度：high）は、dsh 自身のローカルコントロールプレーン 127.0.0.1:3080 から始まるチェーンを記述しています：任意のサンドボックス付きセッション内で 1 コマンド実行できるだけで（ファイルポリシーが read-only でも）、制限されたエージェントがサンドボックスを脱出して承認ポリシーを迂回し、承認プロンプトなしにあなたのユーザーとして任意のファイル書き込みができます。dsh 0.2.0-rc.2（Linux/WSL2）で検証済みで、報告者はプラットフォーム非依存としています。

今すぐやること：

  1. Web UI はデフォルトのループバック専用バインドのままにします——攻撃チェーンの起点は「127.0.0.1:3080 に届くすべて」なので、バインドを広げないのはもちろん、ポート 3080 を完全には信頼できないネットワークへトンネルしないでください（安全な公開の姿はリモートアクセスガイド参照）。
  2. 修正版が出るまでの間、「サンドボックス」は「強化であってセキュリティ境界ではない」と捉えます：重要なものを置いたマシンでは、サンドボックス付きセッションを信頼できないリポジトリや注入されやすいコンテンツに向けないでください。
  3. 修正が着地したらすぐ dsh を更新し、#8887 をフォローします——開示スレッドが公式対応と修正リリースの一次情報源です。

22. セキュリティ勧告：ルートが / のワークスペースはサンドボックスを無効化する（#9026）

何が起きたか。#8887 のコントロールプレーン脱出（第 21 セクション）から 3 週間、今度は 2 件目のサンドボックス開示です：ルートが / のセッションやワークスペースは、resolveWorkspaceRoot() の唯一の検査——isAbsolute()——を素通りして writableRoots() にそのまま流れ込み、書き込み可能集合が ['/', '/tmp', tmpdir()] になります。するとすべての強制系バックエンドがファイルシステム全体の読み書きを許します：bwrap は --bind / /、Landlock は RW ルールが読み取り専用ルールを上書きするため、sandbox-exec は / の書き込み可能プレフィックスによって。入口はどちらも未検証です：session.create({ cwd: '/' }) と workspace.create({ path: '/' })。

今すぐやること。

  1. 修正が着地するまで、ルートが / のセッションやワークスペースは絶対に実行しない——セッションを代わりに作るツールも監査してください。現時点ではこれが防御の全部です。
  2. 第 21 セクションの項目はすべて引き続き有効：Web UI はループバック専用、ポート 3080 のトンネル禁止、サンドボックスは境界ではなく強化と扱う。
  3. 修正が着地したら dsh を更新し、#9026 をフォローします——開示スレッドが公式対応の一次情報源です。

23. デスクトップ安定性の嵐：クラッシュループ、消えたプラグイン依存、Electron 44（2026 年 10 月）

症状。1 週間のうちに 4 つのデスクトップ形態が公式ディスカッションに集中しました：起動のたびに落ち、全プラグイン無効化でしか復帰できない（#8995）。デスクトップ更新後にあるプラグインだけが静かに死に、どこにもエラーが出ない（#9030）。ホストプロセスが 0xC0000409 で落ち、renderer が Electron 44 / Chromium 152 上で繰り返しクラッシュし（#8972）、renderer の OOM クラッシュを記録した姉妹報告（#8932）。そして 30 日間・100+ セッションの記録から、プラグイン読み込み・依存ツリー・セッションファイル・設定にまたがる 22 項目の再現可能な安定性リストを公開したパワーユーザー（#8951）。

形態ごとの原因と対処。

  1. 起動クラッシュループ（#8995）。サードパーティープラグイン内の未処理の rejection がホストの fail-loud ハンドラーで致命扱いされ、起動のたびに同じ失敗を繰り返します——記録された事例では 3 分で 6 回。自動セーフモードはまだないため、復旧は手動です：~/.dsh/cordis.patch.yml で疑わしいプラグインの enabled を false にする（またはファイルを退避させる）、再起動する、その後 1 本ずつ戻して元凶を特定します。
  2. 更新後のプラグインの静かな死（#9030）。記録された事例：デスクトップ更新がプラグインの実行時依存ディレクトリを消し去ったのに、パッケージマネージャーの状態ファイルは在籍したまま——中身だけがなく、どこにもエラーが出ません。更新後にプラグインのパネルだけが忽然と消えたら、再インストールしてください（dsh plugin remove + dsh plugin add、またはデスクトップのプラグインマネージャー）。依存関係が改めてインストールされます。
  3. 0.2.0-rc.2 での繰り返すホスト/renderer クラッシュ（#8972、#8932）。ホストは 0xC0000409 で終了し、renderer は Electron 44 / Chromium 152 で繰り返しクラッシュ、間隔は縮まる一方。姉妹報告は renderer の OOM クラッシュを記録しています。デスクトップが書き出す診断バンドルを添え、dsh --version を付けてスレッドに事例を追加してください——各形態は「頻度と、どのプロセスが死ぬか」で切り分けられています。
  4. 22 項目の安定性リスト（#8951）。30 日・100+ セッションの記録が、ほかより先に直すべき 3 つを挙げています：登録されても読み込まれもエラーも出さないプラグイン。マウント失敗がクライアント全体を道連れにする fail-closed。公式の検証/修復ツールがないセッションファイル——最後のものは第 20 セクションのコーデック領域です。デバッグの前に一読の価値あり：あなたの形態はすでに P-01 から P-22 のどれかかもしれません。

それでも解決しない場合

  • プラグインの安全なインストール —— インストール方法と CLI コマンド早見表
  • 設定ガイド —— bundle・profile・patch、どのレイヤーを編集しているのか
  • dsh CLIチートシート — コマンド・フラグ・起動モードを1ページにまとめた早見表
  • DeepSeek Harness の巻き戻し術 — dsh-undo-savepoint のスナップショットとクラッシュ復旧。再インストールの前にロールバックを
  • プラグインを登録する —— プラグインの README と実際の挙動が食い違う場合は、リポジトリに issue を開いてください。dsh --profile の起動コマンドとエラー全文を添えると解決が早くなります。自身が開発者なら README を修正してディレクトリに登録しましょう。
広告

DSH Plugins は DeepSeek Harness プラグインの独立したコミュニティ ディレクトリです。DeepSeek との提携・公認はありません。サードパーティ製プラグインはセキュリティ監査を受けていません。インストール前にソースコードをご確認ください。

DeepSeek Harnessの新着プラグインを毎週お届け。スパムはありません。