1. 项目速览

T3 Code 在官方 README 中把自己描述为一个“agent harness control surface”，即代理控制面。它的作用是控制运行在你机器上的编程代理，客户端包括 iOS 应用、Android 应用、Web 应用（app.t3.codes）以及基于 Electron 的桌面应用（t3.codes）。README 明确列出它可配合你的订阅使用 Claude Code、Codex、Cursor、Grok Build、OpenCode 和 Google Antigravity，“如果它们已经在你电脑上配置好，T3 Code 就能控制它们”。

官方仓库地址为 ，默认分支为 main，根目录 LICENSE 为 MIT License（Copyright (c) 2026 T3 Tools Inc.）。

需要提前说明的是，README 的“Some notes”一节写明：项目还处在非常早期的阶段，会出现 bug；并且目前基本不接受贡献，小的修复可能会被考虑，大的功能不会。本文涉及的安装命令、配置项与流程均来自项目 README 与 docs 目录下的官方文档，未做任何实机验证。

2. 项目定位

从官方材料看，T3 Code 的定位不是替代某个代理 CLI，而是把多个已配置好的代理 CLI 统一到一个可远程访问的控制层。README 中专门用了一节自问自答“Wait, what are you selling me?”，答案是什么都不卖：作者称他们构建 T3 Code 是因为想要尽可能好的代理开发体验，曾受 Codex desktop app、Conductor、Claude Desktop 和 Cursor Glass 等已有方案启发，但没有一个达到他们的标准；他们想要的是高性能、支持远程、且真正开放的方案，并希望即使方向走错，用户也有足够的东西去 fork 并构建自己想要的编辑器。

架构文档进一步把这条边界写成硬约束：执行留在拥有工作区的那个环境里，Web、桌面、移动客户端通过认证的 RPC 控制它；远程客户端绝不能用自己的文件系统、提供方凭据或机器状态去替代环境的。桌面应用虽然内置了一个服务端，但其渲染进程遵循同一套边界。

因此可以这样理解：T3 Code 是一个“控制面”，而不是“执行面”。代理进程、终端、Git 和项目文件属于服务端，客户端负责展示与下发。

3. 核心功能

多端客户端与远程接入。客户端覆盖 iOS、Android、Web 与 Electron 桌面端。远程接入提供多条路径：T3 Connect（无需自行配置路由器转发）、局域网或私有网络直接配对、Tailscale HTTPS，以及桌面应用托管的 SSH 连接。托管 Web 应用 app.t3.codes 需要一个 HTTPS 端点才能连接。

多提供方接入与多实例。README 列出六个提供方；安装文档给出各自的安装与认证命令。在 Web 或桌面应用打开 Settings → Providers，选择环境后启用需要的提供方。文档说明可以为不同账号或配置新增另一个提供方实例，每个实例可有自己的环境变量，例如 API Key 或自定义 base URL，敏感值会被标记。

权限模式。消息输入区可选择权限模式，作用于该线程。四种模式为：Supervised（命令与文件改动都请求批准）、Auto-accept edits（自动批准文件编辑，其他操作仍可能请求批准）、Auto（使用提供方的自动审查批准常规操作）、Full access（命令与编辑不再提示批准）。新线程默认权限在 Settings → General → New threads → Permissions 设置，项目可以覆盖环境默认值；初始默认是 Full access。

快捷键与配置。在 Settings → Keybindings 中定制快捷键。配置存放在环境所在机器的 ~/.t3/userdata/keybindings.json，是一个规则数组，每条规则包含 key、command，可选的 when 表达式。文档说明当同一条快捷键的多条规则都匹配时，最后一条生效。

设置层级与项目覆盖。设置面包屑会显示改动作用到的环境与项目，起点是 All environments 与 All projects。客户端本地偏好始终显示并忽略该选择，其余设置存储在服务端。服务器行标题旁的层叠图标显示该值的来源是内置默认、环境还是项目覆盖；选中环境之间取值不一致时控件显示 Mixed。

源码托管集成。支持 GitHub、GitLab、Forgejo、Gitea、Bitbucket 与 Azure DevOps，用于克隆与发布仓库、创建拉取请求、评审改动。GitHub 还提供 stack 相关的合并与 rebase 操作。

后台服务与更新。Linux 与 macOS 上可以把 T3 Code 作为用户级服务常驻：t3 service install 安装并启动、t3 service status 查看状态与日志位置、t3 service restart 重启、t3 service uninstall 停止并移出开机启动。t3 update 下载新版本并把 t3 与服务切换到新版本。

检查点。架构文档说明检查点使用隐藏 Git 引用捕获工作区状态，不会向用户分支添加提交；回滚必须让工作区状态与提供方会话协同，无法回滚自身会话的提供方必须在改动文件系统之前拒绝该操作。

4. 技术或工作流程

架构文档给出了几条关键规则。第一，所有权边界清晰：提供方进程、终端、Git 与项目文件属于服务端；共享的连接与领域状态放在 packages/client-runtime；客户端只提供平台服务与 UI。RPC 契约位于 packages/contracts/src/rpc.ts，是独立升级的客户端与服务端之间的边界；订阅只下发客户端需要的状态，因此查看单个线程的客户端不必为所有线程的历史付出代价；socket 认证并不等于授权该连接调用所有方法。

第二，持久意图与副作用分离。事件日志是编排状态的唯一事实来源，引擎串行化命令，decider 只产生事件、不执行提供方或文件系统工作；事件、持久化投影和被接受的命令回执在同一数据库事务中提交，提交之后才变更内存状态并通知订阅者，从而使命令重试幂等。反应器在意图记录完成之后执行副作用，再把结果通过命令回传。因此一次命令确认只代表意图已提交，不代表提供方、检查点或其他后续工作已经完成。

第三，回合结束与后续工作落定是两个里程碑。投影器根据会话状态结算回合，迟到的检查点或 diff 不应延长已记录的回合时长。

第四，提供方差异被收敛到适配器之后，编排只处理归一化的命令与事件，因此新增提供方不应在领域层或客户端造成到处分支。

下面的流程只概括官方文档描述的边界关系，不包含未在来源中出现的处理环节。

把上述机制落到一次实际使用上，官方文档提供的主线是：在将运行代理的机器上安装并登录至少一个提供方 CLI；安装 t3 或桌面应用；运行 t3 启动服务并打开本地 Web 应用；在 Settings → Providers 选择环境并启用提供方；然后选择工作区、分支、模型与权限模式，发起线程。代理进程、终端与 Git 都在服务端机器上运行，客户端只是通过认证 RPC 下发命令并订阅状态。

5. 适用场景与落地建议

场景 1：代理跑在一台常驻机器上，从其他设备接入

场景 2：在同一台机器上区分工作与个人账号

场景 3：让服务在 Linux 或 macOS 上后台常驻

场景 4：把代理工作与源码托管流程衔接起来

6. 安装与运行要求

命令行安装提供脚本形式。macOS / Linux：

curl -fsSL https://t3.codes/install.sh | sh

Windows PowerShell：

irm https://t3.codes/install.ps1 | iex

安装脚本会把 t3 放到 ~/.local/bin；如果之后 shell 报 command not found，说明该目录还不在 PATH 中，安装器会打印需要添加的那一行。文档还说明可以用 T3CODE_CHANNEL=nightly 安装 nightly 通道，或用 T3CODE_VERSION 固定一个确切版本。

运行 t3 会启动服务并打开本地 Web 应用；t3 serve 只启动服务而不打开浏览器；t3 app 为当前目录打开一个新线程并在需要时添加该项目，但它要求桌面应用已在同一台机器上运行，独立服务端或 SSH 会话不满足条件。

只想试用一次而不安装，可以运行 npx t3@latest（需要 Node.js 来提供 npx）。

桌面应用可以从 GitHub Releases 下载，也可以通过包管理器安装：Windows 使用 winget install T3Tools.T3Code，macOS 使用 brew install --cask t3-code，Arch Linux 稳定版使用 yay -S t3code-bin、nightly 使用 yay -S t3code-nightly-bin。文档说明 AUR 打包维护在本仓库的 packaging/aur 下。

移动端从 App Store 或 Google Play 安装，手机连接的是另一台机器上的服务端，需要按远程访问文档通过 T3 Connect 或配对 URL 完成关联。

7. 环境、硬件或依赖

启动一个线程之前，需要至少安装并认证一个受支持的提供方，可以在启动 T3 Code 之后再配置提供方。各提供方的安装与登录方式为：Codex 安装 Codex CLI 后运行 codex login；Claude 安装 Claude Code 后运行 claude auth login；Cursor 安装 Cursor CLI 后运行 agent login；Grok Build 安装 Grok Build CLI 后运行 grok login；OpenCode 安装 OpenCode 后运行 opencode auth login；Antigravity 在设置中启用，并使用 Install Antigravity 与 Sign in with Google，不需要 CLI。

提供方 CLI 必须在服务端的 PATH 上；如果 T3 Code 找不到，可以在提供方设置里指定 Binary path，使用版本管理器时尤其需要注意。文档特别指出 Cursor 的可执行文件是 cursor-agent，尽管登录命令是 agent login；Antigravity 可以使用其托管运行时而不需要 PATH 条目。

Windows Subsystem for Linux 场景下，需要在 Settings → Connections 中选择一个 WSL 发行版来运行代理与项目，并在该发行版内安装提供方 CLI；T3 Code 会在其中自动安装自己的服务端运行时，应用更新后的首次启动可能更耗时。

Intel Mac 没有 t3 可执行文件（桌面应用可用）。若要在其上运行服务端，需要用 Node.js 24 与 vp 从源码构建：

git clone
cd t3code && vp i && vp run build:desktop
node apps/server/dist/bin.mjs

文档说明这种方式运行的服务器不适用 t3 update 和后台服务，需要通过 git pull 加重新构建来更新。

桌面应用托管的 SSH 连接要求远端主机是 Linux 或 Apple Silicon Mac，并具备 curl 或 wget、tar、sha256sum 或 shasum 以及提供方配置；首次启动会把 T3 Code 服务端下载到远端的 ~/.t3/runtime，因此比后续启动更慢。

在本次已采集的官方资料中未见明确说明：内存、CPU 或磁盘容量等硬件规格要求。

8. 已知限制

官方 README 直接写明项目非常早期、会出现 bug，并且目前基本不接受贡献：小的修复可能被考虑，大的功能不会被接受。CONTRIBUTING 文档补充说明，外部贡献者的 PR 会自动打上 vouch:* 信任状态与 size:* 体量标签，未被显式加入名单前预期为 vouch:unvouched；功能请求属于 Ideas 讨论区而非 issue。

文档站点尚未建立，完整文档位于仓库的 docs/ 目录中。

Windows 不支持后台服务。Intel Mac 没有 t3 可执行文件。t3 app 依赖桌面应用已在同一台机器上运行。远程访问要求承载代理的机器保持运行且可达。

权限模式的行为在提供方之间存在差异：Auto 模式在 Codex、Claude 和 Cursor 上使用自动审查，而 OpenCode 与 Antigravity 等没有等价能力的提供方会退回到询问；Antigravity 在 Full access 下仍可能发送原生批准请求。

更新方面，Settings → General → Continue threads after restarts 默认关闭，需要开启才能在更新、崩溃或机器重启后恢复受支持的活动线程；终端命令仍可能被中断，缺少已保存恢复状态的线程需要新消息。

许可方面，本次来源把该仓库的许可范围标注为待核验（非全仓统一授权）：根目录 LICENSE 为 MIT License，而仓库内部分子目录带有各自的 LICENSE 文件。本文不复述具体条款，也不推测这些条款对应的权利范围。

9. 青峰联创分析

从边界设计看，T3 Code 把“代理在哪台机器上跑”和“你从哪台设备看”拆开了：执行留在拥有工作区的环境，客户端只通过认证 RPC 下发命令并订阅状态。这样的划分使得多端接入时的语义相对清晰，凭据与项目文件也留在各自机器上。不过团队能否共用一台主机、如何划分多人权限，本次已采集的官方资料只描述了创建配对链接与撤销客户端会话这类主机侧管理动作，尚未覆盖更细的组织级权限模型。

从扩展成本看，架构文档把提供方差异收敛在适配器之后，编排只处理归一化命令与事件，并明确新增提供方不应在领域层或客户端造成分支。对希望长期维护一套自建控制面的团队来说，这可能降低后续接入新代理工具的改造成本；具体幅度取决于适配器接口的稳定性，本次来源未提供相关衡量数据。

从采用节奏看，README 自述项目处于非常早期阶段且贡献策略收紧，这两点共同意味着现在更适合作为试用与观察对象，而不是深度定制的基座。我们建议先用 npx t3@latest 做一次性试用，确认提供方与权限模式符合预期之后，再决定是否安装后台服务；在 Linux 上启用服务前，建议先确认 lingering 所需的权限是否可用。

我们建议在把 T3 Code 指向真实仓库之前，先按官方文档列出的示例命令核对一遍环境：提供方 CLI 是否在服务端 PATH 上、需要的托管方 CLI 版本是否满足、以及远程主机是否具备文档列出的基础命令。涉及分发或二次开发时，我们建议逐目录核对 LICENSE 文件，本次已采集来源未给出全仓统一的许可结论。

对于需要远程接入的场景，我们建议在首次配对完成后立即确认访问撤销路径是否可用（Settings → Connections 中撤销客户端会话，或在 T3 Connect 页面中 Deregister），并把配对链接与授权码按密码对待。

10. 信息来源

• 官方项目仓库《t3code》