T3 Code 安装部署完全指南从 npx 免安装启动到桌面端、移动端与 Provider 配置【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款把编码 Agent 运行在你自己电脑上的开发工具Agent 在宿主机上执行任务而你通过桌面端、Web 端或移动端随时控制它们。本文以 docs/user/install.md 为主体系统梳理 T3 Code 的完整安装路径——包括npx t3latest免安装启动、桌面应用与包管理器安装、WSL 后端、移动端远程连接以及 Codex、Claude、Cursor、Grok Build、OpenCode、Antigravity 等 Provider 的安装认证流程并结合仓库源码CLI 入口、配置解析、桌面激活协议等深入解释每条命令背后的实现原理。读完后你将能够根据机器类型、网络环境与使用习惯为 T3 Code 选择最合适的安装方式并完成全部环境配置。安装前的系统要求T3 Code 的核心运行模型是先在将要执行 Agent 工作的那台机器上完成安装与配置再用任意前端桌面、Web、移动接入。因此安装的第一步是确定工作机——也就是运行 Agent 的宿主机。官方对运行环境的要求如下与 apps/server/package.json 中声明的engines字段一致运行方式依赖要求npx t3启动仅需 Node.js 用于运行 npm 本身CLI 安装下来后是一个自包含可执行文件SSH 主机 / WSL 后端需要 Node.js 22.1622.x、23.1123.x或 24.10 及以上版本原生桌面应用自带服务器运行时无需单独安装 Node.js另有两点需要提前知晓需要已安装且已认证的 Provider 才能开始一个线程thread。你可以先启动 T3 Code之后再在界面里配置 Provider但开始真正的 Agent 会话前必须完成 Provider 的安装与登录。Provider 的安装、登录和配置都归属工作机这台机器即使你从手机或其他电脑连接过来配置也只在工作机上生效。免安装快速启动npx t3latest最快的上手方式是直接通过 npm 运行无需提前下载安装包npx t3latest这条命令会启动 T3 Code 服务器并自动打开本地 Web 应用。查看全部命令行选项npx t3latest --help从 CLI 入口源码 apps/server/src/bin.ts 可以看到t3命令实际注册了相当完整的子命令集合start/serve—— 启动服务器serve前台运行start常用于配合后台服务app—— 在已运行的桌面应用中打开项目pair—— 生成配对链接/二维码供其他设备连接auth—— 管理认证与授权如t3 auth --helpproject—— 项目管理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 中可见--modedesktop/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和vpVite 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 页面下载安装包或直接使用系统包管理器平台安装命令Windowswinget install T3Tools.T3CodemacOSbrew install --cask t3-codeArch Linuxyay -S t3code-binArch Linux nightlyyay -S t3code-nightly-bin以 Arch Linux 的 AUR 包为例仓库中的 packaging/aur/t3code-bin/PKGBUILD 展示了它的落地方式包内是官方发布的 x86_64 AppImageT3-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 LinuxWSL如果你想在 WSL 发行版中运行 Agent 和项目流程是在桌面应用的Settings → Connections中选择一个 WSL 发行版在该发行版内部安装 Node.js 与各 Provider 的 CLIT3 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 StoreiOS或 Google PlayAndroid安装 T3 Code。手机本身不运行 Agent而是连接另一台机器上的服务器通过T3 Connect云中转或配对 URL将手机与服务器关联具体流程见 docs/user/remote-access.md。关联之后手机的连接设置位于Settings → Environments桌面/Web 端为 Settings → Connections。如果你遇到应用启动崩溃可以在下一次成功启动后打开Settings → Diagnostics它会列出过去 7 天内的启动崩溃记录包含错误信息与组件调用栈这些是崩溃报告通常不会留存的细节。复制报告提交到 GitHub issue 时请注意错误信息可能引用应用内的敏感值分享前先通读一遍。配置 ProviderAgent 能力来自 Provider因此配置 Provider 是安装后最关键的一步。在 Web 或桌面应用中打开Settings → Providers选择环境environment然后启用你需要的 Provider。注意Provider 的安装、登录和配置都归属于该环境的机器——即使你从手机或其他电脑连接也是在主机那侧完成的。各 Provider 的安装与认证方式如下表Provider安装与认证Codex安装 Codex CLI然后运行codex loginClaude安装 Claude Code然后运行claude auth loginCursor安装 Cursor CLI然后运行agent loginGrok Build安装 Grok Build CLI然后运行grok loginOpenCode安装 OpenCode然后运行opencode auth loginAntigravity直接在 T3 Code 的 Provider 设置中通过 Google 登录配置 Provider 时有几个关键要点PATH 要求Provider CLI 必须位于服务器的PATH中。如果 T3 Code 找不到某个 CLI请在 Provider 设置中为其指定Binary path使用版本管理器安装时尤其常见。特例Cursor 的可执行文件名是cursor-agent但其登录命令是agent loginAntigravity 可以使用其托管运行时无需在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更新应用与已连接的服务器。常见命令速查目的命令免安装启动服务器与 Web 应用npx t3latest查看 CLI 全部选项npx t3latest --help在桌面应用中打开当前目录npx t3 app打开指定路径npx t3 app ../my-project安装并启动后台服务Linux/macOSnpx t3latest service install查看服务状态与日志位置npx t3latest service status更新/修复服务npx t3latest service update停止并移除自启动npx t3latest service uninstall无 Node 机器安装 CLIcurl -fsSL https://t3.codes/install.sh | shWindows 用 PowerShell 执行 install.ps1关于后台服务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 t3latest一行启动Intel Mac 或特殊环境则从源码构建最后在主机侧完成 Provider 的安装认证即可通过任意端设备开始你的 Agent 会话。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考