TLDR DeepSeek Harness（dsh）は、DeepSeek AI が開発したオープンソースのエージェント実行環境（ランタイム）で、2026年8月13日前後に MIT ライセンスで開発者プレビューとして公開されました。「Model + Harness = Agent」という原則に従い、あらゆる機能（モデル、ツール、セッション、サンドボックス、ループ、UI）は交換可能な Cordis プラグインとして実装されています。
ローカルで最速に実行する方法は npx @deepseek-ai/dsh web（Node.js ^22.19 または ≥24 が必要）で、http://127.0.0.1:3080. に Web UI が起動します。DeepSeek（または OpenAI 互換）API キーとワークスペースを指定します。ソースビルド、デスクトップアプリ、Docker、Python SDK、Ollama 連携も利用可能です。実運用レベルのマルチモデルアクセス、信頼性、コスト管理を重視する場合、ハーネス利用時のリクエストは CometAPI の OpenAI 互換統一エンドポイント経由にルーティングすることを推奨します。
Key Takeaways
- DeepSeek Harness はモデルではありません。ファイル、シェル、ツール、セッションに対してモデルを「行動させる」ためのローカル実行環境／オーケストレーターです。
- 公式ワンライナー:
npx @deepseek-ai/dsh web→ ローカルの Web UI がポート 3080 で開きます。 - Node.js 要件は厳格: ^22.19.0 または ≥24.x。
- DeepSeek 公式モデル（deepseek-v4-flash, deepseek-v4-pro）、OpenAI 互換ゲートウェイ、Ollama 経由のローカルモデルをプラグインでサポート。
- アーキテクチャは完全プラグインベース（Cordis カーネル）。モードは Standard、Minimal、Code、Creator。
- 急速な普及: リリース後数日で数万〜10万超の GitHub スターを獲得。
- パワーユーザー向け推奨: カスタムプロバイダとして CometAPI（https://www.cometapi.com/）を組み合わせ、500+ モデル、20–40% のコスト削減、単一 API キーで運用。
- 常に隔離されたワークスペースを使用してください。エージェントはファイルを変更し、コマンドを実行できます。
- 開発者プレビューのため破壊的変更があり得ます。本番相当の検証ではバージョン固定を推奨。
What Is DeepSeek Harness and Why It Matters in 2026
DeepSeek Harness（dsh）は、DeepSeek AI が開発したオープンソースのエージェント実行環境です。MIT ライセンス下の開発者プレビューとして公開され、コンポーザビリティを重視しています。すべての機能—モデルアダプタ、ツール、スキル、セッション、サンドボックス、ストレージ、エージェントループ、スケジューリング、UI—は Cordis プラグインとして存在し、構成でマウント／アンマウント、差し替え、再構成が可能です。パッチを当てるべき特権的コアは実質的に存在しません。
主な設計原則:
- Agent = Model + Harness.
- 再開・分岐・検索・再生をサポートするトレース可能なイベントストリーム。
- 複数のランタイムモード（標準のフルツールセット、コード／オーケストレーションモード、ベンチマーク用のミニマルモード、クリエイター／実験モード）。
- 対話用のローカルファーストな Web UI と、自動化のためのヘッドレス／SDK オプション。
公式リソース:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- プロダクト／ランディング: https://www.deepseek.com/harness/en/（および中国語版）
- インストールガイドやコミュニティミラーでも同じ基本コマンドが案内されています。
重要な用語上の注意: 「ローカルデプロイ」には2つの意味があり得ます。本ガイドで扱う DeepSeek Harness はあなたのコンピュータ上でローカルに稼働しますが、標準の
deepseek-harnessプロジェクトは API を通じて DeepSeek V4-Pro または V4-Flash に接続します。つまり、ハーネス、構成、セッション、検証、クライアントロジックはローカルで動作する一方、推論は通常 DeepSeek の API で行われます。モデルの重みを自分の GPU に置いて真にオフラインで推論したい場合は、別のデプロイアーキテクチャが必要です。
Prerequisites and System Requirements
インストール前に以下を確認してください:
- OS: Windows 10+、macOS 10.15+、主流の Linux（x64 または arm64）。Python SDK には追加要件（Linux x64/arm64 または macOS 14+ arm64）。
- Node.js: メインの Web UI パスに必要。対象範囲は ^22.19.0 || ≥24.0.0。node --version で確認。範囲外の奇数版は非サポート。
- パッケージマネージャ: npm/npx（Node に同梱）。ソースビルドには pnpm（npm install -g pnpm で導入）。
- Git: ソースクローンに必要。
- Python（任意）: 公式 Python SDK 用に 3.10+。
- API キー／エンドポイント: platform.deepseek.com の DeepSeek API キー、または任意の OpenAI 互換エンドポイント＋キー＋モデル名。
- ハードウェア: ハーネス自体に GPU は不要—推論はリモート（または設定したローカルプロバイダ）で実行。Web UI とオーケストレーションには一般的なノート PC で十分。
- ネットワーク: 初回起動時にパッケージ取得が必要。以降はモデル API 呼び出しのみで UI 動作可。
- ワークスペース: 隔離ディレクトリを用意。エージェントは設定したワークスペース内で読み書きやコマンド実行が可能—本番データや個人データを不用意に指定しないでください。
要件の情報源: 公式 README と、公開直後に出た複数の独立系インストールガイド。
Method 1: Official One-Liner with npx (Recommended for Most Users)
これは最速かつ公式に推奨される方法です。
- Node.js が要件を満たすことを確認。
- ターミナルで次を実行:
Bash
npx @deepseek-ai/dsh web
- パッケージがダウンロード（またはキャッシュ利用）され、Web UI プロファイルが起動し、待受アドレスが表示されます。デフォルトは http://127.0.0.1:3080.
- ブラウザでその URL を開きます。表示される場合は開発者プレビューの注意に同意。
- 初回はモデルプロバイダ（Settings → Models）で API キーを貼り付け、deepseek-v4-flash や deepseek-v4-pro などのモデルを選択。
- ワークスペースディレクトリを選択または作成。
- タスクを実行開始。
別ポートを使うには:
Bash
npx @deepseek-ai/dsh web --port 8080
Platform-specific one-liners （Windows の PowerShell＋winget、macOS の Homebrew、Debian/Ubuntu の NodeSource などで Node も整えるもの）もコミュニティから提供されています。
利点: npm キャッシュ以外に恒久的なインストール不要／常に最新の公開版を取得／最も簡単なオンボーディング。欠点: 初回はネットワーク依存／ソース精読やカスタムビルドには不向き。
Method 2: Install and Run from Source
Cordis プラグインを読みたい、コミットを固定したい、カスタムプリセットを作る、コントリビュートしたい場合に。
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
同じ Web UI がデフォルトポートで現れます。開発者プレビュービルドはコミット間で壊れる場合があるため、実験的手法として扱ってください。
Method 3: Desktop Applications (Zero Node Setup)
コミュニティおよびサードパーティ製のデスクトップラッパーは、Node/pnpm を自分で入れずにランタイムを利用できるようパッケージ化しています。
- Tauri ベースの軽量クライアント: バンドル済み Node ランタイムを起動時にブートストラップし、最新の上流ハーネスを同期。127.0.0.1:3080 で動作し、データはローカルに保持、dsh コマンドも登録。
- Electron ベースのパッケージ: 依存関係を固定して同梱。
各 GitHub Releases ページからインストーラをダウンロード（「deepseek-harness-desktop」で検索）。初回起動でコアコンポーネント（数百 MB）を取得。非開発者に便利ですが、DeepSeek 公式プロダクトではないため、リポジトリと SHA チェックサムを確認してください。
Method 4: Docker / Container Deployment
コンテナ内で Web UI を動かすためのコミュニティ Docker イメージや compose ファイルがあり、多くは nginx による HTTPS 終端や任意の OpenAI 互換ゲートウェイをサポートする構成です。一般的な手順:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # set API key / public host
docker compose up -d --build
LAN アクセス、サーバ、ホストに Node を入れたくない環境に有用。一部のセットアップは DeepSeek 以外のプロバイダ向け settings.yaml をサポートします。
Method 5: Python SDK for Programmatic / Headless Use
無人のエージェントや Python パイプライン統合向けに:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
環境変数を設定:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash
チェックイン済みのサンプルを実行するか、独自コードで DeepSeekHarness クラスを使用し、隔離されたワークスペースとセッションディレクトリで動かしてください。SDK は独自のランタイムを同梱し、システムの Node.js を必要としません。
Method 6: Ollama Integration
Ollama は便利なランチャーを提供します:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
必要に応じてパッケージのインストールも行い、起動設定は別途保持します。Web 検索やツールサポートは選択したモデルと Ollama のクラウドアクセスに依存します。
Configuring Models and Providers (Including CometAPI)
Web UI 内の「Settings → Models」へ移動。
- 公式 DeepSeek の場合: platform.deepseek.com から取得したキーを貼り付け。代表的なモデルは deepseek-v4-flash と deepseek-v4-pro。
- カタログプロバイダ（Anthropic、OpenAI など）の場合: 「Add provider」フローを使用。
- カスタム／セルフホスト／アグリゲータのエンドポイントの場合: 「Add a custom provider」を選択。永続的な Provider ID、Base URL、プロトコル（通常は openai-completions）、API キーの環境参照または値、少なくとも1つのモデル ID を指定。
CometAPI の推奨（多くの本番相当ワークフローで強く推奨） CometAPI は、単一の OpenAI 互換エンドポイント https://api.cometapi.com/v1. から 500+ モデル（DeepSeek 系、GPT、Claude、Gemini、Grok ほか多数）を提供する統合 AI 基盤です。
DeepSeek Harness と組み合わせる利点:
- 複数プロバイダの資格情報管理が不要（API キーは1つ）。
- 競争力のある料金（多くのモデルでベンダ直接比 20–40% のコスト削減が報告）。
- 高可用性（目標 99.9% SLA）、低中央値レイテンシ、従量課金。
- モデル ID の変更以外にハーネス構成を変えずに A/B テストやコスト最適化が容易。
- ドロップイン互換: base_url とキーを変えるだけで既存の OpenAI SDK パターンが利用可能。
ハーネスのカスタムプロバイダ設定では:
- Base URL:
https://api.cometapi.com/v1 - Protocol: openai-completions（または同等のサポートオプション）
- API key: あなたの CometAPI キー
- Model ID: CometAPI のモデルカタログに掲載の任意のモデル文字列
これにより、強力なローカルエージェントランタイムを維持しつつ、柔軟でコスト効率の高いマルチベンダーなモデルアクセスが可能になります。新規ユーザーには無料トライアルクレジットが提供されるのが一般的です。ドキュメント: https://apidoc.cometapi.com/.
キーは書き込み専用で保存されます（例: $DSH_HOME/.credentials.yaml）。UI ではマスクされた記述のみが表示されます。
Troubleshooting DeepSeek Harness
DEEPSEEK_API_KEY not found
次を確認:
echo $DEEPSEEK_API_KEY
Windows:
echo $env:DEEPSEEK_API_KEY
空なら再設定してください。
400 reasoning_content error
多くの場合、推論ライフサイクルの不適切な取り扱いが原因です。
思考／ツールコールのマルチターンにまたがる関連するアシスタントの推論情報を、アプリケーションが正しく保持しているか確認してください。
これはハーネスがまさに対処することを目指している中核課題の1つです。
Context-length error
次を確認:
input tokens + max_tokens
記載のハード上限は:
1,048,576 tokens
入力コンテキストか要求出力長を減らしてください。
Tool calls become malformed during streaming
ストリームチャンクがツール順で到着するとは限りません。
ハーネスの契約どおり、tool_call.index 単位でツールコールの差分を集約してください。
Requests are unexpectedly expensive
次を確認:
- thinking mode
- output length
- cache-hit rate
- prompt prefix stability
- model choice
- current API pricing
単純な改善としては、 routine なタスクを Pro から Flash に移すことがよく有効です。
Comparison of Installation and Deployment Methods
| Method | Ease of Use | Node Required | Best For | Persistence / Control | Typical Port / Access | Notes |
|---|---|---|---|---|---|---|
| npx one-liner | 最高 | はい | クイックトライアル、ほとんどのユーザー | 一時的（キャッシュのみ） | 3080（変更可） | 公式推奨 |
| Source (pnpm) | 中 | はい | 開発、プラグイン、バージョン固定 | フルソース管理 | 3080 | pnpm＋ビルドが必要 |
| Desktop (Tauri/Electron) | 高 | いいえ（同梱） | 非技術ユーザー | ローカルプロファイル＆自動更新 | 3080（内部） | コミュニティパッケージ |
| Docker | 中 | いいえ（コンテナ） | サーバ、LAN、HTTPS | コンテナボリューム | カスタム／443 | コミュニティイメージ |
| Python SDK | 中 | いいえ | ヘッドレス、自動化、パイプライン | プログラマティックなセッション | N/A（デフォルトで UI 無し） | 公式 SDK |
| Ollama launch | 高 | 任意 | ローカルモデル実験 | Ollama 設定 | 3080 | Ollama 連携 |
データは公式ドキュメントとローンチ後のガイド（2026年8月）をもとに整理。
Conclusion and Next Steps
DeepSeek Harness は、「npx ワンライナー」でほぼゼロ摩擦のローカル導入を実現し、完全プラグイン型の美しい設計を備えたエージェントランタイムです。統一プラットフォーム（特に CometAPI）による柔軟なモデルルーティングと組み合わせれば、最新のエージェント的コーディングワークフローの力と、コスト・モデル選択・データローカリティの実用的な制御を同時に得られます。
まずは次で開始:
npx @deepseek-ai/dsh web
DeepSeek または CometAPI のキーを設定し、安全なワークスペースを指定して Standard モードを試してください。次に、ベンチマーク向けの Minimal モード、コスト最適化のカスタムプロバイダ、あるいは自動化のための Python SDK を試行してみましょう。
最新の公式手順は常に GitHub リポジトリと ドキュメントを優先してください。ハーネスを使いながらマルチモデルの信頼性と価格優位性を得るには、CometAPI とそのドキュメント https://apidoc.cometapi.com/. を参照してください。