DeepSeek Harness Web UIが開かない時の診断手順

DeepSeek Harness Web UIが開かない場合、今週は再インストールを先に行わず、dsh web の終了状態とターミナルに表示された待受アドレスを確認し、その後にブラウザー、モデル認証、ワークスペース、操作承認の順で切り分けます。遠隔のMacでは、標準のローカル待受をそのまま外部へ公開せず、安全な接続経路を先に確認します。

この記事は、初回起動後にページへ接続できない個人開発者、モデルやワークスペースを選択できないAIエージェント開発者、遠隔Macの開発環境を管理する運用担当者向けです。インストール手順ではなく、起動後にどこで止まっているかを判定するための内容です。

最終更新：2026年8月18日。DeepSeek Harnessの公開README、CLI関連資料、DeepSeek APIのエラーコード・レート制限・モデル資料を確認しています。具体的な待受ポート、設定ファイルの場所、エラー文は、実行時の公式ドキュメントと端末ログを優先してください。

DeepSeek HarnessのWeb UIは、画面だけを見ていると「サービス全体が停止した」ように見えます。しかし実際には、コマンドが起動直後に終了した、待受はしているが別のアドレスを開いた、画面は表示できるがモデル認証で止まった、ワークスペースが未登録だった、操作承認を待っていた、という複数の状態を区別する必要があります。

公開されているREADMEでは、CLIとしてdshを導入し、Web UIを起動する流れが案内されています。まずはDeepSeek Harnessの公開READMEとCLI構成を確認し、現在のサブコマンド名とヘルプ表示が実行環境と一致しているかを見ます。(github.com)

dsh webを実行したあと、最初に確認するのはブラウザーではなく端末です。プロンプトがすぐ戻っているなら、Web UIは動作していません。反対に、端末が待機状態のままでアクセス先が表示されているなら、起動処理は少なくとも待受段階まで進んでいる可能性があります。

次の順番で確認します。

• dsh --helpでコマンド自体が認識されるか確認します。
• dsh web --helpで、現在の環境が受け付けるオプションを確認します。
• dsh web実行直後に表示されたURL、ホスト名、ポート番号をそのまま控えます。
• 端末にエラーが出ている場合は、最後の数行だけでなく、起動直後から終了まで保存します。
• ブラウザーには推測したURLではなく、端末に表示されたURLを入力します。
• 別のブラウザーを試す前に、同じMac上で表示されたアドレスへ接続できるか確認します。

待受ポートを推測して別の番号へ変更するのは、診断を複雑にします。ポート占用が疑われても、先にログに競合やバインド失敗が出ているかを確認し、設定を変更した場合は変更前後のログを分けて保存します。公開READMEにあるインストール方法と手元のCLIヘルプが食い違う場合は、古い実行ファイルがPATHの先に残っている可能性もあります。(github.com)

起動チェーンの確認リスト

• [ ] dshが実行可能である
• [ ] dsh web --helpがエラーなく表示される
• [ ] 起動後にプロセスが終了していない
• [ ] 端末に表示されたアクセス先を保存した
• [ ] 端末ログに待受失敗や設定読込失敗がない
• [ ] URLを手入力する際に、ホスト名とポートを変更していない

この段階の復旧基準は、画面の見た目ではありません。起動プロセスが維持され、端末に示されたアドレスへ同じMacから接続できることです。

ローカルMacで開けるアドレスと、別の端末から開けるアドレスは同じとは限りません。ローカル待受は、そのMac自身からの接続だけを想定している場合があるため、遠隔Macで起動したWeb UIを手元のブラウザーから開けないこと自体は、直ちにアプリケーションの故障を意味しません。

遠隔Macの安全な確認では、まず遠隔Mac内部でWeb UIが開くかを確認し、次に認証済みの遠隔接続経路を使って手元から表示します。SSHポート転送を使う場合も、実際の転送先ポートは端末ログと現在のCLI資料に合わせます。固定のポート番号を前提に設定ファイルを作るのは避けます。

外部から直接アクセスできる待受へ変更する場合は、認証、ファイアウォール、接続元制限、TLS、ログ管理を用意してからにします。DeepSeek Harnessの動作確認だけが目的なら、公開待受よりも限定された管理経路のほうが、API Keyやワークスペースを不用意に露出しにくい構成です。

遠隔Macの調達先を検討している場合は、JEXCLOUDのMac利用プランだけでなく、接続方式、管理権限、再起動後の復旧手順を先に確認します。Web UIの障害では、CPUやメモリのスペックよりも、誰が端末へ入り、どの経路でログを取得できるかが復旧時間を左右します。

画面が表示されているのにモデルが選べない場合、UIの問題とDeepSeek APIの認証問題を分けます。まずモデル選択欄が空なのか、モデル名は表示されるが送信時に失敗するのかを確認します。前者は設定読込やモデル一覧取得、後者は認証、残高、パラメーター、レート制限の可能性が高くなります。

DeepSeek APIの公式エラー資料では、401は認証失敗、402は残高不足、422はパラメーター不正、429はレート制限、500や503は提供側の障害または過負荷として整理されています。したがって「モデルが使えない」という表示だけでKeyを何度も作り直すのではなく、HTTPステータス、発生時刻、モデル名を保存します。(api-docs.deepseek.com)

モデル名やエンドポイントは、画面に表示された名称をそのまま信じず、DeepSeek APIのモデルと接続先に関する資料と照合します。モデル資料ではOpenAI互換形式の接続先、モデル名、コンテキスト長、同時実行制限などが管理されており、古い設定を残したままでは選択欄に表示されても要求時に失敗する場合があります。(api-docs.deepseek.com)

API Key確認の実作業

1. Web UIへ保存したKeyの末尾数文字だけを識別用に記録し、全文をログへ貼り付けないようにします。
2. 環境変数、UI設定、設定ファイルのどれを実際に参照しているか確認します。
3. APIの接続先が意図した提供元になっているか確認します。
4. モデルIDの大文字小文字、旧名称、余分な空白を確認します。
5. 複数要求を止め、単一の最小要求だけを実行します。
6. 401、402、422、429、500、503のどれに該当するかで復旧策を分けます。

レート制限はAPI Key単位だけでなく、アカウントやモデルの同時実行条件に関係するため、別Keyを作るだけでは解決しないことがあります。公式資料でも、制限を超える要求は429になると説明されています。(api-docs.deepseek.com)

DeepSeek Harnessの起動ディレクトリと、Web UIで選択するワークスペースは同じ意味とは限りません。起動した場所が初期のファイルシステム位置として使われても、UI側で利用するプロジェクトを追加・選択する操作が完了していなければ、入力欄や実行ボタンが無効になることがあります。

確認する順番は次のとおりです。

• [ ] 選択対象のディレクトリが実際に存在する
• [ ] 相対パスではなく、実行ノード上の絶対パスを確認した
• [ ] Web UIを起動したユーザーが読み取り権限を持つ
• [ ] ファイル一覧を表示できる
• [ ] リポジトリのルートを選択している
• [ ] 手元のMacではなく、遠隔Mac側のディレクトリを指定している
• [ ] パスに移動・改名・同期遅延がない

遠隔Macで特に多いのは、手元のMacで見えているパスを遠隔ノードにも存在すると考えてしまうことです。共有ボリューム、コンテナ内パス、ログインユーザーごとのホームディレクトリは、同じ文字列でも別の場所を指す場合があります。

ワークスペースの復旧基準は、単に選択欄が有効になることではありません。対象ディレクトリの一覧を読み取り、既存ファイルを変更しない確認用タスクを実行できる状態まで進めます。書き込み権限を広げる前に、まず読み取りと作業対象の一致を確認します。

タスクが進まないとき、画面のスピナーだけを見てプロセスを強制終了すると、セッション状態や未保存のログを失うことがあります。先に、操作承認を待っているのか、DeepSeek APIからの応答を待っているのか、制限やセッション異常なのかを分けます。

DeepSeek APIは、応答まで時間がかかる場合に接続を維持する仕組みを説明しています。そのため、一定時間画面が変化しないだけでは、直ちにプロセス停止とは判断できません。API資料では、長時間応答が始まらない場合の接続終了条件も示されています。(api-docs.deepseek.com)

最低限、次の情報を一組で保存します。

• 発生日時
• 実行した最小タスク
• 使用モデル
• セッション識別子
• 端末ログの該当箇所
• HTTPステータスとエラーコード
• 承認操作を行ったかどうか

ツール呼び出しを含む会話では、推論内容を次の要求へ正しく引き継げないと400エラーになる実装上の問題も報告されています。これはWeb UIの表示障害とは別の層なので、ページが開くか、モデル要求が送信されるか、複数ターンのツール処理で止まるかを分けて確認します。(github.com)

復旧後はいきなり本番リポジトリを編集せず、次の順番で受け入れ確認を行います。

1. Web UIを開き、ページの読み込みが完了することを確認します。
2. モデル選択欄に利用可能なモデルが表示されることを確認します。
3. API Keyを使った最小の読み取り要求を実行します。
4. ワークスペース内のファイル名だけを読み取るタスクを実行します。
5. 副作用のないコマンド、たとえばバージョン確認や作業ディレクトリ表示を承認します。
6. 新しいセッションを作成し、会話状態が分離されることを確認します。
7. Web UIを再起動し、必要な設定とワークスペースが再び読み込まれるか確認します。

再起動やアップグレードの前には、設定、ワークスペース登録情報、セッションを復元できる形で保存します。設定の場所がバージョンによって変わる可能性があるため、パスを決め打ちせず、CLIのヘルプと実際の設定出力を記録しておく方法が安全です。

次の条件に当てはまる場合は、再インストールよりも新しいセッションまたは検証済み環境への回退を選びます。

• 旧環境のログが残っており、原因を特定できていない
• API Keyとワークスペース設定を再利用できる
• 直前のアップグレード後から問題が発生した
• 本番リポジトリへの変更をまだ行っていない

一方、実行ファイルの所在が不明、依存関係が壊れている、設定をバックアップ済みで最小環境でも同じ失敗が再現する場合は、クリーン環境での再構成を検討します。

現在の自宅Macや共有の開発環境で運用している場合、端末がスリープする、遠隔接続の経路が変わる、ログインユーザーと実行ユーザーが一致しない、設定を手作業で戻せない、といった弱点が残りやすくなります。短期間の検証や障害再現であれば、JEXCLOUDのMac環境を使い、起動ログ、接続経路、設定のバックアップ、復旧後の確認結果を一つの記録として残すほうが、次回のアップグレードで「また最初から再インストールする」状態を避けやすくなります。

ただし、長期の固定負荷、物理USB機器への常時アクセス、社内ネットワーク内だけで完結する厳格な要件には、自社管理のMacや専用環境が適する場合もあります。臨時のDeepSeek Harness検証、遠隔Macでの再現試験、AIエージェント環境の受け入れ確認が目的なら、JEXCLOUDのMacレンタル環境を比較対象に加え、料金だけでなく復旧記録と接続管理まで確認するのが現実的です。