在后台运行 T3 Code¶

在 Linux 和 macOS 上，T3 Code 可以作为您的用户服务运行，因此无需一直保持终端打开。

管理服务¶

首先安装 t3 CLI（安装 T3 Code），然后在将托管 T3 Code 的机器上运行以下命令：

卸载服务不会影响您的项目、会话和设置。如果 t3 service status 报告服务已损坏，重新运行 t3 service install 即可修复。

t3 update 会下载您所在频道的最新版本，并将 t3 和服务切换到该版本。重启会中断正在运行的 agent 轮次、终端和远程客户端，因此它会先询问；如果回答「否」，服务将继续运行旧版本，直到您运行 t3 service restart。在脚本中传入 --yes 即可自动确认。手动启动的服务器会保持运行；停止并重新启动它即可加载新版本。更新前请等待任何已在进行的远程更新完成；如需匹配远程客户端的版本，请参阅更新 T3 Code。

传入具体版本号（t3 update 0.0.42）可固定版本，--channel nightly 可切换发布轨道，--allow-downgrade 可降级。preview 是维护者的测试轨道：其构建版本可能无法使用，且永远不会作为更新推送，因此安装器和 t3 update 在安装前都会要求确认。

t3 uninstall 会在显示列表并询问一次后，移除后台服务、t3 启动器和已下载的版本。~/.t3/userdata 下的项目、会话和设置会保留，T3 主目录下的 service.env 也会保留。在脚本中传入 --yes 即可自动确认。

本地网络访问¶

新服务仅响应来自本机的请求。其他设备可通过 T3 Connect 访问它，或者在您通过 t3 up 选择本地网络后直接访问（或运行 t3 up --lan，这会在 service.env 中设置 T3CODE_LAN=true）。之后它会在本地网络和 Tailscale 地址上监听，因此同一网络上的桌面应用和移动应用会直接连接，而无需通过 T3 Connect。它仍然不会响应公共地址。同一网络上的任何人都可以访问该端口，因此配对码是阻止他们的唯一屏障。位于 app.t3.codes 的托管 Web 应用仍通过 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 命令，也不进行变量展开。条目会覆盖继承的服务环境，但 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 用户服务。安装程序会启用 linger，以便 T3 Code 在开机时启动并在注销后继续运行。如果这需要管理员权限，安装程序会在更改服务前打印一条恢复命令。

macOS 会在您登录时启动服务，并在注销时停止服务。如需无人值守的远程访问，请保持 Mac 处于登录状态并保持唤醒。当 Mac 屏幕前无人登录时，通过 SSH 安装可能会在最后的启动步骤失败；服务仍会安装成功，并将在下次登录时启动。

不支持 Windows 后台服务。要让 Windows 主机通过 T3 Connect 保持可用，请保持桌面应用运行并启用其本地环境，或在终端中保持 t3 serve 运行。请最小化桌面应用，而不要关闭其最后一个窗口，因为关闭窗口会停止其本地服务器。关联 T3 Connect 不会在 Windows 登录时配置自动启动。

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

在 agent 耗尽内存时保持服务器响应¶

在 Linux 上，agent 已经以低于服务器的优先级运行。然而，当它们耗尽机器内存时，内核仍可能使服务器变慢或停止，因为只有管理员才能为其预留内存。请以您的普通用户身份运行：

t3 service protect

它会显示将要更改的系统设置，在应用前询问您，然后要求输入您的 sudo 密码。如果机器运行 Tailscale 或 SSH，它还会提供保护这些服务的选项，以便您仍能访问该机器。内存保护会立即生效。服务器免受内核 OOM killer 影响的保护会在 t3 service restart 后生效。t3 service status 会报告保护是否已在生效，t3 service protect --undo 可移除保护。

故障排查¶

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

如果服务在您的 SSH 会话关闭时停止，请检查 linger-disabled。管理员可以通过以下方式启用驻留：

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 并保持该会话打开。

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

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

回收数据库空间¶

T3 Code 在运行时会自行删除超过一天的历史记录；您的对话会被保留。在自动缩减功能生效之前创建的数据库，在一次性离线修复归还磁盘空间并开启自动缩减之前，仍会在磁盘上占用已释放的空间。当至少可以回收 1 GiB 空间时，设置 > 维护（网页端和桌面端）或设置 > 维护（移动端）会建议进行修复。

当桌面应用或后台服务在该机器上运行 T3 Code 时，请在网页端或桌面端的设置中选择回收。T3 Code 会检查可用磁盘空间，然后停止、修复数据库并重新启动。修复运行期间它会处于离线状态，正在运行的代理也会停止。如果修复失败，设置中会显示原因。

在其他情况下，例如手动启动的服务器，请在承载该环境的机器上运行 t3 doctor。它会报告数据库大小和可回收的空间，然后询问要运行哪些修复；传入 --fix 可以无需提示直接运行推荐的修复（适用于脚本），或传入 --dry-run 仅进行报告。同一数据目录的已安装后台服务会在修复期间停止，之后重新启动，即使修复失败也是如此。请先退出手动启动的服务器或桌面应用：修复程序拒绝处理正在使用的数据库。使用 --base-dir 指定其他数据目录。

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

如果您是从 0.1.0 之前的版本升级的，其数据库（state.sqlite）仍会保留在当前数据库旁边，以便您可以回滚。t3 doctor 会提供删除它的选项，但绝不会为您选择该修复，--fix 也会跳过它：一旦删除，0.1.0 之前的版本启动时将没有任何会话或设置。