T3 Connect 故障排查
一次 T3 Connect 连接按这个顺序经过四个部分：
- 本设备经互联网连到 T3 Connect。
- T3 Connect 核验你的登录，以及主机的链接。
- 主机的隧道（主机上的 cloudflared）把请求送到主机。
- 主机上的 T3 Code 作出应答。
连接失败时，打开 设置 > 环境，找到对应的环境（environment），再选 详情。第一个被标成失败的部分就是原因。到下文找到它的那一节。
要看主机这一侧，在主机上运行 t3 connect status，或者在主机上打开 设置 > 共享与访问。两者都会从主机去检查主机的 T3 Connect 地址，并说明失败的原因。t3 connect 在设置完成时会做同样的检查。这项检查测不了另一台设备的网络。某台设备上的问题，就到那台设备上打开 详情。
主机的隧道离线
T3 Connect 联系不上主机的隧道。原因是下面之一：
- 主机在睡眠、已经关机，或者不在线。
- 主机上没有在运行 T3 Code。
- 主机的网络把隧道挡住了。参见 主机上的 7844 端口被挡住。
处理办法：
- 确认主机是醒着的，而且上面正在运行 T3 Code。
- 在主机上运行
t3 connect status。它会指出主机这一侧的问题。 - 如果主机离线了很久，T3 Connect 会把它的隧道拆掉。在主机上启动 T3 Code，并更新到最新版本。它会拿到一条新隧道。
主机上的 7844 端口被挡住
主机上的隧道向外连到 Cloudflare 的 7844 端口，TCP 和 UDP 都走这个端口。两种隧道协议（QUIC 和 HTTP/2）用的都是它。主机的网络一旦把它挡住，隧道就起不来，可是普通的网页访问仍然正常。主机看上去在线，所以这个问题很容易被漏掉。
常见原因：
- 主机上开了 Tailscale 出口节点。 主机的全部互联网流量都从出口节点出去，而那边的网络挡住了 7844 端口。在主机上用
tailscale set --exit-node=关掉出口节点，或者在出口节点所在的网络上放行出站的 7844 端口。 - 主机上开了 VPN。 工作用的 VPN 经常挡住不认识的端口。请对方放行 7844 端口，或者改走直连路由（见下文）。
- 防火墙，或者管得很严的网络。 放行出站的 TCP 和 UDP 7844 端口。
如果这个端口放行不了，可以不经过 T3 Connect 来连接。主机和本设备在同一个 Tailscale 网络上时，把主机的 Tailscale 地址加为直连路由。参见 用多种方式到达同一台机器。
隧道是通的，但 T3 Code 没有应答
主机的隧道已经起来了，可是到不了主机上的 T3 Code。常见原因：
- 主机上的 T3 Code 停了、崩溃了，或者还在启动。
- T3 Code 换了一个端口重新启动，比如刚更新完，隧道却还指着旧端口。
- 服务器用
T3CODE_HOST只绑定了一个网络地址。隧道把请求发到127.0.0.1，所以服务器也必须在那里监听。
处理办法：在主机上重启 T3 Code。如果跑的是后台服务，执行 t3 service restart。然后在主机上运行 t3 connect status。
T3 Connect 地址解析不了，或者没有应答
主机的 T3 Connect 地址没有解析出来、拒绝了连接、安全连接（TLS）失败，或者没有及时应答。
处理办法：
- 确认主机是醒着的，并且在线。
- 在主机上运行
t3 connect status。 - 如果只有在主机上检查才失败，就查主机的 DNS、VPN 或代理。
本设备到不了 T3 Connect
问题在本设备的网络上，不在主机上。本设备到不了 T3 Connect，或者到了 T3 Connect，却到不了主机的隧道地址。
处理办法：
- 检查本设备的互联网连接。碰到强制门户，或者 Wi-Fi 已经名存实亡时，设备可以看起来在线，其实哪里都到不了。
- 本设备上的 VPN、防火墙、广告拦截或 DNS 过滤，都可能挡住 T3 Connect。先关掉一会儿，用来确认。
- 在 iPhone 上，Wi-Fi 设置里的 Connectivity Assist 可能让 T3 Connect 无法工作。关掉它再试。
- 换一个网络，或者给主机加一条直连路由，比如它的 Tailscale 地址。参见 用多种方式到达同一台机器。
登录、账户或链接出了问题
本设备的 T3 Connect 登录还没准备好，或者 T3 Connect 里没有你的账户和这台主机之间的有效链接。
- 主机链接的是另一个账户。 在本设备和主机上登录同一个 T3 Connect 账户。在主机上先运行
t3 connect logout，再运行t3 connect。 - 主机上的 T3 Connect 是关着的，或者主机只在发布智能体活动。 在主机上打开 设置 > 共享与访问，把 T3 Connect 打开，或者运行
t3 connect。 - 主机已经链接过，但服务器还没有把这次链接应用上去。 在主机上重启服务器：退出再重新打开 T3 Code 桌面应用，运行
t3 service restart，或者先停掉t3 serve，再运行一次。 - 本设备的登录已经过期，或者主机不再接受这台设备。 退出 T3 Connect，再重新登录。
- 本设备还在加载自己的 T3 Connect 登录。 等一会儿；T3 Code 会自己重试。如果一直停在等待，就在本设备上重新加载或重启 T3 Code。
- 你的账户已经达到隧道数量上限。 到你的 T3 账户的 T3 Connect 页面，去掉一个你不用的环境，或者关联一个付费的 T3 Chat 账户，以换取更高的上限。然后在主机上重启 T3 Code。
时钟不准
T3 Connect 用短时有效的证明给请求签名。本设备或主机的时钟只要偏差了几分钟，T3 Connect 就会拒绝这些请求。在两台设备上都打开自动设置日期和时间，然后再试一次。
主机上跑的是较旧的 T3 Code
这个应用要求主机上的 T3 Code 再新一些。请在主机上更新 T3 Code。参见 更新 T3 Code。
T3 Connect 返回了错误
| 错误 | 处理办法 |
|---|---|
environment_link_limit_exceeded 或托管隧道上限 | 去掉一个不用的环境，或关联一个付费的 T3 Chat 账户，然后在主机上重启 T3 Code。 |
auth_invalid 或 invalid_bearer | 运行 t3 connect login。如果凭据已被撤销，先运行 t3 connect logout，再运行一次 t3 connect。登录之后重启服务器。 |
| 链接证明已过期或无效 | 检查主机的日期和时间，更新 T3 Code，然后重启。 |
| 没有识别出具体错误的 HTTP 403 | 检查中继（relay）的访问、代理和防火墙规则。把 Cloudflare Ray ID 留着，提交缺陷报告时用得上。 |
| HTTP 408、429 或 5xx | 等几分钟。暂时性的失败，T3 Code 会自己重试。 |
永久性的拒绝处理好之后，用 t3 service restart 重启主机上的服务器。如果是前台服务器，先停掉它，再重新运行 t3 serve。
如果 SSH 一断开，主机上的 T3 Code 就消失了，参见 后台服务故障排查。
报告问题
如果这些都没有用，请到 GitHub 提交一条 issue。请附上：
- 该环境的 详情 里，复制诊断信息 得到的文本。
- 在主机上运行
t3 connect status的输出。 - 跟踪 ID，如果界面上有显示。
- 如果隧道更早掉过线，附上主机的隧道日志，也就是日志文件夹里的
relay-client.ndjson（默认是~/.t3/userdata/logs）。它记下隧道何时连上、何时告警、何时退出、何时重启，隧道令牌已经去掉。