T3 Code 远程访问完全指南T3 Connect、局域网直连、Tailscale HTTPS 与 SSH 托管【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本篇指南系统讲解 T3 Code 的远程访问能力如何让手机、浏览器或另一台桌面设备连接到运行在其它机器上的 T3 Code 环境覆盖 T3 Connect 云连接、局域网/私有网络直连配对、Tailscale HTTPS 发布、桌面托管 SSH、访问撤销管理与常见故障排查。读完你可以在命令行宿主机上熟练使用npx t3 connect、npx t3 serve、npx t3 pair等命令并在桌面应用中完成连接与负载均衡配置。远程访问的基本前提T3 Code 的远程访问遵循一个朴素的模型被连接的宿主机必须保持运行并且在你的工作期间保持可达。所有远程方案云中继、局域网直连、Tailscale、SSH最终都是把运行在宿主机上的 T3 Code 服务器暴露给其它设备因此宿主机本身的存活与网络可达性是第一条铁律。在动手之前先明确两种互补的技术路线T3 Connect通过云端中继relay打通网络无需配置路由器端口转发适合设备不在同一网络、NAT 之后或没有公网 IP 的场景直接配对LAN / 私有网络 / Tailscale设备能够直接访问宿主机的网络地址时用配对链接建立连接无需经过云端。T3 Connect无需端口转发的云连接桌面宿主机上的开启方式在桌面应用中打开Settings → Connections登录 T3 Connect 账户并为目标环境启用T3 Connect即可。启用后该环境会对同一账户下的其它设备可见其它设备登录同一账户后即可选择并连接该环境。命令行宿主机的开启方式命令行宿主机运行npx t3latest connect按照提示完成登录。需要特别注意两点设置流程会询问是否安装后台服务background service——后台服务说明 会在 Linux/macOS 上把 T3 Code 作为用户级服务运行这样你不需要一直开着终端。如果拒绝安装后台服务就必须手动用npx t3 serve启动服务器仅保存登录状态并不会让机器变得可达。connect完成的是授权 记录连接意图两件事真正的环境链接environment link与托管隧道要等服务器启动后才会建立。从源码实现看t3 connect是connect.ts中connectCommand定义的命令树apps/server/src/cli/connect.ts它携带--headless标志并派生出login、link、publish、status、unlink、logout六个子命令子命令作用t3 connect login仅授权 CLI不启用远程访问t3 connect link授权环境并在下次启动时建立 T3 Connect 链接--publish-only时只发布 Agent 活动、不创建托管隧道t3 connect publish开关向移动端发布 Agent 活动推送通知与 Live Activities可用--disable关闭t3 connect status展示已保存的授权、链接与 relay 客户端状态t3 connect unlink关闭 T3 Connect 但保留登录授权t3 connect logout关闭 T3 Connect 并清除本地登录授权其中link命令在建立链接前会检查 relay 客户端managed relay client未安装时提示下载安装connect.ts 中的acquireRelayClientForLink链接建立完成后源码会提示你启动服务器Start the server withnpx t3 serveto make this machine reachable——这与文档中仅登录不足以让机器可达的告诫完全一致。SSH 会话中的无浏览器授权在 SSH 会话中执行connect时本地没有浏览器可用于回环 OAuth 回调因此 CLI 会打印一个浏览器链接并等待你输入浏览器中返回的授权码out-of-band 授权。CLI 通过检测SSH_CONNECTION/SSH_TTY环境变量自动识别 SSH 会话connect.ts 的headlessSessionConfig所以无需转发 OAuth 回调端口。交互式客户端与无头 CLI 使用的是同一个 Clerk 应用但不同的凭证CLI 是使用 PKCE 的公共 OAuth 客户端不保存客户端密钥而中继同时接受 session-template JWT 与 CLI OAuth 令牌架构说明。凭证续期与连接稳定性T3 Connect 会在必要时自动续期访问凭证且不会断开一个健康的连接。Pull Request diff 与 Provider 设置远程机器上的凭证在旧凭证过期后依然可用一次失败的续期只影响发起该次请求的操作不会中断一个本可继续的会话。架构上T3 Connect 的中继扮演可信中介角色客户端与应用环境之间通过一次性 bootstrap 凭证交换环境会话令牌中继永远不会拿到该会话令牌仅持有 bootstrap 凭证也无法在没有客户端私钥的情况下兑换docs/internals/t3-connect.md。局域网 / 私有网络直连配对当其它设备能够直接访问宿主机的网络地址如同一 Wi-Fi、公司内网或 Tailscale tailnet时使用直接配对。桌面宿主机打开Settings → Connections启用Network access然后创建一条使用其它设备可达地址的配对链接。注意更改网络访问设置会重启桌面应用你可以在同一位置关闭它。命令行宿主机用宿主机的 LAN 或 tailnet 地址替换private-ipnpx t3 serve --host private-ip如果服务器已经在运行无需重启即可生成新的链接npx t3 pairt3 pair会把配对令牌以QR 码 URL的形式打印到终端并附上过期时间默认 5 分钟可用--ttl调整例如--ttl 1h。手机扫描 QR 码或在接收端应用的Add environment中粘贴配对 URL 即可完成配对。连接设置在 Web 与桌面端位于Settings → Connections移动端位于Settings → Environments。需要留意的边界回环地址陷阱诸如127.0.0.1这样的回环地址只能到达打开链接的那台设备本身无法用于跨设备配对一次一码配对会授权该设备后续连接。每台新设备应使用一条新的一次性链接之后重连不需要原始令牌链接的可见性在 Settings 中创建的链接只能由创建它的客户端复制且其 Connections 页面需保持打开。离开或刷新该页面后需要重新创建一条链接再分享其它配对选项npx t3 pair --help可查看全部选项。从源码看t3 pair通过读取正在运行的服务器持久化的server-runtime.json状态来发现配对目标在 git worktree 内运行时优先配对 dev 服务器并通过 PID 存活检查与/.well-known/t3/environment描述符探测防止把令牌铸入已死服务器的数据库apps/server/src/cli/pair.ts。--ttl与--label在服务器的连接列表中显示的标签都在这里定义。跨机器新建线程的负载均衡Auto balance自动负载均衡默认关闭。在 Web 与桌面端进入Settings → Connections → Load balancing启用后系统会自动为跨多个已连接环境分组的项目中的新线程选择机器。当两台或更多机器开启后该区块才会出现。每台机器的档位从Normal开始可调整为档位含义Normal默认参与自动选择Prefer在 CPU 与内存可用时优先选择该机器Less often降低该机器的被选中份额Manual only从自动选择中排除这些都是偏好而非固定的流量百分比且各客户端的偏好设置是独立保存的。合成器composer在为草稿选择环境时会检查候选机器并保持该选择稳定再次选择Auto balance会按当前资源重新评估选择某一具体机器则覆盖自动选择选择分支或 worktree 也会把草稿固定在那台机器上。已有线程留在其最初启动的机器上。当资源检查不可用或所有候选机器都已满载时需要手动选择一台机器继续。移动端始终保留手动环境选择。Tailscale HTTPS 发布将两台设备加入同一个 tailnetTailscale 网络然后在桌面应用中启用Settings → Connections → Tailscale HTTPS在同一位置关闭即可移除该路由。命令行方式启动一个带 Tailscale HTTPS 的服务器npx t3 serve --tailscale-serve对已在运行的服务器npx t3 pair --tailscale此时配对链接使用类似https://machine.tailnet.ts.net/的地址。pair --tailscale创建的映射在重启后依然保留。如需移除其默认端口443映射tailscale serve --https443 off若 443 端口已被占用用--tailscale-serve-port指定其它端口。从源码看Tailscale 集成封装在 packages/tailscale/src/tailscale.tsreadTailscaleStatus调用tailscale status --json解析 MagicDNS 名称buildTailscaleHttpsBaseUrl据此构造https://machine.tailnet.ts.net/地址ensureTailscaleServe执行tailscale serve --bg --httpsport http://127.0.0.1:localPortdisableTailscaleServe对应tailscale serve --httpsport off默认服务端口常量DEFAULT_TAILSCALE_SERVE_PORT 443。实现还把所有 stderr 分类为no-existing-handler、not-logged-in、permission-denied等安全标签避免把tskey-…认证密钥写进日志。配对时pair.ts会先探测目标 HTTPS 端点只有不可达或已映射到本环境时才允许重新配置映射避免静默覆盖其它服务或其它 T3 Code 实例的 Tailscale Serve 映射首次访问时 Tailscale 需要几秒钟签发 HTTPS 证书探测会重试最多 5 次每次间隔 1 秒。Hosted Web 应用app.t3.codes与 HTTPSapp.t3.codes 需要HTTPS 端点。它直接连接你的服务器一条 hosted 配对链接既不能把不可达的后端变可达也不能把 HTTP 转成 HTTPS。对于纯 HTTP 的 LAN 端点在能打开它的浏览器中直接使用直连配对 URL或从桌面应用配对移动端不带 scheme 输入的 IP 地址默认走HTTP所以当你的服务器使用 HTTPS 时务必在地址中包含https://。桌面托管 SSH把远端机器变成工作环境在桌面应用中打开Settings → Connections → Add environment选择SSH输入主机名或 SSH 别名例如userexample.com。T3 Code 会在该远端启动或复用 T3 Code 服务器为你建立端口转发让项目、Provider 凭证与 Agent 工作都留在远端机器上。远端主机的前置要求远端主机需要兼容的 Node.js 安装 与 Provider 配置。如果启动时找不到 Node 或报告版本不兼容通过非交互式 SSH 会话检查ssh userexample.com sh -lc command -v node node --version若输出与你平时终端里的版本不一致为版本管理器配置非交互式 shell 的默认版本即可。例如 nvm 用户设置一个兼容的默认版本nvm alias default 24更新与连接管理应用更新后若 SSH 重连失败重试启动一次移除连接会停止 T3 Code 启动的服务器原本已在运行的服务器不受影响会被保留Antigravity 的 Google 回调在远端主机上的处理参见 远端设备登录说明。管理与撤销访问在宿主机上Settings → Connections允许授权管理员创建配对链接并撤销客户端会话撤销一条未使用的链接阻止新的配对撤销某台设备的会话移除其现有访问。命令行管理通过npx t3 auth --help查看。此外一个保持连接打开的会话在访问凭证过期后仍会继续显示在列表中。从 T3 Connect 中移除一个环境打开账户菜单的T3 Connect页面移动端为Settings → T3 Connect并选择Deregister。这会撤销其云访问并释放其宿主空间即使该环境离线或已被抹除也能生效。命令行宿主机的两条退出路径需要区分connect.ts 的disconnectCloud实现命令行为t3 connect unlink关闭 T3 Connect 暴露保留登录授权t3 connect logout关闭 T3 Connect 并清除登录授权无论哪条后台服务都独立管理t3 service系列命令不会被注销操作自动停止或卸载后台服务管理 单独说明。安全红线配对 URL 与授权码应视同密码处理不要把它们放进截图、日志或 bug 报告中。T3 Connect 故障排查在宿主机上运行t3 connect status该命令检查已保存的授权与链接配置--json可输出机器可读结果它不是一次实时的可达性检查——源码输出的文案也明确写着 This is saved setup, not a live connection check。如果环境显示离线t3 service status并阅读其打印的日志。如果环境在 SSH 关闭时消失参见 后台服务故障排查通常是 Linux 上缺少 lingering。常见错误与恢复方法错误恢复方法environment_link_limit_exceeded或托管隧道上限注销deregister一个未使用的环境然后重启宿主机上的 T3 Codeauth_invalid或invalid_bearer运行t3 connect login若凭证已被撤销运行t3 connect logout后再次t3 connect登录后重启服务器过期或无效的链接证明link proof检查宿主机的日期与时间更新 T3 Code 后重启HTTP 403 且无已知错误检查 relay 访问、代理与防火墙规则保留 Cloudflare Ray ID 用于 bug 报告HTTP 408、429 或 5xx检查网络与 relay 可用性启动过程中的临时失败会自动重试最长十分钟修复一次永久性拒绝后重启宿主机的服务器Linux 后台服务用systemctl --user restart t3code.service前台服务器则停掉后用常用参数重新运行t3 serve。持续失败时报告诊断信息与 trace ID。链接成功但连接仍失败的场景先核对两台设备的日期与时间出现服务器版本警告时按 更新 T3 Code 操作。让远端访问更可靠后台服务与版本一致远程访问的稳定性高度依赖宿主机服务器的持续运行。文档 运行 T3 Code 后台服务 说明了完整的管理命令npx t3latest service install安装并启动、service status查看状态与日志路径、service update更新或修复、service uninstall停止并移除开机启动。Linux 需要 systemd 用户服务并开启 lingering 才能在登出后继续运行macOS 在登录时启动、登出时停止Windows 不支持后台服务。T3 Connect 的设置流程可以顺带提供服务安装但两者是独立管理的。当桌面客户端与远端服务器版本不一致时更新指南 用于对齐版本后台服务更新会重启服务器进行中的 Agent 轮次、终端与远程客户端会被中断请先完成手头工作。附T3 Connect 的部署与身份体系进阶对于自建部署或审计信任边界仓库提供两篇配套文档T3 Connect 架构说明解释中继作为可信中介的信任边界、DPoP 绑定的一次性 bootstrap 凭证交换、链接生命周期链接比连接器进程更长寿、托管隧道仅暴露经校验的回环 HTTP 源等设计约束T3 Connect 部署配置给出.env中T3CODE_CLERK_PUBLISHABLE_KEY、T3CODE_CLERK_JWT_TEMPLATE、T3CODE_CLERK_CLI_OAUTH_CLIENT_ID、T3CODE_RELAY_URL等公共标识的配置方式、Clerk JWT 模板aud: t3-code-relay、桌面与 Android 原生 OAuth 回调 allowlist 等部署细节。这两篇文档能帮助你在排障时理解auth_invalid、链接证明等错误背后的机制——例如中继持有的签名权、环境链接记录与托管分配的生命周期这些都会影响注销环境重启服务器等恢复动作为何有效。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考