在后台运行 T3 Code

在 Linux 和 macOS 上，T3 Code 可以作为你的用户服务运行，因此不必一直开着终端。

管理服务

请先安装 t3 CLI（安装 T3 Code），然后在将要托管 T3 Code 的机器上运行这些命令：

任务	命令
设置从你的其他设备进行访问	t3 up
查看你的其他设备如何访问它	t3 status
安装并启动	t3 service install
查看状态和日志位置	t3 service status
换到较新的发行版	t3 update
重启	t3 service restart
停止，并从开机启动中移除	t3 service uninstall

卸载该服务后，你的项目（project）、对话线程（thread）和设置都会保留。再次运行 t3 service install，可以修复被 t3 service status 报告为已损坏的服务。

t3 update 会下载你所在通道上的最新发行版，并把 t3 和该服务切换到这个版本。重启会中断正在运行的智能体回合（turn）、终端和远程客户端（client），因此它会先询问；若回答否，服务会继续运行旧版本，直到你运行 t3 service restart。在脚本中传入 --yes。你手工启动的服务器会保持运行；先停止再启动，才能换上新版本。更新之前，请等任何已经在进行的远程更新完成；若要与远程客户端的版本保持一致，请按照更新 T3 Code操作。

传入一个确切版本（t3 update 0.0.42）即可固定到该版本，--channel nightly 用来切换通道，--allow-downgrade 用来回退。preview 是维护者的测试通道：它的构建可能是坏的，也绝不会作为更新被提供，因此安装程序和 t3 update 在安装这类构建之前都会要求确认。

t3 uninstall 会先向你展示清单并询问一次，然后移除后台服务（background service）、t3 启动器，以及已下载的版本。~/.t3/userdata 下的项目、对话线程和设置会保留，T3 主目录下的 service.env 也会保留。在脚本中传入 --yes。

本地网络访问

新建的服务只在这台机器上应答。其他设备通过 T3 Connect 访问它；你在 t3 up 中选择本地网络之后，也可以直接访问（或者运行 t3 up --lan，它会把 T3CODE_LAN=true 写进 service.env）。此后它会监听你的本地网络地址和 Tailscale 地址，因此同一网络上的桌面应用（desktop app）和移动应用（mobile app）会直接连接，而不经过 T3 Connect。它仍然不会在公网地址上应答。同一网络上的任何人都能访问这个端口，因此能把他们挡在外面的只有配对码。托管在 app.t3.codes 的 Web 应用（web app）仍然使用 T3 Connect，因为浏览器会阻止从 HTTPS 页面发出明文 HTTP。

在 T3CODE_LAN 存在之前就已安装的服务，会继续监听本地网络。t3 status 会指出这一点，t3 up --no-lan 会关闭它。任意 T3CODE_HOST 取值都会取代这项设置。

配置服务环境

把自定义环境变量写到服务的 T3 主目录下的 service.env 中，通常就是 ~/.t3/service.env。这个文件在服务安装和更新之后仍然保留。例如：

T3CODE_PORT=3773
T3CODE_HOST=127.0.0.1

使用 KEY=VALUE 条目，包含空格或 # 的值要加引号。这些值按字面量处理：不会执行 shell 命令，也不会展开变量。条目会覆盖服务继承来的环境（environment），但 PATH、T3CODE_HOME、T3_BOOT_SERVICE_UNIT 和 T3_SERVICE_LAUNCHER_CONTEXT 除外（包括大小写变体）。

修改该文件之后运行 t3 service restart。更改会在服务再次启动时生效；只切换服务器版本时，当前的值保持不变。对于在支持环境变量文件之前安装的服务，请用已是最新的 CLI 运行一次 t3 service install。文件不存在时会被忽略；其他读取失败会阻止服务启动。如果文件里有凭据，请用 chmod 600 限制对该文件的访问（默认的 T3 主目录对应 chmod 600 ~/.t3/service.env）。

平台支持

Linux 需要 systemd 用户服务。安装过程会启用 lingering，使 T3 Code 在开机时启动，并在注销后继续运行。如果这需要管理员权限，安装过程会在更改服务之前先打印一条恢复命令。

macOS 在你登录时启动该服务，在你注销时停止它。若要在无人值守时远程访问，请让 Mac 保持登录且不休眠。如果 Mac 的屏幕前没有人登录，通过 SSH 安装可能会在最后的启动步骤失败；服务本身已经安装，会在下次登录时启动。

不支持 Windows 后台服务（background service）。要让一台 Windows 主机通过 T3 Connect 保持可用，请让桌面应用（desktop app）保持运行并启用其本地环境（environment），或者在终端里保持 t3 serve 运行。请最小化桌面应用，而不要关闭它的最后一个窗口，关闭最后一个窗口会停掉它的本地服务器。关联 T3 Connect 并不会把它配置为在 Windows 登录时自动启动。

设置 T3 Connect 时，t3 up 会安装该服务，但两者分开管理。退出 T3 Connect 并不会停止或卸载该服务。

在智能体占满内存时保持服务器可响应

在 Linux 上，智能体的运行优先级已经低于服务器。不过，当它们把机器的内存占满时，内核仍可能拖慢或停掉服务器，因为只有管理员才能为它预留内存。请以你的普通用户身份运行：

t3 service protect

它会显示将要更改的系统设置，在应用前征求同意，然后询问你的 sudo 密码。如果这台机器运行着 Tailscale 或 SSH，它也会提议一并保护它们，这样你仍然能够连上这台机器。内存保护会立即生效。服务器针对内核 out-of-memory killer 的保护，要到 t3 service restart 之后才生效。t3 service status 会报告保护是否已经就位，t3 service protect --undo 会移除该保护。

故障排除

先在主机上运行 t3 service status。它会打印日志路径，并在 Linux 上检查已安装的服务是否正在运行、是否已启用，以及是否允许在注销后继续运行。

如果它在你的 SSH 会话关闭时停止，请检查 linger-disabled。管理员可以用下面的命令启用 lingering：

sudo loginctl enable-linger "$(id -un)"

通过 SSH 时，允许 sudo 出现提示：

ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'

然后以普通用户身份重新执行服务安装。只用 sudo 运行 loginctl 这一条命令；以 root 身份运行 T3 Code 会创建单独的一套安装和 Connect 身份。如果没有管理员权限，请在终端中运行 t3 serve，并保持该会话打开。

状态问题	下一步
linger-unavailable	运行 loginctl show-user "$(id -un)" --property=Linger，并检查 systemd-logind 是否可用。
user-manager-unavailable	在该服务用户的登录会话中运行 systemctl --user status；检查你的发行版对 systemd 用户会话的支持。
service-disabled 或 service-stopped	阅读日志和 systemctl --user status t3code.service，然后使用 T3 Code 打印出的修复命令。
restart-pending	已经安装了较新版本，但服务仍在运行前一个版本。请运行 t3 service restart。

在 macOS 上，如果服务不再于登录时启动，请检查 系统设置 → 通用 → 登录项。如果智能体的工作无法访问桌面、文稿或下载，可能需要为 t3 可执行文件授予完全磁盘访问权限；它列在 ProgramArguments 中，而该键位于 ~/Library/LaunchAgents/com.t3tools.t3code.service.plist。

登录 T3 Connect 之后如果出现故障，请参阅连接故障排除。

回收数据库空间

T3 Code 在运行期间会自行删除超过一天的内部历史；你的对话会保留。在这项自动收缩出现之前创建的数据库，仍然会把已经腾出的空间占在磁盘上，直到一次离线修复把空间归还，并开启自动收缩。当至少可以回收 1 GiB 时，「设置 > 维护」（Web 和桌面）或「设置 > 维护」（移动端）会建议进行这次修复。

当桌面应用（desktop app）或后台服务（background service）在这台机器上运行 T3 Code 时，请在 Web 或桌面端的「设置」中选择 回收。T3 Code 会检查空闲磁盘空间，然后停止、修复数据库，并再次启动。修复进行期间它处于离线状态，正在运行的智能体也会停止。如果修复失败，「设置」会说明原因。

在其他情况下，例如你手工启动的服务器，请在托管该环境（environment）的机器上运行 t3 doctor。它会报告数据库大小以及可以回收的空间，然后询问要执行哪些修复；传入 --fix 可以不经提示就运行推荐的修复（供脚本使用），传入 --dry-run 则只做报告。同一数据目录上已安装的后台服务会为这次修复而停止，并在之后重新启动，修复失败时也是如此。请先退出你手工启动的服务器或桌面应用：修复会拒绝触碰正在使用中的数据库。数据目录不同时，请使用 --base-dir。

大型数据库上的修复可能要花上几分钟。它通过一份临时副本重建数据库，因此需要大约两倍于仍在使用的数据的空闲空间（数据库大小减去可回收空间）：一处在系统临时目录中（在 Linux 和 macOS 上是 TMPDIR，未设置时是 /var/tmp），另一处在数据库旁边，供其预写日志使用。

如果你从 0.1.0 之前的版本升级而来，它的数据库（state.sqlite）仍会保留在当前数据库旁边，以便你回滚。t3 doctor 会提议删除它，但绝不会替你选中这项修复，--fix 也会跳过它：一旦删掉，0.1.0 之前的版本启动时将没有任何对话线程（thread）或设置。