DeepSeek Harness チュートリアル：最も人気のオープンソース AI エージェントをはじめよう

DeepSeek Harness が人気の理由

DeepSeek Harness は公開から短期間で注目を集め、GitHub スター 160,000 超、フォーク 18,000 に到達しました（本記事公開時点）。

大きな理由のひとつは、開発者が DeepSeek だけでなくさまざまなモデルから強力な結果を引き出せると実感している点です。特にコーディングや長いエージェントタスクで、Qwen3.8-27b などのモデルを問題なく使えているという報告が Reddit で頻繁に見られます。

もうひとつの理由は自律性と柔軟性です。Harness は複数ステップのタスクを継続的に実行し、エラーから回復し、長いコンテキストを管理し、常時の介入なしでも進められるとユーザーは報告しています。プラグインベースの設計により、モデルの入れ替え、ツールの追加、エージェントのワークフローのカスタマイズが容易で、固定構成に縛られません。

Harness を競合ツールと比較検討している場合は、Claude Code の代替ガイドで主要な 7 つの選択肢を横並びで比較しています。

DeepSeek Harness の主な機能

主な機能は次のとおりです。

• プラグインベースのアーキテクチャ：エージェントのほとんどの部分はプラグインで拡張・置換でき、セットアップのカスタマイズが容易です。

• ローカル Web UI：dsh web を実行すると、モデル、セッション、ワークスペース、設定、エージェントを管理できるブラウザベースのインターフェースが利用できます。

• Python SDK：deepseek-harness-sdk を使うと、Python アプリ、スクリプト、テスト、自動化ワークフローから直接 Harness エージェントを実行できます。

• 複数のモデルプロバイダー：DeepSeek モデルに限定されません。OpenAI や Anthropic などのプロバイダーを使うことも、自前の互換エンドポイントに接続することもできます。

• ツール呼び出し：エージェントはテキスト生成だけでなく、ツールを呼び出してアクションを実行できます。

• ファイルとターミナルのツール：ファイルの読み取り、検索、編集用ツールに加え、Linux と macOS では Bash、Windows では PowerShell を利用できます。

• 内蔵ウェブ検索：DeepSeek のウェブ検索プロバイダーがデフォルト構成に含まれており、モデルと同じ DeepSeek API キーを使用します。

• Code Mode：コードベースの実行モードでツールを公開でき、ツール呼び出しの組み合わせや実行方法をエージェントがより細かく制御できます。

• Trajectory：Trajectory ビューでは、モデルの応答、ツール呼び出し、ネストしたツールの動作、時間、トークン使用量など、エージェントの処理をステップごとに確認できます。

• エージェントのプリセット：ツールやプロンプトを個別に持つエージェント構成を作成し、複数のセッションで使い回せます。

• セッション統計：ターン数、ステップ数、モデル時間、ツール時間、最初のトークンまでの時間、デコード時間などの有用な情報を記録します。

• サブエージェント：メインエージェントがタスクの一部を子エージェントに委譲でき、複雑なワークフローに有用です。

• コミュニティプラグイン：サードパーティのプラグインで、ベースモデルにはない機能を追加できます。本ガイドでは、ビジョン対応のために ModLens を使用しました。

• MIT ライセンス：DeepSeek Harness はオープンソースで、寛容な MIT ライセンスの下で提供されています。

最大の利点は、単一のモデル、ツールセット、エージェントタイプに縛られないことです。デフォルト構成から始め、異なるワークフローを試しながら、コンポーネントを段階的に追加・置換できます。

DeepSeek Harness のセットアップ方法

まず DeepSeek Harness をインストールし、このガイドに必要な準備を整えましょう。Node.js、DeepSeek Harness、pnpm をインストールし、続いて API キーを追加します。

Node.js をインストールする

DeepSeek Harness は Node.js 上で動作します。後でビジョン用に ModLens も使用するため、Node.js 22.19 以降を推奨します。

Ubuntu または Debian の場合は次でインストールできます。

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs

インストール後、Node.js と npm が動作しているか確認してください。

node --version
npm --version

筆者の環境では次のとおりでした。

v24.19.0
11.17.0

まったく同じバージョンである必要はありません。十分に新しい Node.js を使っていれば問題ありません。

DeepSeek Harness をインストールする

次に、DeepSeek Harness 本体をインストールします。

公式のクイックスタートでは npx を使いますが、このガイドでは dsh コマンドを通して使えるよう、グローバルにインストールする方法を採用します。

次を実行します。

npm install -g @deepseek-ai/dsh

正しくインストールされたか確認します。

dsh --version

本ガイド検証時点では次を使用しました。

0.1.0-rc.7

pnpm をインストールする

pnpm も必要です。DeepSeek Harness はプラグインの追加・削除に pnpm を使用します。グローバルにインストールしてください。

npm install -g pnpm

API キーを設定する

本チュートリアルで必要な API キーは 2 つだけです。

• DeepSeek API キー：DeepSeek モデルおよび内蔵ウェブ検索に使用します。
• Gemini API キー：ModLens が画像理解に使用します。

まずは DeepSeek キーを設定します。コーディングとウェブ検索にはこれだけで十分で、ModLens でビジョンを追加する段階になったら Gemini キーを追加します。

DeepSeek を使うには、DeepSeek アカウントの作成、API キーの発行、アカウントへのクレジット追加が必要です。本ガイドでは、まずは 2 ドル程度のクレジット追加をおすすめします。例を試すには十分で、最初から大きな金額を入れる必要はありません。

API キーを取得したら、環境変数に追加します。

Linux または macOS の場合：

export DEEPSEEK_API_KEY="your_deepseek_api_key"

Windows PowerShell の場合：

$env:DEEPSEEK_API_KEY="your_deepseek_api_key"

このセットアップの良い点は、ウェブ検索用の別 API が不要なことです。DeepSeek Harness にはすでに DeepSeek のウェブ検索プロバイダーが含まれており、同じ DEEPSEEK_API_KEY を使用します。

Web UI のSettings → Models から後で DeepSeek API キーを追加することもできます。

DeepSeek Harness の起動方法

準備が整ったら、DeepSeek Harness を起動して Web UI を開きます。dsh web を実行するだけで、デフォルトでポート 3080 のブラウザインターフェースが起動します。

ブラウザでアドレス http://127.0.0.1:3080 を開くと、UI を確認できます。

そこから新しいワークスペースを作成（または既存を選択）し、新規セッションを開始して、使用する DeepSeek モデルを選びます。

セッションの準備ができたら、コーディング、ウェブ検索、ビジョン、サードパーティモデルのサポートをテストできます。

DeepSeek Harness をコーディングに使う方法

DeepSeek Harness が動作したので、セットアップの主な機能を試してみましょう。まずは簡単なコーディングタスクから：

Create a simple Python calculator with a command-line interface.

DeepSeek Harness はファイルとターミナルを直接扱えるため、Python ファイルの作成、コード編集、ワークスペース内でのコマンド実行まで行えます。

タスク完了後、生成されたファイルと実行手順が表示されるはずです。

Harness を支える DeepSeek モデルをさらに活用するには、DeepSeek V4 API チュートリアルで、V4 の推論モードと Python の API パラメータを解説しています。

DeepSeek Harness をウェブ検索に使う方法

次にウェブ検索を試します。DeepSeek Harness にはすでに DeepSeek のウェブ検索プロバイダーが含まれているため、追加の設定は不要です。

次のようなプロンプトを試してください。

Search the web for the latest open-source AI model releases and summarize the top three as of August 18, 2026.

エージェントがウェブを検索し、出典付きの要約を返すはずです。

処理中に Trajectory タブを開くと、SUBTOOL: web_search などのツール呼び出しが表示されます。

これは、モデルの既存知識だけに頼らず、実際にウェブ検索ツールを使っていることを示します。デフォルトでは、この検索は deepseek-official プロバイダーによって処理され、先ほど設定したのと同じ DEEPSEEK_API_KEY を使用します。

DeepSeek をビジョンタスクに使う方法

Harness における DeepSeek のチャットモデルはテキスト専用のため、アップロードした画像を自力で理解することはできません。ビジョン対応を追加するには、ModLens を使用します。これは DeepSeek とビジョン対応モデルの橋渡しを行います。

ModLens プラグインをインストールする

画像をアップロードすると、ModLens はビジョンモデルでそれを処理し、有用な視覚情報を抽出して DeepSeek に返し、画像について推論できるようにします。

まず web プロファイルに ModLens プラグインをインストールします。

dsh plugin --profile web add @liustack/modlens@3.20.0

インストールが完了すると、ModLens は modlens_read_image ツールを追加し、``DeepSeek-V4-Flash (modlens vision)` のようなモデルオプションを作成します。

これらのモデルバリアントを使うと、メインの推論モデルとして DeepSeek を維持したまま、画像をアップロードできます。

ビジョンのバックエンドを登録する

本ガイドでは Gemini API をビジョンのバックエンドとして使用するため、Gemini の API キーが必要です。まずは Gemini API の Free Tier から始められます。Google は Free Tier のレート制限内でサポート対象の Gemini モデルへの無料アクセスを提供しているため、本ガイドのビジョン設定を試すだけであれば支払い情報の追加は不要です。

キーを取得したら、環境変数に追加します。

Linux または macOS の場合：

export GEMINI_API_KEY="your_gemini_api_key"

Windows PowerShell の場合：

$env:GEMINI_API_KEY="your_gemini_api_key"

ModLens CLI をインストール・設定する

次に、ModLens CLI をインストールします。

npm install -g @liustack/modlens

続いて、Gemini API キーで設定します。

Linux または macOS の場合：

modlens config set gemini-api.apiKey "$GEMINI_API_KEY"
modlens config set provider gemini-api

Windows PowerShell の場合：

modlens config set gemini-api.apiKey "$env:GEMINI_API_KEY"
modlens config set provider gemini-api

最後に、動作確認を行います。

modlens doctor

gemini-api がプロバイダーとして選択され、準備完了と表示されるはずです。

ModLens と DeepSeek Harness のテスト

それでは画像理解をテストしましょう。

モデルピッカーから、名前に (modlens vision) が付いたモデルのいずれか（例：DeepSeek-V4-Flash (modlens vision)）を選択します。

画像を貼り付けるかアップロードし、Explain what is shown in this image. と尋ねてください。

上の例のとおり、DeepSeek はアップロードした画像を記述し、推論できるようになりました。

裏側では、ModLens が画像を Gemini に送って視覚的理解を行い、抽出した情報を DeepSeek に返しています。これにより、ビジョン部分だけ Gemini を使いながら、メインの推論モデルとしては引き続き DeepSeek を利用できます。

サードパーティモデルと DeepSeek Harness を使う方法

最後に、別プロバイダーのモデルを試してみます。Settings → Models を開きます。

ここから、OpenAI や Anthropic などのプロバイダーを追加したり、自身の API 資格情報でサポート対象の他モデルプロバイダーを設定できます。

セルフホストのモデルや互換エンドポイントに接続したい場合は、カスタムプロバイダーを追加することもできます。これにより、プロバイダー ID、ベース URL、API タイプ、認証情報、モデル名といった詳細を設定できます。

プロバイダーを追加したら、セッションに戻ってモデルピッカーから新しいモデルを選択します。

例えば、次のプロンプトを試してください。

Create a Python command-line to-do app that lets users add, list, complete, and delete tasks, with tasks saved locally in a JSON file.

上の例では、サードパーティの Kimi-K3 モデルでコーディングタスクを完了しており、DeepSeek Harness が DeepSeek モデルに限定されないことを示しています。

構成済みのモデル間は、モデルピッカーから直接切り替えられ、Harness サーバーを再起動しなくても次のリクエストから反映されます。

まとめ

DeepSeek Harness を試した結果、筆者個人のワークフローでは、依然として Pi Coding Agent と OpenCode を好みます。

DeepSeek Harness は、プラグインベースのエコシステムを中心に設計されている点で Pi Coding Agent とよく似ています。必要に応じて拡張機能をインストールし、コーディングエージェントに追加能力を与えられます。柔軟性は魅力ですが、テストした限りでは、DeepSeek Harness をめぐる熱狂がまだ十分には理解できませんでした。全体的な体験は、これまで使ってきた他のコーディングエージェントと比較して、かなり通常どおりに感じられました。

いくつか苛立つ問題にも遭遇しました。たとえば、エージェントが理由の説明なしにタスクの途中で停止し、再開するには continue と入力する必要があることがありました。プラグインのインストールと設定も難所でした。何をすべきかを正確に把握していないとかなり難しく、現時点ではドキュメントもあまり助けになりません。

とはいえ、DeepSeek Harness はまだ非常に新しい製品であり、こうした問題は理解できます。今後、体験、ドキュメント、プラグインエコシステムは大きく改善されていくと期待しています。また、DeepSeek 独自のモデルと特に相性の良いハーネスを構築している可能性もあり、それが盛り上がりの一因なのかもしれません。