企业官网建设流程全解析

T3 Code 安装部署完全指南：从 npx 免安装启动到桌面端、移动端与 Provider 配置

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code

T3 Code 是一款把编码 Agent 运行在你自己电脑上的开发工具：Agent 在宿主机上执行任务，而你通过桌面端、Web 端或移动端随时控制它们。本文以 docs/user/install.md 为主体，系统梳理 T3 Code 的完整安装路径——包括npx t3@latest免安装启动、桌面应用与包管理器安装、WSL 后端、移动端远程连接，以及 Codex、Claude、Cursor、Grok Build、OpenCode、Antigravity 等 Provider 的安装认证流程，并结合仓库源码（CLI 入口、配置解析、桌面激活协议等）深入解释每条命令背后的实现原理。读完后，你将能够根据机器类型、网络环境与使用习惯，为 T3 Code 选择最合适的安装方式并完成全部环境配置。

安装前的系统要求

T3 Code 的核心运行模型是：先在将要执行 Agent 工作的那台机器上完成安装与配置，再用任意前端（桌面、Web、移动）接入。因此，安装的第一步是确定"工作机"——也就是运行 Agent 的宿主机。

官方对运行环境的要求如下（与 apps/server/package.json 中声明的engines字段一致）：

另有两点需要提前知晓：

• 需要已安装且已认证的 Provider 才能开始一个线程（thread）。你可以先启动 T3 Code，之后再在界面里配置 Provider，但开始真正的 Agent 会话前必须完成 Provider 的安装与登录。
• Provider 的安装、登录和配置都归属"工作机"这台机器，即使你从手机或其他电脑连接过来，配置也只在工作机上生效。

免安装快速启动：npx t3@latest

最快的上手方式是直接通过 npm 运行，无需提前下载安装包：

npx t3@latest

这条命令会启动 T3 Code 服务器，并自动打开本地 Web 应用。查看全部命令行选项：

npx t3@latest --help

从 CLI 入口源码 apps/server/src/bin.ts 可以看到，t3命令实际注册了相当完整的子命令集合：

• start/serve—— 启动服务器（serve前台运行，start常用于配合后台服务）
• app—— 在已运行的桌面应用中打开项目
• pair—— 生成配对链接/二维码，供其他设备连接
• auth—— 管理认证与授权（如t3 auth --help）
• project—— 项目管理
• service—— 后台服务安装/状态/更新/卸载
• update/uninstall—— CLI 自身的升级与卸载
• connect—— T3 Connect 云连接（依赖公开配置的构建才会启用）
• claudeHistory、serviceLauncher、servicePreflight、sshHelper、theme、triage等辅助命令

npx t3安装的 CLI 是针对Apple Silicon Mac、Linux、Windows构建的自包含可执行文件。没有 Intel Mac 构建版本——原因是 Node 无法为 Intel Mac 平台产出单一可执行文件（Intel Mac 上的桌面应用不受影响）。因此，如果你要在 Intel Mac 上运行独立服务器，只能从源码构建（见下节）。

补充说明：上述启动类命令还支持丰富的参数与环境变量。例如在 apps/server/src/cli/config.ts 中可见--mode（desktop/web 运行模式）、--port、--host（绑定地址，如127.0.0.1、0.0.0.0或 Tailnet IP）、--base-dir（数据目录，等价于T3CODE_HOME）、--no-browser、--cwd、--tailscale-serve等 flag；对应的环境变量包括T3CODE_PORT、T3CODE_HOST、T3CODE_HOME、T3CODE_MODE、T3CODE_NO_BROWSER、T3CODE_LOG_LEVEL、T3CODE_TAILSCALE_SERVE等。这些参数在普通npx t3启动时一般不常使用，但在远程访问、CI 化部署场景中非常有用，具体用法见 docs/user/remote-access.md。

在 Intel Mac 上从源码构建

由于没有 Intel Mac 的预编译 CLI，若要在 Intel Mac 上运行独立服务器，需要从源码构建。构建要求Node.js 24和vp（Vite Plus 工具）：

git clone https://gitcode.com/GitHub_Trending/t3/t3code cd t3code && vp i && vp run build:desktop node apps/server/dist/bin.mjs

几点需要明确：

• 最终入口apps/server/dist/bin.mjs与 apps/server/package.json 中"bin": { "t3": "./dist/bin.mjs" }的声明一致，构建产物是纯 Node 程序。
• 以这种方式运行的服务器不适用t3 update与后台服务机制：升级时你需要git pull拉取新代码后重新构建，并像管理其他 Node 进程一样自行决定如何启动、守护它。

桌面应用安装

桌面应用自带服务器运行时，是最省心的"工作机"形态。你可以从项目 Releases 页面下载安装包，或直接使用系统包管理器：

以 Arch Linux 的 AUR 包为例，仓库中的 packaging/aur/t3code-bin/PKGBUILD 展示了它的落地方式：包内是官方发布的 x86_64 AppImage（T3-Code-${pkgver}-x86_64.AppImage），安装后解压到/opt/t3code-bin/，通过/usr/bin/t3code与t3-code-desktop两个可执行入口启动，并注册x-scheme-handler/t3code协议处理器——这也是桌面端能够响应t3 app等本地调用的一部分基础。nightly 对应包为t3code-nightly-bin，跟随每日构建版本。

Windows Subsystem for Linux（WSL）

如果你想在 WSL 发行版中运行 Agent 和项目，流程是：

1. 在桌面应用的Settings → Connections中选择一个 WSL 发行版；
2. 在该发行版内部安装 Node.js 与各 Provider 的 CLI；
3. T3 Code 会自动在该发行版中安装与之匹配的服务器运行时。

注意：应用更新后的首次启动可能耗时更长，因为需要重新安装/匹配服务器运行时。

从终端打开项目：npx t3 app

当桌面应用已在本机运行时，你可以在任意项目目录下用一条命令把项目"送进"桌面应用并开启新线程：

npx t3 app

这会为当前目录打开一个新线程（必要时自动添加该项目）；也可以显式指定路径：

npx t3 app ../my-project

它的实现机制可以从 apps/server/src/cli/app.ts 中看到：CLI 会通过本地 Unix 域套接字/命名管道向桌面应用发送一个open-workspace类型的激活请求（DesktopAppActivationRequest），包含工作区根目录、平台、请求 ID 等字段，并等待 JSON 响应（超时 17 秒，CLI_RESPONSE_TIMEOUT_MS = 17_000）。

该命令有明确的适用边界，源码中定义了对应的错误类型：

• 必须要求同机桌面应用。t3 app只能在"桌面应用与本机"这一形态下工作，独立服务器或 SSH 会话都不够——代码会检测SSH_CONNECTION/SSH_TTY环境变量并直接抛出DesktopAppSshUnsupportedError（提示"t3 app只能控制本机的桌面应用，无法通过 SSH 使用"）。
• 如果命令无法触达桌面应用，会得到DesktopAppUnreachableError，提示先启动或更新桌面应用再重试（错误信息原文："A running T3 Code server is not enough."）。

移动应用安装

手机端可通过 App Store（iOS）或 Google Play（Android）安装 T3 Code。手机本身不运行 Agent，而是连接另一台机器上的服务器：

• 通过T3 Connect（云中转）或配对 URL将手机与服务器关联，具体流程见 docs/user/remote-access.md。
• 关联之后，手机的连接设置位于Settings → Environments（桌面/Web 端为 Settings → Connections）。

如果你遇到应用启动崩溃，可以在下一次成功启动后打开Settings → Diagnostics：它会列出过去 7 天内的启动崩溃记录，包含错误信息与组件调用栈（这些是崩溃报告通常不会留存的细节）。复制报告提交到 GitHub issue 时，请注意错误信息可能引用应用内的敏感值，分享前先通读一遍。

配置 Provider

Agent 能力来自 Provider，因此配置 Provider 是安装后最关键的一步。在 Web 或桌面应用中打开Settings → Providers，选择环境（environment），然后启用你需要的 Provider。注意：Provider 的安装、登录和配置都归属于该环境的机器——即使你从手机或其他电脑连接，也是在主机那侧完成的。

各 Provider 的安装与认证方式如下表：

配置 Provider 时有几个关键要点：

• PATH 要求：Provider CLI 必须位于服务器的PATH中。如果 T3 Code 找不到某个 CLI，请在 Provider 设置中为其指定Binary path（使用版本管理器安装时尤其常见）。
• 特例：Cursor 的可执行文件名是cursor-agent，但其登录命令是agent login；Antigravity 可以使用其托管运行时，无需在PATH中注册。
• 版本滞后提示：当 Provider CLI 落后于其最新版本时，Provider 卡片会显示可用版本。Update now按钮只在 T3 Code 能够识别"该 CLI 由哪个安装器管理"（其自身更新命令、Homebrew，或全局 npm、pnpm、bun、Vite+ 安装）时才会出现，此时更新会直接调用对应安装器；否则请按你当初安装 CLI 的方式自行更新。注意 Homebrew 安装的版本会与 Homebrew 提供的版本比较，而 Homebrew 的版本可能比 npm 发布滞后几个小时。
• 多实例与敏感值：可以为不同的账号或配置添加多个 Provider 实例，每个实例可以设置独立的环境变量（如 API key 或自定义 base URL）。标记为敏感（sensitive）的变量在保存后，T3 Code 不会显示其原始值。

各 Provider 的详细配置与账号说明，请分别参考 Codex、Claude、OpenCode 和 Antigravity。

安装后的下一步

完成基础安装后，建议按需阅读以下文档继续配置：

• 线程与并行工作：开始任务并组织并行工作；
• 权限模式：选择 Agent 在何时需要先征得同意再执行操作；
• 远程访问：从其他设备连接（T3 Connect、LAN 配对、Tailscale HTTPS、SSH 托管等）；
• 后台运行：让 Linux/macOS 主机常驻可用（t3 service install等命令）；
• 更新 T3 Code：更新应用与已连接的服务器。

常见命令速查

关于后台服务：Linux 需要 systemd 用户服务（会启用 lingering 使服务在注销后继续运行），macOS 在登录时启动、注销时停止，Windows 不支持后台服务。这些与t3 update、t3 uninstall、安装脚本环境变量（如T3CODE_CHANNEL、T3CODE_VERSION、T3CODE_RELEASE_BASE_URL）的完整说明均见 docs/user/background-service.md。

总结来说，T3 Code 的安装哲学是"Agent 工作机优先配置，前端设备按需接入"：日常开发建议直接使用自带服务器运行时的桌面应用（或 WSL 后端），临时使用场景用npx t3@latest一行启动，Intel Mac 或特殊环境则从源码构建；最后在主机侧完成 Provider 的安装认证，即可通过任意端设备开始你的 Agent 会话。

【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code