DeepSeek Harness のインストールと初回起動：npx・グローバル・ソースビルド — AI開発チュートリアル

DeepSeek Harness を実際に使い始める前のインストール手順は、一見単純に見えますが、実は多くの分岐点が隠れています。3分以内に Web インターフェースを見たいのか、ソースコードを読んで Plugin を書きたいのか、それとも自分の Python プログラムから Agent を呼び出したいのか。この3つの経路は、それぞれまったく異なる前提条件と成果物に対応しており、方向を間違えると Node のバージョン、pnpm の欠如、あるいはエントリコマンドが見つからないといったところで詰まりがちです。この記事では、1つの表、いくつかのセルフチェックコマンド、そして貼り付け可能な実践コードを使って、npx ですぐ使える、グローバルインストール、ソースビルドという3つの方法を徹底的に解説し、ついでに Python SDK のインストール経路も視野に入れます。前半を読み終えれば、自分がどの道を進むべきかが明確になり、最初にどのコマンドを打てばよいかも分かるはずです。

インストール前にまず通す3つのセルフチェックコマンド：node -v、git --version、Python 3.10+

DeepSeek Harness のランタイムは Node.js の上に成り立っているため、ほとんどのインストール経路は Node 環境を避けて通れません。ただし、3つの方法で前提依存の要件は同じではありません。npm のワンクリックインストールは Node 本体だけで済み、公式推奨のすぐ使える経路です。ソース方式では追加で Git と pnpm が必要です。Python SDK はシステムに Node を用意する必要がまったくありません。独自のランタイムを同梱しているからです。これらの違いを着手前に把握していないと、「コマンドは打ったのにエラーが出て、何が足りないのか分からない」という状況に陥りやすくなります。

したがって最初のステップは、急いでインストールすることではなく、環境のセルフチェックです。まず最初に、Node が存在し、バージョンが十分に新しいことを確認します。ターミナルで node -v を実行し、v22.23.1 のようなバージョン番号が出力されれば、Node は準備できています。command not found と表示された場合は、まず Node 公式サイトからインストールする必要があります。素材で示されている経験値は v20+、つまり Node のメジャーバージョンが少なくとも 20 であることです。リポジトリの package.json には独自の engines 宣言もあり、ビルド段階ではバージョン要件がより厳しくなることが多いため、バージョンは高いほど安心です。

2つ目は Git の確認です。ソースインストールではこの手順が必須です。リポジトリのクローン自体が Git に依存しているからです。git --version を実行し、git version 2.x のような情報が表示されれば問題ありません。Git は npm のワンクリックインストール経路では任意ですが、手元にあると、後でソース方式に切り替えたいときにずっとスムーズになります。3つ目は Python バージョンの確認で、Python SDK の道を進む場合にのみ必要です。最低ラインは Python 3.10 以上です。python -m venv --help で venv モジュールの有無を確認したり、直接 python --version でバージョン番号を見たりできます。3.10 未満のバージョンでは、その後の仮想環境作成や SDK インストールで問題が起きる可能性があります。

ツールチェーン以外にも、3つの方法すべてに共通して必要な前提が1つあります。DeepSeek API キーです。これは起動後のモデルルーティング設定に使われ、OpenAI 互換のエンドポイントもサポートします。キー自体はインストール過程には関与しませんが、これがなければ、インストールに成功して Web UI が開いても、Agent を実際に動かすことはできません。オペレーティングシステムについては、Linux、macOS、Windows のいずれも対応しています。Python SDK はプラットフォーム要件がやや狭く、Linux x64 / arm64 と macOS 14+（arm64）をサポートします。

これらの前提条件を対照チェックリストに整理しておくと、着手前に自分に何が足りないかを判断するのに役立ちます：

npm ワンクリックインストール：Node.js が必須；Git は任意；pnpm は不要；Python は不要；API Key が必要。
ソースからのインストール：Node.js が必須；Git が必須；pnpm が必須；Python は不要；API Key が必要。
Python SDK：システムの Node は不要（SDK がランタイムを同梱）；Git が必須；pnpm は不要；Python 3.10+ が必須；API Key が必要。

ここに、見落とされがちなエンジニアリング上の細かい点があります。pnpm がプリインストールされていない場合は、npm install -g pnpm という 1 コマンドで補えます。npm 自体は Node と一緒にインストールされるため、「Node だけがある」状態から「ソースビルドができる」状態までの差は、この 1 ステップだけです。もう 1 つの細かい点は、ネットワークが制限された環境でのミラー設定です。npm も pnpm も、ミラーソースを使えばパッケージ取得が遅い問題を解決できます。これについては後半のトラブルシューティングの部分で再度触れます。

示意图 — 3 つのインストール方法の前提依存をセルフチェックする流れ。まず Node、Git、Python のバージョンを確認してから、どの道を進むかを決めます

3 つのインストール方法の成果物の違いを 1 つの表で理解する：Web UI、ビルド成果物、deepseek_harness パッケージ

インストール方法を選ぶことは、本質的には「最終的に何を得たいか」を選ぶことです。同じ DeepSeek Harness のインストールでも、npm ワンクリックインストールの終着点はブラウザで動く Web UI です。ソースからのインストールの終着点は、ローカルリポジトリと完全なビルド成果物です。Python SDK の終着点は、プログラム内で import できる deepseek_harness パッケージです。3 つは競合関係ではなく、まったく異なる 3 つの利用目的に向けたものです。

まず npm ワンクリックインストールを見てみましょう。これは、ほとんどのユーザー、つまり手早く Web UI を試したいだけの人を対象にしています。インストール後の成果物は非常に直接的です。Web インターフェースを起動し、デフォルトのアドレスは http://127.0.0.1:3080 です。TypeScript のエントリがどこにあるか、フロントエンドの成果物がどうバンドルされるかを気にする必要はありません。dsh がそれらすべてを舞台裏に隠してくれます。DeepSeek Harness に初めて触れ、それが何をできるのか見てみたいだけの人にとって、これは最も抵抗の少ない道です。

次にソースからのインストールです。その対象は明確に開発者です。プラグインを開発したい、ソースコードを読みたい、コントリビュートしたいという人たちです。成果物は、クローンしたローカルリポジトリと、pnpm run build で生成される完全なビルド成果物です。ソース方式には他にはない能力もあります。pnpm dsh で TypeScript エントリを直接実行でき、先に JavaScript にコンパイルしてから実行する必要がありません。つまり、ソースを変更したらすぐに動作を検証でき、特にプラグインのデバッグではこれが重要です。

最後に Python SDK です。これは、自分の Python プログラム内で Agent を呼び出したいというシナリオに応えるものです。deepseek_harness パッケージを生成し、さらにランタイムを同梱しているため、システムにインストールされた Node に依存しません。この点は、多くのデータサイエンスやバックエンドチームのマシンにとって重要です。彼らは 1 つの Agent のために Node 環境を維持したいとは限りませんが、SDK がランタイムを同梱することで、依存関係の問題を内部で吸収していることになります。代償は、サポートされるプラットフォームの範囲が狭まることです。Linux x64 / arm64 または macOS 14+（arm64）が必要です。

これら3つのパスを同じ表で比較すると、選択が一目瞭然になります：

比較軸	npm ワンクリックインストール（推奨）	ソースインストール（開発）	Python SDK（プログラム的）
対象者	ほとんどのユーザーで、Web UI を最速で体験したい人	プラグインを開発したい、ソースコードを読みたい、コントリビュートしたい人	自分の Python プログラムから Agent を呼び出したい人
主要な前提依存	Node.js（Git は任意）	Node.js + Git + pnpm	Python 3.10+、Git
システム Node が必要か	必要	必要	不要。SDK にランタイムが同梱
最終的な成果物	Web UI を起動、デフォルトは http://127.0.0.1:3080	ローカルリポジトリ + 完全なビルド成果物、pnpm dsh で TypeScript エントリを直接実行可能	deepseek_harness パッケージ + 内蔵ランタイム
典型的なコマンド	npx @deepseek-ai/dsh web または dsh web	pnpm dsh web	python -m pip install deepseek-harness-sdk
その後の拡張方向	モデルの設定、ワークスペースの選択、タスクの実行	プラグインの作成、完全な設定ツリーの確認、開発への参加	Python コード内で import して呼び出し

この表を読む際に押さえるべき判断基準は1つです：DeepSeek Harness 自体を変更する必要があるかどうか。答えが「不要」で、使えるインターフェースが欲しいだけなら、npm ワンクリックインストールで十分です。コードを変更したり、プラグインを書いたり、設定の詳細を確認したりする必要があるなら、ソースインストールを選ぶ必要があります。ホスト環境が Python プログラムで Node を導入したくないなら、SDK を選びます。これら3つのパスは互いに切り離されたものではありません——まず npm 方式で製品への直感を養い、その後必要に応じてソース方式に切り替える、というのが多くの開発者が実際にたどる道です。

npx @deepseek-ai/dsh web クイック体験：初回実行時に web 設定テンプレートが自動初期化される仕組み

グローバル環境を汚さずに DeepSeek Harness をちょっと覗いてみたいなら、npx が最も手軽な入口です。これは本質的に「一時的にダウンロードして実行する」もので、事前にグローバルインストールするパッケージはありません。コマンド全体は次の1行だけです：

npx @deepseek-ai/dsh web

このコマンドを実行すると、npx は @deepseek-ai/dsh パッケージを解決し、ローカルキャッシュに取得して実行します。引数の web は Web インターフェースを起動することを指定します。ここでの最初の重要な挙動は：初回実行時に web 設定テンプレートが自動的に初期化されることです。つまり、事前に手動で設定ファイルを作成する必要はなく、dsh が web profile に必要な設定の骨組みを用意してくれるので、その後のモデル設定やワークスペース選択に落とし込む場所ができます。

2つ目の重要な挙動は、ターミナルにアクセス用アドレスを表示することです。デフォルトは http://127.0.0.1:3080 です。このアドレスは 127.0.0.1 にバインドされている点に注意してください。つまりローカルマシンからのみアクセス可能であり、開発期間中のセキュリティとしては妥当なデフォルト値です。もしポート 3080 が他のプログラムに占有されている場合は、別のポートで起動できます。たとえば引数を --port 8080 に変更します。ただし、起動引数はアプリケーション引数より前に置く必要があり、この点は後述の profile の説明で改めて展開します。

成功したかどうかを確認する方法は直感的です。ターミナルに表示されたアドレスを開き、DeepSeek Harness の Web インターフェースが見えれば、インストールと起動の一連の流れが通っていることになります。ただし、ここには初心者がよくハマる落とし穴があります。新しい Web UI はワークスペースを追加する前は、どのワークスペースも選択されていません。そのため、インターフェースは「利用不可」のように見えます。これはインストールの失敗ではなく正常な状態であり、次のステップでワークスペースを設定すれば再び利用可能になります。

また、事前に覚えておく価値のある小さなヒントがあります。dsh は呼び出しディレクトリをデフォルトのファイルシステム位置として扱います。つまり、npx コマンドを実行したときにいるディレクトリが、デフォルトのファイルシステム位置と見なされます。したがって、より賢い方法は、まずプロジェクトディレクトリに cd してから npx @deepseek-ai/dsh web を実行することです。こうすれば、後でワークスペースを選択するときに最も便利で、遠く離れたパスを手動で追加する必要がありません。

以下では、npx によるクイック体験の完全な流れを、そのままコピーできる操作シーケンスに圧縮します。ディレクトリの切り替え、起動、およびポート競合時の代替記述を含みます。

# 1. まず Node 環境を確認
node -v
# v22.23.1 のような出力が期待されます

# 2. プロジェクトディレクトリに入る（この手順により dsh は現在のディレクトリをデフォルトのファイルシステム位置として扱います）
cd ~/projects/my-app

# 3. インストール不要のクイック体験。初回実行時は web 設定テンプレートが自動的に初期化されます
npx @deepseek-ai/dsh web
# ターミナルにデフォルトのアクセス用アドレスが表示されます: http://127.0.0.1:3080

# 4. ポート 3080 が占有されている場合は、別のポートで起動
npx @deepseek-ai/dsh web --port 8080

補足しておくと、npx 方式は便利ですが一時的なものです。実行のたびにパッケージを解決して取得する可能性があり、頻繁に起動する人にとってはグローバルインストールほど安定していません。最も適しているのは「長期的に使うかまだ決めていないので、まず動かして見てみたい」という場面です。継続的に使うと確認できたら、次に説明するグローバルインストールを検討すべきです。

npm install -g @deepseek-ai/dsh によるグローバルインストール後、dsh web と npx 方式の使い分け

DeepSeek Harness を長期的に使うと決めたなら、グローバルインストールは npx では得られないものを提供します。それは安定して使える dsh コマンドです。インストールコマンドはたった1行です。

npm install -g @deepseek-ai/dsh

ここでの -g はグローバルインストールを意味し、パッケージはグローバルの node_modules ディレクトリに配置され、対応する実行ファイルはシステムの PATH にリンクされます。インストール完了後は、npx プレフィックスは不要になり、直接 dsh web と入力すれば Web インターフェースを起動できます。挙動としては、dsh web と npx @deepseek-ai/dsh web は等価であり、どちらも Web UI を起動します。違いは、前者はローカルにインストール済みのバージョンを再利用し、後者は毎回リモートパッケージを解決する可能性があることです。

この等価関係は、移行コストがほぼゼロであることを意味します。これまで npx で試してきたすべての引数は、dsh プレフィックスに置き換えてもそのまま使えます。たとえば dsh --profile web --port 8080 はポートを変えて起動する書き方です。コマンド構造を理解しておくとトラブルシューティングに非常に役立ちます——dsh 自身の起動引数は前に、アプリケーション側の引数は後ろに置きます。--profile web は dsh の profile 選択に属し、--port 8080 こそが Web アプリケーション自身の引数です。順序を逆に書くと、引数が誤った階層で解釈され、「設定したはずなのに効いていない」という混乱が生じる可能性があります。

では、どのような場面で npx を使い続けるべきで、どのような場面でグローバルインストールすべきでしょうか。次のように分けられます:

npx を使う場面: 初めて試すとき、他人のマシンで一時的に動かすとき、グローバルにインストールの痕跡を一切残したくないとき、ある引数の効果だけを検証したいとき。
グローバルインストールを使う場面: 日常開発の主力として使うとき、スクリプトを書いたり CI で繰り返し呼び出したりする必要があるとき、すでに検証済みの特定バージョンを固定したいとき、dsh のサブコマンド体系を使いたいとき(たとえば設定の確認やプラグインの管理)。

グローバルインストールにはもう一つ隠れた利点があります。コマンド名が長いパッケージ名から dsh に短縮されるため、複数のサブコマンドを組み合わせる必要があるときに、入力の負担が大幅に軽減されます。よく使うサブコマンドには、headless profile でタスクを一度に実行するもの、--dump-config で完全な設定ツリーを確認するもの、plugin サブコマンドで特定の profile のプラグインを管理するものなどがあります。これらは後述のソースコード方式のセクションで具体的に展開しますが、たとえ npm のワンクリックインストールの道を選んだとしても、dsh というプレフィックスさえ覚えておけば、いつでも呼び出せます。

起動ディレクトリがデフォルトのファイルシステム位置になる: コマンド実行前にまずプロジェクトディレクトリへ cd することが推奨される理由

これはインストール工程の中で最も軽視されやすい一方、その後の使用で繰り返し実感されるルールです: dsh は呼び出しディレクトリをデフォルトのファイルシステム位置とします。言い換えれば、どのディレクトリで起動コマンドを打ったか、そのディレクトリがその後のワークスペースのデフォルト候補になります。ランダムに選ばれるわけでもなく、ユーザーのホームディレクトリに固定されるわけでもなく、コマンドを実行したときのカレントワーキングディレクトリに厳密に従います。

このルールを理解すれば、「なぜ自分の Agent が自分のファイルを見られないのか」という多くの問題はすぐに解決します。仮にユーザーのホームディレクトリで直接 npx @deepseek-ai/dsh web を実行すると、デフォルトのファイルシステム位置はホームディレクトリになります。その後 Web UI でワークスペースを選択するとき、実際に追加する必要があるのはあなたのプロジェクトディレクトリです。逆に、先に cd ~/projects/my-app を実行してから dsh を起動すれば、呼び出しディレクトリは my-app になり、その後ワークスペースを選択するときにそれが最も手に取りやすい位置に現れ、ほとんど追加操作は不要です。

このルールのエンジニアリング上の価値は、「設定作業を一回分減らし、エラーの確率を下げる」ことにあります。ワークスペースという概念は DeepSeek Harness において実際の権限上の意味を持ち、権限ポリシーはワークスペースを中心に、Agent がアクセスできるファイルの範囲を画定します。最初からワークスペースを正しく選んでおけば、その後の読み書きやコマンド実行はすべて想定範囲内に収まります。誤って選ぶと、agent がワークスペース外のファイルにアクセスしようとしてブロックされる状況に遭遇するかもしれません。したがって、「まず cd、それから起動」を習慣的な動作とすることをお勧めします。

もう一点、早めに整えておく価値があることがあります。それは、プロジェクトを置くための専用ディレクトリをできるだけ早く作成することです。素材で示されている方法は、新しい DeepSeekProjects ディレクトリを作業領域として作成するというものです。これは必須ではありませんが、「どのディレクトリが Agent 用なのか」ということがファイルシステムのレベルで明確になり、Agent があなたのホームディレクトリをあちこち探し回るのを避けられます。まずこれを作成し、その中に cd してから起動するとよいでしょう：

# Agent 専用のプロジェクトディレクトリを作成する
mkdir -p ~/DeepSeekProjects

# その中に入り、dsh にそれをデフォルトのファイルシステム位置として扱わせる
cd ~/DeepSeekProjects

# 以降は npx でもグローバルの dsh でも、起動ディレクトリはすでに正しい
npx @deepseek-ai/dsh web
# または：dsh web

ここで「ディレクトリがデフォルト位置を決める」という連鎖的な影響を少し整理しておきましょう。起動ディレクトリがデフォルトのファイルシステム位置を決め、デフォルトのファイルシステム位置がワークスペース選択の便利さを決め、ワークスペースがさらに権限境界内で Agent が何をできるかを決めます。この3つのステップは密接に連動しているため、cd のステップを前倒しすることが最もコストの低い最適化です。

ソースからのインストールは4ステップ：git clone、pnpm install、pnpm run build、pnpm dsh web

「利用者」から「開発者」へと役割を移すと、ソースからのインストールは避けて通れない道になります。これは、プラグインを開発したい人、ソースコードを読みたい人、あるいはコントリビュートしたい人に適しています。全体の流れは、順番に実行する4つのステップにまとめられます。リポジトリをクローンし、依存関係をインストールし、成果物をビルドし、ソース方式で起動する、という流れです。順番は入れ替えられません。特にビルドは起動より前に行う必要があります。そうでなければ、本番運用に必要なパッケージやフロントエンド成果物が欠けてしまいます。

最初のステップはリポジトリのクローンで、対象アドレスは https://github.com/deepseek-ai/deepseek-harness.git です。クローンが完了したらリポジトリのディレクトリに入ります。この時点で完全なソースツリーを取得できます。2つ目のステップは依存関係のインストールで、コマンドは pnpm install です。このステップは pnpm に依存しています。まだマシンに入っていない場合は、先に npm install -g pnpm を実行してインストールできます。このプロジェクトにおける pnpm の役割は単なる「より高速なパッケージマネージャー」にとどまりません。profile ディレクトリ配下のプラグイン管理も担っているため、ソースの経路ではほぼ切り離せません。

3つ目のステップはビルドで、コマンドは pnpm run build です。このステップはパッケージとフロントエンド成果物の両方をビルドする役割を担っており、公式のコメントには「本番運用に必要」と明記されています。つまり、ビルドを飛ばして直接起動すると、完全な実行成果物が得られず、フロントエンドページが読み込めなかったり、一部のパッケージが正しくコンパイルされなかったりする可能性があります。ビルドを「ソースコードを本番運用できる形に翻訳すること」と理解すれば、余計なことだとは思わなくなるでしょう。4つ目のステップは起動で、コマンドは pnpm dsh web です。ここではグローバルの dsh ではなく pnpm dsh を使っている点に注意してください。これはリポジトリ内の TypeScript エントリポイントを通るもので、ソースコードを先にグローバルコマンドへコンパイルする必要はありません。まさにこれがソース方式の便利さです。

4つのステップをコピー可能な一連のコマンドにまとめると、次のようになります：

# 1. リポジトリをクローン
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 依存関係をインストール（pnpm が必要。npm install -g pnpm でインストール可能）
pnpm install

# 3. パッケージとフロントエンド成果物をビルド（本番運用に必要）
pnpm run build

# 4. ソース方式で Web UI を起動
pnpm dsh web

ソースからのインストールで最もよくある失敗点はビルド段階です。素材が示すトラブルシューティングの方向性は三つあります。pnpm がインストールされていることを確認する。ネットワークが制限されている場合は npm / pnpm にミラーソースを設定する。そして、Node.js のバージョンがリポジトリの package.json の engines で宣言された要件を満たしていることを確認する、です。特に三つ目は注目に値します。多くのビルドエラーの根本原因はコードの問題ではなく、Node のバージョンが低すぎるために一部の構文やツールチェーンが動作しないことです。したがって、前述の node -v でバージョン番号が表示されていても、engines の宣言と照らし合わせて十分に新しいかを確認する必要があります。

また、「ソースからのインストール」と「ソースからの実行」という二つの概念を区別する必要があります。インストール段階で生成されるのはローカルリポジトリとビルド成果物です。実行段階では異なる profile を選択でき、たとえば pnpm dsh web で Web UI を起動したり、後述の headless profile で単発タスクを実行したりできます。同じソースコードで複数の起動形態を支えられることが、ソース方式が npm のワンクリックインストールより柔軟な点でもあります。

ソース方式の二つの隠れた入口：pnpm dsh --profile headless と --dump-config

ソースからの実行では、pnpm dsh web という主入口のほかに、よく見落とされながら非常に便利な二つの入口があります。それらはそれぞれ二種類の問題を解決します。一つは「Agent にタスクを一度実行させて、そのまま答えを得たい」というもの、もう一つは「今回の起動で実際にどの設定が読み込まれたのかを知りたい」というものです。プラグイン開発者にとって、後者はほぼ日常的に必須です。

一つ目の入口は pnpm dsh --profile headless "run the tests" です。この profile の動作は、一つのタスクを一度実行し、最終的な答えを出力して終了するというものです。常駐する Web サーバーを起動しないため、スクリプトや CI フローに組み込むのに適しています。引用符の中身がタスクの説明で、任意の指示に置き換えられます。Web UI の対話型セッションと比べて、headless モードは「コマンドラインの中の Agent」に近く、出力はクリーンで終了も明確であり、手動で閉じる必要のあるサービスプロセスを残しません。

二つ目の入口は pnpm dsh --profile web --dump-config です。その役割は、実際に起動される完全な設定ツリーを確認することであり、しかもサーバーを起動しません。これがプラグイン開発にとって重要なのは、プラグインは最終的に設定ツリー内のプラグイン項目によって読み込まれるため、設定ツリーがどのようなものかを把握して初めて、自分のプラグインがどの層にぶら下がり、どのパラメータを受け取るのかが分かるからです。これと対になる --dump-default-config もあり、デフォルトの設定ツリー、つまりユーザーの patch を含まないバージョンを確認するために使います。両者を比較すれば、ユーザーの上書き操作が具体的に何を変えたのかが分かります。

この二つの入口を一つのコマンドリストにまとめておくと、対照して使いやすくなります。

# タスクを一度実行して最終的な答えを出力（スクリプト / CI に適する）
pnpm dsh --profile headless "run the tests"

# 実際に起動される完全な設定ツリーを確認（サーバーを起動せず、プラグイン開発でよく使う）
pnpm dsh --profile web --dump-config

# デフォルトの設定ツリー（ユーザー patch を含まない）を確認し、上のコマンドと対照する
dsh --profile web --dump-default-config

ここでは profile の初期化ルールを補足する必要があります。web と headless の 2 つの profile は、初回使用時に組み込みテンプレートから自動的に初期化されます。つまり、手動で作成しなくてもそのまま使えます。それ以外の profile は dsh plugin サブコマンドで作成する必要があります。このルールは、上記の 2 つのコマンドがすぐに使える理由を説明しています。一方、カスタムの profile 名を試す場合は、まず作成を求められることがあります。

もう一度、引数の順序について強調します。dsh の起動引数が先で、アプリケーション引数が後です。pnpm dsh --profile web --port 8080 では、--profile web は dsh に対するもので、--port は Web アプリケーションに対するものです。同様に、--dump-config は dsh レベルのスイッチであり、profile の後、アプリケーション引数の前に置くのが最も安全です。このレイヤリングを理解すれば、コマンドの書き方で間違えにくくなります。

Python SDK のインストール経路：venv 分離 + pip install deepseek-harness-sdk の同梱ランタイム

DeepSeek Harness をブラウザ経由で操作するのではなく、自分の Python プログラム内で動かしたい場合、Python SDK がその道です。その前提条件は前述の 2 つとは明らかに異なります。Python 3.10+ が必要で、Git も必要です。さらに、DeepSeek 互換の API エンドポイントと認証情報、そして agent が変更可能な分離された workspace も必要です。最後の点に注意してください。Agent はワークスペース内でファイルの読み書きやコマンドの実行を行うため、分離されたディレクトリを与えることは良いセキュリティ習慣です。

インストール経路の最初のステップは、仮想環境を作成して有効化することです。仮想環境の意義は、SDK とその依存関係をシステム Python から分離し、バージョン競合を避けることにあります。作成コマンドは python -m venv .venv、Unix 系システムでの有効化コマンドは . .venv/bin/activate です。有効化後、以降の pip インストールはこの分離環境に配置されます。2 番目のステップは SDK 自体のインストールで、コマンドは python -m pip install deepseek-harness-sdk です。このパッケージの特別な点は同梱ランタイムであり、通常はシステムに Node を用意する必要はありません。実行時にランタイムが見つからないエラーが出る場合は、通常、インストールされたパッケージが不完全であることを意味するので、インストールコマンドをもう一度実行すれば解決します。

インストールと認証情報の設定の完全な流れは、以下のブロックをそのままコピーできます。

# 1. リポジトリをクローン（SDK 関連のサンプルもリポジトリに含まれています）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 2. 仮想環境を作成して有効化（Python 3.10+ が必要）
python -m venv .venv
. .venv/bin/activate

# 3. SDK をインストール（同梱ランタイム、システム Node は不要）
python -m pip install deepseek-harness-sdk

# 4. 認証情報を設定
export DEEPSEEK_API_KEY=sk-your-key-here

# モデルがデフォルトの DeepSeek エンドポイントではなく、OpenAI 互換プロキシの場合は、次も設定する必要があります：
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash

資格情報の部分には、分けて見る価値のある三層の情報があります。第一層は DEEPSEEK_API_KEY で、これは必須項目であり、形式は sk- で始まります。第二層は DEEPSEEK_BASE_URL で、これはデフォルトの DeepSeek エンドポイントを使わず、OpenAI 互換プロキシを経由する場合にのみ必要で、値の例は http://127.0.0.1:8000/v1 です。第三層は DSH_MODEL で、モデル名を指定するために使い、値の例は deepseek-v4-flash です。この三者の関係は、API Key が呼び出しの資格があるかどうかを決め、Base URL が呼び出しをどこへ送るかを決め、モデル名が実際にどのモデルを使うかを決める、というものです。

呼び出しの起点は from deepseek_harness import DeepSeekHarness です。この一行の import が SDK 全体の入口です。素材では、リポジトリに組み込まれている examples/jsonrpc-agent/minimal.py は SDK 呼び出しの軽量ラッパーであり、そのまま参考にできると述べられています。実行すると assistant の最終応答が出力され、同時にセッションディレクトリにはモデルリクエストとツール呼び出しを含む JSONL ログが届きます。この JSONL ログという点は重要です。つまり、呼び出しごとに構造化された記録が残り、Agent の挙動をデバッグするときに勘に頼る必要がありません。

SDK の経路と前述の二つの経路を素早く対照すると、その位置づけがより明確になります。

npm 経路との共通点：どちらも同じ一套の Agent 能力を駆動でき、どちらも API キーが必要です。
npm 経路との相違点：SDK は Web UI を提供せず、入口はブラウザではなく Python コードです。
ソースコード経路との共通点：どちらも Git でリポジトリを取得する必要があり、どちらもリポジトリ内のサンプルコードを参考にできます。
ソースコード経路との相違点：SDK はランタイムを同梱しておりシステム Node は不要ですが、ソースコード方式は Node と pnpm に強く依存します。

プラットフォームの制限についてもう一度注意を促します。Python SDK が対応するのは Linux x64 / arm64 と macOS 14+（arm64） です。対象マシンが別のプラットフォームの組み合わせである場合、npm またはソースコード経路に切り替え、別の方法で連携する必要があるかもしれません。この制限は SDK に同梱されたランタイムに由来するもので、Python 言語そのものによるものではないため、Python のバージョンを上げても回避できません。

ここまでで、三つのインストール経路の地図が広がりました。npx はゼロコストのお試しを担い、グローバルインストールは長期的に使える dsh コマンドをもたらし、ソースコードビルドはプラグインとデバッグへの扉を開き、Python SDK は Agent 能力をあなたのプログラムに組み込みます。各節では実行可能なコマンドと判断基準を示しており、まず自分の目標に合った一本を選んで、最初の Web UI または最初の import を動かすことができます。環境確認、成果物の選択、起動ディレクトリといった事前作業が完了した後、本当の作業はようやく始まったばかりです。次の部分では、インストール後の最初の起動と設定に進みます。モデルルーティングの記入方法、ワークスペースの選び方、四つの実行モードと三段階の権限がそれぞれどのような場面で使われるのか、そしてブラウザが開かない、セッションの入力欄が使えないといった典型的な問題のトラブルシューティング方法を扱います。

前回は、npx での一時試用、npm グローバルインストール、ソースからのビルドという 3 つのインストール経路について、それぞれのトレードオフと手順を整理し、Node.js、pnpm、Git、Python といった前提条件がそれぞれどの方式に対応するのかも確認しました。ここまででプロセスは起動できるようになりましたが、実際に体験の良し悪しを決めるのは、認証情報をどう渡すか、モデルをどう設定するか、権限をどう絞るかという 3 点です。本節では、初回起動の一連の流れに沿って、環境変数、Web UI での 3 ステップ設定、実行モード、権限ティア、プロバイダの追加、そして 2026 年 9 月時点で最新の settings.yaml における視覚モダリティ宣言まで、すべてコピー＆ペーストで実行できる操作に落とし込みます。

認証情報の三点セット：DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DSH_MODEL の設定順序

DeepSeek Harness のモデルルーティングプラグインは、起動時に 1 つのことを行う必要があります。それは「どこに問い合わせるか、どの身元で問い合わせるか、どのモデルに問い合わせるか」を知ることです。この 3 つの問いの答えは、それぞれ 3 つの環境変数に対応します。DEEPSEEK_API_KEY は身元の認証情報であり必須です。DEEPSEEK_BASE_URL はエンドポイントアドレスで、DeepSeek 公式エンドポイントを使わない場合にのみ補う必要があります。DSH_MODEL はデフォルトのモデル名で、同様に自前のゲートウェイやプロキシを経由し、デフォルト以外のモデルを指定する必要がある場合にのみ関係します。

したがって、設定順序には非常に実用的な原則があります。まず API キーだけを入力し、うまくいかない場合に残りの 2 つを追加する。DeepSeek 公式エンドポイントをそのまま使うなら、キー以外は一切気にする必要はありません。dsh に内蔵されたカタログがエンドポイントアドレスと利用可能なモデルをすでに把握しているため、ルーティングはすぐに使えます。リクエストを社内ゲートウェイ、ローカルの vLLM、One-API などの OpenAI 互換プロキシに向ける場合にのみ、baseURL とモデル名を明示的に補う必要があります。この場合、dsh はエンドポイントがどこにあり、モデルが何と呼ばれているかを推測できないからです。

環境変数の書き方は Linux/macOS と Windows で若干異なりますが、意味は同じです。いずれもプロセスレベルの環境変数で、dsh が起動時に読み取ります。以下はターミナルにそのまま貼り付けて実行できる例で、「キーのみ」と「互換プロキシ」の 2 つの形態を同時に示しています。

# ---- 形態 1：DeepSeek 公式エンドポイントを使う場合、必要なのはキーだけ ----
export DEEPSEEK_API_KEY=sk-your-key-here
npx @deepseek-ai/dsh web

# ---- 形態 2：ローカルまたは自前の OpenAI 互換プロキシを使う場合 ----
export DEEPSEEK_API_KEY=sk-your-key-here
export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
export DSH_MODEL=deepseek-v4-flash
npx @deepseek-ai/dsh web

# Windows PowerShell での等価な書き方（形態 1 のみを例に）
# $env:DEEPSEEK_API_KEY = "sk-your-key-here"
# npx @deepseek-ai/dsh web

ここには見落とされやすいエンジニアリング上の細かい点がいくつかある。第一に、baseURL にはプロトコルとパスプレフィックスを必ず含める必要がある。例えば http://127.0.0.1:8000/v1 であり、裸の 127.0.0.1:8000 ではない。そうでなければ、まずプロトコル層で失敗する。第二に、@deepseek-ai/dsh web は、コマンドを実行したときのカレントディレクトリをデフォルトのファイルシステム位置として使用する。これが、先に cd でプロジェクトディレクトリへ移動してから起動することが推奨される理由であり、後で「ワークスペースを選択」するときに手間が大幅に省ける。第三に、環境変数の命名は固定の三点セットである。もしキーを別の名前（例えば DEEPSEEK_KEY）で書いてしまうと、ルーターはあなたの意図を推測せず、直接 MISSING_CREDENTIAL を報告する。

もう一点、事前に説明しておく価値がある。環境変数と Web UI の「設定 → モデル」パネルは排他的ではない。環境変数はスクリプト、CI、ヘッドレス実行に適しており、Web UI の入力欄は日常的な対話に適しており、保存後は永続化される。両方が同時に存在する場合は、実際に保存された設定が優先される。したがって、環境変数を変更したのに動作が変わらない場合は、まず設定ページに古いキーがすでに保存されていないか確認してほしい。以下の表は、三点セットの役割と必須性を整理し、トラブルシューティングを容易にするためのものである：

環境変数	役割	必須かどうか	典型的な値	欠落時の挙動
DEEPSEEK_API_KEY	プロバイダー身元の資格情報	必須	sk- で始まるキー文字列	MISSING_CREDENTIAL
DEEPSEEK_BASE_URL	エンドポイントアドレスを上書きし、OpenAI 互換プロキシを指す	プロキシの場面でのみ必須	http://127.0.0.1:8000/v1	リクエストは公式エンドポイントに送られ、プロキシが有効にならない
DSH_MODEL	デフォルトのモデル名を指定する	非デフォルトモデルのみ入力が必要	deepseek-v4-flash	UNKNOWN_MODEL に該当する可能性がある

実行可能な順序として一文にまとめると、まずキーを設定 → 起動 → ページを開いて一度キーを入力（永続化）→ プロキシが必要なときに baseURL とモデル名を追加である。最初から三つの変数をすべて埋めてはいけない。そうすると、エラーが起きたときにどの層の問題なのか判断しにくくなる。

初回起動の三步走：設定 → モデルでキーを入力、ワークスペースを選択、最初のタスク指示を送信

ブラウザでターミナルが出力したアドレス（デフォルトは http://127.0.0.1:3080）を開いた後、初回利用の全体は実質的に三つのステップの閉ループである：モデルを設定し、ワークスペースを選び、指示を送る。これら三つのステップには厳密な順序依存があり、飛ばすと詰まってしまうため、以下では順番に分けて説明する。

ステップ1：設定 → モデルで、API キーを入力して保存します。ここで保存すると、モデルルーティングは即座に有効になり、サーバーの再起動は不要です。これは多くの人が初めて使うときに誤解しやすい点です——習慣でターミナルを閉じて開き直してしまいますが、実際には必要ありません。まだキーをお持ちでない場合は、DeepSeek プラットフォームで申請できます。現在このプロジェクトはクローズドベータ段階にあり、ページを開くとまずベータ版の声明が表示されることがありますが、「続行」をクリックすればメイン画面に入れます。DeepSeek 公式カードのほか、このページはディレクトリプロバイダーとカスタムプロバイダーにも対応しており、後の2つの小节でそれぞれ詳しく説明します。

ステップ2：ワークスペースを選択します。「ワークスペースを選択」をクリックし、dsh を起動したときのプロジェクトディレクトリを追加して選択します。ここには非常に重要な挙動があります：ワークスペースを選択するまで、セッションの入力ボックスは使用できません。初心者が最もよく遭遇する「入力ボックスがクリックできない」「入力しても反応しない」という問題は、9割以上がワークスペースを選んでいないことが原因であり、ソフトウェアの不具合ではありません。そのため、dsh を起動する前にまず対象のプロジェクトディレクトリへ cd しておくことをおすすめします。そうすれば「ワークスペースを選択」の候補の1番目が目的のディレクトリになります。

もし手元に既存のプロジェクトディレクトリがない場合は、チュートリアルのようにまず作成しましょう：mkdir DeepSeekProjects。そしてこの空のディレクトリをワークスペースとして選択し、最初の探索的なタスクに使います。空のディレクトリでも同様に選択でき、agent はその中でファイルを作成し、コマンドを実行します。

ステップ3：セッションで最初のタスク指示を出します。公式クイックスタートガイドのアドバイスはとても控えめです：いきなり本格的な重い作業を任せるのではなく、まず agent にワークスペースを慣れさせましょう。最初のタスクには軽量な指示がおすすめです：Summarize this repository and identify its main packages. この指示の利点は、agent がファイルを読み、ディレクトリ構造を識別し、パッケージ情報を要約する必要があるため、「ワークスペースのファイルの読み書き、コマンドの実行、サブエージェントへの委任、計画の維持」という一連の流れを実際に一通り体験でき、しかも一度の誤操作で何かを失うこともない点です。

実行中、agent は要件分析を行い、その後計画を分解して実行します。ある操作が設定した権限ポリシーを超える場合、強行突破するのではなく、まず停止してあなたの承認を求めます。この「まず宣言し、次に承認する」という仕組みこそ、以下の権限ティアの節で扱う核心です。

3ステップのループをもう一度圧縮して、照合・切り分けに使えるようにしましょう：

モデルを設定：設定 → モデルで、DeepSeek API キーを入力して保存。ルーティングは即座に有効になり、再起動は不要。他のプロバイダーやカスタムの OpenAI 互換エンドポイントにも対応。
ワークスペースを選択：「ワークスペースを選択」をクリックし、dsh を起動したときのプロジェクトディレクトリを追加して選択；選択するまでセッションの入力ボックスは使用できない。
タスクを実行：セッションに指示を入力。例えば Summarize this repository and identify its main packages.；agent はワークスペースのファイルを読み書きし、コマンドを実行し、サブエージェントに委任し、計画を維持し、権限を超える操作はまず承認を求める。

ついでに、「故障に見えるが実は正常」な現象を1つ注意しておきます：新しい Web UI はワークスペースを追加するまでどのワークスペースも選択しません。これは設計上の仕様であり、インストールの失敗ではありません。これを覚えておけば、無駄な再インストールを1回省けます。

4つの実行モードの選び方：標準モード、PTC モード、ミニマルモード、クリエイティブモードの適用範囲

DeepSeek Harness は 4 つの実行モードを提供しています。それらは「機能の多さ」による単純な段階的進化ではなく、異なる利用シーンに向けた能力のトレードオフです。モードを間違えると、通常は 2 種類の代償を払うことになります。1 つは能力を使わないまま余分に token を消費してしまうこと、もう 1 つは自分が使いたい能力をオフにしてしまい、なぜ使いにくいのか分からないことです。以下でそれぞれの境界を明確にします。

標準モードは初心者に最適です。完全なコード Agent 機能を内蔵しており、ファイル操作、Shell、検索、タスク計画、サブ Agent などの Plugin がすべてプリインストールされていて、すぐに使えます。agent にリポジトリを読ませたり、ファイルを修正させたり、テストを実行させたりしたいだけなら、迷わずこれを使ってください。

PTC モードは標準モードと同じ能力を持ちますが、さらに TypeScript によるツール呼び出しのバッチオーケストレーションをサポートし、複数ラウンドのやり取りを 1 回のオーケストレーションにまとめることで、会話回数を減らし Token を節約できます。そのハードルは、強力なコード計画能力に依存する点にあり、デバッグの難易度も高くなります。したがって、その適用範囲は明確です。大量の繰り返し呼び出しが発生するシーンに明確にいる場合——たとえば、一批のファイルに対して同型の処理を行ったり、一組のインターフェースに対して同じチェックを実行したりする場合——に切り替えてこそ、効果がはっきりと現れます。散発的なタスクで切り替えると、かえって認知的負担が増えます。

ミニマルモードは永続 Bash とファイルエディタのみを残し、追加機能を削除します。その位置づけはモデルのベースライン性能テストです——外側の Plugin がもたらす「足場の恩恵」を剥ぎ取り、モデル自体が裸のツール条件下でどのように振る舞うかを見ます。検索、計画、サブ Agent といった本当に効率を高めるものを失うため、日常的な開発には向いていません。

創造モードは標準モードのすべての能力を備え、さらに Cordis 実行環境の調査、Plugin のオンラインデバッグ、新しい Agent の作成ができ、機能の自律的な拡張を実現します。Plugin 開発をしていて、実行時に何がロードされているかを把握したい、その場で新しい Agent を作ってアイデアを検証したい、というときに適しています。「作る」ではなく「使う」だけの読者には、標準モードで十分です。

モード	中核能力	追加特性	適用シーン	不適用
標準モード	完全なコード Agent、Plugin プリインストール	ファイル、Shell、検索、タスク計画、サブ Agent	初心者に最適、日常開発	—
PTC モード	標準モードと同じ	TypeScript バッチオーケストレーション、複数ラウンドの統合、Token 節約	大量の繰り返し呼び出しシーン	散発的なタスク、デバッグ能力が弱い人
ミニマルモード	永続 Bash + ファイルエディタ	追加機能を削除	モデルのベースライン性能テスト	日常開発
創造モード	標準モードと同じ	Cordis 環境の調査、オンラインデバッグ、Agent の作成	Plugin 開発、機能の自律的拡張	すぐに使いたいだけのユーザー

操作としては、モードを選択してから新規セッションをクリックし、要件を入力してから会話を開始する流れです。つまり、モードはセッション単位の選択であり、モードを切り替えるということは通常、新しいセッションを開始することを意味し、古いセッションを新しいモードに「改造」するわけではありません。この点は権限ティアと似ており、後述しますが、権限の変更も新しいセッションと組み合わせて適用するのが推奨されます。

権限の3ティア：Read Only、Workspace Write、Full access のセキュリティ上のトレードオフ

DeepSeek Harness の権限メカニズムは、Agent がローカルファイルにアクセスし、コマンドを実行する範囲を制御するために使われます。セキュリティレベルは高い順に、Read Only > Workspace Write > Full access です。ここでの「高い順」はセキュリティレベルを指し、能力の大きさではありません。能力の方向はちょうど逆で、セキュリティが高いティアほどできることが少なくなります。

Read Only はワークスペースのファイル読み取りのみを許可し、ファイルの変更もターミナルコマンドの実行もできず、セキュリティが最も高いです。「agent にコードを理解してもらう、ドキュメントを要約してもらう、コードレビュー前の初期的な読み取りをしてもらう」といったシナリオに適しており、ディスクに何も書き込んでほしくない場合にぴったりです。代償として、結論を検証するためにコマンドを1つ実行する必要があるタスクでは、権限で行き詰まってしまいます。

Workspace Write は現在の作業ディレクトリ内のファイルの読み書きを許可し、作業ディレクトリ内でコマンドを実行することもできますが、作業ディレクトリ以外のファイルにはアクセスできません。これは日常的な開発で推奨されるティアです。ほとんどのコーディングタスクはプロジェクトディレクトリ内で完結するため、この境界は十分であり、リスクを回収可能な範囲に閉じ込められます。プロジェクトディレクトリが乱れたとしても、最悪のケースはそのリポジトリだけで、ロールバックすれば済みます。

Full access は完全なファイルシステムアクセス権を持ち、任意のパスのファイルを読み書きでき、各種のターミナルコマンドを実行できるため、高いセキュリティリスクがあります。有効にできないわけではありませんが、なぜ有効にするのかをよく考える必要があります。たとえば、ワークスペース外の設定ファイルに触れる必要がある、システムレベルのツールチェーンにアクセスする必要がある、といったタスクです。一度有効にすると、agent のミスはディレクトリの境界では受け止められなくなります。自分が何をしているかを明確に理解しており、バージョン管理やバックアップで保護されている場合にのみ、一時的に使用することをお勧めします。

ティア	ファイル読み取り	ファイル書き込み	コマンド実行	セキュリティレベル	推奨シナリオ
Read Only	ワークスペースのみ	不可	不可	最高	理解・要約・レビュー系の読み取り専用タスク
Workspace Write	ワークスペース	作業ディレクトリ内のみ	作業ディレクトリ内で実行可能	中	日常的な開発（推奨）
Full access	任意のパス	任意のパス	任意のコマンド	最低	境界を越える必要が確実にある特殊なタスク。慎重に

ここで補足しておく価値のある動作上の詳細がもう一つある。低いセキュリティレベルの段階であっても、権限ポリシーを超える操作はまずあなたの承認を求めます。つまり権限レベルは「全部許可か全部拒否か」のスイッチではなく、デフォルトの境界に承認確認の層を組み合わせたものだ。実践上の推奨は、Workspace Write から始めること。本当に境界を越える必要があるタスクに遭遇したら、一時的に権限を上げて処理し、できるだけ早く元に戻す。タスク完了後に権限を変更した場合は、新しいセッションを開いて設定をクリーンに反映させる。

セキュリティについてもう一度強調しておく。権限レベルの意義は「悪意ある AI」を防ぐことではなく、「指示を誤解する人間 + 過剰に実行する Agent」という組み合わせを防ぐことにある。曖昧な表現の指示は、Full access では削除すべきでないものを削除してしまうかもしれないが、Workspace Write ではせいぜい現在のリポジトリを乱す程度で済む。これが、公式が Workspace Write を日常開発の推奨値として挙げている理由でもある。

カタログプロバイダーを追加する：Anthropic または OpenAI を選んだ後は API キーを入力するだけで、エンドポイント・プロトコル・モデルが自動的に読み込まれる

DeepSeek 公式エンドポイントだけを使いたくない場合、DeepSeek Harness はサードパーティモデルもサポートしており、経路は二つある。カタログプロバイダーとカスタムプロバイダーだ。まずカタログプロバイダーについて説明する。こちらの方が手間が少ないからだ。

いわゆるカタログプロバイダーとは、dsh のインストール済みカタログにすでに収録されているプロバイダーであり、例えば Anthropic や OpenAI だ。その価値は、エンドポイント、プロトコル、モデル一覧がすべてカタログから自動的に提供され、手入力する必要がない点にある。操作は「プロバイダーを追加を選択 → 具体的なプロバイダーを選ぶ → その API キーを入力 → 保存」に簡略化される。保存が完了すると、ダイアログのモデル一覧に先ほど追加したモデルが表示される。例えば智譜の coding plan パッケージに接続する場合はこの経路をたどる。プロバイダーを選び、キーを入力し、保存し、モデル一覧でそれを選ぶ。

ただし、ここで必ず注意すべき落とし穴がある。ネイティブ認証を使うプロバイダーはそれぞれのネイティブ資格情報が必要であり、API キーのフィールドだけを入力しても設定は完了しない。これはバグではなく、これらのベンダーの認証機構自体が「一つの Bearer キー」というモデルに従っていないためだ。以下に、素材で明示されている四種類を整理する。

プロバイダー	必要なネイティブ資格情報
Bedrock	AWS 資格情報とリージョン
Vertex	ADC プロジェクト
Azure	api-version
Codex	OAuth

適用場面から見ると、カタログプロバイダーの位置づけは「すでに収録されている主要ベンダーへの接続」だ。目的のベンダーがカタログにあればそれを使い、わざわざカスタムを書く必要はない。カタログにない場合——例えば自社の内部ゲートウェイや自建の推論サーバー——に初めて、次の節のカスタムプロバイダーを使う。また、原文で示されている重要な区別を覚えておこう。カタログプロバイダーはインストール済みカタログを使用し、ネットワークリクエストを発行しない。つまり、プロバイダーを選ぶ段階ではオンラインでの検出は不要で、エンドポイントとモデル一覧はローカルカタログから直接提供される。

カスタムプロバイダーの追加：Provider ID、baseURL、API プロトコル、資格情報、モデルの5項目を入力する際の要点

社内ゲートウェイや自前のサーバーなど、カタログに存在しないエンドポイントには、カスタムプロバイダーで接続します。「カスタムプロバイダーを追加」を選択すると、フォームで以下の項目の入力を求められます。ここでは各項目の要点を1つずつ説明します。というのも、ここで入力ミスをすると、実行時にエラーコードという形で返ってくるからです。

項目	説明	必須かどうか
Provider ID	小文字、永続的な識別子	必須
表示名	インターフェースに表示される名前	任意
ベース URL	エンドポイントの baseURL	必須
API プロトコル	例：openai-completions	必須
資格情報	API キーまたは環境変数参照	必須
モデル	少なくとも1つのモデル	必須

Provider ID はこの中で最も慎重に扱うべき項目です。それは小文字であり、かつ永続的だからです。永続的である理由は、リクエスト、保存済みのセッション、モデルのデフォルト値、資格情報の参照がすべてこれを使用するためです。Provider ID は名前を変更できません。もし本当にプロバイダーをリネームする必要があるなら、正しい方法は新しいプロバイダーを追加して古いプロバイダーを削除することであり、ID を書き換えることではありません。相対的に、表示名、ベース URL、プロトコル、資格情報、モデルは引き続き編集可能です。ですから「名前を打ち間違えた」場合は慌てる必要はなく、表示名を変更すれば済みます。「ID を打ち間違えた」場合にこそ、新規作成＋削除の手順が必要になります。

ベース URL にはエンドポイントの baseURL を入力します。通常は /v1 のようなバージョンプレフィックスが付いたルートアドレスです。API プロトコルはリクエストの送信方法を決定します。素材で示されている典型値は openai-completions、つまり OpenAI 互換の補完プロトコルです。資格情報には API キーを入力することも、環境変数参照を入力することもできます。後者のほうが安全で、共有可能な設定にキーを保存せずに済みます。モデルは少なくとも1つ入力し、複数入力することもできます。

フォームには非常に便利な補助機能もあります。モデルカタログで利用可能なモデルを取得を選択すると、フォームに現在表示されているベース URL と資格情報を照会し、候補を一覧表示できます。ここではその境界を理解しておく必要があります。候補を選択しても更新されるのはドラフトのみで、保存するまでプロバイダーは保存されません。言い換えれば、あちこちクリックして照会を試しても安心です。保存を押さなければ、中途半端な設定が残ることはありません。もう1つの境界は、モデル検出が OpenAI 互換の GET /models を呼び出すという点です。そのエンドポイントを提供しないサービスでは、モデルを手動で入力してください。これが、後述のトラブルシューティング表にある「利用可能なモデルを取得が 401 を返す」という項目で、キーが無効な場合とエンドポイントがモデル検出をサポートしていない場合を区別する必要がある理由でもあります。

カスタムプロバイダーの完全な設定方針を、そのまま参考にできる YAML の一節に落とし込むと（$DSH_HOME/settings.yaml に記述）、フィールド間の対応関係がより直感的に分かります：

# ファイルパス：$DSH_HOME/settings.yaml
# トップレベルのキー llm-pi-ai はモデルルーティングプラグインの id で、providers の下にプロバイダー id ごとに整理する
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY          # 資格情報の参照：GATEWAY_API_KEY 環境変数から読み込む
      api: openai-completions             # API プロトコル：OpenAI 互換の補完プロトコル
      baseURL: https://gateway.runoob.example/v1   # あなたのゲートウェイエンドポイント
      models:
        - id: legacy-chat                 # テキスト専用モデル。input を書かなければテキスト専用として扱われる
        - id: vision-preview              # 視覚モデル
          input: [text, image]            # テキストと画像の両方を受け付けることを宣言

この設定において、apiKeyEnv は「資格情報を環境変数で参照する」書き方であり、api はフォームの API プロトコルに対応し、baseURL はベース URL に対応し、models はモデル一覧です。カスタムプロバイダーにはフォームに「モデルモダリティ」のフィールドがないため、視覚能力は YAML で宣言する必要があります——これこそが次の節のテーマです。

2026 年 9 月時点の最新プラクティス：settings.yaml で input と defaultInput を使って視覚モデルのモダリティを宣言する

ここで、現行バージョンで最もつまずきやすい落とし穴を説明します：手動で入力したモデルはデフォルトでテキスト専用として扱われます。画像をサポートするには、モダリティを明示的に宣言しなければなりません。これは設計上の見落としではなく、dsh が採用している明確な戦略です——なぜならエンドポイントがどのモダリティを受け付けるかを尋ねる工程がどこにも存在しないため、「まず宣言してから使う」しかないからです。あなたの宣言はエンドポイントに対する検査ではなく断言として扱われます：エンドポイントが提供しない画像能力を宣言しても、設定段階で止められることはなく、代わりにリクエスト時にプロバイダー側で拒否されます。

具体的な方法は：$DSH_HOME/settings.yaml でそのモデルに input を追加することです。このフィールドは text と image を受け付け、しかもそのモデルにのみ作用するため、1 つのルートでテキスト専用モデルと視覚モデルの両方を同時に扱えます。画像モダリティを宣言していないモデルに画像を添付すると、リクエストは送信前に拒否され、そのモデル名が示されます——これは送信して相手側から 400 が返ってくるよりも親切で、少なくとも問題がローカル設定にあることが分かります。

これら 3 つのフィールドの適用範囲は明確に区別する必要があります。これが本節の最も核心的なポイントです：

input：特定のモデルの下に記述し、そのモデルにのみ作用します。省略する場合と空リストとして記述する場合は同義であり、その際はインストール済みカタログがそのモデルに記録したモダリティが保持され、カタログに記述されていないモデルはそのルートの defaultInput にフォールバックします。
defaultInput：これは上書き値ではなくフォールバック値であり、デフォルトは [text] です。このルートの下に記述し、このルート内でカタログに記述されていないモデルに対して有効になります。手動で入力したモデルがすべて画像を受け入れる場合は、このフォールバック値を一度設定するだけで、モデルごとに記述する必要はありません。
modelOverrides：カタログ提供元のあるモデルのモダリティを絞り込むために使用し、モデル id をキーとします。カタログ提供元には記入できる models リストがないため、上書きはここでしか行えません。

典型的な例を 2 つ挙げます。1 つ目は「ルートレベルのフォールバック + 個別モデルに input を書かない」書き方で、手動で入力したモデルがすべて画像を見られる場合に適しています：

# ファイルパス：$DSH_HOME/settings.yaml
# defaultInput は上書き値ではなくフォールバック値で、デフォルトは [text]
llm-pi-ai:
  providers:
    vision-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://vision.runoob.example/v1
      defaultInput: [text, image]   # このルート下でカタログに記述されていないモデルに対して有効
      models:
        - id: first-model
        - id: second-model

2 つ目は「逆方向の絞り込み」の書き方です。カタログ提供元には記述できる models リストがないため、カタログ内のモダリティを上書きするには modelOverrides を使う必要がある点に注意してください：

# ファイルパス：$DSH_HOME/settings.yaml
# カタログ提供元には記入できる models リストがないため、上書きは modelOverrides で行う
llm-pi-ai:
  providers:
    anthropic:
      modelOverrides:
        claude-sonnet-4-5:
          input: [text]   # このモデルの画像能力を外す

覚えておくべき重要な制約は、input と defaultInput はどちらもあなたのエンドポイントに対する断言であり、そのチェックではないということです。したがって、画像能力を宣言してもエンドポイントが実際に提供していなければ、dsh は設定段階で止めません。最終的には提供元がそのリクエストを拒否します。逆に、あるモデルの能力を [text] に絞り込んでも、それはローカルなポリシーにすぎず、モデル自体が画像を見られないわけではありません。設定レイヤーと能力レイヤーは分離されています。これを理解していれば、トラブルシューティングの際に両者を混同せずに済みます。

最後に、モデル設定のよくあるエラーをトラブルシューティング表にまとめます。問題が起きたらまずここで照合すると、多くの推測を省けます：

エラー	意味	解決
MISSING_CREDENTIAL	提供元のキーが不足	モデルページで提供元のキーを保存するか、参照されている環境変数を提供する
UNKNOWN_MODEL	リクエストされたモデルが設定されていない	設定済みのモデルを選択するか、カスタム提供元に不足しているモデルを追加する
利用可能なモデルの取得が 401 を返す	キーが無効、またはエンドポイントがモデル検出をサポートしていない	キーを確認する。モデル検出は OpenAI 互換の GET /models を呼び出すため、このエンドポイントを提供しないサービスではモデルを手動入力する
画像が送信前に拒否される	モデルが画像モダリティを宣言していない	カスタム提供元のモデルに input: [text, image] を追加する。DeepSeek 自身のルートは純テキストであり、設定では変更できない
提供元が画像付きリクエストを拒否する	モデルがエンドポイントで実際には提供されていない画像能力を宣言している	画像能力を付与しているリストから image を外し、新しいセッションを開始する

最後の 2 項目の違いに注意してください。「送信前に拒否された」はローカルのモダリティが宣言されていないことを意味し、「提供元による拒否」はローカルの宣言が過剰であることを意味します。2 つの方向では修正作業がまったく異なり、一方は image を追加し、もう一方は image を削除します。後者は設定を有効にするために新しいセッションを開く必要もあります。さらに、特に明記すべき点があります。DeepSeek 自体のルーティングは純テキストであり、設定では変更できません——画像を見たい場合は、視覚をサポートする提供元に切り替えてください。

よく使うコマンド早見表

このセクションと前のセクションで扱った入口コマンドをまとめて列挙します。実際の操作でいつでも参照できるようにするためです。これらのコマンドに共通する点は、いずれもプロジェクトディレクトリで直接実行でき、追加でディレクトリを移動する必要がないことです:

コマンド	役割
npx @deepseek-ai/dsh web	Web UI を起動する（--profile web と同等）
dsh --profile headless "タスクの説明"	1 回だけタスクを実行し、最終回答を出力して終了する（スクリプト/CI に適している）
dsh plugin --profile <name> <pnpm 引数>	特定の profile のプラグインを管理する（pnpm に転送して profile ディレクトリで実行）
dsh --profile web --dump-config	実際に起動時に使われる完全な設定ツリーを表示する（サーバーは起動しない）
dsh --profile web --dump-default-config	デフォルトの設定ツリーを表示する（ユーザー patch を含まない）
pip install deepseek-harness-sdk	Python SDK をインストールする（ランタイム同梱）

Profile についてもう 1 つ覚えておくべきことがあります。web と headless の 2 つの profile は初回使用時に組み込みテンプレートから自動初期化され、それ以外の profile は dsh plugin で作成する必要があります。また、dsh の起動引数が先で、アプリケーション引数が後です。たとえば dsh --profile web --port 8080 では、--port は Web アプリケーションに属し、dsh 自体には属しません。この順序を逆にすると、そのまま引数エラーになります。

トラブルシューティングでは、--dump-config と --dump-default-config の組み合わせを特に覚えておく価値があります。前者は「実際に何が有効になっているか」（あなたが書いた patch を含む）を教えてくれ、後者は「テンプレートが本来何であったか」を教えてくれます。両者を比較すれば、あなたの settings.yaml が本当に読み込まれているかどうかを確認できます——たとえばモダリティ宣言が有効になっていない場合、まず前者を実行して設定ツリーに input があるかどうかを見てください。

最後に、前のいくつかのセクションで触れたよくある問題もまとめておきます。素早く原因を特定するためです:

ブラウザで http://127.0.0.1:3080 を開けない: ターミナルで dsh プロセスがまだ実行中で、エラーが出ていないことを確認する。ポートが使用中の場合は dsh --profile web --port 8080 でポートを変更する。ファイアウォールがローカルポートを許可しているか確認する。
npx が @deepseek-ai/dsh を見つけられない、またはバージョンが古すぎる: Node.js がインストールされており、比較的新しいバージョンであることを確認する（node -v）。プロジェクトは開発者プレビュー段階で反復が速いため、必要に応じて npx キャッシュをクリアして再試行するか、ソースからのインストールに切り替える。
ソースからのインストール時に pnpm install / build が失敗する: pnpm がインストールされていることを確認する（npm install -g pnpm）。ネットワークが制限されている場合は npm/pnpm にミラーソースを設定する。ビルドには、リポジトリの package.json の engines 宣言を満たす Node.js バージョンが必要である。
セッション入力欄が使えない / agent がファイルを読み書きできない: 最も一般的な原因はワークスペースを選択していないことです。「ワークスペースを選択」に戻ってプロジェクトディレクトリを追加して選択してください。「設定 → モデル」で有効な API キーが保存されていることを確認してください。モデルルーティングは再起動なしで有効になります。
Python SDK のランタイムが Node.js を見つけられない: SDK はランタイムを同梱しており、通常はシステムの Node.js は不要です。ランタイムが見つからないと報告された場合は、SDK と同じバージョンの完全なパッケージをインストールしたことを確認し（python -m pip install deepseek-harness-sdk）、公式の前提条件に従って Linux x64 / arm64 または macOS 14+（arm64）を使用してください。

まとめとベストプラクティス

この記事全体の内容を、そのまま実行できるチェックリストに凝縮しました。インストール部分（前段）は「プロセスを動かす」ことを解決し、設定部分（本段）は「期待どおりに動作させる」ことを解決します。両者が揃って初めて、本当の意味での初回起動が完了します。

まず環境を確認してから着手する：共通の前提は Node.js（node -v、v20+ を推奨）です。ソースからのインストールには追加で Git と pnpm が必要です。Python SDK には Python 3.10+ が必要で、公式にサポートされるプラットフォームは Linux x64 / arm64 と macOS 14+（arm64）です。
ニーズに応じてインストール経路を選ぶ：最速で Web UI を試したいなら npm install -g @deepseek-ai/dsh の後に dsh web、または直接 npx @deepseek-ai/dsh web。プラグインを開発したり、ソースを読んだり、コントリビュートしたいならソースからのインストール（clone → pnpm install → pnpm run build → pnpm dsh web）。自分の Python プログラムから Agent を呼び出したいなら SDK を使います。
起動前にプロジェクトディレクトリへ cd する：dsh は呼び出しディレクトリをデフォルトのファイルシステム位置とするため、先に cd してから起動すると、後のワークスペース選択が最も楽になります。
認証情報は順番に設定する：デフォルトの DeepSeek 公式エンドポイントを使う場合は DEEPSEEK_API_KEY だけで十分です。OpenAI 互換プロキシに接続する場合は、さらに DEEPSEEK_BASE_URL（プロトコルと /v1 プレフィックスを含む）と DSH_MODEL を補います。一度に三つとも埋めないでください。エラー時の切り分けが難しくなります。
初回の三ステップを完了する：設定 → モデルにキーを入力（保存で即反映、再起動不要）→ ワークスペースを選択（選択するまでセッション入力欄は使用不可）→ 最初のタスクを送信。最初のタスクには Summarize this repository and identify its main packages. のような軽量な指示を使い、まず agent にワークスペースを慣れさせましょう。
モードはシーンに応じて選ぶ：初心者や日常的な開発には標準モード。大量の繰り返し呼び出しがあり、デバッグコストを許容できるなら PTC モードで Token を節約。モデルのベンチマークテストのみなら最小モード。プラグインをオンラインデバッグしたり、新しい Agent を作成するなら創造モード。
権限は Workspace Write から始める：読み取り専用のタスクには Read Only、日常的な開発には Workspace Write（読み書きは作業ディレクトリ内に限定）、Full access はリスクが最も高く、必要でなければ有効にしない。権限外の操作はまず承認を求められ、権限変更後は新しいセッションを開くことを推奨します。
サードパーティモデルはカタログ提供元を優先する：Anthropic、OpenAI など既に収録されているベンダーは、提供元を選べば API キーを入力するだけで、エンドポイント、プロトコル、モデル一覧が自動的に入力され、ネットワークリクエストも発生しません。Bedrock、Vertex、Azure、Codex はそれぞれネイティブの認証情報（AWS 認証情報とリージョン / ADC プロジェクト / api-version / OAuth）が必要です。
カタログにないエンドポイントはカスタム提供元を使う：必須項目は Provider ID（小文字、永続、改名不可。改名したい場合は新規作成してから旧を削除）、ベース URL、API プロトコル（例：openai-completions）、認証情報（環境変数参照も可）、少なくとも一つのモデル。表示名、baseURL、プロトコル、認証情報、モデルは後からでも編集可能。「利用可能なモデルを取得」はドラフトを更新するだけで、保存しなければディスクに書き込まれません。
視覚モダリティは明示的に宣言する必要がある：手動で入力したモデルはデフォルトで純テキストとして扱われます。$DSH_HOME/settings.yaml の llm-pi-ai ルート配下で、そのモデルに input: [text, image] を記述します。全ルートでデフォルトの画像認識を有効にするには defaultInput（フォールバック値、デフォルトは [text]）を使います。カタログ提供元のモデルを絞り込むには modelOverrides を使います。input と defaultInput は検査ではなく断言であることを覚えておいてください。DeepSeek 自身のルートは純テキストで、設定では変更できません。
トラブルシューティングは推測より先に表を確認する：MISSING_CREDENTIAL はキーまたは環境変数参照を確認。UNKNOWN_MODEL はモデルが設定されているか確認。モデル検出の 401 は、キーが無効かエンドポイントが GET /models をサポートしていないかを区別。「送信前に拒否」はローカルで image を宣言していないこと、「提供元に拒否」は宣言しすぎなので image を削除して新しいセッションを開きます。
設定の自己診断コマンドを活用する：dsh --profile web --dump-config で実際に有効な設定ツリーを確認し、--dump-default-config でデフォルトテンプレートを確認します。両者を比較すれば settings.yaml が本当に読み込まれているか確認できます。起動パラメータが先、アプリケーションパラメータが後です。例：dsh --profile web --port 8080。

ひとつだけ覚えるなら：まず API Key を設定し、ワークスペースを正しく選び、最小権限（Workspace Write）で軽量なコマンドを実行して一連の流れを検証する。この3つを正しく押さえておけば、その後に提供元を切り替えたり、モダリティを調整したり、サブ Agent を起動したりしても、すでに通った経路への増分調整で済み、ゼロから原因を探る必要はない。