Claude DesktopのリンクでSSH接続つきセッションを開く

Claude Desktopのclaude://code/newリンクは、ssh_hostなどのパラメータを足すとSSH接続先まで指定できます。障害対応のランブックやチームのwikiに貼っておけば、クリックした人のDesktopが「この踏み台サーバーのこのフォルダー」を向いた状態で開きます。

この形式に使うパラメータは4つで、必須はssh_hostだけです。SSH接続つきのリンクを扱えるのはClaude Desktop v2.110.0以降です。

SSH接続つきリンクの形

claude://code/newは、Desktopの新規セッション画面を開くリンクです。ここにSSH用のパラメータを足すと、接続先も指定できます。公式の例は次のとおりです。

claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

このリンクが指すのは、build.example.comのユーザーdev、ポート2222、フォルダー/srv/paymentsです。さらにプロンプト欄には「Investigate the failed deploy」が入ります。@は%40に置き換わっています。

4つのパラメータの書き方

パラメータ	必須	値の条件
`ssh_host`	必須必須	値の条件`host`または`user@host`。DesktopのSSH host欄と同じ書き方
`ssh_port`	必須任意	値の条件1〜65535のポート番号
`ssh_folder`	必須任意	値の条件リモート側のフォルダー。`/`か`~/`で始めるか、`~`だけを書く
`q`	必須任意	値の条件プロンプト欄に入れるテキスト(URLエンコード済み)

ssh_hostには制約があります。先頭を-にはできません。ホスト部分に使えるのは英字・数字と.、_、:、-だけです。

値の書き方の合否例

上の条件に当てはめると、次のように判定できます。判定はドキュメントの条件から導いたもので、Desktopでの実機確認ではありません。

値	判定	理由
`ssh_host=dev%40build.example.com`	判定通る	理由`user@host`の形で、ホスト部分は使える文字だけ
`ssh_host=-oProxyCommand%3Dx`	判定通らない	理由先頭が`-`のため
`ssh_port=70000`	判定通らない	理由1〜65535の範囲外
`ssh_folder=~/work`	判定通る	理由`~/`で始まる
`ssh_folder=work`	判定通らない	理由`/`・`~/`・`~`のいずれでも始まらない

先頭が-の値を禁じているのは、ホスト名がsshのオプションとして読まれる事態を避ける条件と読めますが、理由の記載はありません。

`~/.ssh/config`のエイリアスは配布向きではない

ssh_hostに~/.ssh/configのエイリアスを書くことはできます。ただし動くのは、そのエントリーを持つ人だけです。

配布するリンクでは、エイリアスを避けて実際のユーザー・ホスト・ポートを書くほうが安全です。既存の接続と照合されるのも、この3つが一致したときだからです(次の節で説明します)。

リンクを開くと何が起きるか

リンクを開いても、Desktopはすぐには接続しません。確認を挟み、結果は2通りに分かれます。

すでにある接続と一致する場合: ホスト・ユーザー・ポートが既存の接続と合えば、その接続を使うか尋ねます。ダイアログには接続の名前とホスト、リンクにフォルダーがあればそのフォルダーも出ます
一致する接続がない場合: SSH接続を追加するダイアログが開きます。接続を追加する段階で、保存の前に「接続するか」を尋ねます。ここにリンクのホストが表示され、ポートとフォルダーがあればそれも表示されます

確認するまで、リンクのホスト・ポート・フォルダーは保存されません。それらを使った接続の選択や接続の開始もありません。

一点だけ注意があります。別のSSH接続をすでに選んでいる場合、新規セッション画面はリンクと無関係にその接続へつなぎにいきます。リンクが同じホストを指していても同じです。

リンクに載せられないもの

リンクには、鍵ファイル・パスワード・コマンドを載せられません。認証情報はリンクの外、つまり各自の~/.ssh/configやSSHエージェントに任せる設計です。鍵のパスを使いたいときは、接続の設定にあるSSH key欄に入れておきます。

プロンプトは入るが、送信はされない

qのテキストは、リンクを開いた時点でプロンプト欄に入ります。まだ送信していなかった入力があれば、それを置き換えます。送信は必ず人が行います。

Desktopはqをプレーンテキストとして扱います。先頭が/や!でもコマンドにならず、@のファイルメンションも効きません。リンクにスラッシュコマンドを仕込む使い方は、この仕様で塞がれています。キャンセルした場合、プロンプトは入力欄に残り、選択中の環境は変わりません。

出どころを問わず、次の2点を確かめます。

確認ダイアログの前に、ホストとフォルダーを見る
送信の前に、プロンプトと選択中の環境を見る

誰でもリンクを書けるので、ランブックの利用者にも同じ手順を周知しておくと安全です。

リンクを手書きせず組み立てる

値はURLエンコードが必要です。手書きだと@や日本語で崩れます。次のスクリプトで組み立てられます。

const e = encodeURIComponent;
const sshLink = ({ host, port, folder, q }) => {
  const p = [["ssh_host", host]];
  if (port) p.push(["ssh_port", String(port)]);
  if (folder) p.push(["ssh_folder", folder]);
  if (q) p.push(["q", q]);
  return "claude://code/new?" + p.map(([k, v]) => `${k}=${e(v)}`).join("&");
};
 
console.log(sshLink({ host: "dev@build.example.com", port: 2222,
  folder: "/srv/payments", q: "Investigate the failed deploy" }));
console.log(sshLink({ host: "dev@build.example.com",
  q: "直近のデプロイ失敗を調べて" }));

Node.jsで実行した出力は次のとおりです。

claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=%2Fsrv%2Fpayments&q=Investigate%20the%20failed%20deploy
claude://code/new?ssh_host=dev%40build.example.com&q=%E7%9B%B4%E8%BF%91%E3%81%AE%E3%83%87%E3%83%97%E3%83%AD%E3%82%A4%E5%A4%B1%E6%95%97%E3%82%92%E8%AA%BF%E3%81%B9%E3%81%A6

1行目は、ドキュメントの例とssh_folderのスラッシュのエンコード(%2F)だけが違います。encodeURIComponentは/も変換するためで、ドキュメントの例は/をそのまま書いています。%2Fのリンクをどう扱うかは、ドキュメントに記載がありません。配布前に実機で開いて確かめてください。

2行目はssh_portとssh_folderを省いた最小形です。ポートを省いた場合の扱いは、ドキュメントに直接の記載がありません。SSH port欄の既定に従うと考えられますが、既存接続との照合にはポートが使われるため、既存接続がポートを明示している場合は揃えてください。

macOSなら、作ったリンクは次のコマンドで試せます。

open "claude://code/new?ssh_host=dev%40build.example.com&q=Hello"

openコマンドでの起動方法は、Claude Desktopをclaude://リンクで起動するにOS別にまとめています。

wikiやREADMEに貼るときの注意

Markdownレンダラーによっては、httpとhttps以外のリンクを削除します。GitHubのREADME・issue・PR・wikiがこれにあたり、[ラベル](claude://...)はラベルだけの文字列になります。こうした場所では、リンクをコードブロックに入れ、読者がURLを自分でブラウザーのアドレスバーに貼れるようにします。

リンクをクリック可能なまま保てる社内wikiやダッシュボードのほうが、この形式には向いています。

リンクの接続先は何で決まるか

リンクが指せるのは「どのマシンのどのフォルダーか」だけで、接続先で何が動くかは、リンクではなくリモート側の状態で決まります。踏む前に知っておきたい前提は次のとおりです。

リモートのOS: LinuxかmacOSである必要があります
Claude Codeの導入: 初めて接続するとき、DesktopがリモートにClaude Codeを自動でインストールします
スキル: SSHセッションは、手元ではなくリモートホストのホームにある~/.claude/skills/を読みます
worktreeの置き場所: 新しいセッションのworktreeは、接続に設定したWorktree folderなど、ドキュメントが定める優先順で決まります

つまり、ランブックのリンクが同じでも、リモートの~/.claude/skills/が違えば使えるスキルも違います。チームでリンクを配るなら、踏み台側のスキル配置もそろえておく必要があります。

claude-cli://のディープリンクとの違い

Claude Codeには、ターミナルで開くための別形式claude-cli://のディープリンクもあります。こちらは新しいターミナルウィンドウでClaude Codeを開き、作業ディレクトリとプロンプトを渡します。リンクをどこに置いても、セッションはクリックしたコンピューター上でローカルに開きます。

SSH接続つきセッションをDesktopで開きたい場合は、claude://のほうを使います。ディープリンクのドキュメントも、DesktopのSSHセッションについてはDesktop側のページに案内しています。

形式	開く先	リモート接続の指定
`claude-cli://`	開く先新しいターミナルウィンドウ	リモート接続の指定なし(クリックした手元で開く)
`claude://code/new`	開く先Claude DesktopのCodeタブ	リモート接続の指定`ssh_host`などで指定できる

ランブックに貼る例

障害対応のランブックなら、症状ごとに調査用のプロンプトを入れたリンクを並べる使い方があります。次のように、同じ接続先でプロンプトだけを変えます。

## web-gatewayの5xxが増えたとき
 
1. 次のリンクをコピーし、ブラウザーのアドレスバーに貼る(GitHubのwikiの場合)
   claude://code/new?ssh_host=oncall%40bastion.example.com&ssh_folder=%2Fsrv%2Fgateway&q=%E7%9B%B4%E8%BF%91%E3%81%AE5xx%E3%81%AE%E3%83%AD%E3%82%B0%E3%82%92%E8%AA%BF%E3%81%B9%E3%81%A6
2. 確認ダイアログでホストとフォルダーを見て、接続する
3. プロンプトの内容を確認してから送信する

上のURLのqは、「直近の5xxのログを調べて」をencodeURIComponentに通した値です。手順2と3は、前の節の確認をそのままランブックに書き込んだ形です。

管理者がチームに接続を配るsshConfigsを使っているなら、リンクのssh_hostとssh_portも、その接続のsshHost・sshPortと同じ値にそろえます。そうすれば、ダイアログは「新しい接続の追加」ではなく「既存の接続を使うか」になり、利用者の手数が減ります。

開いてもダイアログが出ないときの原因

リンクでDesktopは開くのに、接続に関するダイアログが出ない場合は、次の原因を順に見ます。

症状	原因	対処
ダイアログが出ない	原因サインアウトしている	対処サインインしてからリンクを開き直す
ダイアログが出ない	原因別のダイアログが開いている	対処そのダイアログを閉じて開き直す
修正を促すメッセージが出る	原因リンクが不正(`ssh_host`の文字種や`ssh_port`の範囲など)	対処メッセージに従ってリンクを直す。プロンプトも入らない
プロンプトだけ入る	原因Desktopがv2.110.0より古い	対処SSHのパラメータは無視され、プロンプトだけの新規セッション画面になる。Desktopを更新する
SSHリンクを拒否される	原因管理者が許可リストを空配列にしている	対処SSHセッションが無効化されているため、管理者に確認する

古いDesktopがエラーにならず、プロンプトだけを入れて開く点は見落としやすい挙動です。配布先のDesktopのバージョンが揃っていない組織では、「リンクは開くがSSHにならない」という問い合わせが出やすくなります。

管理者が設定する許可ホストはリンクでも有効

リンクはsshHostAllowlistを回避しません。許可リストは接続する時点で確認されるため、許可されていないホストへは、リンクから開いても接続できません。

許可リストの書き方と、パターンが解決後のホスト名に対して一致する仕組みは、sshHostAllowlistの解説にあります。リンクを配る側と許可リストを管理する側が別のチームなら、リンクのホストが許可パターンに入っているかを先に突き合わせます。

リンクは接続を呼び出す入口で、接続の保存や認証は別の仕組みです。接続の追加手順やSSH鍵まわりはClaude Code SSH接続ガイドが扱っています。

まとめ

SSH接続つきリンクの要点は次の5つです。

claude://code/newにssh_host(必須)・ssh_port・ssh_folder・qを付ける
Claude Desktop v2.110.0以降が必要で、v2.110.0より古いDesktopではプロンプトだけ入って開く
開くと必ず確認ダイアログが出て、確認までは何も保存されない
鍵・パスワード・コマンドは載せられず、プロンプトは自動送信されない
許可リストはリンクでも有効

配布の前に、実際のユーザー・ホスト・ポートで、既存接続と一致する場合としない場合の両方を自分で開いておくと、利用者が見る画面を事前に確認できます。

Claude DesktopのリンクでSSH接続つきセッションを開く

SSH接続つきリンクの形

4つのパラメータの書き方

値の書き方の合否例

`~/.ssh/config`のエイリアスは配布向きではない

リンクを開くと何が起きるか

リンクに載せられないもの

プロンプトは入るが、送信はされない

リンクを手書きせず組み立てる

wikiやREADMEに貼るときの注意

リンクの接続先は何で決まるか

claude-cli://のディープリンクとの違い

ランブックに貼る例

開いてもダイアログが出ないときの原因

管理者が設定する許可ホストはリンクでも有効

まとめ

Claude Codeとは — できること・料金・始め方と使い方の全体像

Claude Desktopをclaude://リンクで起動する

sshHostAllowlistでClaude Code DesktopのSSH接続先を制限する

Claude apps gatewayのdesktopブロックでClaude Desktopに設定を配る

Claude Desktopでキーチェーンの許可を毎回求められる原因と対処

Claude Code Desktopの内蔵ブラウザで外部サイトを操作する

SSH接続つきリンクの形

4つのパラメータの書き方

値の書き方の合否例

~/.ssh/configのエイリアスは配布向きではない

リンクを開くと何が起きるか

リンクに載せられないもの

プロンプトは入るが、送信はされない

リンクを手書きせず組み立てる

wikiやREADMEに貼るときの注意

リンクの接続先は何で決まるか

claude-cli://のディープリンクとの違い

ランブックに貼る例

開いてもダイアログが出ないときの原因

管理者が設定する許可ホストはリンクでも有効

まとめ

関連する記事

Claude Codeとは — できること・料金・始め方と使い方の全体像

Claude Desktopをclaude://リンクで起動する

sshHostAllowlistでClaude Code DesktopのSSH接続先を制限する

Claude apps gatewayのdesktopブロックでClaude Desktopに設定を配る

Claude Desktopでキーチェーンの許可を毎回求められる原因と対処

Claude Code Desktopの内蔵ブラウザで外部サイトを操作する

`~/.ssh/config`のエイリアスは配布向きではない