远程访问

把手机、浏览器或另一台桌面应用连接到运行在另一台机器上的 T3 Code。你工作期间，那台机器必须保持运行，并且处于可访问状态。

T3 Connect

T3 Connect 让环境（environment）可供你的其他设备使用，而无需在路由器上设置转发。在主机上的桌面应用中，打开 设置 → 共享与访问，登录，并为该环境启用 T3 Connect。

对于命令行主机，运行：

t3 up

它会询问你的其他设备如何到达这台机器：T3 Connect、本地网络，或二者都要。选择 T3 Connect，并按照登录说明操作。在 Linux 和 macOS 上，它随后会以后台服务（background service）的方式运行 T3 Code。 t3 connect 与 t3 up --connect 相同。再次运行 t3 up 可以更改你的选择，运行 t3 status 可以查看当前选择。

后台服务在 Windows 上不可用，因此在 Windows 上，t3 up 会打印 t3 serve 命令（command），以便在终端里保持运行。你也可以让桌面应用保持运行，并启用它的本地环境。关闭桌面应用的最后一个窗口，会停掉它的本地服务器。只保存登录状态，既不会启动服务器，也不会让这台机器可被访问。

在另一台设备上，登录同一个 T3 Connect 账户，并选择该环境。在还没有添加计算机的 app.t3.codes 主页上，登录后会加入与你的账户关联的兼容计算机。通过 SSH 时，CLI 会打印一条浏览器链接和一个短代码。在任意设备上打开该链接，确认代码一致，然后批准。CLI 会自己继续运行，因此你不必转发 OAuth 回调端口。

T3 Connect 会在需要时续期访问凭据，而不会断开一条健康的连接。先前的凭据过期之后，拉取请求（pull request）差异和提供方（provider）设置仍然可用。续期失败只影响这一次请求；它不会断开原本健康的对话。

脚本与智能体

当你指定一个选择时，t3 up 不会再询问：--connect、--lan，或它们的 --no- 形式。你没有指定的选择会保留各自的设置，--yes 则采用默认值。没有终端时：

• T3 Connect 登录会打印一个 URL 和一个代码。在任意设备上批准它。
• 需要重启时会直接执行，不再询问，并停止正在运行的智能体回合（turn）。
• 如果尚未设置任何内容，也没有指定选择，t3 up 会停止并指出这些标志。

t3 status --json 会打印这些设置。t3 up --help 会列出每一个标志，并附上示例。

借助 T3 Chat 关联更多机器

每个 T3 Connect 账户最多可以关联 3 台机器。手机和浏览器不算在内。付费的 T3 Chat 方案会提高这一上限：Pro 为 10 台，Premier 为 100 台。

要关联 T3 Chat，请在 Web 端或桌面应用中打开账户菜单，进入 T3 Chat，然后选择 关联 T3 Chat。在打开的窗口中登录 T3 Chat 并批准。新的上限会在你下一次添加机器时生效。如果你取消或降级 T3 Chat，已经关联的机器仍保持关联，但在数量回到上限以内之前，不能再添加机器。

通过局域网或专用网络配对

当另一台设备能够访问主机的网络地址时，使用直接配对。

在桌面主机上，打开 设置 → 共享与访问，启用 网络访问，然后用另一台设备能够访问的地址创建配对链接。更改网络访问会重新启动桌面应用。你可以在同一位置把它关掉。

对于命令行主机，在 t3 up 中选择本地网络，或运行：

t3 up --lan

对于终端里的服务器，运行 t3 serve --lan。无论哪种方式，T3 Code 随后都会接受来自你的本地网络和 tailnet 的连接，因此能把这些网络上的其他设备挡在外面的，就只剩下配对代码。

如果服务器已经在运行，可以不重启它而生成一条新的链接：

t3 pair

用手机扫描二维码，或把配对 URL 粘贴到接收端应用的 添加环境 里。连接设置在 Web 和桌面上位于 设置 → 环境，在移动端也位于 设置 → 环境。像 127.0.0.1 这样的环回地址，只能到达打开该链接的那台设备。

在装有桌面应用的计算机上，你也可以改为打开打印出来的 t3code://pair 应用链接。桌面应用会请你确认服务器地址，然后把它添加进来。

如果你的 HTTPS 端点使用自己的证书颁发机构签发的证书，请在 Android 的安全设置中把该 CA 安装为 CA 证书；Android 应用随后就会信任它。

配对会授权该设备，供以后的连接使用。每台新设备都使用一条新的一次性链接；重新连接时不需要原来的令牌。在「设置」中创建的链接，只能从创建它的客户端（client）复制，而且该客户端的「共享与访问」页面必须保持打开。如果你离开或重新加载该页面，请另外创建一条链接再分享。

通过多种途径访问同一台机器

一台机器可以有不止一条路由：局域网、Tailscale、其他 VPN、公网 URL、SSH 或 T3 Connect。Tailscale 与 Cloudflare WARP 等其他 VPN 共用它的 100.64.0.0/10 地址范围，因此落在该范围内的地址会显示为 VPN，除非这台机器确认自己处于 Tailscale 上。要添加路由，请在该机器的路由列表中选择 添加路由，或在 T3 Connect 列表里该机器的旁边选择。针对已保存机器的配对链接，如果来自该机器尚不具备的地址，会被拒绝；请改用 添加路由 来添加该地址。通过这台机器已经具备的地址再次配对，仍然有效。新路由会按速度依次排入，你也可以随时重新调整路由顺序。

通过 T3 Connect 或某个已配对地址连接时，T3 Code 还会获知这台机器当前的局域网地址和 Tailscale 地址，并把它们添加为路由，因此通过 T3 Connect 配对一次，就足以在家使用局域网。当这台机器的局域网地址改变时，例如它加入了另一个 Wi-Fi 网络，已学习到的路由会跟着改变。这台机器必须允许网络访问，它的局域网地址才会被学习到：桌面应用中的 网络访问，或本地网络这一选项，它在 t3 up 中。你可以调整已学习路由的顺序，但不能移除它；它会随着学习它时所经由的那条路由一起消失，或在这台机器不再报告该地址时消失。

T3 Code 会走第一条有应答的路由。不在家时，没有应答的局域网地址会先经过短暂检查，然后被跳过。只有当其他路由都连不上时，才会在它们之后再次尝试该地址。当连接落在较后的路由上时，T3 Code 会在你的网络发生变化时、你回到应用时，以及每一分钟，检查更靠前的路由，并且一旦有一条可用就立刻切回去。

在 Web 和桌面上，于 设置 → 环境 中点选机器名称下方的路由数量，即可查看它的路由。拖动一条路由可以改变顺序，也可以移除它。在移动端，于 设置 → 环境 中打开该机器，并选择 编辑。退出 T3 Connect 只会移除那一条路由；如果你仍能通过其他方式访问某台机器，它会继续保存。

在 Web 或桌面上，打开 路由 旁边的 权限；在移动端的路由详情中，打开 你的权限，即可查看你当前的连接在该环境（environment）上能够做什么。对于远程环境，这项内容在它的路由详情里。那里显示的权限只适用于标记为 使用中 的路由；其他路由不会被检查。直接配对与 T3 Connect 的会话彼此独立，授予的权限也可能不同。

在多台机器之间均衡新的对话线程

自动均衡默认关闭。在 Web 和桌面上，于 设置 → 环境 → 负载均衡 中启用它，即可为跨已连接环境分组的项目（project）中的新对话线程（thread）自动选择一台机器。有两台或更多机器处于开启状态后，这一节才会出现。 每台机器一开始都是 正常。选择 优先，会在它有可用的 CPU 和内存时优先选用它；选择 较少，会减少分给它的份额；选择 仅手动，会把它排除在自动选择之外。这些是偏好，不是固定的流量百分比。偏好在每个客户端中分别保存。

Composer（编写器）在为草稿选择环境时会检查符合条件的机器，然后保持这一选择不变。再次选择 自动均衡，可按当前资源重新检查；也可以选定一台具体的机器来覆盖这一选择。选择某个分支或工作树（worktree），也会让草稿留在那台机器上。已有的对话线程仍停留在它们开始的地方。如果资源检查不可用，或者所有符合条件的机器都已满，请手动选择一台机器再继续。移动端仍然手动选择环境。

Tailscale HTTPS

让两台设备加入同一个 tailnet。在桌面应用中，于 设置 → 共享与访问 启用 Tailscale HTTPS。在同一处关闭它，即可移除这条路由。

要用 Tailscale HTTPS 启动命令行服务器：

t3 serve --tailscale-serve

对于已经在运行的服务器：

t3 pair --tailscale

配对链接使用的地址类似于 https://machine.tailnet.ts.net/。 pair --tailscale 创建的映射会在重启之后保留。用下面的命令移除它的默认端口映射：

tailscale serve --https=443 --set-path=/ off

如果该端口已被占用，请用 --tailscale-serve-port 另选一个。其他配对选项见 t3 pair --help。

托管的 Web 应用

app.t3.codes 需要一个 HTTPS 端点。它直接连接到你的服务器；一条托管的配对链接并不能让原本不可达的后端变得可达，也不能把 HTTP 转成 HTTPS。

对于普通的 HTTP 局域网端点，请在能够打开它的浏览器中使用直接配对 URL，或者从桌面应用发起配对。在移动端，不带协议地输入 IP 地址时会使用 HTTP，因此当服务器使用 HTTPS 时，请带上 https://。

由桌面应用管理的 SSH

在桌面应用中，打开 设置 → 环境 → 添加环境，选择 SSH，并输入主机或 SSH 别名，例如 user@example.com。T3 Code 会在那里启动或复用一台服务器，并为你打开端口转发。项目（project）、提供方（provider）凭据和智能体的工作都留在远程机器上。

远程主机必须是 Linux 或 Apple Silicon Mac，并且具备 curl 或 wget、tar、sha256sum 或 shasum，以及提供方设置。首次启动会把 T3 Code 的服务器下载到主机上的 ~/.t3/runtime，因此比之后几次更久。 提供方 CLI 必须位于那里非交互式登录 shell 的 PATH 之中；检查方法如下：

ssh user@example.com 'sh -lc "command -v claude codex"'

如果应用更新之后 SSH 重新连接失败，请把启动再试一次。移除这条连接会停止由 T3 Code 启动的服务器；原先已经在运行的服务器则不会被停止。

每个桌面应用都会在主机上为其 SSH 连接保留一个会话，并在重新连接时复用该会话。请在主机的 设置 → 共享与访问 中吊销你不再使用的会话；在无界面主机上，则使用 t3 auth session list 和 t3 auth session revoke <id>。仍然能够通过 SSH 登录的桌面应用，会在下次连接时重新配对。

关于远程主机上 Antigravity 的 Google 回调，请参阅远程登录。

远程环境上的浏览器

浏览器标签页属于该环境（environment），因此你和你的智能体从任何设备看到的都是同一批标签页。桌面应用会直接显示它自己这个环境的标签页。其他每一台设备，以及桌面应用在查看其他环境时，都从主机串流这些标签页。没有设备连接时，智能体仍会继续使用它们，并且 localhost 地址可以访问主机上的服务器。

第一个标签页会把一个无头 Chrome（约 120 MB）下载到 T3 主目录中。它与HTML 渲染使用的是同一个浏览器，因此一台主机只会下载一次。有些 Linux 主机需要先完成设置，它才能启动。

智能体的标签页拥有各自的存储，并共享一个 Chromium 进程。向智能体的标签页输入之前，请先取得控制权；想让智能体继续时，再释放控制权。只读连接可以观看，而不会更改页面。

你持有控制权时，标签页会与你的设备配合：页面复制或剪切的文本会进入你的剪贴板，页面上的文件选择器会打开你设备上的选择器，完成的下载会提供给你保存。登录窗口等弹出窗口会作为各自的标签页打开。下载内容会留在主机上，直到该标签页关闭。音频不会在你的设备上播放。

在手机上，点按浮动预览角落上的圆点以显示它的控件，然后选择 弹出为独立窗口，即可在其他应用之上以画中画继续观看。

本地服务器

浏览器会列出由你的终端和智能体所启动的进程占用的端口。T3 Code 会读取每个端口由哪个进程占用，但从不连接到该端口，因此列出的端口会按 http://localhost:<port> 打开，而且它未必是网页。对于 HTTPS 服务器或某个特定路径，请在启动它的项目脚本上设置 预览 URL；T3 Code 会检查该地址，并按所写地址原样打开。

要停止列出端口，请在启动 T3 Code 服务器的环境中设置 T3CODE_PORT_DISCOVERY=0，例如后台服务（background service）所用的 service.env，然后重启它。脚本的预览 URL 仍会显示。

浏览器的主机设置

macOS、Windows 和 Linux 桌面会按原样运行浏览器。有些 Linux 主机需要一次性设置：Ubuntu 23.10 及更高版本会阻止浏览器运行所用的沙箱，精简镜像和容器则缺少它要加载的库。出现这种情况时，服务器会在启动时说明这一点，浏览器标签页和 HTML 预览会显示需要在主机上运行的命令：

sudo t3 browser setup

服务器会按你的启动方式给出确切的那一行，并保留你的 PATH，前提是你用 npx 启动，且 Node 只为你的用户安装。在 t3 不在你的 PATH 中的情况下，例如只安装了桌面应用，它会改为给出该应用自带的 t3 的完整路径。它会用一份 AppArmor 配置文件放行 Chrome 的沙箱，并用 apt 安装缺少的库和系统字体；页面能加载出来却没有文字，可能是主机上没有字体。再次运行是安全的。如果没有 sudo，它只会报告将要做出的更改。

浏览器默认运行在 Chrome 的沙箱中。Chrome 无法以 root 身份启动该沙箱。如果你的 T3 服务器以 root 运行，请改用非 root 用户来运行，以便继续启用沙箱。t3 browser setup 并不能解决这一 root 限制。

如果你必须以 root 运行，或无法在主机上启用沙箱，请在 T3 服务器的环境 中设置 T3CODE_SERVER_BROWSER_SANDBOX=0，并重启服务器。这样做会禁用 Chrome 的沙箱。如果手动启动：

T3CODE_SERVER_BROWSER_SANDBOX=0 t3 serve

对于 systemd 服务，把 Environment=T3CODE_SERVER_BROWSER_SANDBOX=0 加到其配置的 [Service] 之下，运行 sudo systemctl daemon-reload，然后重启你的 T3 服务。在智能体的终端里设置这个变量，并不会改变已经在运行的 T3 服务器所处的环境。

连接外部智能体

Claude Code、Codex、ChatGPT，以及并非由 T3 Code 启动的其他智能体，可以通过某个环境的 MCP 服务器来驱动其上的对话线程（thread）。设置方法见外部智能体。

关联另一个环境

把两台机器关联起来，例如你的笔记本电脑和一台 VPS，其中一台机器上的智能体就可以在另一台上工作：启动、发送消息、等待并停止它的对话线程（thread），回答它们的问题，并管理它的队列、项目（project）和计划任务。

关联环境是一项 beta 功能。请在两台机器的 设置 → 实验室 中打开它；在移动端，设置 → 实验室 会列出每一台已连接的机器。只要任意一台机器关闭了该功能，智能体就不会经由它们之间的关联启动任何内容。已经在另一台机器上运行的任务仍会完成；如果那台机器关闭了该功能，它的结果会在该功能重新打开后送达。

在你将要从中开展工作的机器上，打开 设置 → 环境 → 已关联的环境，选择 关联，然后挑选另一台机器，或输入它的地址。这个列表收录此应用已经知道的机器，以及你的 T3 Connect 账户上的机器。如果此应用已有那台机器的地址，并且是用一个能够在那边管理访问权限的会话连上去的，它就会自己生成配对代码；否则，请从那台机器的 设置 → 共享与访问 粘贴一个代码。凡是你亲手输入的地址，都需要粘贴一个代码。在终端中，使用 t3 environment link <address> --pairing-code <code> --access <mode>。

你也可以让智能体按名字关联一台机器，例如「把这个委派给我的 vps」。它会在对话线程中显示一张卡片，你在卡片上用同样的方式选择机器和访问权限，然后批准。如果智能体给出的地址并不被此应用识别为你某台机器的地址，同样需要粘贴代码。只对你信任的地址粘贴代码，因为代码会被发送到那个地址。

• 你挑选的访问权限，是来自这台机器的智能体在那边最多可以做的事。智能体在那边得到的权限，也不会超过它在这边自己的模式。
• 由关联启动的对话线程，在那边会标成 来自 加上这台机器的名称。
• 完全访问的关联，在那边的作用和那台机器自己的智能体一样。低于完全访问时，该关联的智能体只能改动它自己启动的对话线程，不能改动那台机器自己的对话线程、项目或设置，而且会跳过它的项目设置脚本。
• 这条关联会像其他外部智能体一样，出现在那台机器的 设置 → 共享与访问 里。在那边吊销它，关联即告结束。在这台机器上选择 忘记，只会在这里把它去掉。
• 关联的有效期是 30 天。要用新的配对代码再关联一次，才能续期。

智能体也可以用 delegate_task 把一项任务交给已关联的机器：它会在那边作为一条普通对话线程运行，项目是仓库相同的那个（或者 target.projectId 点名的那个），结束时，这个对话线程会像任何委派任务一样，带着它的结果被唤醒。即使重启，它也会继续跟踪这项任务。如果另一台机器吊销了关联，或关联在这里被移除，这项任务会以该原因失败。

管理或吊销访问权限

在主机上，设置 → 共享与访问 让获得授权的管理员创建配对链接，并吊销客户端（client）会话。吊销一条还没用过的链接，可以阻止新的配对；要去掉某台设备已经获得的访问权限，请吊销它的会话。命令行管理通过 t3 auth --help 进行。

当应用连接到不止一个环境（environment）时，在页面顶部选择其中一个。关闭了 本地环境 的桌面应用，可以借此管理同一台机器上的后台服务（background service），包括它的 T3 Connect 关联。

仍有打开连接的会话，在访问凭据过期之后还会留在列表里。

要选择某个令牌的权限，请对你想要的每一个作用域各传入一次 --scope：

t3 pair --scope orchestration:read --scope relay:read

选中的作用域会取代默认权限。同一选项也适用于 t3 auth pairing create 和 t3 auth session issue；每条命令（command）的 --help 会列出可用的作用域。不使用 --scope 时，配对令牌和签发出来的 bearer 会话会得到全部权限，包括管理访问权限和 T3 Connect。主机上的终端，或拥有完全访问权限的智能体，同样能够用到这些权限，因此不应当管理访问权限的客户端，也不能带有 terminal:operate 和 orchestration:operate。

要更改现有客户端的权限，请创建一条包含它所需作用域的新配对链接。在直接于该环境中打开的浏览器里打开这条链接，即可替换该浏览器当前的授权。对于移动端，或 Web 与桌面中已保存的远程环境，请使用 添加环境，并填入这条新链接或代码；对同一个环境再次配对，会替换已保存的授权。只是重新连接，并不会改变权限。

把多个检出编为一组，并不会把它们的权限合并起来。共享的项目（project）设置要求每一个成员环境都拥有 orchestration:operate；对某一个检出所做的操作，使用的是该检出自己的权限。

source-control:write 涵盖从客户端直接做出的 Git 和拉取请求（pull request）更改：推送、切换或创建分支、克隆，以及移除工作树（worktree）。它并不限制一项任务可以做什么。在新的工作树里启动任务，仍然会用 orchestration:operate 创建该分支和工作树，而它运行的智能体仍可在该环境允许的范围内使用 Git。

设置更改、提供方（provider）管理、环境维护、访问权限管理以及 T3 Connect 管理，都可以单独授予。不带 --scope 的新配对会把它们全部包含在内。现有客户端会保留配对当时的权限，更新之后也可以继续保持连接，但新拆分出来的功能，可能需要带上它们所需的权限重新配对。较旧的客户端可能会显示出服务器会拒绝的控件。要更改某个客户端的权限，请创建一条新的配对链接。

filesystem:read 允许浏览主机上的文件、打开工作区文件，以及查看本地更改。再加入 filesystem:write，即可允许编辑文件，或把计划保存到工作区。这些作用域控制的是客户端对文件的直接访问。

要从 T3 Connect 移除一个环境，请打开账户菜单中的 T3 Connect 页面，或在移动端打开 设置 → T3 Connect，然后选择 注销。这会吊销它的云端访问权限，并释放它占用的主机名额，即使该环境处于离线状态，或者已经被清除，也是如此。当 T3 Connect 拒绝某台主机的关联时，主机会显示自己已从 T3 Connect 移除。要再次关联它，请在桌面主机的 设置 → 共享与访问 中打开 T3 Connect，或在命令行主机上运行 t3 connect link，然后在那里重启 T3 Code。如果一台命令行主机在上次停止时释放了自己的隧道，它可能在下次启动时自行重新关联；在该主机上运行 t3 connect unlink，即可让它保持关闭。从某台设备的连接设置里移除一个环境，只会让该设备忘记它，并不会更改你的 T3 Connect 账户。环境注销之后，设备仍会保留这个已保存的环境，直到你从该设备上把它移除。

启用空闲隧道清理后，如果某个已关联环境的隧道持续离线数分钟，T3 Connect 会移除该隧道。该环境仍然保持关联，地址也不变。当主机再次启动或唤醒时，T3 Connect 会自行建立一条替代隧道。你不需要再次配对。清理通常在隧道中断后五到十分钟执行。

对于运行较旧版本 T3 Code 的环境，一旦它离线满七天，T3 Connect 也会移除其隧道。该环境会显示一条提示，要求你更新。在那台计算机上启动 T3 Code，并把它更新到最新版本；它会在原来的地址重新连接，无需再次配对。

在命令行主机上，t3 connect unlink 会关闭对外暴露，同时保留你的登录；t3 connect logout 还会清除这次登录。后台服务的移除是另一项操作。

请把配对 URL 和授权代码当作密码来对待。不要把它们放进截图、日志或缺陷报告。

T3 Connect 故障排除

当 T3 Connect 连接失败时，请参阅 T3 Connect 故障排除。文档会逐一说明每种错误、问题出在哪里，以及如何修复。

仅将桌面应用用作远程端

如果某台计算机只用来驱动在别处运行的工作，请关闭它的本地环境。在桌面应用中，打开 设置 → 环境，并关掉 本地环境。T3 Code 会在没有本地服务器的情况下重新启动：本地智能体和终端都不再运行，WSL 后端保持关闭，其他设备也不能再连接到这台计算机。你的项目（project）、历史记录和已保存的连接都会保留，你仍然可以通过配对、T3 Connect 或 SSH 继续工作。如果这台计算机上的后台服务（background service）使用同一个 T3 主目录，应用仍会把它视为这台计算机：无论你经由哪一种连接访问它，其项目的 打开于 和显示文件位置都会在这台计算机上执行。

在同一位置把 本地环境 重新打开，即可按你先前的本地设置重新启动。