2026年版 DeepSeek Harnessのカスタムモデル接続

DeepSeek Harnessでは、公式APIを直接使う場合と、インストール済みカタログのProviderを使う場合、独自の接続先を登録する場合で、確認すべき範囲が異なります。特に、モデルを切り替えるだけなのに同じサービスの設定を複数作ると、認証情報、既定モデル、既存会話の記録が分散し、障害原因を追いにくくなります。

カタログProviderは、インストール済みの定義からエンドポイント、プロトコル、モデル一覧を解決します。一方、カスタムProviderは、接続先がOpenAI互換APIを名乗っているだけでは十分ではなく、DeepSeek Harnessが実際に送る認証方式、モデル指定、一覧取得の動作まで確認する必要があります。公式ガイドも、会社のゲートウェイ、自社運用サーバー、カタログにないProviderをカスタムProviderの対象として説明しています。 公式設定ガイドのProvider分類

設定画面を開く前に、接続先の管理者から次の情報を受け取ります。ここが曖昧なままだと、保存は成功してもモデル検出や初回リクエストで止まります。

• Provider ID：リクエスト、保存済み会話、既定モデル、認証情報の参照に使われる識別子です。公式ガイドでは小文字で入力し、保存後は恒久的な値として扱われます。
• Base URL：モデルサービスへ接続する基点URLです。ゲートウェイ側が想定するパスと、DeepSeek Harness側が追加するAPIパスが重複しないか確認します。
• APIプロトコル：OpenAI互換APIとして処理するのか、別のプロトコルを使うのかを決めます。Base URLが正しくても、プロトコル選択が違えばリクエスト形式が一致しません。
• 認証情報とモデルID：APIキー、環境変数参照、または接続先固有の認証情報と、実際に呼び出せるモデルIDを用意します。

Provider IDは表示名と違い、後から気軽に変更する名前ではありません。名称を変えたい場合は、公式ガイドの説明どおり、新しいProviderを追加してから旧Providerを削除する運用にします。 Provider IDと認証情報の公式説明

DeepSeek HarnessのWeb UIで Settings → Models を開き、カスタムProviderの追加を選びます。現行の開発者プレビューでは画面や項目名が変わる可能性があるため、以下は公式ガイドに記載された概念と確認順として扱い、実際の入力欄は使用中の版に合わせます。

1. Provider IDを小文字で決め、命名規則をチーム内で記録します。
2. Base URLを入力し、末尾のパスがゲートウェイの仕様と一致するか確認します。
3. APIプロトコルを選び、接続先が想定するリクエスト形式と照合します。
4. 認証情報を登録します。キーは画面上で再表示されず、設定側には認証情報そのものではなく参照情報が保存されます。
5. 少なくとも1つのモデルを登録し、保存します。

認証情報の保存先について、公式ガイドはキー本体を $DSH_HOME/.credentials.yaml に保存し、設定には認証情報の参照だけを残すと説明しています。設定ファイルを共有するときに、キーを含むファイルをそのまま添付しないことが重要です。 認証情報の保存仕様

保存後は、いきなり重要なリポジトリでAgentを動かさず、モデル一覧の取得から始めます。カスタムProviderのモデルカタログで利用可能なモデルを取得し、候補を選んで保存します。公式ガイドでは、一覧取得はフォームに表示されたBase URLと認証情報を使い、Providerは保存するまで確定しないと説明されています。 モデル検出の公式手順

成功の判断は、単にProviderが保存されたことではありません。モデル選択欄に期待するIDが表示され、選択したモデルが新しい会話の既定値として選べることまで確認します。

• 401が返る場合：認証情報を確認します。モデル検出はOpenAI互換の GET /models を使うため、推論リクエストだけ許可して一覧取得を拒否するゲートウェイでは失敗します。
• 一覧が空、または取得機能が使えない場合：接続先がモデル一覧を提供していない可能性があります。管理者から受け取った正確なモデルIDを手入力します。
• 選択後にモデルが見つからない場合：Provider IDやモデルIDの綴りを確認します。表示名ではなく、エンドポイントが受け付ける識別子を登録します。

注意：保存成功、モデル一覧取得成功、推論成功は別々の検証です。3つを一つの「接続できた」という判定にまとめると、認証、モデル名、API仕様のどこで止まったのか分からなくなります。

モデルを選べたら、隔離したワークスペースで新しい会話を作成します。最初からソースコードの編集やシェル操作を許可せず、次の順番で実行すると、失敗範囲を限定できます。

1. 短い文章の要約を依頼します。
2. 実際に選択されたProviderとモデルを画面またはログで記録します。
3. 応答状態、応答本文、失敗内容を保存します。
4. 読み取り専用の情報取得など、影響範囲を限定したツール呼び出しを1つだけ追加します。
5. ツールの引数、実行許可、結果の返送、最終応答まで確認します。
6. 失敗した場合は、同じ会話で設定を何度も変更せず、原因を分類して検証済みルートへ戻します。

テキスト応答が成功しても、ツール呼び出しまで動くとは限りません。ゲートウェイが通常のチャット処理には対応していても、ツール関連のメッセージ形式、ストリーミング、権限制御を変換できない場合があるためです。ここは「OpenAI互換API」と書かれていることだけで互換性を断定せず、実際の最小ツール呼び出しで確認します。

上記の作業でよく発生する問題は、保存、検出、推論、会話状態を分けて考えると整理できます。特にモデル一覧取得の401は、モデルが存在しないのではなく、一覧取得用の認証や権限が不足しているケースがあります。

FAQは、接続先が一覧APIを提供しない場合の手入力、既定値と既存会話の違い、Provider IDの固定という3点を中心に確認してください。なお、公式ガイドにないエラーコードや未確認のサービス互換性を、DeepSeek Harnessの保証として扱うことは避けます。

モデルを選択すると、そのモデルは新しい会話の既定値になります。しかし、すでにリクエストを送った会話は、自身のログに記録されたモデルを保持します。そのため、旧会話が新しいProviderへ自動移行すると考えてはいけません。 会話ごとのモデル保持に関する公式説明

Providerを削除した後に既定モデルが参照先を失うと、モデル選択を求められ、入力が止まる状態になります。この場合は旧会話の履歴を守ろうとして設定を上書きし続けるのではなく、新しい会話を作成して、検証済みのProviderとモデルを選び直します。

運用上は、次のように分けると安全です。

• 旧会話：再現性のため、当時のProviderとモデルを記録したまま保管します。
• 新会話：新しいProviderを選び、最小テキストとツール呼び出しを再実行します。
• 既定値：新規作成時に使うモデルだけを変更します。
• 旧Provider：新ルートの検証完了後に削除します。

安定運用へ移る前に、Provider ID、Base URL、APIプロトコル、認証情報の参照先、モデルID、変更日時、検証結果を記録します。キー本体を記録するのではなく、どの保管場所や環境変数を参照するかだけを管理台帳に残します。

DeepSeek Harness自体が開発者プレビューであり、公式リポジトリも互換性を壊す変更の可能性を明記しています。そのため、Harnessを更新した場合やモデルゲートウェイを更新した場合は、少なくとも次の受け入れ確認を再実行します。 公式READMEの開発者プレビュー告知

• 認証情報を読み込める。
• モデル一覧を取得できる、または登録済みの手入力モデルを選べる。
• 新しい会話で短いテキスト処理が成功する。
• 隔離されたツール呼び出しが成功する。
• 失敗時に、検証済みProviderを新しい会話から選び直せる。

現在の方式が開発者のノートPCだけに依存している場合、スリープ、VPNやDNSの差、権限設定の個人差、認証情報の混在が継続運用の弱点になります。社内ゲートウェイを一時的に検証する段階なら、常時接続しやすく、作業領域を分離できるmacOS環境で確認したほうが、端末固有の問題とモデル接続の問題を切り分けやすくなります。

必要な期間だけ隔離されたMac環境を用意する場合は、日本向けのMacレンタル環境や、利用者のネットワーク条件に合う米国東海岸のMac環境を候補にし、本文のチェック項目をそのまま受け入れ手順にしてください。長期の固定負荷や物理インターフェースが必要な運用では自社保有環境が適しますが、モデルゲートウェイの隔離検証や短期の回帰確認なら、NUKCLOUDのMac環境を使うほうが、端末の停止、設定のばらつき、検証後に余剰機材を抱える問題を避けやすい選択です。