SSD Nodes Learn 🎉 VPS $5.50/月〜
ガイド Matt Connor著者 Matt Connor ・更新日 2026-08-21

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

Linuxでdshの設定場所、DeepSeek API keyやローカルOllama endpointの接続方法を解説します。各モードで端末外へ送信される情報も正確に確認できます。

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 は 17 August 2026 に、この 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 経由で転送してください。

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

ノートパソコンで 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

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

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

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

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

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

dsh をローカルエンドポイントに向けて、コードをホスト内に保持する

Ollama は http://127.0.0.1:11434/v1 で OpenAI-compatible API を提供します。dsh はカスタムプロバイダーを通じて任意の OpenAI-compatible base 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 は、apiKeyEnv が示す名前の変数を dsh が読み取れなかったことを示します。そのため、ターミナルの環境ではなく、プロセスの環境を確認してください。UNKNOWN_MODEL は、id が設定済みのモデルと一致しないことを示します。ollama list と文字単位で比較してください。コロンの後のタグも含めます。利用可能なモデルの取得時に 401 が返る場合は、モデル検出が原因です。この処理では base URL に対して GET /models が呼び出されます。そのパスを提供しないエンドポイントでは、モデルを手動で入力する必要があります。

base URL に関する別の注意点もあります。/v1 を省略すると、リクエストは Ollama が提供していないパスに送られます。そのため呼び出しは 404 になり、モデルは実行されません。このサフィックスは装飾ではなく、OpenAI-compatible API の一部です。

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

各モードでマシンから送信される内容

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

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

ローカルエンドポイントを使用すると、モデルへのリクエストは 127.0.0.1:11434 に送信され、マシン内に留まります。コードがモデルベンダーに送信されることはありません。ただし、ネットワークを経由するものは3つあります。npx は npm registry からパッケージをダウンロードします。エージェントが実行するツールは、接続した MCP (model context protocol) サーバーを含め、独自にインターネットへアクセスできます。この点については、VPS 上で MCP サーバーを実行する で詳しく説明しています。もう1つは、有効にした場合のテレメトリです。

オプトインするまで、テレメトリは無効です。DSH_TELEMETRY_MODE が同意を切り替える設定で、未設定、空、または認識されない値は DISABLED として扱われます。この状態では、dsh は OpenTelemetry (OTel) のプロバイダー、プロセッサー、エクスポーターを作成しません。そのため、新しいプロファイルではテレメトリのネットワークリクエストは一切発生しません。FEEDBACK_ONLY は、フィードバックを契機としたセッションログ共有をオプトインします。FULL はランチャーのレポート送信も許可します。セッションフィードは、セッションの内容、ツールデータ、プロンプト、ワークスペースのパスをエクスポートできます。そのため、FULL は作業内容を DeepSeek に送信する設定として扱ってください。

モード文字列を正しく設定できているかに依存しない完全な停止には、DSH_TELEMETRY_DISABLED=1 を設定します。空でない値は明示的なオプトアウトとして扱われ、実行開始前に読み込まれます。そのため、プロジェクトコードがセッション中に再度有効化することはできません。デフォルトのコレクターアドレスは harness-telemetry.deepseeksvc.com です。自分のファイアウォールログを確認するときに覚えておくと便利です。

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

sudo ss -tnp | grep -i node

ローカルモデルモードでは、11434 への loopback 接続が表示され、パブリックアドレスへの接続は表示されないはずです。それ以外の接続があれば、続行する前に特定してください。コーディングエージェントが外部へ送信する内容 では、他のハーネスに対して同じ確認を行い、結果の読み方も説明しています。

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

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

これらのルールは dsh 固有のものではありません。同じサーバーのコンテナ側で同じ問題を扱う方法については、Compose env files から secrets を除外する方法を参照してください。

開発者プレビューと共に運用する

テストしたバージョンを固定してください。プレビュー版では、パッチリリースで設定キーが変更され、プロバイダーの読み込みに失敗することがあります。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 で環境変数名を指定すれば、custom provider によってファイルを完全に使わない構成にもできます。

DeepSeek API の代わりにローカルモデルを dsh で使うにはどうすればよいですか？

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

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

ホスト型モデルを使う場合は送信します。prompt と、agent が読み取ったファイルの内容は、その vendor への 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 の version はいくつですか？

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

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