T3 Connect 设置

T3 Connect 的部署与客户端（client）配置。架构说明解释信任边界；中继 README负责中继（relay）的置备说明。

公开的应用配置

全新克隆中，T3 Connect 是禁用的。要针对生产部署进行构建，请复制仓库根目录的示例：

cp .env.example .env

对于其他部署，请在仓库根目录的 .env 或 .env.local 中设置这些值：

dotenv

T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
T3CODE_RELAY_URL=https://relay.example.com

进程变量优先于 .env.local，其次是 .env。请使用这些规范名称；构建加载器会提供各框架专用的别名。这些值是公开标识符。CLERK_SECRET_KEY 只属于中继的密钥，绝不要放进客户端配置。

客户端构建和捆绑服务器构建会嵌入这些公开值，因此请在构建之前设好。EAS 的预览环境和生产环境（environment）需要可发布密钥、JWT 模板名称以及中继 URL。捆绑服务器也接受运行时覆盖，供由运营人员管理的部署使用。

将 infra/relay/.env.example 复制为 infra/relay/.env，作为中继的部署设置。请在个人阶段之前先部署 prod，因为它拥有这些分支所依赖的那份保留数据库。该技术栈的 PublishClientConfig 动作会把得到的中继 URL 写回根目录的 .env。

CLI 的 OAuth 应用

在 Clerk 的 OAuth 应用设置中：

为 T3 CLI 创建一个公开的 OAuth 应用，使用带 PKCE 的授权码交换。
允许重定向 URI http://127.0.0.1:34338/callback。
启用 openid、profile、email 和 offline_access 这些作用域。
在该应用上启用 Device authorization grant（设备授权授予）。无头授权和 SSH 授权都会使用它，而且只有启用之后，Clerk 才会通告设备端点。该功能处于 beta 阶段，Clerk 会应请求按账户启用。
在本地构建环境和发布构建环境中，将 T3CODE_CLERK_CLI_OAUTH_CLIENT_ID 设为生成的公开客户端 ID。

JWT 模板

创建一个名为 t3-relay 的 Clerk JWT 模板，声明如下：

json

{ "aud": "t3-code-relay" }

为客户端设置 T3CODE_CLERK_JWT_TEMPLATE=t3-relay，为中继设置 CLERK_JWT_AUDIENCE=t3-code-relay。生产中继的部署环境还会定义 CLERK_JWT_TEMPLATE。受众在各个中继阶段保持不变；由中继 URL 选定部署。

桌面端 OAuth 重定向

启用 Clerk 的 Native API，并把桌面端重定向加入其 SSO 重定向允许列表：

text

t3code-dev://app/
t3code://app/

把对应的源加入该 Clerk 实例 Backend API 的 allowed_origins 数组。开发环境使用 t3code-dev://app；生产环境使用 t3code://app。使用 Clerk 密钥，通过 PATCH https://api.clerk.com/v1/instance 更新该数组，并保留已有条目。Clerk 的 Electron 集成负责令牌持久化，以及系统浏览器回调的送达。

Clerk 的原生 Android SDK 使用 clerk://<applicationId>.callback。在由应用的可发布密钥所选定的 Clerk 实例中，把每个受支持的包加入 Native applications > Allowlist for mobile SSO redirect（原生应用 > 移动端 SSO 重定向允许列表）：

变体	回调
开发	`clerk://com.t3tools.t3code.dev.callback`
预览	`clerk://com.t3tools.t3code.preview.callback`
生产	`clerk://com.t3tools.t3code.callback`

保留已有条目。这些回调与 t3code-dev / t3code-preview / t3code 导航 scheme 彼此独立。使用生产 Clerk 密钥的私人开发构建，仍然需要该实例的管理员允许其开发回调；重新构建同一个包并不会改变允许列表。

桌面通行密钥

对于 bundle ID 为 com.t3tools.t3code 的生产 macOS 应用：

在 Apple Developer 门户中创建一个显式的 macOS App ID，并启用 Associated Domains（关联域名）。
为该 App ID 和分发签名证书创建描述文件。
在 Clerk 的 Native API 设置中，添加一个使用相同 Apple Team ID 和 bundle ID 的 iOS 应用。此设置也会配置 Electron/macOS 通行密钥。
检查 https://<frontend-api>/.well-known/apple-app-site-association。它的 webcredentials.apps 必须包含 <TEAM_ID>.com.t3tools.t3code。
按照发布操作手册中的说明配置签名。

本地的签名构建还要使用：

dotenv

T3CODE_APPLE_TEAM_ID=ABC1234567
T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
# Override only when the RP domain differs from the Clerk Frontend API hostname.
T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com

如果没有这项覆盖，构建会从 Clerk 的可发布密钥推导 RP 域。更改关联域名之后，请先提高构建版本，再重新构建。否则，macOS 可能会对同一对应用与版本复用过期的 Shared Web Credentials（共享 Web 凭据）元数据。

普通的 dev:desktop 启动器未经签名，无法用来试用 macOS 通行密钥。若要使用渲染进程 HMR，请安装一份签名构建，启动 vp run dev:web，再用实际的 Web 端口和服务器端口启动已安装的可执行文件。例如，使用默认端口：

VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
T3CODE_PORT=13773 \
  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"

原生依赖、主进程、preload、entitlement（授权项）、描述文件或签名发生变化之后，请重新构建这份签名应用。渲染进程的修改可以继续沿用它。测试之前，请先核对已安装的包：

codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"

限制注册

使用 Clerk 的允许列表来限定许可的电子邮件地址或域名，或使用 Restricted 模式做仅限邀请的注册。允许列表已启用但为空时，会阻止所有新注册。

注册限制不会撤销已有账户的访问权限。若必须禁用其活动会话以及今后的登录，请在 Clerk 中封禁该账户。

T3 Connect 设置 ​

公开的应用配置 ​

CLI 的 OAuth 应用 ​

JWT 模板 ​

桌面端 OAuth 重定向 ​

Android 原生登录重定向 ​

桌面通行密钥 ​

限制注册 ​