Claude DesktopにsshConfigsでチーム共通のSSH接続を配る

Claude Desktopで共有の開発VMにSSHでつなぐチームなら、接続情報を全員に手入力させる必要はありません。管理者が sshConfigs をmanaged settingsに書くと、各メンバーの環境ドロップダウンに接続が自動で並びます。

sshConfigs は、環境ドロップダウンにSSH接続を追加するDesktop用の設定です。スコープはユーザー設定かmanaged settingsのどちらか。managed settingsで配った接続は「管理対象」として表示され、利用者が変えられるのはWorktree folderだけです。

sshConfigsの中身 — 必須3項目と任意2項目

値は、接続を表すオブジェクトの配列です。各要素のフィールドは次の5つです。

sshPort と sshIdentityFile を空にすると、SSH設定やSSHエージェントの内容がそのまま使われます。id の使われ方は設定リファレンスに説明がないので、チーム内で重ならない短い英数字にしておくのが無難です。

既定値は未設定で、何も書かなければ配られる接続はありません。

managed settingsに書く最小の例

共有開発VMを1件配る例です。公式ドキュメントの例に沿った形です。

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

ファイルで配るなら、置き場所は managed-settings.json を入れるシステムディレクトリです。

MDMやサーバー管理の設定でも、キーは settings.json と同じです。managed settingsを管理設定として配る型は、allowedProvidersで接続先を限定する記事でも同じです。

利用者の画面ではどう見えるか

配られた接続は、環境ドロップダウンのSSHの下に管理対象として並びます。利用者にできることは次のとおりです。

• 接続を選んでセッションを始める
• 歯車アイコンから、その接続のWorktree folderを自分で設定する

編集と削除はアプリ上でできません。ホスト名やポートの打ち間違いが各自の端末に散らばらず、変更は管理者が配り直すだけで済みます。

Worktree folderは、新しいSSHセッションがworktreeを作るリモート側のフォルダです。接続側の設定が最優先で、その次がリモートの worktree.location、最後が既定の <project-root>/.claude/worktrees/ になります。この優先順位とプロジェクト内を指したときの扱いは、SSHでWorktreeの置き場所を決める設定で詳しく扱っています。なお組織がセッションで使えるフォルダを制限している場合、Desktopはこのフィールドを隠します。

sshHostAllowlistとの整合を取る

sshConfigs は接続の候補を配るだけで、接続先の制限はしません。制限は sshHostAllowlist の役目で、managed settingsからだけ読まれます。

2つを併用するときは、sshHostAllowlist のパターンが各 sshConfigs の sshHost と一致する必要があります。ただし照合に使うのは user@ を除いたホスト名です。user@dev.example.com を配るなら、許可側には dev.example.com か *.example.com を置きます。一致しないと、配った接続に利用者が入れません。

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "dev.example.com"
    }
  ],
  "sshHostAllowlist": ["dev.example.com"]
}

disableDesktopLocalSessions も足すと、ローカルセッションを止めたうえで、SSHを配った接続だけに絞れます。この3つの組み合わせは公式が1つの構成として示しています。disableDesktopLocalSessions にはClaude Desktop v1.37937.0以降が必要です。allowlist側の詳しい設計はsshHostAllowlistの記事にあります。

ホスト名の別名を使うときの考え方

sshHost には、~/.ssh/config に定義したホスト名も書けます。踏み台を挟む構成なら、ProxyJump などの細かい指定を各自のSSH設定側に持たせ、配る接続は別名だけにする手もあります。

sshHostAllowlist の照合は、~/.ssh/config を ssh -G で解決したあとのホスト名に対して行われます。Host の別名や ProxyCommand / ProxyJump があっても、解決後の HostName がパターンに一致すれば通ります。配る別名と許可パターンの対応は、別名ではなく解決後のホスト名で見てください。

ただし別名の定義そのものは各開発者の端末にあるため、sshConfigs では配れません。別名で配るなら、SSH設定の配布も別途必要です。

読み込み元は1つだけ — 配ったのに出ないとき

Desktopは sshConfigs をローカル端末のmanaged settingsから読みます。複数の経路で設定を配っている組織では、ここが最大のつまずきどころです。

既定の managedSourcesBehavior は "first-wins" です。ランク最上位で、ポリシーキーを1つでも持つソースだけが使われ、残りは統合されずに無視されます。無視されたソースについて警告は出ません。順位は次のとおりです。

たとえばサーバー管理設定で別のキーを配っている組織が、sshConfigs だけを端末の管理設定ファイルに書いても、既定ではファイル側が読まれません。端末で /status を実行して Setting sources の行を見ると、どのソースが選ばれたか分かります。sshConfigs は、選ばれたソースに入れてください。

同じ理由で、サーバー管理設定を使う組織は、各端末の最上位のMDMまたは設定ファイルにも同じキーの写しを置いておくのが公式の案内です。Desktopはサーバー管理設定を起動時に取得し、キャッシュを持たないため、取得が成功するまでは端末側の写しが効きます。

すべてのソースを合成したいときは、managedSourcesBehavior を "merge" にします。必要なClaude Codeはv2.1.242以降で、キーは最上位のソースに置きます。

ユーザーが自分のsettings.jsonに書くこともできる

スコープが「User or managed」なので、個人が ~/.claude/settings.json に sshConfigs を書いても接続を追加できます。「管理対象」として固定されるのは、managed settingsで配った接続です。接続先を制限したい目的に sshConfigs は使えません。ここは sshHostAllowlist の担当です。

ユーザー設定側に書かれた接続の編集の可否は、公式ドキュメントに記載がありません。運用で統制したい接続は、managed settings側で配ってください。

配ったあとの確認と典型的な失敗

配布後は、利用者の端末で次の2点を確かめます。

接続は見えるのにつながらないときは、リモート側の条件が原因のことがあります。公式が挙げる条件は次のとおりです。

• SSHサーバーがSFTPサブシステムを提供している
• sshd_config が MaxSessions 1 になっていない(macOSとLinuxのDesktopは1接続で複数セッションを開く)
• ~/.claude/remote/ を含むホームのファイルシステムが noexec でマウントされていない
• ホームディレクトリに約1GBの空きがある

最初の接続時に、DesktopがリモートにClaude Codeを自動でインストールします。サードパーティプロバイダー経由でDesktopを使う組織では、SSHセッションが既定で無効になり、別の設定が必要です。その場合は sshHostAllowlist を設定すると有効にできるため、導入前に公式の3P向けSSH案内を読んでください。

合わせて検討したい設定と、動かない範囲

関連するのは disableSshSavedPasswords です。true にすると、DesktopがSSHパスワードの保存を提案せず、保存済みのパスワードも使わず表示もしません。保存済みのものは削除されません。managed settingsからだけ読まれ、Claude Desktop v1.49585.0以降が必要です。

これらのキーが効くのはデスクトップアプリです。CLIで動かすClaude Code、Cowork、クラウドセッションの利用可否は変えません。

接続の配布は、リンクからSSH接続つきでセッションを開く運用とも組み合わせられます。リンクの ssh_host と ssh_port を配った接続の値と揃えておくと、ダイアログが「新しい接続の追加」にならず、既存接続の利用に進みます。リンク側の作り方はClaude DesktopのリンクでSSH接続つきセッションを開くにまとめています。

まとめ

sshConfigs の要点は、配る手間より「どのソースから読まれるか」にあります。id・name・sshHost の3項目を書くだけで接続は並びますが、複数経路で管理設定を配る組織では、書いた場所が読まれない事故が起きます。端末で /status を見る確認を、配布手順に1行入れておくと安全です。