つまずいたらここから
目次
SSH・tmux・Tailscale を使ったリモート開発が止まる原因は、おおむね 8 つの典型パターンに収まります。タイムアウト、鍵やパスワードの拒否、tmux や claude が見つからないエラー、Tailscale や Mac の接続拒否、非対話での sudo 失敗です。
前の記事通りに組めば大半は初回で動きます。動かないときもほぼこの 8 つのどれかに当てはまるため、出たエラーメッセージの項目へ直接飛んでください。上から順に読む必要はありません。
接続がタイムアウトする(Operation timed out)
症状
ssh user@host を実行しても画面が止まったままになり、しばらく待ったあとに Operation timed out または Connection timed out が出ます。パスワードを聞かれる段階まで進みません。
原因
- ホスト名の入力ミス(例:
my-serverr)。この場合は待たずにCould not resolve hostnameが返るため、その表示が出たら綴りを確認してください。無反応のまま固まるのは IP アドレスの間違い、桁抜け、または何も待ち受けていないアドレス宛てです。 - 接続先の SSH が標準のポート 22 以外で動いており、
-pの指定が抜けている。 - 接続先のマシンがスリープしている、または電源が切れている。
- 途中のファイアウォール(自宅ルーター、社内ネットワーク、ホテルの Wi-Fi など)がパケットを破棄しており、マシンに届いていない。
対処法
対処法:タイムアウトはパケットがマシンに届いていない状態なので、推測せず 1 ホップずつ切り分けます。まずマシン自体が応答するか確認します。
ping host-address
ping の応答が返らない場合は、IP の誤り、スリープ、電源断を確認してください。ただし ping を意図的に遮断しているマシンもあるため、失敗しただけで到達不能とは言い切れません。そのまま次の確認へ進みます。
次に、SSH ポートで何かが待ち受けているか確認します。
nc -vzw 5 host-address 22
22 は接続先が実際に使っているポート番号に置き換えてください。-w 5 で待機を 5 秒に区切るため、ブロックされていても固まらず結果が出ます。
結果は 3 通りのいずれかです。succeeded または open ならポートには届いているため別の原因です。Connection refused ならマシンまでは届いているものの、そのポートで SSH が動いていません。再びタイムアウトするなら途中の経路(多くの場合ファイアウォール)で落ちているため、ルーターや利用中のネットワーク設定を確認してください。
Permission denied (publickey)
症状
接続した瞬間に拒否され、Permission denied (publickey). と表示されます。パスワードの入力も求められません。
原因
サーバーが提示された鍵を受け入れていません。もっともよくあるのは、そもそも公開鍵をサーバー側へ登録していないケースです。
もう 1 つ見落としやすい原因が、~/.ssh や authorized_keys のパーミッションが緩すぎることです。SSH はこの点に厳格で、パーミッションが不適切だと中身が正しい鍵でもファイルごと無視します。
対処法
対処法:鍵が拒否される場合、多くはサーバーに公開鍵がまだ入っていないことが原因です。まだコピーしていないなら、パスワードで 1 度ログインしてサーバーの authorized_keys に公開鍵を追記する ssh-copy-id が最短です。
ssh-copy-id user@host
これはサーバー側でパスワードログインが有効な場合に限ります。すでに無効化されている場合(下の「パスワードは合っているのに拒否される」を参照)は、そのマシンを直接操作できる環境から ~/.ssh/authorized_keys へ公開鍵を貼り付ける必要があります。
鍵が 1 行ずつ欠けずに正しく入っているのに拒否されるなら、パーミッションを疑います。次の表と照合してください。特に最後の行は見落とされがちです。~/.ssh と authorized_keys を直しても、ホームディレクトリ自体にグループや他ユーザーの書き込み権限が残っていると StrictModes に弾かれます。
| パス | 必要なパーミッション | コマンド |
|---|---|---|
~/.ssh | 700 | chmod 700 ~/.ssh |
~/.ssh/authorized_keys | 600 | chmod 600 ~/.ssh/authorized_keys |
~(ホームディレクトリ自体) | グループ・他ユーザー書き込み不可 | chmod go-w ~ |
パーミッションを直したら再接続します。それでも失敗する場合はローカル側で -v を付けて、想定通りの鍵が提示されているか確認してください。
ssh -v user@host
50〜60 行ほど出力されますが、見るのは 2 行だけです。Offering public key: ... が出ていればクライアント側からは正しく送信されています。その直後に Authentications that can continue: publickey が続くなら、サーバーが鍵を受け取った上で拒否しているため、鍵の配置先かパーミッションを再確認してください。
パスワードは合っているのに拒否される
症状
パスワードは確実に合っており貼り付けも試したのに、SSH が Permission denied, please try again. を返し続けます。パスワードを聞かれずに終了することもあります。
原因
ほとんどの場合、パスワード自体は問題ではありません。サーバー側の SSH 設定でパスワード認証が無効(PasswordAuthentication no)になっています。公開鍵認証を強制してパスワード総当たり攻撃を防ぐための一般的な設定で、これが有効だと正しいパスワードを何度入れても拒否されます。
ここで多くの人が時間を使う落とし穴があります。Ubuntu 22.10 以降、Debian 12、および大半のクラウド事業者の標準イメージでは、sshd_config の先頭付近に Include /etc/ssh/sshd_config.d/*.conf という行があり、そのディレクトリ内の設定ファイルをすべて読み込みます。
sshd は各設定について最初に読んだ値を採用するため、後ろの行に書いても上書きされません。/etc/ssh/sshd_config.d/ の中に 50-cloud-init.conf などのファイルがあり、そこに PasswordAuthentication no が書かれていると、メインの sshd_config を編集してサービスを再起動しても拒否され続けます。
対処法
対処法:より望ましい解決策は公開鍵認証に切り替えることです。上の「Permission denied (publickey)」の手順でサーバーの authorized_keys に公開鍵を登録してください。
サーバーの管理者としてパスワードログインを有効にしたい場合のみ設定を変更します。まず、編集しようとする値を別のファイルが上書きしていないか確認します。
sudo grep -r PasswordAuthentication /etc/ssh/sshd_config /etc/ssh/sshd_config.d/
/etc/ssh/sshd_config.d/ 配下のファイルにも PasswordAuthentication が書かれていたら、そちらも変更するかコメントアウトします。その上で /etc/ssh/sshd_config の PasswordAuthentication を yes にします。
この時点で現在の SSH 接続を閉じないでください。設定構文が壊れているとマシンに入れなくなります。新しい接続でログインできると確認できるまで、今のウィンドウを退路として残します。まず構文チェックを実行します。
sudo sshd -t
エラーが出なければサービスを再起動して反映します。
sudo systemctl restart ssh
ディストリビューションによってはサービス名が sshd の場合もあります。見つからない場合は sudo systemctl restart sshd を試してください。その後、退路のウィンドウとは別に新しい接続を開いてパスワードログインが通ることを確認し、通ってから古いウィンドウを閉じます。
Tailscale 経由で接続する構成なら、インターネット全体にパスワードログインを開く代わりに、Tailscale のアドレス帯からのみパスワードを許可し、それ以外は公開鍵のみにする方が安全です。sshd_config の末尾に次を追記します。
Match Address 100.64.0.0/10
PasswordAuthentication yes
Match All
PasswordAuthentication no
tmux not found
症状
Agentmux が tmux を見つけられないと表示する、または自分で接続して tmux を実行すると command not found: tmux になる。
原因
接続先のマシンにまだ tmux が入っていません。通常は Agentmux が apt、yum、dnf、pacman、apk(Alpine)、brew のどれを使うか判別して SSH 越しに自動インストールするため、終わるまで待つだけで済みます。
それが失敗する一番の理由は sudo です。インストールコマンドに sudo が含まれているのに実行経路が非対話のため、パスワードを入力する端末がありません(下の「sudo: a terminal is required to read the password」を参照)。2 番目に多いのは Mac に root で接続して Homebrew を動かそうとするケースで、Homebrew は仕様上 root での実行を拒否します。
Windows ホストでも仕組みは同じで、対象が psmux に変わります。Agentmux は winget、Scoop、cargo の順で導入を試みますが、3 つとも入っていない環境では「Neither winget, scoop, nor cargo was found on the Windows server. Install psmux manually, then reconnect.」と表示します。パッケージマネージャーがないだけなので、下の手動手順で導入してください。
稀に誤解しやすいケースもあります。tmux 自体は入っているのに、Linuxbrew(~/.linuxbrew)や MacPorts(/opt/local/bin)など Agentmux の PATH 探索から外れた場所にある場合です。表示されるエラーは同じでも、原因は PATH 設定にあります。下の「Terminal では動くのに claude: command not found になる」と同じ方法で対処します。
対処法
対処法:まず Agentmux が表示したエラーを確認します。sudo パスワードの入力や passwordless sudo の案内が出ているなら、パスワードを入力して再試行するのが別ウィンドウを開くより早道です。それでも通らない場合や TTY に関するエラーが出る場合は、下の「sudo: a terminal is required to read the password」を確認してください。それが解消すれば自動インストールが通ることがほとんどです。
sudo の問題を切り分けても自動導入できない場合だけ、手動でインストールします。
# Debian / Ubuntu
sudo apt install -y tmux
# RHEL / CentOS
sudo yum install -y tmux
# Fedora
sudo dnf install -y tmux
# Arch
sudo pacman -S tmux
# Alpine
sudo apk add tmux
# Mac(root ユーザーで実行しないこと)
brew install tmux
Windows の場合は psmux をインストールします。
# Windows (PowerShell)
winget install -e --id marlocarlo.psmux --accept-package-agreements --accept-source-agreements
すでに psmux が入っている場合、winget は二重インストールせず「利用可能な新しいバージョンはありません」と返して止まらず終了します。この出力が出ればプログラムは存在しています。
winget がない環境では Scoop または cargo を使うか、バイナリを取得して PATH の通ったフォルダへ置きます。いずれの場合も導入後に再接続すれば、セッション開始時にアプリが自動で検出します。
Terminal では動くのに claude: command not found になる
症状
Mac の Terminal で claude と打つと起動するのに、Agentmux 経由や ssh host claude で直接実行すると claude: command not found や bash: claude: command not found になる。同じマシン・同じアカウントなので Agentmux の不具合に見えます。
原因
Agentmux の不具合ではなく、シェルの起動仕様によるものです。自力で原因を特定しにくい問題なので仕組みを整理しておくと、同種の現象をすべて自力で診断できるようになります。
Mac で開く Terminal は対話的ログインシェルです。そこで claude に PATH が通っているのは、nvm、npm、またはインストーラーが起動ファイルへ PATH 設定を書き込んだからです。どの起動ファイルを読むかは zsh と bash で異なり、混同すると見当違いのファイルを直すことになります。
zsh(macOS の標準):対話的ログインシェルは .zshenv → .zprofile → .zshrc → .zlogin の順に読み込みます。一方、ssh host claude のように単発コマンドを実行する接続は「非対話・非ログイン」の zsh を起動するため、.zshenv だけを読んで、多くの人が PATH を書いている .zshrc を含む残りをすべて飛ばします。
bash:こちらはディストリビューションによって挙動が異なります。対話的ログインシェルが読むのは .bash_profile(または .profile)で、多くの環境ではその中から .bashrc を読み込む記述が入っています。
一方、ssh host claude のように単発コマンドを実行する接続で ~/.bashrc を読むかどうかは、SSH_SOURCE_BASHRC というコンパイル時オプション次第です。Debian や Ubuntu 系はこのパッチが入っているため非対話の単発実行でも ~/.bashrc を読みますが、RHEL、Fedora、Arch は標準の bash のため読み込みません。
さらに .bashrc を読むディストリビューションであっても、既定の .bashrc の冒頭には次の記述があります。
case $- in
*i*) ;;
*) return;;
esac
これは「対話シェルでなければここで終了し、後ろを読まない」という意味です。この判定がファイルの先頭付近にあるため、bash が .bashrc を開いても、あなたが追記した PATH 行に届く前に抜けてしまい、結果として読んでいないのと同じになります。
zsh でも bash でも結末は同じです。PATH を設定する行は自分で Terminal を開いたときだけ実行され、SSH の単発コマンド実行では読まれないため、シェルは「claude が見つからない」と報告します。そのシェルに実行ファイルの場所が伝わっていないだけです。
非対話実行でこれらを飛ばすのは意図的な仕様です。そうしないと、リモートコマンド 1 つ実行するたびに大量の対話用エイリアスやプロンプト設定まで読み込まれ、余計な不具合の原因になるためです。
もう 1 点、Agentmux は Mac 上で PATH を調べる際に zsh -lc(ログイン・非対話)を使います。これも .zshrc を飛ばして .zshenv と .zprofile だけを読みます。そのため Mac の zsh ユーザーにとって、PATH 設定をこの 2 つのどちらかに移すことは、手動 SSH と同様に Agentmux 自体がエージェントを見つけられるかどうかに直結します。
対処法
対処法:もっとも手早いのは、PATH に頼らず claude の絶対パスを直接指定することです。普段 claude が動く Terminal ウィンドウで次を実行します。
which claude
/Users/yourname/.nvm/versions/node/v20.11.0/bin/claude のようなパスが出るので、Agentmux のエージェントコマンド設定欄に claude の代わりにこのフルパスを入れます。
nvm で Node を入れている場合、このパスにはバージョン番号が含まれるため、Node をアップグレードすると動かなくなり which claude をやり直す必要があります。やり直さずに済む恒久対策は次の通りです。
恒久対策はシェルによって異なるため、混ぜないでください。
zsh(macOS 標準)の場合:.zshrc に書かれている PATH 設定(nvm、pyenv、または自分で書いた export PATH=...)を ~/.zshenv へ移します。~/.zprofile でも構いません。どちらも非対話 SSH 実行と Agentmux の探索時に読み込まれます。
bash の場合:~/.profile や ~/.bash_profile へ移しても効果はありません。ssh host claude は非ログインシェルを起動するため、どちらも読まれません。
Debian・Ubuntu 系なら、~/.bashrc の先頭にある case $- in ... esac ブロックより上に PATH 行を置けば、対話チェックで抜ける前に実行されます。RHEL、Fedora、Arch 系ではそもそも ~/.bashrc が読まれないため、編集しても変わりません。
自分のディストリビューションがどちらか分からない場合は、絶対パスを使ってください。どの環境でも動き、ディストリビューションを問わず確実に通用する唯一の方法です。
設定を移したら、新しい SSH 接続で反映を確認します。
ssh host 'claude --version'
バージョン番号が返れば、非対話シェルでも PATH が正しく読まれています。
Tailscale は接続済みなのに SSH で繋がらない
症状
スマートフォンの Tailscale アプリでは両方の端末が緑色のオンライン表示になっているのに、Agentmux や素の ssh で接続すると失敗またはタイムアウトする。
原因
192.168.x.xのようなローカルネットワーク IP に繋ごうとしている。ローカル IP は同じ Wi-Fi 内でしか通じず、モバイル回線に切り替わった瞬間に無効になるため、MagicDNS 名や100.xの Tailscale IP を使う必要があります。- 接続先の端末が直前にオフラインになったかスリープに入り、アプリ上の「オンライン」表示の更新がまだ追いついていない。
- Tailscale 自体は正常でも、接続先の SSH サービスが有効化または起動されていない。Tailscale は 2 台のネットワークを繋ぐだけで、SSH までオンにしてくれるわけではありません。
- もっともよくある原因はノードキーの期限切れです。接続先マシンで再認証が必要になっているのに、アプリ側では緑色の「接続済み」のまま残ることがあります。Tailscale の管理コンソールで再サインインが必要なマークが付いていないか確認してください。
対処法
対処法:アプリ側の緑表示は古いキャッシュが残ることがあるため、まず接続先マシン側から確認します。スマートフォン版の Tailscale にはコマンドラインがないため、接続先の Mac または Linux マシンで tailscale status を実行します。
tailscale status
接続先マシン側でスマートフォンのノードがオンラインになっているか確認し、スマートフォン側の Tailscale アプリでも接続先マシンがグレーアウトしていたり「再サインインが必要」と出ていたりしないか確認します。
どちらも正常なら、tailscale status に出ている MagicDNS 名(例:mac-mini.tail1234.ts.net)または 100.x IP を使って接続します。これで自宅 Wi-Fi でもモバイル回線でも同じアドレスが使えます。
そこまで確認して問題なければ、接続先マシンで SSH サービスが動いているか確かめます。Linux なら sudo systemctl status ssh、Mac なら下の「リモートログインがオンなのに Mac が接続を拒否する」を確認してください。
リモートログインがオンなのに Mac が接続を拒否する
症状
システム設定で「リモートログイン」が有効になっており Mac も確実にネットワークに繋がっているのに、SSH で接続できない。あるいは接続できても、正しいはずのパスワードや鍵で拒否される。
原因
- リモートログインのアクセス許可が既定で「次のユーザーのみ」になっており、接続に使っているアカウントがそのリストに入っていない。
- Mac がスリープに入るとネットワークインターフェースも一緒に眠るため、リモートログインがオンでも SSH の応答を返せない。
対処法
対処法:「システム設定」→「一般」→「共有」を開きます(macOS Ventura 以降。それ以前は「システム環境設定」→「共有」)。「リモートログイン」のスイッチがオンであることを確認し、詳細を開いて許可されたユーザー一覧に自分のアカウントが入っているか確認するか、「すべてのユーザー」を選びます。
次に、ノート型なら「システム設定」→「バッテリー」、デスクトップ型(Mac mini、Mac Studio、iMac など)なら「システム設定」→「省エネルギー」を開き、自動スリープまでの時間を延ばすか無効にします。
「ネットワークアクセスによるスリープ解除」という項目があれば、これもオンにしてください。着信時にスリープから起きて SSH に応答できるようになります。
sudo: a terminal is required to read the password
症状
Agentmux や SSH 経由で sudo を含むコマンドを実行すると、実行された気配もなく即座に sudo: a terminal is required to read the password で失敗する。
原因
通常 sudo は端末にパスワードプロンプトを表示して入力を待ちます。しかし非対話の経路(単発コマンドの SSH や、Agentmux がバックグラウンドで走らせるインストール処理)ではプロンプトを出す端末(TTY)も入力先もないため、sudo は届かない入力を待たずに即座に拒否します。
一度 sudo パスワードを入力すればしばらく再入力不要になると思われがちですが、近年の sudo は認証記録をアカウントやマシン単位ではなく、そのとき使っていた TTY 単位(tty_tickets)で保持しています。
そのため、対話型 SSH ウィンドウでパスワードを入れた直後に Agentmux が TTY なしの別接続でコマンドを走らせても、sudo から見れば別の記録扱いになり再びパスワードを要求します。期限が切れたのではなく、参照している記録が別物です。
対処法
対処法:非対話の経路では sudo が入力を受け取れないため、Agentmux 経由でパスワードを渡すか、対話型の端末で一度だけ自分でコマンドを実行します。まずは Agentmux の案内を確認してください。自動インストールが失敗した際、sudo パスワードの入力欄や passwordless sudo の提案が表示されることがあり、そこに入力して再試行するのが一番手軽です。
その入力欄が使えない場合は、自分でマシンへ SSH ログインして通常の対話セッションを開き、sudo apt install -y tmux などのコマンドを手動で実行してパスワードを入力します。
手動で導入すれば、次の非対話実行時にはすでにインストール済みとなり、そもそも sudo を呼ぶ必要がなくなります(TTY の認証記録自体は別のまま引き継がれません)。
特定のコマンドだけを非対話経路からパスワードなしで長期間実行させたい場合は、sudo visudo でそのコマンドだけに絞った NOPASSWD ルールを追加できます。
youraccount ALL=(ALL) NOPASSWD: /usr/bin/apt
ただしこの設定には見た目以上のリスクがあります。apt のようなパッケージマネージャーに NOPASSWD を許すのは、実質的にパスワードなしの root 権限を与えるのとほぼ同じです。任意のパッケージをインストールでき、APT::Update::Pre-Invoke などのフックを通じて root 権限で任意のコマンドを実行できるためです。
そのコストを理解した上で意図的に受け入れる場合のみ設定してください。そうでなければ、一度だけ手動でインストールする方が安全です。また、マシン全体の sudo パスワード要求を外す NOPASSWD: ALL のような無制限の許可は決して設定しないでください。