DeepSeek Harnessは、AIモデルを実際に動作するエージェントに変えるための、DeepSeekのオープンソースフレームワークです。あらゆるAIモデルに、環境、ツール、メモリとセッション、ファイルとシェルへのアクセス、ウェブ検索、サブエージェント、スケジューリング、サンドボックスなど、複数のステップからなるタスクの実行に必要な機能を提供します。
この記事では、Atomic Chatを推論プロバイダーとして使い、DeepSeek Harnessをローカル実行する方法を手順に沿って説明します。全体の流れは次のとおりです。
DeepSeek Harness → http://127.0.0.1:1337/v1 → Atomic Chat → local AI model
DeepSeek Harnessとは？
DeepSeek Harnessは、DeepSeekが提供するオープンソースのエージェントハーネスです。次の機能が含まれています。
- ブラウザベースのインターフェース
- 設定可能なエージェントループ
- プラグインシステム
- 権限制御
- モデルプロバイダー
- 再利用可能なエージェントプリセット
- ウェブ検索やスケジューリングなどのエージェント用ツール
設計の中心にあるのは、すべてをプラグインにするという考え方です。モデル、ツール、ストレージ、インターフェース、エージェントの動作を交換したり組み合わせたりできます。また、詳細な実行ログを保持するため、エージェントの実行内容を確認、再開、分岐、再現できます。執筆時点では開発者プレビュー段階で、DeepSeekのCordisプラグインアーキテクチャを基盤としています。
このガイドで検証したバージョンは@deepseek-ai/dsh0.1.1-rc.2です。パッケージはプレビュー段階のため、インターフェースや設定が変更される可能性がある点に注意してください。
前提条件
始める前に、次のものを用意してください。
- ローカルモデルを実行できるmacOS、Windows、またはLinuxのコンピューター。
- デスクトップにインストール済みのAtomic Chat。
- Node.js。このガイドではNode
v22.23.1で検証しました。 - Atomic Chat、モデル、npmパッケージを初回にダウンロードするためのインターネット接続。
- Harnessに調査させるローカルのプロジェクトディレクトリ。
- モデルの重みとコンテキストキャッシュの両方を格納できる十分な空きRAM。
ステップ1：Atomic Chatをインストールする
このガイドでは、私たちが開発したオープンソースのローカルAIアプリであるAtomic Chatを推論プロバイダーとして使用し、DeepSeekに接続するQwenモデルのダウンロード、インストール、実行を行います。
DeepSeek Harnessでは任意の推論プロバイダーを使用できるため、Ollama、LM Studio、llama.cpp、または別のアプリを使いたい場合は、このステップをスキップしてください。
このガイドと同じ手順で進める場合は、次のように操作します。
atomic.chatにアクセスし、Downloadを選択します。お使いのOS向けのデスクトップビルドを選び、インストールしてアプリを開きます。
この構成にはデスクトップアプリが必要です。モバイルクライアントでは、ローカルモデルサーバーをホストしたり、コンピューター上のプロジェクトを対象にコーディングエージェントを起動したりすることはできません。
ステップ2：ツールを使用できるローカルモデルをダウンロードする
Atomic Chatで次の操作を行います。
- サイドバーのModelsを開きます。
- CapabilitiesにTool Useが記載されているモデルを検索するか、一覧から探します。
- モデルカードを開きます。
- Download Optionsを選択します。
- コンテキストキャッシュやシステムのほかの処理に必要なメモリを十分に残せる量子化を選びます。
- Downloadを選択し、モデルファイルのダウンロードが完了するまで待ちます。
コーディングエージェントで使うには、Harnessがファイルを読み取り、シェルを呼び出し、その結果を処理できるように、モデルが構造化されたツール呼び出しを生成できる必要があるため、ツール呼び出しに対応したモデルを探してください。
Atomic ChatのDownload Optionsには、利用可能なGGUF量子化とそのファイルサイズが表示されます。
システムプロセス用のRAMまたはVRAMを十分に残せるモデルと量子化を選んでください。たとえば、16 GBのマシンでは、重みやキャッシュの一部がスワップに追い出される9Bモデルよりも、小型の4Bモデルのほうが大幅に高速になる場合があります。
ステップ3：Atomic ChatのLocal API Serverを起動する
Atomic ChatでIntegrationsを開きます。Local API Serverパネルでは、アクティブなモデルをOpenAI互換エンドポイント経由で公開できます。デフォルト構成のエンドポイントは次のとおりです。
http://127.0.0.1:1337/v1
ダウンロードしたモデルを読み込み、サーバーを起動します。
Coding Agentsセクションには、DocsとRunの操作ボタンを備えたDeepSeek Harnessカードがあります。
Atomic Chatは、PATH上のdsh実行ファイルを検出し、ローカルプロバイダーの設定を書き込み、Harnessを起動できます。以下の手動セットアップに従うこともでき、その場合は接続に使うすべての設定値を確認できます。
続行する前に、Server Configurationを開いてAPIキーを設定します。この場合、Atomic ChatとDeepSeek Harnessで同じ値を使う限り、APIキーは任意の値で構いません。このキーは、Atomic ChatがHarnessからのリクエストを認証するために使う共有パスワードにすぎません。
macOSまたはLinuxでランダムなキーを生成するには、次を実行します。
openssl rand -hex 32
Windows PowerShellでは、次を実行します。
([guid]::NewGuid()).ToString("N")生成された値をコピーし、Atomic ChatのAPI Keyフィールドに貼り付けて、サーバー設定を保存します。ステップ5では、まったく同じ値をDeepSeek HarnessのカスタムプロバイダーのAPI keyフィールドに貼り付けます。
サーバーのバインド先をデフォルトのループバックアドレスである127.0.0.1のままにする場合は、atomic-localのような単純な値でも動作します。
ただし、フィールドを空のままにしないでください。DeepSeek Harnessはキーが空のプロバイダー設定を保存できますが、最初のリクエストを拒否します。
サーバー設定のほかのデフォルト値は次のとおりです。
| 設定項目 | 値 |
|---|---|
| Server Host | 127.0.0.1 |
| Server Port | 1337 |
| API Prefix | /v1 |
| Request timeout | 600秒 |
ステップ4：DeepSeek Harnessを起動する
ターミナルを開き、エージェントに使用させたいプロジェクトに移動します。Harnessを起動したディレクトリが、デフォルトのファイルシステム上の場所になります。
Node.jsがインストールされていることを確認してから、ウェブインターフェースを起動します。
node --version npx @deepseek-ai/dsh web
初回実行時には、npxがパッケージと約60個のスコープ付き依存パッケージをダウンロードします。コマンドがローカルURLを表示するまで待ちます。
dsh web: http://127.0.0.1:3080
このコマンドはブラウザでHarnessを開きます。ブラウザを自動で開かないようにするには、--no-openを追加します。
このバージョンは開発者プレビューのため、初回起動時にプレビューに関する通知が表示されます。
DeepSeek APIキーの入力も求められます。この入力画面はDeepSeekのホスト型サービス用であり、ここではローカルAIモデルを使うため、Configure laterを選択します。
ステップ5：Atomic Chatをカスタムプロバイダーとして追加する
DeepSeek HarnessでSettingsを開き、続いてModelsを開きます。デフォルトではホスト型プロバイダーを参照しています。ローカルモデルを使うには、Add a custom providerを選択します。
次の値を入力します。
| フィールド | 値 |
|---|---|
| Provider ID | atomic |
| Display name | Atomic Chat |
| Base URL | http://127.0.0.1:1337/v1 |
| API protocol | openai-completions |
| API key | Atomic Chatで設定したキー |
プロバイダーIDは小文字にしてください。このIDは後から変更できず、Harnessが使用する認証情報名も決定します。たとえば、プロバイダーID atomicはATOMIC_API_KEYに対応します。
Base URLには、/v1プレフィックスを含める必要があります。
Fetch available modelsを選択します。Harnessがエンドポイントに問い合わせ、Atomic Chatが現在提供しているモデルを一覧に表示します。この1回の確認で、次のことがわかります。
- ローカルサーバーに接続できること。
- Base URLに正しいAPIプレフィックスが含まれていること。
- APIキーが一致していること。
- Atomic Chatにモデルが読み込まれていること。
プロバイダーを保存します。緑色のステータスドットは認証情報を正しく解決できていることを示し、赤色のドットは解決できていないことを示します。
ステップ6：モデルとワークスペースを選択する
Harnessのメイン画面に戻り、モデル選択メニューを開きます。モデルはプロバイダーごとにグループ化されているため、ローカルモデルはAtomic Chatの下に表示されます。
モデルを選択してから、Choose workspaceを選択し、プロジェクトディレクトリを追加します。ワークスペースを選択するまで、メッセージ入力欄は無効のままです。
DeepSeek Harnessは、この設定を次の場所に保存します。
$DSH_HOME/settings.yaml
DSH_HOMEが設定されていない場合、デフォルトの保存先は~/.dsh/settings.yamlです。
settings.yaml内のルートには、プロバイダーURL、プロトコル、認証情報を保持する環境変数の名前が含まれます。APIキー自体は保存されません。
Atomic ChatのRunボタンは、同じ設定を自動的に書き込みます。プロバイダーID、エンドポイント、モデルID、認証情報が一致していれば、Harnessのインターフェースで作成したプロバイダーとAtomic Chatで設定したプロバイダーは、どちらでも同じように使用できます。
ステップ7：最初のローカルエージェントタスクを実行する
たとえば、次のような簡単なプロンプトで動作を確認してみましょう。
Summarize this project and list every HTTP route it exposes.
エージェントが調査を行います。
結果は次のとおりです。
または、AIにファイルの作成を依頼します。
権限、プラグイン、エージェントモードを設定する
Harnessでは、各セッションに与えるコンテキストの量や機能も制御でき、非常に強力です。
エージェントプリセットを選ぶ
DeepSeek Harnessには、Standard、PTC、Minimal、Creatorのプリセットがあります。Creatorモードでは、カスタムエージェント設定の草案を作成できます。
プリセット選択メニューは、セッションの開始時または設定時に使用できます。
Standardモードはモデルに幅広いツールとスキルのカタログを提供しますが、その分、初期プロンプトが大きくなります。私たちの測定では、Standardのシステムプロンプトは約11,900トークンで、初回実行時にキャッシュされるため、システムに負荷のかかるモデルを使っている場合は多少時間がかかることがあります。同じセッション内の後続メッセージは、ランタイムがプロンプトのプレフィックスを再利用するため大幅に高速になり、私たちのケースではキャッシュヒット率が90%に達したので、この点を念頭に置いてください。
最初のターンの待ち時間が主な問題であれば、Minimalモードを試してください。このモードでは公開されるツールが2つだけになり、カタログの大部分がプロンプトから取り除かれます。
セッションのアクセスモードを設定する
各セッションでは、次の3つのアクセスモードのいずれかを使用できます。
- Read Onlyでは、エージェントはワークスペースを変更せずに調査できます。
- Workspace Writeでは、選択したプロジェクト内の変更が許可されます。
- Full accessでは、エージェントにより広範なファイルシステムへのアクセスを許可します。
Read Onlyで書き込みを試みると、サンドボックスが拒否します。エージェントはエラーを読み取り、理由を文章で示して権限の昇格を要求でき、その後HarnessがRejectまたはAllow onceの選択を求めます。
1回限りの承認を行うと、編集が適用され、会話履歴に表示されます。
プラグインを設定する
Harnessの中心にあるのは、すべてをプラグインにするという考え方です。私たちの環境には初期状態で165個の項目があり、それぞれを有効または無効にできました。Shell、Agent loop、Web searchには専用の設定タブがあります。
DeepSeek Harnessのプラグインツリーは次のようになっています。
タスクに不要な機能を無効にすると、利用可能な機能の範囲とモデルが処理する指示文の量が減り、パフォーマンスが向上します。
組み込みコマンド
DeepSeek Harnessには、アクティブなセッション内で実行できる便利なコマンドもあります。
compactexportfeedbackgoalpermissionplanmodel
アクティブなモデルを切り替えるにはmodel、アクセスモードを変更するにはpermissionを使用し、長いセッションでコンテキストを小さくする必要がある場合はcompactを使用します。
セットアップ時に起こりうるエラーの対処法
ローカルモデルでDeepSeek Harnessを実行する際に私たちが遭遇した問題と、その対処法を紹介します。
最初のメッセージで「No API key for provider」が表示される
APIキーがなくてもプロバイダーは保存され、最初のメッセージを送信したときに初めてエラーが発生します。
This turn failed — No API key for provider: atomic
エラーコードはPI_AI_ERRORで、接続の問題のように見えます。実際には接続の問題ではありません。Atomic ChatのAPI Keyフィールドは初期状態では空で、DeepSeek Harnessは認証情報のないルートにリクエストを送信しません。Atomic ChatのServer Configurationでキーを設定し、Harnessのカスタムプロバイダーに同じ値を入力してください。
「Fetch available models」で何も返されない、または取得に失敗する
取得結果が空の場合、Atomic Chatにモデルが読み込まれていません。401が返される場合、両者のAPIキーが一致していません。まったく接続できない場合は、Base URLの末尾が/v1になっていることと、ポートがServer Configurationの設定と一致していることを確認してください。
メッセージ入力欄に「Select model」と表示され、入力できない
これは、プロバイダーのモデル一覧を変更した後に発生します。Harnessはsettings.yamlのagent-default-model配下に以前のデフォルト設定を保持しており、そのモデルIDが存在しなくなると、モデルを選び直すまで入力欄への入力がブロックされます。モデル選択メニューを開き、Atomic Chatが現在提供しているモデルを選択してください。
短い回答でもエージェントが実用に耐えないほど遅い
モデルのサイズが空きメモリに収まるか確認してください。16 GBのマシンでは、4ビット量子化の9Bモデルはコンテキストキャッシュが追加されるとメモリに常駐できなくなり、重みの一部がディスクにページアウトされ、生成速度が毎秒約0.3トークンまで低下して、エージェントの1ステップに数分かかりました。同じ量子化の4Bモデルでは、同じタスクを4回のツール呼び出しで最初から最後まで実行できました。エージェントのコンテキストも同じメモリを使用するため、実用上の上限はファイルサイズから想定されるものより低くなります。
セッションの最初の応答だけが遅い場合は、システムプロンプトの処理とキャッシュが行われているためなので、上のエージェントプリセットのセクションを参照してください。
初回実行時にnpxが停止しているように見える
このパッケージは約60個のスコープ付き依存パッケージを取得し、それらを解決している間は何も表示しません。初回実行時には、ローカルURLが表示されるまで数分かかる場合があります。処理が停止しているわけではありません。
よくある質問
DeepSeek Harnessと、ローカルモデルに接続して実行する方法について、よくある質問を紹介します。
DeepSeek Harnessとは？
DeepSeek Harness、別名dshは、DeepSeek AIが開発したオープンソースのエージェントハーネスです。AIモデルをツール、ファイル、シェルコマンド、セッション、サンドボックス、ストレージなど、エージェントとして動作するための機能に接続します。
DeepSeekは、Cordisプラグインシステムを中心にHarnessを構築しています。モデル、ツール、スキル、エージェントループ、ストレージ、スケジューリング、ユーザーインターフェースは、すべて交換可能なプラグインとして動作できます。
DeepSeek HarnessはAIモデルですか？
いいえ。DeepSeek Harnessは言語モデルではなく、エージェントソフトウェアです。対応するモデルがファイルの調査、コマンドの実行、コードの編集、情報の検索、複数のステップからなるタスクの完了を行うためのランタイムとツールを提供します。
言語能力と推論能力はモデルが提供します。Harnessは、モデルが周囲の環境とやり取りする方法を制御します。
DeepSeek Harness自体がモデルを実行するのですか？
いいえ。DeepSeek Harnessは、推論を実行するモデルプロバイダーに接続します。ホスト型APIがモデルを提供することも、Atomic Chatなどのソフトウェアがモデルをローカル実行し、OpenAI互換API経由で公開することもできます。
この構成では、Atomic Chatがモデルの読み込みと推論を担当し、DeepSeek Harnessがエージェントループとツールを管理します。
DeepSeek Harnessは無料ですか？
はい。DeepSeek Harnessは、MIT Licenseの下で公開されているオープンソースソフトウェアです。Harness自体の利用にサブスクリプション料金を支払う必要はありません。
モデルの費用は、設定するプロバイダーによって異なります。ホスト型APIではトークン数に応じて課金される場合がありますが、ローカルでホストするモデルはトークン単位のAPI料金なしで実行できます。
DeepSeek HarnessでローカルAIモデルを実行できますか？
はい。DeepSeek Harnessは、互換性のあるモデルプロバイダーまたはAPIエンドポイント経由でローカルモデルを使用できます。モデルサーバーはHarnessが利用できるインターフェースを公開する必要があり、選択したモデルはエージェントが必要とする機能に対応していなければなりません。
この構成では、Atomic ChatがモデルランタイムとOpenAI互換APIを提供します。
DeepSeek HarnessをAtomic Chatに接続するにはどうすればよいですか？
DeepSeek Harnessでカスタムモデルプロバイダーを次のように設定します。
- Base URL:
http://127.0.0.1:1337/v1 - Protocol:
openai-completions - API key: Atomic Chatで設定したものと同じ値
その後、Atomic Chatが公開しているローカルモデルを選択します。
ローカルモデルにはツール呼び出しへの対応が必要ですか？
はい。ツール呼び出しへの対応が明記されているモデルを選んでください。DeepSeek Harnessは、ファイルの調査、コマンドの実行、プロジェクト内の検索などのエージェント操作を、構造化されたツールリクエストに依存して行います。
通常のテキストしか生成しないモデルは、質問に正しく答えられても、Harnessのツールを安定して操作できない場合があります。
DeepSeek Harnessは完全にオフラインで動作しますか？
はい、ただし制限があります。DeepSeek Harness、その依存パッケージ、Atomic Chat、モデルファイルをダウンロードした後は、基本的なローカルワークフローをインターネット接続なしで実行できます。
外部サービスに接続する機能には、引き続きインターネット接続が必要です。これには、ウェブ検索、リモートMCPサーバー、オンラインのモデルAPI、パッケージレジストリ、ウェブに接続するプラグインが含まれます。
DeepSeek Harnessは私のコードやリポジトリをDeepSeekに送信しますか？
DeepSeekのデータ処理に関するドキュメントによると、DeepSeek Harnessはデフォルトで、プロンプト、モデル出力、ツールの記録、ファイルパス、ランタイムデータをローカルに保存します。モデルのエンドポイントが127.0.0.1を指している場合、ローカルモデルの推論もコンピューター内で完結します。
外部のモデルプロバイダー、ウェブツール、MCPサーバー、プラグインは、それぞれのサービスにデータを送信することがあります。DeepSeekは、トラブルシューティングと製品改善のために、Harnessが匿名化された設定情報やプロジェクト一覧を報告する場合があるとも述べており、ユーザーはその報告を無効にしたり、送信先を変更したりできます。
DeepSeek Harnessの設定はどこに保存されますか？
DeepSeek Harnessは、デフォルトの設定を~/.dsh/settings.yamlに保存します。
DSH_HOMEでHarnessのホームディレクトリを独自に設定した場合は、$DSH_HOME/settings.yamlが使用されます。
Harnessは、シークレットの値をYAML設定に直接保存する代わりに、環境変数名を通じてAPIシークレットを参照できます。
DeepSeek Harnessをインストールするにはどうすればよいですか？
Node.jsをインストールしてから、npx @deepseek-ai/dsh webで公式のWeb UIを起動します。
デフォルトでは、Harnessはhttp://127.0.0.1:3080でローカルWeb UIを提供します。開発者は、公式GitHubリポジトリをクローンし、ソースからHarnessをビルドすることもできます。
DeepSeek HarnessはWindowsで動作しますか？
はい。ただし、一部のランタイム機能やサードパーティー連携は、OSによって異なる場合があります。主要なWeb UIとCLIにはWindows向けの実行経路がありますが、一部の開発用コンポーネントはLinuxやmacOSをより直接的な対象としている場合があります。
プラットフォーム固有のシェル、サンドボックス、PTY、プラグインの動作に依存する前に、現行リリースのドキュメントを確認してください。
DeepSeek HarnessはClaude CodeやCodexとどう違いますか？
DeepSeek Harnessは、構成要素を組み合わせられることと、特定のモデルに依存しないことを重視しています。モデル、ツール、スキル、ストレージ、サンドボックス、セッション、エージェントループ、さらにはインターフェースまで、プラグインアーキテクチャを通じて公開します。
Claude CodeとCodexは、それぞれが対応するワークフローに沿って、より明確な設計方針を持つコーディングエージェント製品を提供しています。リポジトリの調査、コードの編集、シェルの使用、別のエージェントへの作業委任といったタスクには共通点がありますが、ランタイムと拡張機能のアーキテクチャは異なります。
要点
- DeepSeek Harnessは、AIモデルを実際に動作するエージェントに変えるための、DeepSeekのオープンソースフレームワークです。設計の中心にあるのは、すべてをプラグインにするという考え方で、モデル、ツール、ストレージ、インターフェース、エージェントの動作をその場で交換したり組み合わせたりできます。
- DeepSeek Harnessは、互換性のある任意のプロバイダーを通じてローカルモデルに接続できます。Atomic Chatは、モデルランタイムを提供し、OpenAI互換APIを公開できます。
- ローカルプロバイダーが
http://127.0.0.1:1337/v1を使用するように設定し、openai-completionsプロトコルを選択して、Atomic Chatと同じAPIキーを入力します。 - ツール呼び出しへの対応が明記されているモデルを使用してください。テキストのみを出力するモデルは、一般にHarnessのツールを安定して操作できません。
- アプリ、必要なパッケージ、モデルファイルをダウンロードした後は、ホスト型モデルのAPI料金や継続的なインターネット接続なしで、主要なワークフローをローカル実行できます。
