DeepSeek Harness（dsh）にはDeepSeek独自のモデルが組み込まれていますが、それらに縛られることはありません。このハーネスは、モデルプロバイダーを構成として扱います。プロバイダーブロックを任意のOpenAI互換エンドポイントに向け、クレデンシャル参照を渡せば、エージェントセッションはそのURLの背後にある任意のモデルで実行されます。ローカルのOllamaインスタンス、企業のゲートウェイ、DashScopeの互換モードを介したQwen、あるいはAnthropicやOpenAIのような大規模なカタログプロバイダーもすべて同じブロックに接続できます。
このガイドでは、そのブロックをキーごとに詳しく説明し、その後、3つの実践的なレシピ（ローカルモデル、ホストされたOpenAI互換エンドポイント、組み込みのカタログプロバイダー）を構築します。ここに引用されているすべての内容は、2026年8月20日に取得したマスターブランチの公式プロバイダーガイドからのものです。ただし、最初に注意点があります。dshは開発者プレビューであり、READMEでは互換性を損なう変更がある可能性があると大文字で警告しています。本番環境に何かをコピーする前に、インストールされているバージョンとドキュメントを照合してください。
ハーネス自体が初めての方は、まずDeepSeek Harnessとは何か、どのように機能するかを読んでから、プロバイダーの配線についてはここに戻ってください。
なぜエージェントハーネスでモデルを切り替える必要があるのか
エージェントハーネスはループです。モデルが計画し、ツールを呼び出し、結果を読み取り、これを繰り返します。ハーネスがループを所有し、モデルは「材料」です。材料を変更する理由は3つあります。
コスト。エージェントセッションは、すべてのツール結果がコンテキストにフィードバックされるため、トークンを急速に消費します。ルーティンセッションをより安価なモデル、またはV4-ProではなくDeepSeek V4-Flashにルーティングすることで、ワークフローを変更せずに費用を抑えることができます。高価なフロンティアモデルは、それが必要なセッションのために設定を維持できます。
データローカリティ。一部のコードベースは外部に持ち出せません。自社ハードウェアで実行されているモデルを指すプロバイダーブロックを使用すると、プロンプト、ファイルの内容、ツール出力がネットワークを越えることはありません。同じハーネス、同じUI、ゼロエグレス。
ローカル開発。プラグインを構築したり、エージェントの動作をテストしたりする際、すべてのイテレーションでAPIクレジットを消費したり、ネットワークに依存したりしたくありません。小さなローカルモデルはループをテストするのに十分な速度で応答し、動作が重要になるときに実際のモデルに戻すことができます。
この設計はdshのアーキテクチャに基づいています。ハーネス内のすべてがプラグインであり、モデルアダプターはその交換可能な部分の1つです。プロバイダーのルーティングはdsh-llm-pi-aiプラグインが所有しており、これはリポジトリのプラグイン設定カタログで「このインスタンスが所有するプロバイダーのルーティング」として文書化されています。それが仕組みです。ユーザーが操作するインターフェースは1つのYAMLブロックです。
プロバイダーブロックのキーごとの説明
カスタムプロバイダーは$DSH_HOME/settings.yamlに保存され、ウェブUIの「設定」→「モデル」からも作成できます。以下は公式ドキュメントからの例です。
llm-pi-ai:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
models:
- id: legacy-chat
- id: vision-preview
input: [text, image]
各キーの役割：
my-gatewayはプロバイダーIDです。永続的な識別子なので、使いやすい名前を選んでください。UIに表示される表示名は別途設定されます。apiKeyEnvはAPIキーを保持する環境変数の名前を指定します。設定ファイルにはシークレット自体は含まれず、この参照のみが含まれます。実際のキーの保存場所については後述します。apiはワイヤープロトコルを宣言します。openai-completionsはOpenAI互換エンドポイントで文書化されている値であり、「どんなモデルでも」という約束を可能にするものです。ほとんどのゲートウェイ、ローカルランタイム、ホスト型プロバイダーはこのプロトコルを話します。baseURLはハーネスがリクエストを送信するエンドポイントのルートです。modelsはこのプロバイダーを通じて利用可能なモデルIDのリストです。各エントリには少なくともidが必要で、これはエンドポイントがリクエストボディで期待するものと一致する必要があります。inputはモデルごとのモダリティを宣言します。カスタムモデルはデフォルトでテキストのみであるため、ビジョンモデルは明示的にinput: [text, image]を宣言しないと、画像添付ファイルはモデルに届きません。プロバイダー内のすべてのモデルにフォールバックを設定するルートレベルのdefaultInputもありますが、モデルレベルのinputがそれを上書きします。compatは、OpenAIの標準的な動作から逸脱するエンドポイントの互換性スイッチを保持します。ドキュメントには2つ挙げられています。developerロールを拒否するバックエンドのためのsupportsDeveloperRole: falseと、古い出力キャップフィールド名を求めるバックエンドのためのmaxTokensField: max_tokensです。compatはルートレベルまたはモデルごとに設定できます。
知っておくと便利な機能の1つとして、Web UIからカスタムプロバイダーを追加する際に、「利用可能なモデルを取得」オプションがエンドポイントのOpenAI互換GET /modelsルートにクエリを発行し、モデルリストを自動で入力してくれます。エンドポイントがそのルートを実装していれば、手動入力をスキップできます。
実際のAPIキーはどこに保存されるか
シークレットは$DSH_HOME/.credentials.yamlに書き込み専用で保存されます。UIを通じてキーを保存すると、dshは編集された記述子のみを返し、リテラル値は二度と表示されません。settings.yamlは参照（apiKeyEnv名、クレデンシャル記述子）のみを保持し、キー自体は保持しません。この分離により、設定ファイルをコミットまたは共有しても情報が漏洩せず、プロバイダー設定に触れることなくキーをローテーションできます。
レシピ1：Ollamaを介してローカルモデルを実行する
Ollamaはhttp://localhost:11434/v1でOpenAI互換APIを公開しています。これはOllama自身のOpenAI互換性ガイドで文書化されています。dshは任意のベースURLに対してopenai-completionsを話すため、ペアリングは簡単です。
【確認：dshのドキュメントにはOllama固有の例は示されていません。このレシピは、文書化されたカスタムプロバイダースキーマをOllamaの文書化されたOpenAI互換エンドポイントに適用したものです。内部で公開する前に、ご自身のインストール環境でテストしてください。】
llm-pi-ai:
providers:
ollama-local:
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://localhost:11434/v1
models:
- id: gpt-oss:20b
- id: qwen3
この点に関する注意点：
- OllamaはローカルではAPIキーを必要としませんが、スキーマはクレデンシャル参照を期待するため、ダミー値（例：
export OLLAMA_API_KEY=ollama）を設定します。Ollamaは送信されたものを無視します。 - モデルの
idは、Ollamaが提供するタグと一致する必要があります。ollama listを実行し、タグを含めて名前を正確にコピーしてください。 - dshに接続する前に、まずモデルをプルし（
ollama pull gpt-oss:20b）、サーバーが応答することを確認してください。完全なローカルセットアップについては、Ollamaを使用してGPT-OSSを実行する方法で説明しており、同じパターンは、お使いのハードウェアが対応していればKimi K3などの他のオープンウェイトモデルにも適用できます。
混乱を招くエージェントセッションを避けるための簡単な健全性チェック：dshの設定に触れる前に、Apidogでhttp://localhost:11434/v1/modelsにアクセスしてみてください。このリクエストがモデルリストを返せば、ベースURLは正しく、サーバーは稼働しており、dsh UIの「利用可能なモデルを取得」も機能します。そうでなければ、どんなハーネス設定も解決策にはなりません。
期待値管理：エージェントハーネスは、ツール呼び出しと長いコンテキストに強く依存します。小さなローカルモデルはテスト用のループを処理できますが、ハーネスが構築されたフロンティアモデルと比較して、計画が劣り、ツール呼び出しをより頻繁に落とすでしょう。これはプラグイン開発には問題ありませんが、実際の作業にはフラストレーションがたまります。
レシピ2：ホスト型OpenAI互換エンドポイント（DashScope経由のQwen）
ホスト型の例では、OpenAI互換性があると思い込んでいるベンダーではなく、OpenAI互換性を文書化しているベンダーを選びましょう。Alibaba Cloud Model Studio (DashScope) はそうしています。そのOpenAI互換性ページには、Qwenモデル用の/compatible-mode/v1エンドポイントが文書化されており、地域ごと、ワークスペースごとのドメイン（シンガポールの場合：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1）と、DASHSCOPE_API_KEY環境変数による認証が示されています。
dshスキーマへのマッピング：
llm-pi-ai:
providers:
qwen-dashscope:
apiKeyEnv: DASHSCOPE_API_KEY
api: openai-completions
baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
models:
- id: qwen3-max
{WorkspaceId}をModel Studioコンソールからの実際のワークスペースドメインに置き換え、ベンダーのモデルリストで現在のIDを確認してください。我々はフラッグシップ層の概要をQwen 3.8 APIガイドで紹介しています。同じパターンは、OpenAI互換性を文書化しているすべてのベンダー（MoonshotのKimi API、OpenRouter、vLLMデプロイメント、または企業の内部ゲートウェイ）に拡張できます。Codexでオープンソースモデルを設定したことがある方には馴染み深いでしょう。dshのYAMLブロックはCodexのmodel_providers設定と同じ役割を果たします。
ホスト型エンドポイント固有の2点：
- ベンダーのエンドポイントが、役割やトークンフィールドに関する奇妙なエラーでリクエストを拒否する場合、そのために
compatスイッチが存在します。まずsupportsDeveloperRole: falseを試してください。古いOpenAI互換の実装はdeveloperロールが登場する前のものです。 - ホスト型モデルが画像をサポートしていても、ビジョンモデルは明示的に
input: [text, image]を宣言する必要があります。dshは、特に指定がない限り、カスタムモデルはテキストのみと想定します。
レシピ3：組み込みのカタログプロバイダー
主要なクラウドには、カスタムブロックは必要ありません。dshには、DeepSeek、Anthropic、OpenAIのカタログプロバイダーが組み込まれており、設定はほとんど「APIキーを貼り付ける」だけです。特殊なカタログエントリには独自のネイティブ認証フローがあります。BedrockはAWSのクレデンシャルを使用し、VertexはADCプロジェクトを必要とし、AzureはそのAPIバージョンを、CodexはOAuthを介して認証します。
カタログプロバイダーは、ハーネスの背後でClaudeやGPTを使いたい場合に摩擦の少ないパスであり、DeepSeek V4-ProのAPIが2026年8月にハーネス自体と同時にローンチされたため（詳細はapi-docs.deepseek.com）、ほとんどの人がこれを使用してDeepSeek V4-Proを実行するでしょう。カスタムプロバイダーは、カタログがカバーしていないすべてのもの、つまりローカルランタイム、ゲートウェイ、地域ベンダー、OpenAI互換のアグリゲーター向けです。
モデルの選択とセッションが記憶すること
プロバイダーを追加するとそのモデルが利用可能になり、「設定」→「モデル」でモデルを選択すると、新規セッションのデフォルトになります。ドキュメントから理解しておくべき2つの挙動があります。
- 既存のセッションは、開始時に使用したモデルを維持します。セッションは元のモデルを記録するため、プロジェクト途中でデフォルトを変更しても、履歴がサイレントに書き換えられたり、進行中のセッションが使用するモデルが変わったりすることはありません。
- 現在のデフォルトを所有するプロバイダーを削除した場合、新しいモデルを選択するまでコンポーザーは入力をブロックします。ハーネスは推測するのではなく、明確に失敗します。
このセッションの固定は再現性にとって重要です。dshを他のハーネスと比較する際（我々はDeepSeek Harness vs Claude Codeでまさにそうしました）、セッションのトランスクリプトが途中でモデルが切り替わることなく、1つのモデルを反映していると信頼できます。
一般的な失敗のトラブルシューティング
間違ったまたは到達不能なbaseURL。最も一般的な失敗は、最も一般的でないものではありません。プロトコルが期待する場所（通常、OpenAI互換エンドポイントの場合は/v1、DashScopeの場合は/compatible-mode/v1）でURLが終了していることを確認し、ハーネス外で通常のGET {baseURL}/modelsが成功することを確認してください。これはApidogをダウンロードする価値が5分でわかるチェックポイントです。ハーネスが送信するのと同じヘッダー（Authorization: Bearer $KEY）でリクエストを送信し、ラップされたハーネスエラーではなく、実際のステータスコードとボディを読み取ってください。オフラインで開発している場合やベンダーが不安定な場合は、Apidogでプロバイダーの/modelsと/chat/completionsの応答をモックし、ビルド中にbaseURLをそのモックに向けます。
環境変数の不足または空。apiKeyEnvは変数の名前を指定するものであり、変数を作成するものではありません。dshが実際に実行されている環境で変数が設定されていない場合、リクエストは認証されずに送信され、401エラーで返ってきます。GUIまたはサービスマネージャーから起動されたプロセスは、シェルプロファイルを継承しない場合があることに注意してください。dsh webを起動するのと同じコンテキストでecho $GATEWAY_API_KEYを実行し、単なる適当なターミナルで実行しないようにしてください。
入力モダリティの不一致。画像を添付しても、モデルがそれを見ないか、リクエストがエラーになります。カスタムモデルはデフォルトでテキストのみです。モデルエントリにinput: [text, image]を追加するか、プロバイダーのすべてのモデルが画像を処理する場合はルートレベルでdefaultInputを設定してください。
プロトコルの癖。サポートされていない役割や拒否されたトークンパラメータに関するエラーは、互換性スイッチを指しています。文書化されているのはsupportsDeveloperRole: falseとmaxTokensField: max_tokensの2つです。これらはcompatの下に記述します。
昨日まで全てうまくいっていたのに。開発者プレビュー版です。デプロイするバージョンを固定し、アップグレードする前にリリースノートを読み、設定スキーマが変更されることを想定してください。deepseek-harnessリポジトリが真実の情報源であり、ブログ記事（この記事も含む）ではありません。
もう1つの統合に関する注意点：モデルプロバイダーはカスタマイズの半分に過ぎません。もう半分はエージェントが呼び出せるツールであり、APIワークフローを直接接続できます。これについてはDeepSeek Harness内でApidog CLIを使用する方法で説明しています。
よくある質問
DeepSeek HarnessはOllamaを公式にサポートしていますか？
公式のプロバイダーのドキュメントにはOllamaの名前は挙げられていません。サポートしているのは、openai-completionsプロトコルを話す任意のエンドポイントであり、Ollamaはhttp://localhost:11434/v1でOpenAI互換APIを文書化しています。上記のレシピは、文書化された2つの部分を組み合わせたものです。dshは開発者プレビューであり、リリース間でスキーマが変更される可能性があるため、ご自身のインストール環境でテストしてください。
dshはAPIキーをどこに保存しますか？
$DSH_HOME/.credentials.yamlに、書き込み専用で保存されます。UIには保存後に編集された記述子が表示され、settings.yamlにはapiKeyEnv名のような参照のみが保持されます。プロバイダー設定内にプレーンテキストのキーが保存されることはありません。
異なるセッションで異なるモデルを実行できますか？
はい、可能です。モデルを選択すると、新規セッションのデフォルトが設定されるだけで、既存のセッションは開始時に使用したモデルを保持します。したがって、ルーティンセッションにはDeepSeek V4-Flashのような安価なモデルを使用し、難しい問題にはより強力なモデルにデフォルトを切り替えることができますが、以前のセッションは影響を受けません。
カスタムエンドポイントが、curlでは発生しないエラーを返します。どうすればよいですか？
正確なペイロードを比較してください。ハーネスがバックエンドが受け入れないdeveloperロールや新しいトークンキャップフィールドを送信している可能性があります。文書化されている修正は、compat下のsupportsDeveloperRole: falseとmaxTokensField: max_tokensです。ハーネス形式のリクエストをAPIクライアントで再現することで、バックエンドがどのフィールドで詰まっているかを確認できます。