卡住了怎么办
本页目录
通过 SSH、tmux、Tailscale 做远程开发,最常卡住的就是下面这八种:Operation timed out、Permission denied (publickey)、密码正确却被拒绝、找不到 tmux、claude: command not found、Tailscale 显示已连接却连不到、远程登录开着但 Mac 不接、sudo: a terminal is required。每一种都分成症状、原因,和你可以照着做的解法。
照着前面几篇配置,十次有八九次一次就通。剩下那一两次卡住的地方,通常就是这八种。找到你看到的错误信息跳过去看,不用整篇从头读。
连接超时(Operation timed out)
症状
敲了 ssh 用户@主机 之后画面卡住不动,等了半天,才跳出 Operation timed out 或 Connection timed out。SSH 从头到尾没有问过你密码。
原因
- host 名称打错字,例如打成
my-serverr。这种情况 SSH 会立刻报错Could not resolve hostname,不会卡到超时,看到它就先去检查拼写。会卡到超时的通常是 IP 打错:少写一段、错一个数字,或是连到一个根本没人响应的地址。 - 对方的 SSH 不是开在标准的 22 端口,你少打了
-p。 - 目标机器正在睡眠,或干脆是关机的。
- 中间有防火墙拦掉连接,例如家用路由器、公司网络、酒店的 Wi-Fi。机器根本没收到你的请求。
解法
超时代表你的请求没有抵达对方,所以要一段一段确认,不要一直猜。先看机器本身有没有响应:
ping 主机地址
ping 完全没响应?先检查 IP 有没有打错,再确认对方机器是不是在睡眠或关机。有些机器会刻意拦截 ping,所以这里不通不代表机器真的连不到,直接跳下一步。
接着确认对方那个 SSH 端口真的有服务在监听:
nc -vzw 5 主机地址 22
把 22 换成对方实际使用的端口。-w 5 让命令最多等 5 秒,碰到被拦掉的端口也会在 5 秒后给你结果,不会卡着不动。
结果只有三种。succeeded 或 open:端口是通的,问题在别的地方。Connection refused:机器收得到你的连接,但那个端口上没有服务在听。又超时:中间有东西把数据包拦掉,通常是防火墙,要检查的是路由器设置或所在网络的限制,不是这台服务器。
Permission denied (publickey)
症状
连接一发出去马上被拒绝,画面直接打印出 Permission denied (publickey).,SSH 连密码都没问。
原因
服务器不接受你这把密钥。最常见的原因是公钥根本没放到服务器上。
另一个容易被忽略的原因,是 ~/.ssh 这个文件夹或 authorized_keys 的权限太宽。SSH 对这件事非常严格:权限不对,它就直接忽略整个文件,不管里面的密钥是不是正确。
解法
多数情况下是公钥还没放上服务器,最快的做法是用 ssh-copy-id 放上去:它会先用密码登录一次,自动把你本地的公钥加进服务器的 authorized_keys。
ssh-copy-id 用户@主机
这个做法的前提是服务器的密码登录还开着;如果密码登录已经被关掉(见下面 密码正确却被拒绝 那节),就需要请能访问这台机器控制台的人,直接把公钥内容粘贴进 ~/.ssh/authorized_keys。
如果公钥确实在里面(一行一把、内容完整没被截断),却还是被拒绝,问题多半出在权限。对照下表检查。最容易漏掉的是最后一行:~/.ssh 和 authorized_keys 都设对了,但主目录本身「组」或「其他人」可写,StrictModes 一样拒绝:
| 路径 | 需要的权限 | 命令 |
|---|---|---|
~/.ssh | 700 | chmod 700 ~/.ssh |
~/.ssh/authorized_keys | 600 | chmod 600 ~/.ssh/authorized_keys |
~(主目录本身) | 组、其他人不可写 | chmod go-w ~ |
改完权限后再试一次连接。如果还是不行,可以在本地加上 -v 看详细过程,确认 SSH 真的有把你预期的那把密钥发出去:
ssh -v 用户@主机
输出会有五、六十行,你只需要其中两行。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,它就比你刚在主文件改的那一行先生效。你保存、重启服务,然后一样被拒绝。
解法
优先做法:改用密钥登录(做法见上面 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。
先不要关掉你现在这个连接窗口。改坏 sshd 配置可能让你之后完全连不进这台机器。确认新配置没问题之前,留着这个窗口当退路。保存后先验证语法:
sudo sshd -t
没有打印出任何错误,才重新启动服务让配置生效:
sudo systemctl restart ssh
部分发行版的服务名称是 sshd 而不是 ssh。上面那行找不到服务的话,改试 sudo systemctl restart sshd。接着开一个全新的连接窗口(不要用你留着当退路的那一个),确认真的能用密码登录,然后才关掉旧窗口。
整套环境都建立在 Tailscale 上,所以有个比「把密码登录对整个互联网开放」更安全的做法:只允许 Tailscale 网段的连接用密码,其余来源仍然只能用密钥。在 sshd_config 尾端加一段:
Match Address 100.64.0.0/10
PasswordAuthentication yes
Match All
PasswordAuthentication no
找不到 tmux
症状
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)。其次是在 Mac 上用 Homebrew 安装、但连接身份是 root,因为 Homebrew 设计上拒绝以 root 运行。
Windows 主机是同一个道理,只是程序换了:Agentmux 在那里装的是 psmux,先试 winget、再试 Scoop、最后试 cargo。如果这三个都没有,你会收到一条很直白的提示:这台 Windows 服务器上找不到 winget、scoop 或 cargo。请手动安装 psmux,然后重新连接。 这不是安装坏掉,只是那台电脑没有包管理工具,手动安装的命令在下面。
还有一种少见但容易误判的情况:tmux 已经装了,只是装在 Agentmux 探测 PATH 时没看到的地方,例如 Linuxbrew 装在 ~/.linuxbrew,MacPorts 装在 /opt/local/bin。信息一样是「找不到 tmux」,问题却出在 PATH,不是没装。照下面 claude: command not found,但桌面终端明明可以跑 那节处理。
解法
先看 Agentmux 弹出的错误信息。如果它要你输入 sudo 密码、或提到启用免密码 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,不是 tmux:
# Windows(PowerShell)
winget install -e --id marlocarlo.psmux --accept-package-agreements --accept-source-agreements
psmux 已经装过的话,winget 不会再装一次,它会返回没有较新的版本;用 SSH 连进去时它也不会停下来问你什么。那样的输出就代表东西已经在了。
那台机器没有 winget 的话,你有在用 Scoop 或 cargo 就用它们,不然就下载一个 binary 放进已经在 PATH 里的文件夹。两种做法之后都要重连一次,因为应用是开 session 的时候才去探那个程序。
claude: command not found,但桌面终端明明可以跑
症状
你在 Mac 自己开的 Terminal 里敲 claude,命令正常运行。通过 Agentmux 连进去、或直接 ssh 主机 claude,却看到 claude: command not found(或 bash: claude: command not found)。同一台机器、同一个账号,两边结果却不一样,看起来就像 Agentmux 坏了。
原因
问题出在 shell 的行为,不是 Agentmux。这是整页最难自己想通的卡点,所以原理值得多写几行。把它读懂之后,再遇到类似的情况,你自己就能判断。
你平常在 Mac 上开的 Terminal 是一个「交互式登录 shell」。claude 找得到,通常是因为 nvm、npm 或安装工具在某个配置文件里加了一行,把它所在的目录放进 PATH。哪一个配置文件,zsh 和 bash 不一样,混着讲会误导,所以分开说:
zsh(Mac 的默认 shell):交互式登录 shell 依次读 .zshenv → .zprofile → .zshrc → .zlogin。而 ssh 主机 claude 这种执行单条命令的连接,开的是非交互、非登录的 zsh,只会读 .zshenv,其余全部跳过,其中就包含大多数人放 PATH 设置的 .zshrc。
bash:这部分的行为因发行版而异,没有统一的规则。交互式登录 shell 读的是 .bash_profile(或 .profile),不是 .bashrc。你会以为 bash 也会读 .bashrc,是因为多数发行版默认的 .bash_profile 里都加了一段「如果 .bashrc 存在就 source 它」。
ssh 主机 claude 这种用法,是 sshd 叫 bash 执行单条命令。这种情况下 bash 会不会读 ~/.bashrc,要看发行版在编译时有没有加上 SSH_SOURCE_BASHRC 这个特例。Debian、Ubuntu 和它们的衍生版加了这个 patch,所以非交互的单条命令 shell 也会读 ~/.bashrc;RHEL、Fedora、Arch 用的是官方原版 bash,没有这个特例,同样场景下 ~/.bashrc 根本不会被读到。
就算在会读的发行版上,几乎每个默认的 .bashrc 开头也放了这样一段判断:
case $- in
*i*) ;;
*) return;;
esac
意思是「如果现在不是交互模式,就直接结束,不要往下读」。这段判断通常写在文件最前面,所以 bash 即使真的把 .bashrc 打开了,也会在读到你加的 PATH 那行之前就跳出去,结果跟没读到一样。
不管 zsh 还是 bash,结果都一样。设置 PATH 的那一行,只在你自己开 Terminal 的时候执行过。SSH 执行单条命令时没读到它,PATH 里就没有 claude 的位置,shell 说找不到是正确的反应。这跟 claude 有没有装好无关:它一直都在,只是没人告诉这个 shell 要去哪里找。
非交互执行时跳过这些配置文件是刻意的设计。不然每跑一段远程命令,都要先加载一堆给人交互用的别名和提示符配置,出错的机会跟着变多。
还有一点。Agentmux 在 Mac 上探测 PATH 用的是 zsh -lc,也就是登录但非交互,一样跳过 .zshrc,只读 .zshenv 和 .zprofile。所以对 Mac 上的 zsh 用户来说,把 PATH 设置搬到这两个文件,影响的不只是你手动 SSH 找不找得到命令,还包括 Agentmux 自己能不能找到 agent 命令。
解法
最快的做法:找出 claude 的绝对路径,直接用它调用,不要依赖 PATH。在平常跑得动 claude 的那个 Terminal 窗口运行:
which claude
会打印出类似 /Users/你的名字/.nvm/versions/node/v20.11.0/bin/claude 的一整串路径。把它填到 Agentmux 要求输入 agent 命令的输入框,取代原本的 claude。
如果你是用 nvm 装 node,这条路径里带着版本号,升级一次就失效,得再跑一次 which claude 重新抓路径。不想每次升级都改,就用下面比较长久的做法。
比较长久的做法,依你的 shell 分开处理,不要混用:
如果是 zsh(Mac 默认):把设置 PATH 的那几行从 .zshrc 搬到 ~/.zshenv。那几行通常来自 nvm、pyenv,或你自己加的 export PATH=...。搬到 ~/.zprofile 也可以,两个文件在 SSH 非交互执行和 Agentmux 探测 PATH 时都读得到。
如果是 bash:搬到 ~/.profile 或 ~/.bash_profile 不会生效。ssh 主机 claude 开的是非登录 shell,这两个文件都不会被读到。
机器是 Debian、Ubuntu 或它们的衍生版的话,把 PATH 那几行搬进 ~/.bashrc,放在文件最前面那段 case $- in ... esac 判断式「之前」,它就会在交互判断拦下之前先生效。RHEL、Fedora、Arch 这类发行版则不同,~/.bashrc 在这个场景下本来就不会被读到,改它没有任何效果。
不知道自己属于哪一种的话,就用上面的绝对路径。那个做法每个发行版都有效,也是唯一保证跨发行版都能用的解法。
搬完之后,开一个新的 SSH 连接测试,确认真的生效了:
ssh 主机 'claude --version'
能打印出版本号,就代表 PATH 这次真的在非交互 shell 里也读到了。
Tailscale 显示已连接,SSH 仍连不到
症状
手机上的 Tailscale App 显示两台设备都是绿灯、在线,但用 Agentmux 或直接 ssh 连过去,还是失败或整个超时。
原因
- 连接用的是局域网 IP(像
192.168.x.x),不是 Tailscale 给的 MagicDNS 名称或100.x开头的 Tailscale IP。局域网 IP 只有在同一个 Wi-Fi 底下连得到。手机一切到移动网络,这组 IP 就完全无效。 - 对方设备的状态其实刚掉线或正在睡眠,Tailscale App 上显示的「在线」还没更新。
- Tailscale 本身正常,但目标机器上的 SSH 服务根本没开或没启动。Tailscale 只负责把两台机器的网络打通,不会帮你把 SSH 服务打开。
- 最常见的原因是 node key 过期。目标机器需要重新验证,App 里看起来还是绿灯「已连接」,实际上这台机器已经不在网络里。到 Tailscale 的管理后台查那台机器有没有被标成需要重新登录,重新验证一次通常就解决了。
解法
先从目标机器查起,因为 App 上的绿灯可能是旧的状态。手机上的 Tailscale 没有命令行,tailscale status 只能在目标机器(要被连接的那台 Mac 或 Linux 机器)上运行:
tailscale status
在目标机器上确认列表里手机那个节点显示在线。手机这边打开 Tailscale App,确认目标机器的状态同样正常:没有变灰,也没有需要重新登录之类的警示。
两边都正常的话,连接时一律用 MagicDNS 名称(例如 mac-mini.tail1234.ts.net)或 tailscale status 列出的 100.x IP,不要用局域网 IP。这样不管你在家里的 Wi-Fi 还是外面用移动网络,地址都有效。
以上都没问题,再到目标机器检查 SSH 服务本身有没有启动。Linux 用 sudo systemctl status ssh;Mac 请见下面 Mac 开了远程登录却连不上 那节。
Mac 开了远程登录却连不上
症状
已经在系统设置里打开「远程登录」,Mac 也确定连着网络,但 SSH 还是连不上;或者连得上却被拒绝,而你很确定密码或密钥都是对的。
原因
- 「远程登录」默认只允许「特定用户」列表里的账号登录。你用来连接的那个账号可能根本不在列表上。
- Mac 进入睡眠之后网络接口跟着休眠,SSH 自然连不到。这跟远程登录有没有打开无关,是机器当下对网络请求完全没响应。
解法
打开「系统设置 → 通用 → 共享」。那是 macOS Ventura 之后的路径,Ventura 之前是「系统偏好设置 → 共享」,没有「通用」这一层。找到「远程登录」,确认开关打开,再点进去看「允许访问」的用户列表里有没有你要连接的那个账号,或直接选「所有用户」。
接着打开「系统设置 → 电池」(笔记本电脑)或「系统设置 → 节能」(Mac mini、Mac Studio、iMac 这类长期开机当服务器用的台式机,上面示例里的 mac-mini.tail1234.ts.net 就是这种)。把「电脑闲置时进入睡眠」的时间调长或关掉。如果面板上有「唤醒以供网络访问」这个选项,一并打开,Mac 就算睡着,收到连接请求时也能醒过来响应 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 在背后帮你跑的安装流程,那里没有一个真正的终端可以显示提示,也没有地方让你打字。sudo 发现没有 TTY 可用就直接拒绝,不会傻等一个永远不会来的输入。
这里有个常见的误会:以为刚打过一次 sudo 密码,接下来一段时间就不用再打。现代的 sudo 确实会记录「已经验证过」,但那条记录绑定的是当下那个 TTY(tty_tickets),跟你的账号、跟这台机器都没有关系。
你在交互式 SSH 窗口里打过密码,Agentmux 之后自动跑命令时,开的是另一条没有 TTY 的全新连接。对 sudo 来说那是另一条记录,所以它会再问一次。这里没有缓存过期的问题:两边查的从来就不是同一条记录。
解法
非交互的渠道没有地方让 sudo 问密码,所以解法有两条:让 Agentmux 帮你填密码,或自己在真正的终端里跑一次。先看 Agentmux 弹出的提示:自动安装失败时,它通常会直接请你输入 sudo 密码、或改成启用免密码 sudo,再重试一次。看到那个输入框就把密码填进去,往往比自己另外处理快。
这个渠道不可用的话,就自己手动 SSH 登录那台机器,开一个正常的交互式 session,在里面执行一次同样的命令(例如 sudo apt install -y tmux)并输入密码,把事情做完。
它会成功,理由却跟多数人想的不一样。这没有帮 Agentmux 之后的自动流程解锁什么,两边查的 TTY 记录本来就不是同一条。真正的原因是该装的东西已经被你装好了:下一次非交互命令检查时发现东西已经在,不需要安装,卡点就消失了。
如果某个特定命令长期都要通过非交互渠道免密码执行,可以用 sudo visudo 帮它加一条 NOPASSWD 规则,只针对那一条命令放行:
你的账号 ALL=(ALL) NOPASSWD: /usr/bin/apt
这个取舍比看起来严重。把 NOPASSWD 开给 apt 这类包管理器,几乎等于交出完整的 root:你可以叫 apt 装任何包,而 APT::Update::Pre-Invoke 这类 hook 还能以 root 身份在安装过程中执行任何命令。实际上那就是免密码的 root,只是换一种写法。
清楚知道这个代价、也刻意接受,才这样设置。否则宁可回到上面「先手动装一次」的做法。也绝对不要直接放行 NOPASSWD: ALL,那等于整台机器的 sudo 都不再需要密码。