Web画面、Headless、ACPの3入口を試すたびに、承認方法やログの残り方が変わって判断が止まります。

最短の選び方は、日常の確認と人工的な承認にはWeb、入力と成功条件が固定された処理にはHeadless、上位のエディターやAgentシステムがセッションを管理する場合だけACPです。

独立開発者は保守の少ない日常入口を探している人、自动化エンジニアは再実行できるコマンドを作りたい人、ツール開発者やプラットフォーム責任者は複数入口の統制範囲を決めたい人に向いています。

最終更新：2026年8月18日。データは同日確認した公式README、ユーザーガイド、開発ガイド、アーキテクチャ文書を基準にしています。DeepSeek Harnessは開発者プレビューで、互換性を壊す変更が予定されているため、導入時には当日の公式資料を再確認してください。 公式README にもこの注意が明記されています。

3つの入口を先に切り分ける

DeepSeek HarnessのWebは、ローカルでWeb UIを起動し、ワークスペースを選択してセッションを始める方式です。公式の起動例は npx @deepseek-ai/dsh web で、既定では http://127.0.0.1:3080 で待ち受けます。画面上で計画、ファイル変更、コマンド実行、承認要求を追えるため、作業の途中で判断を差し込めます。 Web UI公式ガイド

Headlessは、ターミナルやCIから対話画面を使わずにタスクを実行する方式です。公式の開発ガイドでは、APIキーを環境変数またはリポジトリ直下の .env から読み込み、pnpm dsh --profile headless "summarize this workspace" を実行する例が示されています。入力範囲と期待する出力が決まっている処理ほど、ログ保存や再試行の設計を加えやすくなります。 公式開発ガイド

ACPは、上位のクライアントがエージェントのプロセスを起動し、セッションを作成してタスクを送るための統合入口です。公式資料では、ACP自動化サーバーをJSON-RPCの標準入出力で動かし、新しいAgentセッションを公開する例が案内されています。これは単なる「高機能なCLI」ではなく、セッションのライフサイクルとプロトコル変換を上位側が引き受ける選択です。 公式アーキテクチャ文書

判断軸 Web Headless ACP
主な利用者 個人開発者、レビュー担当者 自動化担当者、CI管理者 エディター・Agent基盤の開発者
操作の見え方 計画、差分、承認を確認しやすい 標準出力、終了状態、成果物で確認 JSON-RPCのイベントと結果で確認
得意な作業 探索、修正、判断が必要な作業 定型処理、検査、バッチ実行 上位ツールからのセッション統合
主な責任 人が承認する境界を決める 再試行、タイムアウト、ログを実装する 互換性、状態管理、エラー変換を実装する
初期の選択 主入口にしやすい 条件が揃ったタスクだけ 統合要件がある場合だけ

この表でWebが上位に見えても、モデルの能力がWebだけ高いという意味ではありません。違うのは、操作の観察方法と、失敗時に誰が判断を引き取るかです。

個人開発者の主入口

日常的にコードを調べ、変更案を確認し、必要なら途中で指示を修正する場合はWebを残すほうが安全です。公式ガイドでも、Web UIではワークスペースを選択した後、ファイルの読み書き、コマンド実行、計画の維持、権限ポリシーに応じた承認が行われると説明されています。 Web UIの操作説明

一方、Webには見落としやすい負担があります。第一に、画面を見ていない時間の処理結果を機械的に判定しにくいことです。第二に、遠隔アクセスを追加すると、待ち受け先、認証、ワークスペース権限を別途管理する必要があります。第三に、同じタスクを別の日に再現する場合、入力文だけでなく、選択したワークスペース、モデル設定、プラグインの版、承認履歴も記録しなければなりません。

偶発的な調査や小規模な修正が中心なら、最初から自動化入口を作る必要はありません。複雑なランナーを先に構築すると、実際の作業よりも権限設定、ログの整形、プロセス監視の保守に時間を使うことになります。

自動化担当者の再現可能な処理

Headlessへ移す条件は、次の3つです。

  • 入力の範囲がファイル、引数、環境変数で明確になっていること。
  • 成功条件を終了状態だけでなく、生成物や検査結果で確認できること。
  • 失敗時に、再実行しても既存ファイルや外部サービスを壊さないこと。

たとえば、リポジトリの要約、テスト失敗の分類、定型的なドキュメント更新はHeadlessと相性がよい処理です。反対に、本番設定の変更、公開ブランチへの直接書き込み、削除を伴う移行は、Headlessにしただけでは安全になりません。外部の承認ステップ、テスト用ワークスペース、差分確認、書き込み禁止の初回実行を組み合わせる必要があります。

運用時には、少なくとも次を分けて記録します。

  1. 実行時点のDeepSeek Harnessの版とNode.js環境。
  2. 使用したプロファイル、モデル設定、ワークスペースのパス。
  3. 標準出力、標準エラー、終了状態、実行を中断した理由。
  4. 生成された差分、検査コマンド、テスト結果。
  5. 再試行回数と、途中から再開したのか最初からやり直したのか。

公式開発ガイドでは、開発環境の前提としてNode.js 22.19以上または24系、Corepack経由のpnpm 11.7.0、Git 2.26以上が示されています。これは性能保証の数字ではなく、公式開発環境を再現する際の確認項目です。 開発環境の前提条件

注意：Headlessで承認画面が表示されないことは、操作が安全になったことを意味しません。人が止める機会が消えるため、書き込み対象の限定、テスト用コピー、タイムアウト、失敗時の退避先を先に設計します。

統合開発者のACP評価

ACPを使う価値が出るのは、エディター、社内ポータル、別のAgentオーケストレーターなどが、DeepSeek Harnessを内部の実行エンジンとして扱う場合です。上位ツールがセッションを作成し、タスクを送信し、イベントと結果を構造化された通信として処理できるため、独自画面や複数の作業フローへ組み込みやすくなります。

ただし、柔軟性の代償は実装責任です。ACPクライアントが対応しているプロトコルやメソッド、セッション終了の扱い、キャンセル時の状態、標準エラーの収集方法、権限要求の表示先を確認しなければなりません。クライアントが「処理完了」と判断しても、エージェント側でファイル書き込みが失敗している可能性があるため、最終成果物の検査は上位側で行います。

公式のアーキテクチャ文書と開発ガイドを照合し、少なくとも initialize、セッション作成、タスク送信、キャンセル、エラー応答をテストします。ACPの実装が変わった場合に備え、固定したJSON-RPCの記録を使う契約テストも用意します。 公式アーキテクチャ文書

既存のWebやHeadlessが安定している場合、ACPへ置き換える理由は「統合要件があるか」で判断します。APIが新しいから、または将来的に便利そうだからという理由だけで移行すると、セッション管理と障害調査の層が増えるだけです。

小型チームの共通設定

チームでは入口を1つに強制するより、役割ごとにWebとHeadlessを併用したほうが自然な場合があります。個人の交互作用は残しても、次の項目は中央で管理します。

  • 使用するモデルと接続先。
  • ワークスペースの許可範囲と書き込み可能な場所。
  • プラグインの版と更新手順。
  • APIキーの保管場所と漏えい時の無効化手順。
  • ログの保存期間、機密情報のマスキング、成果物の命名規則。
  • 成功条件、テスト、差分確認、承認者の記録。

反対に、画面のテーマ、個人用の表示設定、調査中のプロンプト補助、Webでの計画確認といった交互作用は個人に残せます。ただし、個人設定が権限やモデル選択を上書きできる状態は避けます。

同じタスクをWebから実行した場合とHeadlessから実行した場合で、使えるプラグインや書き込み先が変わるなら、それは入口の違いではなく統制の分裂です。監査やロールバックが必要なチームほど、入口を統一するのではなく、契約と証拠を統一します。

5段階の選定手順

  1. 低リスクの基準タスクを決めます。
    例として、ワークスペースの要約と主要パッケージの一覧化を使います。公開、削除、本番変更を含むタスクは避けます。

  2. Webで人が確認する地点を記録します。
    計画が出るか、差分を見られるか、コマンド実行前に承認できるか、途中で停止できるかを確認します。

  3. 同じ入力をHeadlessで実行します。
    標準出力と標準エラーを分離し、終了状態、生成物、差分、再実行結果を保存します。成功を「プロセスが終わった」だけで判定しないことが重要です。

  4. ACPでは通信と状態を確認します。
    クライアントからセッションを作り、同じタスクを送信し、途中イベント、正常終了、キャンセル、異常終了を記録します。

  5. 主入口、予備入口、禁止場面を文章化します。
    例として、主入口はWeb、定型要約の予備入口はHeadless、本番書き込みは承認なしのHeadless禁止、ACPは社内エディターからの統合時だけ、と定義します。

選定チェックリスト

  • [ ] 日常作業で計画、差分、ツール呼び出しを確認する必要があるため、Webを主入口として試した。
  • [ ] Headlessの入力、出力、終了条件、再試行条件を個別に定義した。
  • [ ] 高リスクの書き込みに、外部承認またはテスト用ワークスペースを設定した。
  • [ ] ACPクライアントの互換性とセッション終了処理を確認した。
  • [ ] Web、Headless、ACPでモデル、権限、プラグイン版、ログ規則をそろえた。
  • [ ] 失敗時に、どの入口から再開するかを決めた。
  • [ ] 開発者プレビューの更新後、公式の起動例と基準タスクを再実行する手順を作った。

よくある判断

WebとHeadlessの違い

Webは人が観察しながら判断を差し込む入口で、Headlessは機械的な反復と検査を優先する入口です。Webが高性能、Headlessが低性能という比較ではなく、人工的な承認と運用自動化のどちらを主責任にするかの違いです。

日常のコード作業

日常のコード作業では、まずWebを選びます。作業の流れが固定され、成功条件を検査できるようになった処理だけをHeadlessへ切り出すと、保守範囲を必要以上に広げずに済みます。

スクリプト呼び出し

DeepSeek Harnessはスクリプトから呼び出せます。公式例のHeadlessプロファイルを起点に、APIキーを環境変数へ置き、ログ、終了状態、生成物の検査を追加します。書き込みを伴う場合は、別の承認やテスト門番を設けます。

ACPを使う場面

ACPは上位ツールがセッションを作り、タスクを送り、結果を受け取る必要がある場合に使います。単独の個人作業や単純なCIなら、WebまたはHeadlessのほうが責任範囲を把握しやすいことがあります。

複数入口のチーム運用

チームでWebと自動化入口を同時に使えます。ただし、権限、モデル、プラグイン、ログ、検査基準を共通化し、入口ごとの設定差分を定期的に比較します。

現在の環境とMac運用の切り替え

手元の開発環境だけでDeepSeek Harnessを運用すると、スリープや再起動でWebセッションが途切れたり、個人のNode.jsやプラグイン更新でHeadlessの結果が変わったり、ACPの標準入出力と通常ログが混ざって障害箇所を追えなくなったりします。短期の検証では許容できても、遠隔から継続して使う場合は、電源状態、アクセス制御、ログ保存、復旧手順まで管理対象になります。

そのため、主モードが決まった後に一時的な検証環境や遠隔のMac作業環境が必要なら、RUVCLOUDの日本向けMac利用案内を確認する価値があります。自前環境を買い足すより導入期間を区切りやすく、既存のPCを常時稼働させるより、作業用の環境と日常端末を分離しやすい点が利点です。長期間の安定した高負荷処理や物理インターフェースが必要な場合は自前機材が向いていますが、短期のWeb、Headless、ACP検証なら、RUVCLOUDのMac環境案内から必要な構成と接続方法を確認して進めるのが現実的です。