dshのAPIキー・モデル・エンドポイント設定方法
dshのLinux設定場所、DeepSeek APIキーやローカルOllama endpointの接続方法を解説します。各モードで端末外へ送信される内容も確認できます。
dsh の設定ファイルの保存場所
dsh (DeepSeek Harness) はハーネスデータを $DSH_HOME に保持します。デフォルト値は ~/.dsh です。また、共有エージェント設定は別のルートである $DSH_AGENTS_HOME から読み込みます。こちらのデフォルト値は ~/.agents です。Web UI で設定した内容は、すべてプレーンテキストファイルとして保存されます。設定を別のサーバーへ移行する際は、ハーネスのホームディレクトリと、共有エージェントルートにあるグローバルな指示やスキルをコピーしてください。
ハーネスの主要な設定、シークレット、セッションログは以下の4つのパスに格納されます。
~/.dsh/profiles/<profile>/cordis.patch.ymlには、Web UI で書き込まれたプロファイルごとの設定が保存されます。これにはプロバイダーやモデルのルート設定が含まれます。dsh webはwebプロファイルを実行するため、ファイルは~/.dsh/profiles/web/cordis.patch.ymlとなります。~/.dsh/.credentials.yamlにはシークレットが保存されます。設定ファイルには認証情報への参照のみが保持され、キーの値自体はこのファイル内に存在します。~/.dsh/profiles/には名前付きプロファイルが、~/.dsh/sessions/には保存されたセッションログが格納されます。~/.dsh/cordis.patch.ymlはユーザー独自のパッチレイヤーです。すべてのプロファイルにおいて組み込み設定の上に適用されます。このレイヤーはプロファイルファイルよりも優先されるため、このレイヤーで上書きされる設定を Web UI で編集しようとすると、保存は拒否されます。
共有エージェントルートは、他のエージェントツールと共有されるため $DSH_HOME の外側に配置されます。dsh は ~/.agents/AGENTS.md からユーザーグローバルな指示を読み込み、~/.agents/skills/ をスキャンしてスキルを検索します。このルートを変更するには DSH_AGENTS_HOME を設定してください。
以前のビルドでは、これらの設定は ~/.dsh/settings.yaml に保持されていました。現在のビルドでは、そのファイルはアクティブなプロファイルへ一度だけインポートされ、settings.yaml.imported にリネームされます。そのため、settings.yaml を編集するように指示する古いガイドは、現在 dsh が読み込まないファイルを指していることになります。
DeepSeek はこのハーネスを MIT ライセンスのデベロッパープレビューとして公開しており、README には互換性を損なう変更が行われる可能性がある旨が記載されています。本ガイドのフィールド名とパスは、2026年11月5日時点でリポジトリのドキュメントと照合した最新のものです。プレビュー版ではリリースごとに名称が変更される可能性があるため、本ガイドを含め、設定をコピーする際は必ずインストールしたバージョンのドキュメントと照らし合わせて確認してください。
最低限必要な初期出力
dsh には Node.js 24.9 以降が必要です。2026 年 11 月 5 日の時点で package.json は >=24.9.0 を要求しているため、22 系はサポートされていません。Node 24.0 から 24.8 も不十分です。バージョン不一致は起動時に失敗し、エラーがパッケージの破損のように見えるため、最初にバージョンを確認してください。
node -v
npx @deepseek-ai/dsh webnpx は 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ラップトップで http://127.0.0.1:3080 を開き、Settings と Models に移動します。DeepSeek カードには API キーの入力フィールドがあります。platform.deepseek.com から取得したキーを貼り付けて保存してください。実行中のサーバーが認証情報を保持し、参照をライブで解決するため、再起動なしでモデルルートが即座に使用可能になります。リモートサーバー上の dsh Web UI へのアクセス ではトンネルとリバースプロキシのケースを、VPS への DeepSeek Harness のインストール ではこのガイドが前提とするサーバー準備について解説しています。
保存後、アプリが作成した内容を確認してください。
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml.credentials.yaml と profiles/ が表示され、Web UI の設定が profiles/web/cordis.patch.yml にあるはずです。古いビルドで作成されたホームディレクトリには settings.yaml.imported が含まれている場合もあります。stat が 600 以外のモードを表示した場合は、chmod 600 ~/.dsh/.credentials.yaml を実行してください。グループ読み取り可能な認証情報ファイルは、そのグループ内のアカウントにキーを漏洩させます。全体読み取り可能な場合は、サーバー上のすべてのアカウントに漏洩します。
ブラウザを使用しない最初の実行には、1 つのコマンドで十分です。
npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"ヘッドレスプロファイルは単一のセッションを実行し、最終的な回答を出力します。
環境変数または設定ファイル
dsh は、保存済みの認証情報または環境変数のフォールバックからキーを解決できます。
カタログプロバイダー(DeepSeek、Anthropic、OpenAI、および組み込みリストにあるその他のプロバイダー)は、Models ページからキーを登録できます。保存済みの認証情報からキーが提供されない場合は、対応する環境変数のフォールバックを使用します。値は ~/.dsh/.credentials.yaml に格納され、設定にはその参照だけが保持されます。キーを保存した後、Web UI にキーが再表示されることはありません。
カスタムプロバイダーでは、apiKeyEnv を使用して認証情報の参照を指定できます。これも環境変数のフォールバックに対応しています。ドキュメントでは、~/.dsh/profiles/web/cordis.patch.yml のようなプロファイルパッチ内のエントリとして次の形式を示しています。
- id: llm-pi-ai
config:
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 つ追加し、次にプロファイルの cordis.patch.yml を開いて、そこに書き込まれた構造をコピーします。開発プレビュー中は入れ子構造が最も変更されやすい部分です。そのため、アプリが直前に書き込んだファイルが常に最新の形式になります。
apiKeyEnv は認証情報ストアを通じて解決されます。保存済みファイルが優先され、次に起動時の環境、実行元ディレクトリの .env、最後に $DSH_HOME/.env の順で確認されます。対話セッションでのみエクスポートしたキーは systemd unit から見えません。そのため、別の認証情報ソースがなければ、手動で dsh web と入力したときに動作する同じ設定でも、サービスとして実行すると MISSING_CREDENTIAL が返されます。unit 専用のファイルを用意してください。
[Service]
EnvironmentFile=/etc/dsh/dsh.envそのファイルのモードは 600 に設定し、サービスの実行ユーザーが所有するようにしてください。
モデルの選択と変更できないID
設定済みのプロバイダーはすべてモデルピッカーに表示されます。モデルを選択すると、それが新規セッションのデフォルトになります。すでにリクエストを送信済みのセッションは、その時点のモデルを保持するため、切り替えても過去の会話が書き換わることはありません。
プロバイダーIDは永続的なものです。リクエスト、保存済みセッション、モデルのデフォルト設定、認証情報の参照先はすべてこのIDに基づいているため、名前を変更するボタンはありません。IDを変更するには、新しいプロバイダーを作成し、古いプロバイダーを削除する必要があります。test2ではなくlocal-ollamaのように、後から変更する必要のない名前を選択してください。
継承された画像機能を持たないカスタムモデルは、明示的に指定しない限りテキスト専用となります。モデルエントリにinput: [text, image]を追加して画像サポートを宣言するか、カタログに記述がないモデルのフォールバックとしてルートレベルでdefaultInputを設定してください。DeepSeek独自のルートでは、モダリティが宣言されていないモデルはテキスト専用とみなされるため、画像を添付する前に画像対応のカタログエントリ(デフォルトはdeepseek-flash)を選択してください。画像サポートを宣言していないモデルに画像を送信した場合、送信前に拒否されます。
ローカルエンドポイントに dsh を接続し、コードをサーバー内で完結させる
Ollama は http://127.0.0.1:11434/v1 で OpenAI 互換 API を提供します。dsh はカスタムプロバイダーを通じて任意の OpenAI 互換 base URL と通信できるため、間に別のサービスは必要ありません。まずモデルサーバーをセットアップします。インストールとモデルの取得については、VPS 上で Ollama を使って LLM をセルフホストするを参照してください。
dsh を操作する前に、エンドポイントが応答することを確認します。
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama list は取得済みの各モデルの正確なタグを出力します。その文字列をコピーします。curl は同じモデルを JSON 形式で返します。空のリストは、Ollama は実行中ですが、モデルが何も取得されていないことを示します。Connection refused は Ollama が実行されていないか、11434 で待ち受けていないことを示します。
このマシンで実行できるモデルを選びます。サインイン済みの Ollama サーバーは、同じローカルアドレスを通じてクラウドモデルも提供します。gemma4:cloud のようなクラウドタグを指定すると、Ollama のサーバー上で実行されます。そのため、dsh が通信する先は 127.0.0.1 だけでも、プロンプトはこのマシンの外部に送信されます。
次に、プロファイルのパッチへプロバイダーを追加します。この設定では、空でない API key の値を指定します。ローカルの Ollama サーバーはこの値を無視します。
- id: llm-pi-ai
config:
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 が参照する名前を解決できなかったことを示します。そのため、ターミナルだけでなく、保存済みの認証情報と起動環境を確認します。UNKNOWN_MODEL は、id が設定済みのモデルと一致しないことを示します。ollama list と文字単位で比較してください。コロンの後ろにあるタグも含めます。利用可能なモデルの取得時に 401 が返る場合は、モデル検出が原因です。モデル検出では base URL に対して GET /models が呼び出されます。このパスを提供しないエンドポイントでは、モデルを手動で入力する必要があります。
base URL に関する問題にも注意してください。/v1 を付けないと、Ollama が提供していないパスにリクエストが送信されます。そのため呼び出しは 404 になり、モデルは実行されません。このサフィックスは OpenAI 互換インターフェースの一部であり、単なる装飾ではありません。
Ollama が別のマシンで実行されている場合、そのマシンのアドレスが base URL になります。この場合、プロンプトはプレーンな HTTP で暗号化されずにネットワークを通過します。同じホスト上で実行するか、TLS(transport layer security)と認証の背後に配置してください。公開された Ollama エンドポイントを保護するを参照してください。
各モードでマシンから送信されるデータ
DeepSeekのキーとデフォルトのエンドポイントを使用する場合、モデルへのリクエストはDeepSeekのAPIへ送信されます。このリクエストには、プロンプト、エージェントが回答のために読み取ったファイルの内容、実行したコマンドの出力、およびエージェントが含めることを選択したツール実行結果が含まれます。エージェントがファイルを開いた場合、そのペイロード内にソースコードが含まれます。これはホスト型モデルの仕組みであり、エージェントをどのディレクトリで起動するかを検討すべき理由です。
現在のリリースでは、デフォルトでネイティブのDeepSeekアダプター(設定済みのゲートウェイを含む)を介したリクエストに対し、セッションイベントログの未送信サフィックスが個別の dsh_session_log フィールドとして付加されます。モデルはこのデータを確認しませんが、リクエストの送信先はこれを受信します。これを無効にするには、Settings の General で "Upload Session Log when using the official model API" をオフにするか、session-log-deepseek プラグインで enabled: false を設定してください。以下のテレメトリスイッチでは、このアップロードを制御できません。
配布されているプロファイルは、ネイティブのDeepSeekアダプターを介して、アクティブなプラグインのパッケージ名とバージョンを個別の dsh_plugin_packages フィールドで送信します。この送信を停止するには、plugin-package-inventory-deepseek で enabled: false を設定してください。
別のカタログプロバイダーや企業用ゲートウェイを使用する場合、同じペイロードがそのベンダーへ送信されます。送信先はベースURLで正確に確認できます。
ローカルエンドポイントを使用する場合、モデルリクエストは 127.0.0.1:11434 へ送信されますが、ループバックアドレスであるというだけでマシン外へ出ないとは限りません。Ollamaのドキュメントには「このサーバー経由でクラウドモデルを使用するには、Ollamaにサインインしてください」とあり、同じローカルサーバー経由でクラウドモデルを選択すると、プロンプトとコードがOllamaのクラウドへ送信されます。モデル自体がローカルで実行されている場合にのみ、モデルリクエストはマシン内に留まります。それでも、以下の3つの要素はネットワークを通過します。npx はnpmレジストリからパッケージをダウンロードします。エージェントが実行するツールは、接続したMCP(Model Context Protocol)サーバーを含め、独自にインターネットへアクセス可能です。これについては running MCP servers on a VPS で詳細を解説しています。プラグインも同様のカテゴリに属します。プラグインをインストールすると、エージェントの権限で他者のコードが実行されるため、checking what a plugin can reach before you install it を行う価値があります。また、テレメトリは現在のリリースにおいて、フィードバックを送信するたびにDeepSeekへのエクスポートが許可されており、これはローカルモデルでもホスト型モデルと同様です。
テレメトリはデフォルトでフィードバックのみに限定されています。DSH_TELEMETRY_MODE でモードを選択し、現在の配布ベース設定では、未設定または空の値は FEEDBACK_ONLY となります。このモードでは、通常の操作においてテレメトリのキャプチャは許可されません。書面によるフィードバックの送信、評価の作成や編集、メモの編集、またはフィードバックの取り消しを行うと、dshはエクスポート未済のセッションログプレフィックスを、継承されたコンテキストを含めてフィードバックイベントとして https://dsh-otel-collector.deepseeksvc.com/v1/logs へエクスポートすることを許可します。完全な配信は保証されません。サイズ超過のイベントは切り捨てられずに拒否され、大きなプレフィックスはCLI終了時に一部未送信のまま残る可能性があります。許可されたバッチは、追加の操作やモデル呼び出しなしで送信を継続する場合があります。テレメトリのREADMEには、これが「すべてのユーザーとプロバイダーに適用される」と記載されているため、モデルをローカルで実行しても無効にはなりません。DISABLED はOpenTelemetry (OTel) トランスポートを一切構築しません。FULL は受け付けられなくなりました。これら2つ以外の値は unsupported mode で拒否されます。フィードバックのエクスポートにはメッセージテキスト、ツール引数と結果、ワークスペースパスが含まれる可能性があるため、フィードバックの送信は、そのセッションプレフィックスをDeepSeekへ送信することに同意したものとして扱ってください。
モード文字列の指定に依存しない確実な停止を行うには、DSH_TELEMETRY_DISABLED=1 を設定してください。空ではない値はすべて権威あるオプトアウトとして機能し、0 や false も含まれます。これは実行開始前に読み込まれるため、プロジェクトコードによってセッション途中で再有効化されることはありません。デフォルトのコレクターアドレスは dsh-otel-collector.deepseeksvc.com です。DSH_TELEMETRY_OTLP_URL でこれを上書きできます。
設定を信頼するのではなく、検証してください。タスク実行中に、プロセスが保持しているアウトバウンド接続をリストアップします。
sudo ss -tnp | grep -i nodeローカルで実行されるモデルの場合、モデルトラフィックはループバックポート 11434 を使用しますが、フィードバックを送信しなくてもツールからパブリック接続が発生する可能性があります。配布されているプロファイルにはWeb検索やフェッチが含まれており、デフォルトの権限プリセットではネットワークアクセスを制限していません。各パブリック接続先を特定してからテレメトリと関連付けてください。タイミングだけでその接続がフィードバックエクスポートであると断定することはできません。このスナップショットでは短命な接続を見逃す可能性もあります。このチェックはdshプロセスのみを対象としています。クラウドモデルのトラフィックはOllamaサーバーから発生するため、モデル id がクラウドタグでないことも確認してください。それ以外の通信については、継続する前に特定する価値があります。What a coding agent sends home では、他のハーネスに対して同じチェックを実行し、結果の読み方を解説しています。
シークレットを置いてはいけない場所
- シェルの履歴。
export DEEPSEEK_API_KEY=sk-...は平文で~/.bash_historyに書き込まれ、鍵をローテーションした後も長期間残ります。HISTCONTROL=ignorespaceが設定されている場合は、コマンドの先頭にスペースを付けてください。またはシェルを使わず、値をモード 600 のファイルに直接書き込んでください。 - コミット済みのドットファイル。ドットファイルを git で管理している場合、
~/.bashrcまたは~/.zshrcにある鍵は、公開リポジトリに入るまであとgit addです。push する前に、そのリポジトリでgit grep -I -n 'sk-'を実行してください。 - Profile のパッチファイル。カスタムプロバイダーには
apiKeyEnvを使用し、cordis.patch.ymlにはシークレットではなく変数名を保持させてください。設定ファイルは issue レポートやサポートチャットに貼り付けられます。認証情報ファイルは貼り付けられません。 envの出力とターミナルのスクリーンショット。環境全体を出力するコマンドは、鍵も一緒に出力します。- バックアップ。
~/.dshはバックアップする価値がありますが、その中の.credentials.yamlは有効なシークレットです。そのファイルを除外するか、アーカイブを暗号化してください。
これらのルールは dsh 固有のものではありません。同じサーバーのコンテナ側で同じ問題を扱う Compose の env ファイルにシークレットを残さない方法 も参照してください。
開発者プレビューとの付き合い方
テストしたバージョンを固定してください。プレビュー版では、パッチリリースで設定キーが変更され、プロバイダーの読み込みに失敗することがあります。固定したインストールで起動できない場合や、npx が要求していないビルドを繰り返し提供する場合は、プレビュー版で発生するインストールおよびバージョンのエラーで、npx のキャッシュと Node に付属する npm について確認できます。認証情報ファイルは除外し、ホームの cordis.patch.yml と profiles/ 配下のパッチファイルをバージョン管理してください。アップグレード後の変更を確認できるようになります。
プロファイルが想定どおりに動作しない場合は、2 つのフラグが役立ちます。--dump-default-config は起動せずに合成後のデフォルト設定を出力します。--dump-config は同じ方法で、プロファイルの合成後の設定を出力します。2 つを比較すると、パッチ層で実際に変更された内容が分かります。各層を手作業で読むよりも効率的です。
dsh --profile web --dump-configアップグレード後に問題が発生した場合は、まずこれを実行してください。リリース間で移動したキーは、ダンプ内の欠落したブランチとして現れます。再インストールではなく、1 行を編集するだけで修正できます。
FAQ
dsh は DeepSeek API キーをどこに保存しますか?
$DSH_HOME/.credentials.yaml に保存されます。DSH_HOME を自身で設定しない限り、場所は ~/.dsh/.credentials.yaml です。Models ページでキーを入力するとそこに書き込まれ、設定ファイルには参照のみが保持されるため、シークレットは 1 つのファイルに集約されます。stat -c '%a %n' ~/.dsh/.credentials.yaml でファイルのモードを確認し、600 以外であれば 600 に設定してください。カスタムプロバイダーを使用する場合、apiKeyEnv で環境変数を指定することで、ファイルへの保存を完全に回避できます。
DeepSeek API の代わりにローカルモデルを dsh で使うにはどうすればよいですか?
ベース URL にローカルの OpenAI 互換エンドポイントを指定したカスタムプロバイダーを追加してください。Ollama の場合は http://127.0.0.1:11434/v1 を指定し、api: openai-completions と ollama list から正確にコピーしたモデル名 id を設定します。この設定には空ではない API キーの値が必要ですが、ローカルの Ollama サーバーはこれを無視します。dsh の設定を編集する前に、curl -s http://127.0.0.1:11434/v1/models でエンドポイントが応答することを確認してください。エンドポイントが停止している場合と設定が誤っている場合で、同様のエラーが発生するためです。
dsh はデフォルトでコードをどこかに送信しますか?
ホスト型モデルを使用している場合は送信されます。プロンプトとエージェントが読み取ったファイルの内容は、そのベンダーへの API リクエストに含まれます。また、設定されたゲートウェイを含むネイティブの DeepSeek アダプター経由のリクエストも、Settings の General でアップロードを無効にしない限り、デフォルトでセッションログのサフィックスが付与されます。Ollama でローカル実行するモデルの場合、リクエストはループバック経由でマシン内に留まりますが、gemma4:cloud のようなクラウドモデルは、同じループバックアドレスを通じて Ollama のクラウドへ転送されます。組み込みの Web 検索やフェッチ、その他のツールやプラグインは、フィードバックとは無関係にパブリックサービスへ接続する可能性があります。テレメトリは別のフィードです。現在のリリースでは、DSH_TELEMETRY_MODE が未設定の場合 FEEDBACK_ONLY に解決されます。そのため、フィードバックを行うと、ローカルモデルを含むすべてのプロバイダーにおいて、継承されたコンテキストを含めたセッションログのプレフィックスがそのイベントを通じてエクスポートされます。配信は保証されておらず、フィードバックのやり取り後も承認済みのアップロードが継続する場合があります。エクスポートを無効にするには DISABLED を設定するか、実行開始前に読み込まれるオプトアウト設定として DSH_TELEMETRY_DISABLED=1 を設定してください。
変数を設定しているのに dsh が MISSING_CREDENTIAL を報告するのはなぜですか?
apiKeyEnv で指定された参照先が、dsh の認証情報ソース内で解決される必要があるためです。保存された認証情報は起動環境よりも優先され、次に実行ディレクトリの .env および $DSH_HOME/.env が参照されます。シェルでエクスポートした変数は、systemd サービスや別のユーザーのセッション、あるいはエクスポート前に開始されたプロセスには反映されません。ユニットに対してはモード 600 の EnvironmentFile に値を記述するか、dsh を起動するのと同じシェルでエクスポートしてください。実行中のプロセスが実際に保持している値は sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ で確認できます。
dsh にはどのバージョンの Node.js が必要ですか?
2026 年 11 月 5 日時点のリポジトリの package.json によると、Node.js 24.9 以降が必要です。22 系はサポートが終了しており、Node 24.0 から 24.8 も要件を満たしません。他の作業を行う前に node -v を実行してください。サポートされていないランタイムによる起動失敗はインストール破損のように見えるため、ランタイムではなくパッケージを再インストールしてしまう原因となります。