DeepSeek Harness入門：Clineとの違いからリモート実行環境の構築・トラブルシュートまで

Wed, 28 Oct 2026 01:57:29 +0900

自律型AIエージェントの実行環境として登場した DeepSeek Harness（CLI名：dsh）は、これまでエディタ統合型ツールを利用してきた開発者にとって、運用の前提を大きく変える存在です。VSCodeと拡張機能の組み合わせ（Clineなど）による開発スタイルと何が異なるのか、その設計思想からローカルネットワーク越しの安全な運用環境の構築手順、初期導入時のトラブルシュートまでを論理的に解説します。

1. エージェントの実行台座「ハーネス」の概念とClineとの違い

工学において「ハーネス（Harness）」は本来、馬を御する馬具や電気配線を束ねるワイヤーハーネス、あるいはソフトウェアの テストハーネス（テスト対象を包み込み、入力を与えて出力を観測する台座）を指す言葉です。

大規模言語モデル（LLM）は単体ではテキストの入出力を行う計算機構に過ぎず、ファイルを読み書きする権限もシェルを実行する手段も持ちません。エージェント工学におけるハーネスとは、モデルを作業環境（ファイルシステム、OS、シェル、ネットワーク）に接続し、その 思考と実行の自律ループを制御・記録・検証するための外枠（実行・観測台座） を意味します。

これまで広く使われてきた VSCode + Cline と DeepSeek Harness の決定的な違いは、その設計思想にあります。

VSCode + Cline：人間のエディタ操作に寄り添う「ペアプログラミング型」のアシスタントです。エディタ上で差分を目視確認しながら対話的にコードを修正する用途に適していますが、VSCodeのGUIセッションに強く依存し、履歴は一本道のチャットとして蓄積されます。
DeepSeek Harness：モデルの自律タスク実行と挙動検証を主眼に置いた「独立型テストベンチ」です。エディタから独立したプロセス（CLIおよびWeb UI）として動作し、エージェントの挙動を Trajectory（実行軌跡） と呼ばれる構造化データとして記録します。過去の任意のステップに戻って別の指示を与える分岐実行（Fork）や、一連の実行ログをそのままトレースする完全再現（Replay）が可能です。

2. macOSでのセットアップと運用設計の思想

macOS上で動作させる場合、Node.js 22.19以上（または24系）の環境を用意し、作業対象のディレクトリから起動します。

# 環境変数の設定（~/.zshrc 等）
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# ワークスペースディレクトリで起動
cd /path/to/project
npx @deepseek-ai/dsh web

Web UIを開くと、VSCodeのような人間向けの対話型ターミナルが存在しないことに気づきます。これは制限ではなく、状態の再現性を担保するための意図的な設計 です。人間が裏で自由にシェルコマンドを叩いてファイルや環境の状態を変更してしまうと、Harnessが記録しているTrajectoryと実際のファイルシステムとの整合性が崩れ、過去ステップへの巻き戻しや分岐の正確性が失われます。そのため、すべてのコマンド実行はエージェントのツール呼び出しとして扱われ、人間はそれを承認（Approve）するかどうかを判断する形を取ります。

また、Harnessを利用する際は トークン消費の累積構造 を意識する必要があります。自律エージェントのコンテキスト長 $C_t$ は、ステップ数 $t$ に対し、初期プロンプト $I$、各ステップの思考 $T_i$、ツール実行ログやコマンド出力 $O_i$ の総和として累積します。

$$C_t = I + \sum_{i=1}^{t} (T_i + O_i)$$

巨大なテストログの出力やファイル全体の読み込みが発生すると、1回のリクエストで送信される入力トークンが急増します。タスクごとにセッションを細かく切り替えることや、DeepSeek Platform側のダッシュボードで利用上限額（Hard Limit）を事前に設定しておく運用が推奨されます。

3. セキュリティ境界の設計：専用マシンとリモート運用の可能性

Harnessは外部アクセス機能を持たないローカルWebサーバーとして動作しますが、外出先から利用するために Cloudflare Tunnel と Cloudflare Access（Zero Trust）を組み合わせる構成は非常に合理的です。ルーターのポート開放を行うことなく、Cloudflareのエッジで強固なゼロトラスト認証（Google認証やメールPIN）を通過した通信のみをローカルの 127.0.0.1:3080 へ安全に転送できます。

しかし、エージェント環境のリモート常時稼働には固有のリスクが存在します。エージェントは「任意のシェルコマンド実行権限」を持つため、設定不備や不測の脆弱性が生じた際の影響範囲（Blast Radius）が、個人データや各種秘密鍵を保管しているメインの作業マシン全体に波及しかねません。

このリスクを根本的に排除するためには、使わなくなったPCやミニPC、隔離された仮想マシン（VM）を DeepSeek Harness専用マシン として切り出し、メインの開発端末と物理的・論理的に分離するアプローチが極めて有効です。専用マシン上には必要最小限のリポジトリとAPIキーのみを配置し、万が一のインシデント時にもメインの環境を安全に保つ構成が取られます。

4. LAN内別マシン（Windows）からのアクセスと認証トークンの解決

家庭内やオフィス内のLANにおいて、Mac上で動くHarnessのWeb UIに対して別のWindowsマシンからアクセスしたい場合、SSHポートフォワーディングを利用するのが最も簡潔で安全です。

Windows 10/11には標準で OpenSSH クライアントが統合されているため、WSL2を起動する必要はありません。WSL2内部でSSHトンネルを張ると、仮想マシンのNATやlocalhostフォワーディングの不整合によってブラウザから通信が届かないトラブルの原因になりやすいため、WindowsネイティブのPowerShell から直接コマンドを実行します。

# WindowsのPowerShellで実行
ssh -N -L 3080:127.0.0.1:3080 <Macのユーザー名>@<MacのローカルIP>

このコマンドを維持した状態でWindowsのブラウザから [http://127.0.0.1:3080](http://127.0.0.1:3080) にアクセスすると、次のようなエラーが表示されることがあります。

dsh web authentication required; reopen the URL printed by dsh web.

これは不具合ではなく、同一LAN内の他者やローカルの別プロセスによる不正操作（CSRF等）を防ぐための ワンタイム認証トークン仕様 によるものです。

解決手順

Mac側で dsh web を起動した際、ターミナルの出力ログの末尾にクエリパラメータが付与されたURLが表示されています。

http://127.0.0.1:3080/?token=abcdef1234567890...

Windows側ブラウザのアドレスバーに、単なる [http://127.0.0.1:3080](http://127.0.0.1:3080) ではなく、この ?token=... を含めた完全なURL を入力して開くことで認証が完了し、以降は別マシンのブラウザからMac上のHarnessを安定して操作できるようになります。