# 把终端装进口袋（五）：排错手记

- URL: https://wuming.si/blog/4082/
- Author: Wuming
- Published: 2026-10-23
- Language: zh-Hans
- Categories: Technology

> 上一篇：[谁能进来，由电脑说了算](https://wuming.si/blog/4081) ｜ English: [Troubleshooting Notes](https://wuming.si/blog/4087)

系列的最后一篇，记一下这几个月里反复遇到的问题，以及几次自己把自己坑了的经历。这类东西通常不会写进文档，但对下一个做类似系统的人可能最有用。

按症状分成四类：连不上、很慢、收不到、敲不进去。

## 连不上

**电脑显示离线。** 十有八九是电脑上的常驻进程没在跑。笔记本合盖睡眠、系统升级重启、用户注销，都会让它停下来。macOS 上用系统的服务管理把它注册成登录项，Linux 上注册成用户级的系统服务，大多数情况就解决了。有一个例外是通过 SSH 登录的 Linux 服务器：用户一退出，用户级服务默认跟着停。要让它留下来，得给这个用户打开「保留会话」的开关，这个在安装文档里写了一行，但几乎每个人都会漏掉。

**电脑在线，手机连不上。** 先看是不是新设备在等批准（上一篇讲的本机批准）。电脑上有一条命令能列出正在等的设备，批准一下就好。这是最常见的「明明在线却连不上」。

**公司网络里连不上。** 有些企业网络把 UDP 全封了，只放 TCP 的 80 和 443。系统的做法是多条路一起试：先 UDP 直连和打洞，不行走 TCP，再不行走 443 端口上的 WebSocket 到中继。这条退路几乎总能通，代价是慢一些。如果连 443 都被代理拦截并做了解密，那就只能请管理员放行域名了。

**某个地区连不上。** 不同地区到各个中继的可达性差别很大。电脑会在不止一个中继上订位置，手机按延迟挑最近的一个。曾经有一台中继的机房上游出了问题，所有订在它上面的电脑都「离线」了一整个下午，而电脑自己毫无感觉，因为它和中继之间的连接还活着，只是中继出不去。后来加了从外部探测每个中继的监控，并让电脑同时订两个中继，这类事就不再是单点了。

## 很慢

**打字有延迟。** 先看状态栏上是直连还是中继。走中继多半是因为打洞失败，这在对称 NAT（很多手机运营商的网络）下很常见，不是故障。切换到 Wi-Fi 往往就直连了。

**滚动很卡。** 终端的字节流原样送到手机，一个疯狂刷屏的程序（比如 `yes` 或者一个进度条每秒刷几百次）会把手机的渲染拖垮。电脑这一侧加了合并：短时间内的多次输出合成一帧再发。另外手机上的终端默认开了「适配手机尺寸」，让 tmux 把窗口缩到手机能显示的大小；关掉它就是电脑的原始尺寸，看得全但字很小。

**时钟不准导致一直重连。** 设备之间的请求带时间戳和签名，时钟差太多会被当成重放攻击拒绝。一台很久没开机的旧 Mac 时钟漂了十几分钟，表现就是「连上又断、断了又连」。对时之后立刻正常。

## 收不到

**智能体停了，手机没动静。** 按顺序查三件事：钩子装了没，装了之后智能体重启了没，手机的通知权限开了没。钩子是写进智能体的配置文件的，智能体只在启动时读一次，所以装完钩子之前就在跑的智能体不会通知。这一点被问过无数次，最后在安装钩子的命令输出里加了一句提醒。

**通知来了，但点开不是那个窗口。** 钩子事件里带着 pane 的编号，但 tmux 的 pane 编号在窗口被关掉重开之后会变。系统改成了同时记窗口名和 pane 编号，优先匹配编号，匹配不上再按名字找。

**同一个问题收到两条。** 智能体有时会连续触发两次钩子，或者一个事件通过两条路径到达。电脑这边按会话和内容做了去重，几分钟内重复的只送一次。

## 敲不进去

**点了「允许」，终端没反应。** 多半是那个问题已经过期了：智能体等不到回答，自己超时或者被电脑前的人回答了。按上一篇讲的一次性回答规则，迟到的回答会被拒绝，手机上应该显示「这个问题已经过了」。如果没显示，那是 App 的版本旧了。

**手机键盘打不出某些键。** 手机键盘没有 Esc、Tab、方向键、Ctrl。系统在键盘上方加了一排额外的键，Ctrl 做成了粘滞键，按一下再按字母。远程桌面那一边还有个坑：Mac 的屏幕共享服务要求大写字母和符号必须带着 Shift 按下，手机键盘直接发大写字母它不认。花了一个下午才发现这个。

**tmux 版本太老。** 系统依赖 tmux 3.0 以后的一些控制模式特性。一些长期支持版的 Linux 自带的 tmux 还是 2.x，表现是能列出会话但打不开窗口。安装时加了版本检查，提示用户升级。

## 把自己坑了的几次

**在 tmux 里面跑了 kill-server。** 一个端到端测试脚本会起一个独立的 tmux 服务做测试，结束时清理。清理命令本来指定了独立的 socket 目录，但如果脚本本身是在用户的 tmux 窗口里跑的，环境变量里的 `TMUX` 会覆盖那个目录，于是 `tmux kill-server` 杀掉的是用户自己的 tmux，连带着杀掉了当时在里面跑的所有东西，包括正在跑这个脚本的那个会话。教训：脚本里永远用 `-S` 显式指定 socket，或者先 `unset TMUX`。

**`pkill -f` 匹配到了自己。** 用 `pkill -f "某个名字"` 清理进程时，这条 pkill 命令自己的命令行里也包含那个名字。于是它先杀了自己。这个坑很老了，但每隔几年还是会再踩一次。

**测试写坏了用户的配置。** 测试在临时目录下起了一个常驻进程，而那个进程启动时会「顺手」刷新一下智能体的钩子配置，指向自己的路径。于是用户真正的钩子配置被改成了指向一个测试结束就被删掉的临时目录。修法是：只有默认安装位置的进程才碰用户的配置，临时目录下的一律不动。后来还加了一条检查，每次测试跑完确认用户的钩子还指向正确的地方。

**构建覆盖了仓库里的二进制。** 仓库里出于某些原因提交了一个二进制文件。在那个目录下 `go build` 一次，它就被本地构建覆盖了，而且 git 会老老实实地把它标成已修改。这种事发生过不止一次。

## 结尾

这个系列到这里就结束了。回头看，这组工具没有什么惊人的技术，它做的只是把几件各自成熟的东西（tmux、点对点网络、设备证书、智能体的钩子）按几条原则拼在一起，然后在无数个小细节上做对选择：回答要一次性，批准要本机，中继要只看到密文，密钥文件永远不传。

如果你也在被一个很勤快的智能体拴在工位上，希望这几篇能提供一点思路。

## 全系列

1. [为什么要在手机上接管电脑](https://wuming.si/blog/4078)
2. [三个部件的架构](https://wuming.si/blog/4079)
3. [让编程智能体学会敲门](https://wuming.si/blog/4080)
4. [谁能进来，由电脑说了算](https://wuming.si/blog/4081)
5. 排错手记（本篇）
