DeepSeek Harnessの使い方【2026年版】プラグイン型AIエージェント基盤を構築する
オープンソースラボ編集部 ・ 2026年9月22日
DeepSeek Harnessは、DeepSeek AIが2026年8月に公開したオープンソースのエージェント実行基盤です。9月22日時点でGitHub Starsは232,323。急速に注目を集めていますが、名前から『DeepSeek専用のコーディングCLI』だと理解すると用途を誤ります。公式READMEが示す中心概念はEverything is a Pluginです。モデル、Agent Loop、ツール、権限、セッション、UI、MCPを交換可能なサービスとして構成し、自社向けのエージェント実行環境を作るための基盤です。
この記事では、公式のREADME↗とArchitecture↗をもとに、最短で動かす方法と、製品評価で見るべき点を整理します。DeepSeek Harnessはdeveloper previewであり、互換性を壊す変更があり得ると公式に明記されています。固定バージョン、再現可能な設定、検証用リポジトリを用意して始めてください。
DeepSeek HarnessとコーディングCLIの違い
| 観点 | DeepSeek Harness | Codex CLI / Claude Code型 |
|---|---|---|
| 主目的 | エージェント実行基盤を構成する | リポジトリ作業をすぐ実行する |
| モデル | providerプラグインで選択 | 製品の対応モデルを利用 |
| UI | Web、headless、SDK、ACPを構成 | 端末やIDEが中心 |
| 拡張 | サービスをプラグインで差し替え | Skills、MCP、Hooks等 |
| 状態 | Sessionサービスを構成・投影 | 製品のセッション管理 |
| 向く人 | エージェント製品の開発者 | AIでコードを書きたい利用者 |
既存リポジトリのバグを今すぐ直したいならCodex CLIなどの完成したCLIが短距離です。独自UI、社内ポリシー、複数モデル、永続イベント、独自ツールを一つの実行グラフとして管理したいならDeepSeek Harnessの価値が出ます。
アーキテクチャを先に理解する
基盤はCordisです。各プラグインが共有Contextへサービス、イベント、効果を登録し、アンロード時に登録を戻せる設計です。公式Architectureは『特権的なcoreを直接パッチするのではなく、隣にプラグインをmountする』考え方を説明しています。これにより、モデルアダプターだけ、ツールレジストリだけ、ポリシーだけを置き換えられます。
Profileは起動時の構成を選びます。Profileは複数Bundleとユーザーのpatchを重ね、最終的なプラグインツリーを作ります。配布テンプレートにはweb、headless、sdk、sdk-minimal、acpがあります。構成を変更したときは、動作の印象だけで判断せず、解決後のグラフを出力して、意図したprovider、tool、policy、sessionがmountされているか確認します。
最短でWeb UIを起動する
公式READMEの最短手順はNode.js環境で次のコマンドを実行することです。
npx @deepseek-ai/dsh web
標準ではhttp://127.0.0.1:3080でWeb UIが起動します。SSH越しでは自動でブラウザを開かず、転送先URLを表示します。ブラウザを開かせたくない場合は--no-openを付けます。
npx @deepseek-ai/dsh web --no-open
初回検証では公開IPへbindしないでください。公式の安全上の注意を読み、localhostだけで動かし、書き込み可能な専用フォルダを割り当てます。エージェントはファイル編集やシェル実行ができるため、Web UIを公開することはホスト上の実行権限を公開することにつながります。
導入前に用意するもの
| 項目 | 推奨する初期値 | 理由 |
|---|---|---|
| 対象リポジトリ | サンプルか複製 | 誤編集の影響を限定 |
| ネットワーク | localhostのみ | 未認証アクセスを防ぐ |
| APIキー | 環境変数・専用キー | 漏えい時に個別失効できる |
| モデル | 1モデルに固定 | Harnessとモデルの差を分離 |
| 同時実行 | 1 | 失敗と費用を追跡しやすい |
| バージョン | packageまたはcommit固定 | previewの破壊的変更へ備える |
| ログ | 秘密情報を除外して保存 | 再現と監査に使う |
モデルproviderを設定する考え方
DeepSeek HarnessはDeepSeekモデルだけに限定される製品ではありません。重要なのは、vendor、endpoint、model、認証情報を明示し、どのリクエストがどこへ送られるかを把握することです。APIキーを設定ファイルへ直接書き込まず、環境変数参照にします。設定例やキー名はpreview期間中に変わる可能性があるため、導入時点の公式Configuration↗を確認してください。
性能評価ではHarnessとモデルを混ぜて採点しないことが大切です。同じHarnessでモデルAとBを比べるテスト、同じモデルでHarnessと別CLIを比べるテストを分けます。そうしなければ、ツール選択の失敗をモデルの推論力だと誤認したり、モデルの差を実行基盤の差だと誤認します。
Profile、Bundle、Patchの使い分け
Profileは『この用途のエージェントをどう起動するか』という入口です。たとえば社内調査用、コードレビュー用、顧客サポート用を別Profileにします。Bundleは複数プラグインをまとまりとして再利用するときに使います。Patchは配布Bundleをforkせず、自社の設定や差し替えを重ねるために使います。
最初から巨大なProfileを作らず、モデルprovider、Agent Loop、最小ツール、Session、headlessまたはWebの順に一つずつ加えます。追加ごとに起動、1ターン実行、再起動、セッション再開、キャンセルを確認すると、不具合の境界を狭められます。
ツールと権限を分離して試す
評価用のテストは次の5種類に分けます。
- 読み取り：指定フォルダ外を読めないことを確認する。
- 書き込み：許可した作業領域だけを変更できるか確認する。
- シェル：無害なコマンド、長時間処理、失敗、キャンセルを試す。
- ネットワーク：許可先、リダイレクト、取得内容の扱いを確認する。
- 破壊操作：削除や上書きがポリシーで止まり、人の承認へ進むか確認する。
正常系だけでなく、モデルが誤った引数を出す、ツールがタイムアウトする、途中でプロセスが落ちる、再起動するという状況を試します。長時間エージェントでは、華やかなデモより復旧の予測可能性が重要です。
SDKでライブエージェントを制御する
公式の@deepseek-ai/dsh-agentパッケージは、エージェントの作成・再開、followup、steer、inject、cancel、idle待ちを扱います。アプリケーションから利用する場合、セッションIDとエージェントIDを混同しないように設計します。また、プロセスをまたぐinitiator情報は自動では保存されないため、ジョブキューや監査ログへ明示的に持たせます。
SDK導入では、作成したエージェントの所有者、停止権限、セッション保持期間、削除手順を先に決めます。Web UIで動いたからといって、そのままマルチテナントのSaaSへ組み込めるわけではありません。認証、認可、テナント分離、予算、レート制限はアプリ側の設計課題です。
DeerFlowとの使い分け
DeerFlowもHarnessとAppを提供し、memory、tools、skills、sandbox、subagentsを統合します。調査、コーディング、コンテンツ制作を長時間走らせる完成形に近い体験を早く試したい場合はDeerFlowが向きます。実行グラフをプラグイン単位で組み替え、自社の制御面そのものを設計したい場合はDeepSeek Harnessを比較対象にします。
本番化の判断基準
本番化前に、設定のバージョン管理、固定した依存関係、秘密情報の注入方法、監査ログ、停止操作、バックアップ、Session移行、費用上限、同時実行制限、アップグレードのロールバックを揃えます。preview版では最新版へ自動追従する運用を避け、ステージングでProfileを再現してから昇格させます。
導入成功の指標は『動いた回数』ではありません。同じ課題を再現できる割合、再起動後に正しい状態へ戻る割合、人の承認回数、失敗時の復旧時間、モデル費用、運用者の介入時間を測ります。
よくある質問（FAQ）
Q. DeepSeek HarnessはDeepSeek API専用ですか？
いいえ。モデルproviderをプラグインとして構成する設計です。利用可能なadapterと設定方法は更新されるため、導入時点の公式Configurationで確認してください。
Q. Codex CLIの代わりになりますか？
目的が違います。すぐにリポジトリ作業をするならCodex CLIが完成した体験を提供します。独自のUI、モデル経路、ツール、ポリシー、永続状態を持つ製品基盤を組むならDeepSeek Harnessが候補です。
Q. 商用サービスへ組み込めますか？
本体はMITライセンスで商用利用可能です。ただしdeveloper previewで互換性変更があり得ます。依存関係、接続モデル、マルチテナント認証、データ処理条件は別に確認してください。
