Claude Code 远程断线排查：六种断法的症状、判据和对应解法

远程跑 Claude Code，最难受的不是连不上，而是连上了又断，而且每次断的原因还不一样。

「断线」这个词其实盖住了六种完全不同的故障。它们的现象各有特征，修法也彼此无关——把切网导致的长连接失效当成机器睡眠去处理，关掉休眠也没用；把半死连接当成网络差去等，等到天亮它也不会自己好。

这篇文章按你实际看到的现象倒推原因：每种断法给出症状、怎么确认是它、以及对应解法。想直接动手的，跳到最后一节的排查清单。

这篇只讲断线排查。远程访问怎么搭见《Claude Code 远程访问：关掉本机也能随地操控会话》，手机端怎么用见《手机连 Claude Code：iOS 上随时查看会话与审批工具》。

先对症状：你看到的是哪一种

远程连接是两段：跑 Claude Code 的开发机 ←→ 你手上的查看设备。两段任何一段出问题都表现为「断了」，但现象有区别：

你看到的现象	大概率是	跳到
会话突然不动了，重连上去发现进度也停在那一刻	开发机睡眠 / 锁屏	§1
走进电梯、切 4G、换 WiFi 的那一刻断	长连接被掐	§2
本机终端一关、或本机一睡，远程立刻跟着断	投屏式方案的硬约束	§3
显示在线，但发消息石沉大海、没有任何报错	半死连接	§4
能重连，但连回去是个空会话 / 断线期间的消息没了	重连没接回原会话	§5
隔了几小时再连，会话不见了	进程被回收，且没有冷恢复	§6

最容易误判的是第四种：它不报错。连接状态是绿的，消息发得出去，只是永远没有回应——比直接断开更难查，因为所有指示灯都告诉你「一切正常」。

1. 开发机睡眠 / 锁屏 / 合盖

症状：会话在某个时刻整个停住。重连上去，进度还停在断的那一刻，一步没往前走。

为什么：很多人以为「我开发机一直开着」，但系统休眠、合盖睡眠、定时锁屏都会把 Claude Code 进程挂起或直接杀掉。查看端这边看到的就是「突然不动了」。

怎么确认：回到开发机上看那个进程还在不在、系统日志里有没有休眠记录。如果进程还在但时间戳停在断线时刻，基本就是它。

解法：把开发机的电源计划设成「不睡眠 / 合盖不休眠」。这是唯一能根治的做法——任何远程方案都救不了一台已经睡过去的机器。

2. 切网导致长连接被掐

症状：断在一个很明确的瞬间——走进电梯、WiFi 切 4G、家里宽带半夜重拨。

为什么：远程实时同步靠一条长连接（WebSocket / SSH）。IP 一变，这条连接当场失效，没有任何商量余地。

怎么确认：断线时刻和你的网络切换时刻对得上，就是它。

解法：这一类没法避免，只能靠自动重连 + 退避兜住（1s→2s→5s…，避免一断就猛打）。裸 SSH 没有这个能力，断了就是断了，得手动敲。选方案时这是硬指标。

3. 投屏式方案：本机必须前台开着

症状：本机终端一关、或本机一睡，手机这头立刻跟着断。不是慢慢超时，是同步失效。

为什么：Anthropic 官方的 Remote Control 是把你本机正在跑的会话投射到手机/浏览器。它的前提是本机那个 Claude Code 一直前台开着、本机一直在线。本机一掉，远程这头没有独立的生命周期可依附。

怎么确认：关掉本机终端窗口，看远程是不是同一秒就断。是的话，你用的就是投屏式方案。

解法：换成开发机侧常驻守护服务的架构——跑会话的那一端做成开机自启的后台服务，独立于你的查看设备活着。查看端关了、换了、断了，它都照常在开发机上跑。这是「投屏」和「常驻服务」的本质区别，不是参数能调出来的。

4. 半死连接（half-open）：最难发现的一种

症状：显示在线，发消息没反应，也不报错。可能卡几分钟，也可能一直卡到你手动重连。

为什么：网络静默中断时（NAT 表项超时、中间设备丢状态、信号弱到只丢包不断链），TCP 两端可能都以为自己还连着，实际数据再也过不去。没有心跳的话，双方会一直保持这个幻觉。

怎么确认：连接状态显示正常，但发出去的消息既没有送达回执也没有报错；手动断开重连之后立刻恢复——那就是它。

解法：连接上要跑心跳（keepalive ping）：约定时间内收不到对端任何回应，就判定这是条半死连接，主动断开重连，而不是傻等。判据必须是「收不到回应」，不能是「没有报错」——半死连接从不报错。

5. 重连接不回原会话 / 丢消息

症状：断了能重连，但连回去要么是个空会话，要么断线期间对方发的消息全没了。

为什么：重连只是重新建了条连接，没有把这条连接订阅回原来的会话；断线期间的消息也没有为你缓存。

怎么确认：重连后会话 ID 变了，或者历史只从重连那一刻开始。

解法：选能重连后自动订阅回原会话，并回放断线期间历史的方案。只能重连、不能接回，等于白连。

6. 会话进程被回收，且没有冷恢复

症状：短时间断开重连都正常，但隔几个小时再回来，会话就不见了。

为什么：长时间空闲的会话进程可能被回收，守护进程本身也可能重启过（升级、崩溃拉起）。内存里的会话状态随之消失。

怎么确认：断得久才复现，短断不复现。

解法：需要冷恢复能力——会话状态落盘，进程没了也能从磁盘把上下文恢复回来。理想情况下你发一条消息它就自动恢复继续，对你是无感的。

排查清单（任何方案都能照着走）

按顺序过，每一步都能独立证伪：

跑会话那台机器睡眠 / 锁屏了吗？ → 关掉自动睡眠、合盖不休眠。（§1）
断线时刻和你切网的时刻重合吗？ → 需要带自动重连 + 退避的方案，别靠裸 SSH。（§2）
本机终端一关，远程是不是立刻就断？ → 投屏式方案的硬约束，得换常驻守护架构。（§3）
卡在「显示在线但发消息没反应」？ → 半死连接，只有心跳检测能自动救回来。（§4）
重连后会话空了 / 消息少了？ → 需要「接回原会话 + 历史回放」。（§5）
只有断很久才丢会话？ → 需要落盘 + 冷恢复。（§6）

落到具体方案上

上面六条里，只有第 1 条是你自己机器的设置问题，其余五条全是架构决定的——方案选型时就定死了，出问题之后调参数救不回来。

一个不断线的远程方案需要同时具备：开发机侧常驻守护进程（对应 §1 剩余风险和 §3）、自动重连 + 退避（§2）、心跳检测（§4）、重连接回原会话 + 历史回放（§5）、落盘冷恢复（§6）。

PandaNpc + pandapaw 这套是按这六条逐条对着做的：pandapaw 在开发机上注册成开机自启的常驻守护进程（不是你得手动开着的终端窗口，崩了会被自动拉起）；查看端断线自动重连并带退避；连接上跑心跳，收不到回应就判半死主动重连；重连后自动订阅回原会话并回放断线期间的历史；会话进程即使被回收，发一条消息就能从磁盘冷恢复继续。

具体怎么装、怎么连，见《Claude Code 远程访问》；手机端的会话查看与工具审批见《手机连 Claude Code》。

一个附带的坑：远程跑别踩计费

排查断线时容易顺手换成 claude -p（headless 模式）跑，但 2026 年 6 月 15 日起 Anthropic 调整了计费——headless 不再走订阅额度，而是吃一笔小额月度 SDK credit，用完按 API 计费，重度用很容易超支。交互模式（claude REPL）仍然走订阅额度。换方案排查断线的时候，注意别顺手把计费模式也换了。