ガイド

著者 Matt Connor 2026-08-18 ・更新日 2026-08-26

dshのAPIキー、モデル、エンドポイント設定方法

Q: dsh は DeepSeek API key をどこに保存しますか？

$DSH_HOME/.credentials.yaml に保存します。DSH_HOME を自分で設定していない場合、~/.dsh/.credentials.yaml です。Models ページはそこに key を書き込み、設定にはその参照だけを保持するため、secret は 1 つのファイルに収まります。stat -c '%a %n' ~/.dsh/.credentials.yaml で mode を確認し、600 より緩い場合は 600 に設定してください。apiKeyEnv で環境変数を指定すれば、カスタムプロバイダーによってファイル自体を使わない構成にできます。

Q: 変数を設定しているのに、なぜ dsh は MISSING_CREDENTIAL を報告するのですか？

dsh は apiKeyEnv が指定する変数を、自身の process environment から読み取るためです。shell で export した変数は、systemd service、別の user の session、または export 前に起動した process には渡りません。unit 用の EnvironmentFile に値を記述し、mode を 600 にするか、dsh を起動する同じ shell で export してください。実行中の process が実際に保持している値は sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ で確認できます。

Q: dsh に必要な Node.js のバージョンは何ですか？

22 系では Node.js 22.19 以降、または 24 以降が必要です。Node 23 はサポート対象外です。最初に node -v を実行してください。サポート対象外の runtime による起動失敗は、インストールの破損に見えるため、runtime ではなく package を再インストールしてしまう原因になります。

dshの設定保存先と4つのパス、DeepSeek APIキーやローカルOllamaエンドポイントの接続方法を解説します。各モードで外部に送信される内容も明記します。

dsh が設定を保持する場所

dsh (DeepSeek Harness) は、設定を1つのディレクトリに保持します。デフォルトは $DSH_HOME で、~/.dsh に設定されています。Web UI で設定した内容は、すべてそこにプレーンテキストファイルとして書き込まれます。そのディレクトリを別のサーバーにコピーすると、新しいサーバーを元のサーバーと同じように動作させられます。

使用する4つのパスです。

~/.dsh/settings.yaml には、手動で作成した設定と UI で作成した設定が保存されます。プロバイダーとモデルのルートも含まれます。
~/.dsh/.credentials.yaml には Secret が保存されます。設定には認証情報への参照だけが保持されるため、キーの値自体は1つのファイルに保存されます。
~/.dsh/profiles/ には名前付きプロファイルが保存され、~/.dsh/storages/ には保存済みセッションが保存されます。
~/.dsh/cordis.patch.yml は独自のパッチレイヤーです。各プロファイルで、組み込み設定に重ねて適用されます。

DeepSeek は、2026年8月17日にこの harness を MIT ライセンスの開発者向けプレビューとして発表しました。README には、互換性を破る変更が予定されていると記載されています。このガイドのフィールド名とパスは、2026年8月時点のリポジトリドキュメントに対応しています。ガイド（このガイドを含む）の内容を使って設定をコピーする前に、インストールしたバージョンのドキュメントと照合してください。プレビュー版では、リリース間で名称が変更されることがあるためです。

最初の出力までに必要な最小構成

dsh には、22 系列では Node.js 22.19 以降、または 24 以降が必要です。Node 23 は対象外です。最初にバージョンを確認してください。バージョンが一致しないと起動時に失敗し、エラーがパッケージの破損によるもののように表示されるためです。

node -v
npx @deepseek-ai/dsh web

npx は npm レジストリからパッケージをダウンロードし、http://127.0.0.1:3080 で Web UI を起動します。ループバックアドレスにバインドするため、ファイアウォールで許可していても、別のマシンからこのポートには接続できません。VPS では、3080 をインターネットに公開せず、SSH 経由で転送してください。表示された URL が分かりにくい場合は、dsh がそのアドレスで起動する理由で、ループバックへのバインドによって保護される範囲と、保護されない範囲を説明しています。

ssh -N -L 3080:127.0.0.1:3080 you@your-server

ノート PC で http://127.0.0.1:3080 を開き、Settings、Models の順に移動します。DeepSeek のカードには API key の入力欄が 1 つあります。platform.deepseek.com から取得したキーを貼り付けて保存します。実行中のサーバーが認証情報を保存し、参照先を実行時に解決するため、モデルのルートは再起動なしですぐに使用可能になります。リモートサーバー上の dsh Web UI に接続するではトンネルとリバースプロキシの構成を、VPS に DeepSeek Harness をインストールするでは、このガイドで前提とするサーバーの準備を説明しています。

保存後、アプリケーションが作成したファイルを確認します。

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

settings.yaml、.credentials.yaml、profiles/ が表示されるはずです。stat が 600 以外のモードを表示した場合は、chmod 600 ~/.dsh/.credentials.yaml を実行してください。グループから読み取り可能、または全ユーザーから読み取り可能な認証情報ファイルがあると、サーバー上の他のすべてのアカウントにキーが渡ります。

ブラウザーを使わずに最初の実行を行う場合は、1 つのコマンドで十分です。

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

ヘッドレスプロファイルは 1 つのセッションを実行し、最終的な回答を表示します。

環境変数または設定ファイル

dsh にキーを渡す方法は2つあります。これらは相互に置き換えられません。

カタログプロバイダー（DeepSeek、Anthropic、OpenAI、および組み込みリストにあるその他のプロバイダー）では、Models ページからキーを登録します。値は ~/.dsh/.credentials.yaml に保存され、設定にはそのキーへの参照だけが保持されます。保存後、Web UI にキーが再表示されることはありません。

カスタムプロバイダーでは、代わりに apiKeyEnv を使用して環境変数を指定できます。ドキュメントでは、~/.dsh/settings.yaml にこの形式を使用しています。

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]

まず Web UI でプロバイダーを1つ追加し、~/.dsh/settings.yaml を開いて、生成された構造をコピーします。開発者向けプレビューでは、入れ子構造が最も変更されやすい部分です。アプリが直前に書き込んだファイルは、常に最新の形式になっています。

apiKeyEnv は、ログインシェルではなく dsh プロセスの環境から読み込まれます。対話セッションで export したキーは systemd unit からは見えません。そのため、手動で dsh web と入力した場合に動作する同じ設定でも、サービスから実行すると MISSING_CREDENTIAL が返されます。unit 専用のファイルを用意してください。

[Service]
EnvironmentFile=/etc/dsh/dsh.env

そのファイルのモードは 600 にし、サービスを実行するユーザーが所有するようにしてください。

モデルの選択と、変更できない ID

設定済みのプロバイダーはすべてモデル選択欄に表示されます。モデルを選択すると、新しいセッションのデフォルトにもなります。既存のセッションにはその時点のモデルが記録されているため、切り替えても過去の会話は書き換えられません。

Provider ID は永続的です。リクエスト、保存済みセッション、モデルのデフォルト設定、認証情報の参照はすべてこの ID を参照するため、名前を変更するボタンはありません。変更するには、新しいプロバイダーを作成して古いプロバイダーを削除します。長く使える名前を選んでください。local-ollama ではなく test2 のような名前にします。

画像対応を明示しない限り、モデルはテキスト専用です。モデルエントリに input: [text, image] を追加すると画像対応を宣言できます。カタログに記載されていないモデルのフォールバックとして、ルートレベルに defaultInput を設定することもできます。DeepSeek 独自の chat-completions ルートはテキスト専用で、別の設定には変更できません。そのため、このルートに画像を添付すると、送信前に拒否されます。

コードを同じホスト上で実行できるよう、dsh をローカルエンドポイントに接続する

Ollama は http://127.0.0.1:11434/v1 で OpenAI 互換 API を提供します。dsh はカスタムプロバイダーを通じて任意の OpenAI 互換ベース URL に接続できるため、両者をそのまま接続できます。まずモデルサーバーを設定します。インストールとモデルの取得については、VPS 上で Ollama を使って LLM をセルフホストするを参照してください。

dsh を操作する前に、エンドポイントが応答することを確認します。

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list は、取得したすべてのモデルの正確なタグを出力します。その文字列をコピーします。curl は同じモデルを JSON 形式で返します。空のリストは、Ollama は実行中ですがモデルを取得していないことを示します。Connection refused は、Ollama が実行されていないか、11434 で待ち受けていないことを示します。

次にプロバイダーを追加します。Ollama では API key フィールドが必要ですが、その値は無視されるため、空でない文字列なら何でも使用できます。

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

dsh プロセスから参照できる場所で変数をエクスポートします。

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

この操作で発生する失敗のほとんどは、次の 3 つに分類できます。MISSING_CREDENTIAL は、dsh が apiKeyEnv で指定された変数を読み取れなかったことを示します。そのため、ターミナルではなく dsh プロセスの環境を確認してください。UNKNOWN_MODEL は、id が設定済みのモデルと一致しないことを示します。ollama list と文字単位で比較し、コロンの後ろのタグも含めて確認してください。利用可能なモデルの取得時に 401 が発生する場合は、モデル検出が原因です。モデル検出ではベース URL に対して GET /models が呼び出されるため、そのパスを提供しないエンドポイントではモデルを手動で入力する必要があります。

もう 1 つの注意点はベース URL です。ベース URL から /v1 を省略すると、Ollama が提供していないパスにリクエストが送られます。その結果、呼び出しは 404 になり、モデルは実行されません。このサフィックスは装飾ではなく、OpenAI 互換 API の一部です。

Ollama が別のマシンで実行されている場合、そのマシンのアドレスをベース URL に指定します。この場合、プロンプトは通常の HTTP により、暗号化されていない状態でネットワークを通過します。同じホスト上で実行するか、TLS (transport layer security) と認証の背後に配置してください。公開した Ollama エンドポイントを保護するを参照してください。

各モードでマシンから送信されるもの

DeepSeek key を使用すると、すべてのリクエストが DeepSeek の API に送信されます。リクエストには、プロンプト、回答のために agent が読み取ったファイルの内容、実行したコマンドの出力、agent が含めることを選択したツールの結果が含まれます。agent がファイルを開いた場合、ソースコードもそのペイロードに含まれます。これがホスト型モデルの動作であり、agent をどのディレクトリから起動するかを検討する理由です。

別のカタログプロバイダーまたは企業ゲートウェイを使用する場合、同じペイロードがそのベンダーに送信されます。送信先は base URL で正確に確認できます。

ローカルエンドポイントを使用する場合、モデルへのリクエストは 127.0.0.1:11434 に送信され、マシン内にとどまります。コードがモデルベンダーに送信されることはありません。ただし、ネットワークを経由するものは3つあります。npx は npm registry からパッケージをダウンロードします。agent が実行するツールは、それ自体でインターネットに接続できます。接続した MCP (model context protocol) server も含まれます。詳細は VPS で MCP server を実行するで説明しています。plugin も同じ分類に含まれます。plugin のインストールでは、agent の権限で別の作者のコードが実行されるため、インストール前に plugin が接続できる先を確認する価値があります。telemetry を有効にした場合は、telemetry も該当します。

telemetry は、明示的に同意するまで無効です。DSH_TELEMETRY_MODE が同意を切り替える設定で、未設定、空の値、認識されない値は DISABLED として扱われます。この状態では dsh は OpenTelemetry (OTel) の provider、processor、exporter を構築しません。そのため、新しい profile から telemetry のネットワークリクエストが発生することはありません。FEEDBACK_ONLY は、フィードバックを契機とした session log の共有に同意します。FULL では launcher による報告も許可されます。session feed は session の内容、tool data、prompt、workspace path をエクスポートできるため、FULL は作業内容を DeepSeek に送信する設定として扱ってください。

mode string の指定に左右されない確実な停止方法として、DSH_TELEMETRY_DISABLED=1 を設定します。空でない値は明示的なオプトアウトとして扱われ、実行開始前に読み込まれるため、project code が session の途中で再び有効にすることはできません。デフォルトの collector address は harness-telemetry.deepseeksvc.com です。自分の firewall log を確認するときに、この名前を知っておくと役立ちます。

設定を信頼するだけでなく、実際に確認してください。タスクの実行中に、プロセスが保持している外向きの接続を一覧表示します。

sudo ss -tnp | grep -i node

local-model mode では、loopback の 11434 への接続が表示され、public address への接続は表示されないはずです。それ以外の接続があれば、続行する前に接続先を特定してください。coding agent が外部に送信するものでは、他の harness に対して同じ確認を行い、結果の読み取り方も説明しています。

シークレットを置いてはいけない場所

シェルの履歴。export DEEPSEEK_API_KEY=sk-... は平文で ~/.bash_history に書き込まれ、鍵をローテーションした後も長期間残ります。HISTCONTROL=ignorespace が設定されている場合は、コマンドの先頭にスペースを付けます。またはシェルを使わず、値をモード 600 のファイルへ直接書き込みます。
コミット済みのドットファイル。~/.bashrc または ~/.zshrc に鍵を保存すると、ドットファイルを git で管理している場合、公開リポジトリに公開されるまで git add です。push する前に、そのリポジトリで git grep -I -n 'sk-' を実行します。
settings.yaml。カスタムプロバイダーには apiKeyEnv を使用し、ファイルにはシークレットではなく変数名を保存します。設定ファイルは issue レポートやサポートチャットに貼り付けられます。認証情報ファイルは貼り付けられません。
env の出力とターミナルのスクリーンショット。環境全体を出力するコマンドは、鍵も一緒に出力します。
バックアップ。~/.dsh はバックアップする価値がありますが、その中の .credentials.yaml は有効なシークレットです。そのファイルを除外するか、アーカイブを暗号化します。

これらのルールは dsh 固有のものではありません。同じサーバーのコンテナ側については、Compose の env ファイルにシークレットを保存しない方法で同じ問題を扱っています。

開発者向けプレビュー版との運用

プレビュー版はパッチリリースで設定キーが変更され、プロバイダーの読み込みに失敗することがあるため、テストしたバージョンを固定します。固定したバージョンのインストール後に起動できない場合や、npxが要求していないビルドを繰り返し提供する場合は、プレビュー版で発生するインストールとバージョンのエラーで、npx のキャッシュと Node に付属する npm を確認します。認証情報ファイルは除外したうえで、settings.yamlとcordis.patch.ymlをバージョン管理に含めます。これにより、アップグレード後の変更を確認できます。

プロファイルが想定どおりに動作しない場合は、2 つのフラグが役立ちます。--dump-default-configは起動せずに、合成後のデフォルト設定を表示します。--dump-configは同じ方法で、プロファイルに対して合成された設定を表示します。2 つを比較すると、パッチ層で実際に変更された内容が分かります。各層を手作業で確認するよりも迅速です。

dsh --profile web --dump-config

アップグレード後に問題が発生した場合は、まずこれを実行します。リリース間で移動したキーは、ダンプ内の欠落したブランチとして表示されます。再インストールではなく、1 行を編集するだけで修正できます。

FAQ

dsh は DeepSeek API key をどこに保存しますか？

$DSH_HOME/.credentials.yaml に保存します。DSH_HOME を自分で設定していない場合、~/.dsh/.credentials.yaml です。Models ページはそこに key を書き込み、設定にはその参照だけを保持するため、secret は 1 つのファイルに収まります。stat -c '%a %n' ~/.dsh/.credentials.yaml で mode を確認し、600 より緩い場合は 600 に設定してください。apiKeyEnv で環境変数を指定すれば、カスタムプロバイダーによってファイル自体を使わない構成にできます。

DeepSeek API ではなくローカルモデルを dsh で使うにはどうしますか？

ローカルの OpenAI-compatible endpoint を base URL に指定するカスタムプロバイダーを追加します。Ollama の場合は http://127.0.0.1:11434/v1 です。api: openai-completions と model id には、ollama list から正確にコピーした値を指定します。Ollama は API key の値を必要としますが、その値は無視するため、空でない任意の文字列を使用できます。dsh の設定を編集する前に curl -s http://127.0.0.1:11434/v1/models で endpoint が応答することを確認してください。停止している endpoint と誤った設定では、似たエラーが発生します。

dsh はデフォルトでコードをどこかに送信しますか？

ホスト型モデルを使う場合は送信します。prompt と agent が読み取ったファイルの内容は、そのベンダーへの API request に含まれます。ローカル endpoint を使う場合、その request は loopback に送られ、マシン内にとどまります。Telemetry は別の feed で、デフォルトでは無効です。DSH_TELEMETRY_MODE は未設定の場合 DISABLED に解決され、その状態では exporter は作成されません。実行開始前に読み取られる opt-out 設定には DSH_TELEMETRY_DISABLED=1 を指定してください。

変数を設定しているのに、なぜ dsh は MISSING_CREDENTIAL を報告するのですか？

dsh は apiKeyEnv が指定する変数を、自身の process environment から読み取るためです。shell で export した変数は、systemd service、別の user の session、または export 前に起動した process には渡りません。unit 用の EnvironmentFile に値を記述し、mode を 600 にするか、dsh を起動する同じ shell で export してください。実行中の process が実際に保持している値は sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ で確認できます。

dsh に必要な Node.js のバージョンは何ですか？

22 系では Node.js 22.19 以降、または 24 以降が必要です。Node 23 はサポート対象外です。最初に node -v を実行してください。サポート対象外の runtime による起動失敗は、インストールの破損に見えるため、runtime ではなく package を再インストールしてしまう原因になります。

#deepseek#dsh#agent-harness #api-keys #ollama #configuration