DeepSeek Harness：インストールと API 接続ガイド

DeepSeek Harness は DeepSeek AI が公開しているオープンソースの Coding Agent と Agent runtime です。モデルの周囲に loop、tools、workspace access、sessions、permissions、UI を提供し、実際の知能は API Provider のモデルが担います。このガイドでは DeepSeek code harness の役割を整理してから、公式の custom-provider フローで OmniaKey に接続します。

DeepSeek Harness とは？

DeepSeek Harness、略称 dsh は新しい言語モデルではありません。モデルに workspace の理解、tool call、ファイル編集、command 実行、session 保存、approval の要求を行わせるソフトウェア層です。

一部の記事は open-source AI agent framework と呼びますが、公式資料はより具体的に、open-source agent harness、local-first で拡張可能な Coding Agent、Agent の開発・runtime 環境と説明しています。

中心となる設計は everything is a plugin です。Cordis plugin system を基盤にしているため、models、tools、skills、sessions、sandboxes、storage、loops、scheduling、UI まで設定で差し替えたり再構成したりできます。

追跡可能な event stream は単なる chat history ではありません。公式ドキュメントでは resume、fork、search、replay が同じ session log 上の操作として説明されており、回答前に多くの tool call が走るときの調査に役立ちます。

DeepSeek Harness ではないもの

• DeepSeek V4 Pro などのモデルそのものではありません。Harness と model は別の層です。
• 安定した production release ではありません。公式は developer preview とし、互換性を壊す変更が起こると明記しています。
• npm quick start で動かす場合、クラウド型の coding service ではありません。Web UI は既定で local loopback に bind します。
• Open source でも inference が無料になるわけではありません。Repository は MIT license ですが、API 利用料は設定した Provider に発生します。

DeepSeek Harness の OmniaKey 設定値

先に必要な値をまとめます。

Base URL には /v1 が必要です。裸の origin、/v1/v1 の重複、完全な /chat/completions request path は入力しないでください。Harness が operation path を付加します。

1. DeepSeek Harness をインストールして起動する

Node.js を用意し、Agent に見せたい project directory で terminal を開き、公式の npm quick start を実行します。

npx @deepseek-ai/dsh web

現在の command は Web UI を次の address で起動します。

http://127.0.0.1:3080

3080 が使用中なら別の port を指定できます。

npx @deepseek-ai/dsh web --port 3081

dsh を起動した directory が既定の filesystem location になります。ただし UI で workspace を追加して選択するまでは composer を使えません。対象 repository を明示的に選び、active permission policy が許す file と shell tools だけを Agent に渡してください。

2. OmniaKey API key を専用に作る

OmniaKey API Keys dashboard を開き、DeepSeek Harness 専用の key を作成します。複数ツールで同じ credential を共有するより、quota、rotation、revocation、audit を分けやすくなります。

平文 key を repository、shell history、screenshots、issues、chat logs に残さないでください。Web UI で保存した key は write-only です。DeepSeek の資料によると secret は $DSH_HOME/.credentials.yaml に保存され、settings には credential reference だけが残り、画面には redacted descriptor が返ります。

3. OmniaKey を custom provider として追加する

新規 install では Internal Testing Notice を Continue で進めます。次の onboarding は公式 DeepSeek API key を求めますが、OmniaKey は built-in route ではなく custom provider に設定するため Configure later を選びます。

DeepSeek Harness の Settings → Models を開き、Add a custom provider を選んで入力します。

1. Provider ID は omniakey。小文字から始めます。
2. Display name は OmniaKey。
3. Base URL は https://api.omniakey.com/v1。
4. API protocol は openai-completions。
5. API key に作成した OmniaKey key を貼り付けます。

Provider ID は作成後に rename できません。保存済み sessions、defaults、requests、credential references が参照するためです。Display name、Base URL、protocol、credential、model list は編集できます。

4. モデルを取得して選択する

Model catalog で Fetch available models を選びます。Custom OpenAI-compatible Provider では、現在の Base URL に Bearer authentication を付けて GET /models を呼びます。この設定なら OmniaKey の GET /v1/models が対象です。

実際に使う model だけを選びます。開始候補は次の二つです。

同じ Provider から、OmniaKey が現在対応する Claude、GPT、Gemini、Grok、GLM も利用できます。正確な ID は live model catalog から取得してください。Model name は曖昧な alias ではなく正確な identifier です。

Discovery が一時的に失敗した場合は、正確な Model ID を手動で追加できます。Custom Provider の作成には最低一つの model が必要です。

5. Workspace を選び、安全に確認する

Provider を保存し、Choose workspace で project を選択します。新しい session を作成し、model picker で OmniaKey / deepseek-v4-pro または OmniaKey / deepseek-v4-flash を選びます。

最初は読み取り専用の狭い task を実行します。

package.json を確認して、利用可能な scripts を要約してください。ファイルを編集せず、command も実行しないでください。

これで workspace、Provider、key、正確な model ID、基本 response path を、編集や shell command を許可する前に確認できます。Text response の成功だけではすべての tool-call pattern は証明できないため、大きな refactor の前に reversible な tool task も試してください。

Model settings は server restart なしで次の request から有効になります。ただし最初の request を送った session は、log に記録した model を保持します。Provider や model を変えた後は新しい session で試すと結果が明確です。

任意：settings.yaml で OmniaKey を設定する

初回は Web UI が分かりやすい方法です。管理されたローカル環境では、$DSH_HOME/settings.yaml に Provider profile を置き、key を直接書かず environment variable を参照できます。

export OMNIAKEY_API_KEY="your-omniakey-api-key"

llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniaKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

Key は Harness process の environment に存在する必要があります。settings.yaml に literal secret を書かず、apiKeyEnv を使ってください。公式 dsh-llm-pi-ai reference も、settings document に secret を入れない credential reference を推奨しています。

DeepSeek Harness で OmniaKey を使う理由

DeepSeek Harness は custom gateway をサポートしており、OmniaKey はその extension point を再利用できる一つの Provider 設定にします。

• 複数の model family に一つの設定。 Vendor ごとに gateway profile を作らず、picker で正確な model ID を切り替えられます。
• Model discovery。 ID を暗記して入力せず、OmniaKey の OpenAI-compatible list を取得できます。
• 独立した運用管理。 Harness 専用 key、quota、rotation、usage trail を設定できます。
• 明確な model identity。 OmniaKey は silent model substitution を行わず、指定した Provider と model が実行されます。Upstream が利用できなければ visible failure を返します。
• 追加の Agent subscription ではなく API usage に支払う。 OmniaKey は prepaid の per-token billing で、availability と rate はカタログに維持されます。

OmniaKey が公式 DeepSeek key より常に優れているという意味ではありません。DeepSeek の native account と endpoint だけが必要なら direct provider が自然です。一つの Harness で選択した DeepSeek と他の model family を一つの key と Base URL の後ろで使いたい場合に価値があります。

トラブルシューティング

Fetch available models が 401 を返す

Key が OmniaKey で発行され、前後に spaces がなく、有効で、正確な https://api.omniakey.com/v1 と組み合わされているか確認します。Model discovery は Bearer authentication を使います。

Provider が 404 を返す

Model を変える前に Base URL を確認します。よくある誤りは /v1 の欠落、/v1/v1 の重複、https://api.omniakey.com/v1/chat/completions を Base URL に入れることです。

UNKNOWN_MODEL

選択した model が custom provider の保存済み list にありません。再度 models を取得するか、OmniaKey catalog の正確な ID を追加し、新しい session で選択します。

MISSING_CREDENTIAL

Settings → Models で key を保存するか、DeepSeek Harness を起動した shell に OMNIAKEY_API_KEY があるか確認します。別の terminal で variable を設定しても、すでに動いている process は更新されません。

Model を変えても反映されない

新しい session を開始します。既存 session は最初の request 後、append-only log に記録された Provider と model を保持します。

Text は動くが Agent tool が失敗する

Basic text generation と structured tool use は別の確認です。Read-only tool task から始め、Harness の Trajectory view で正確な failure を調べてから limits や permissions を広げます。不正な tool call は有効な API key を rotate しても直りません。

よくある質問

DeepSeek Harness は無料ですか？

Source code は MIT license です。Model inference は別であり、DeepSeek、OmniaKey、その他の Provider を使うと API charge が発生する場合があります。

OmniaKey 経由で DeepSeek V4 Pro を使えますか？

はい。OmniaKey を openai-completions custom provider として追加し、正確な ID deepseek-v4-pro を選択します。より低価格の route として deepseek-v4-flash も利用できます。

0813 release、公式 peak/off-peak rate、token cost の計算は DeepSeek V4 Pro API pricing guide (English) を参照してください。新しい Flash route、native vision、benchmark evidence、V4 Pro の現状は DeepSeek V4.1 Flash review にあります。

OmniaKey key を built-in DeepSeek card に貼るべきですか？

代わりに Add a custom provider を使います。Built-in card は公式 DeepSeek route を設定します。Custom-provider form は gateway のための公式経路で、OmniaKey に必要な Base URL、protocol、model list を入力できます。

同じ Provider で Claude、GPT、Gemini を使えますか？

OmniaKey の OpenAI-compatible surface が現在対応していれば使えます。Live list を取得し、必要な正確な ID を追加してください。Protocol-specific behavior は異なるため、すべての model が同じだと仮定せず tool behavior を確認します。

API key はどこに保存されますか？

Models page で保存した key は write-only で $DSH_HOME/.credentials.yaml に格納され、settings には credential reference が残ります。YAML を直接使う場合は apiKeyEnv で process environment から渡します。

安定した production workflow に使えますか？

現時点では evaluation target として扱います。DeepSeek は明示的に developer preview とし、compatibility-breaking changes を警告しています。Version を pin し、secret を含まない設定を backup し、upgrade 後に公式ガイドを再確認してください。

確認した情報源

• DeepSeek Harness product page
• DeepSeek Harness GitHub README
• Official Web UI quick start
• Official model and custom-provider guide
• Official dsh-llm-pi-ai provider reference
• OmniaKey OpenAI-compatible API reference (English)
• OmniaKey live model catalog