托管策略

托管策略让管理员为同一台机器上的每一位用户配置 T3 Code。它为各项设置指定默认值与锁定，并施加限制，例如允许使用的最宽权限模式（permission mode），或哪些提供方（provider）可以运行。机器上的 T3 Code 服务器会对每一个接入的应用强制执行该策略：桌面应用、浏览器或移动应用。

推出策略

以 JSON 编写策略，可从示例开始。
运行 t3 policy check policy.json。它会打印该策略将产生的效果，或指出其中的问题。
用你的设备管理工具把策略部署到每一台机器，放在受支持的位置之一。
重启该机器上的 T3 Code。服务器只在启动时读取策略。
在该机器上运行 t3 policy show，以检查服务器加载的内容。

桌面应用包含 t3 命令（command）；参见 t3 命令。

编写策略

json

{
  "schemaVersion": 1,
  "organization": "Example Corp",
  "supportUrl": "https://it.example.com/t3",
  "settings": {
    "defaultRuntimeMode": { "value": "approval-required", "locked": false },
    "enableAgentBrowserAccess": { "value": false, "locked": true }
  },
  "limits": {
    "maxRuntimeMode": "auto-accept-edits",
    "clients": ["desktop", "local-browser"],
    "telemetry": false
  }
}

schemaVersion 和 organization 为必填项。用户会在「设置」中，以及策略所锁定的每一个控件旁边看到组织名称；如果你设置了 supportUrl，旁边还会带有指向它的链接。settings 用于设置默认值与锁定，limits 用于限制 T3 Code 可以执行的操作。

这台机器上的每一位用户都能读取该策略，因此不要在其中放入凭据。

策略的存放位置

每台机器选用下面其中一种：

操作系统	原生策略	策略文件
macOS	用于 `com.t3tools.t3code` 的配置描述文件	`/Library/Application Support/T3Code/policy.json`
Windows	组策略模板，或一个 `Policy` JSON 值（二者都位于 `HKLM\SOFTWARE\Policies\T3Tools\T3Code` 下）	`C:\Program Files\T3Code\policy.json`
Linux		`/etc/t3code/policy.json`

T3 Code 不会合并多个来源。如果一台机器同时存在原生策略和策略文件，T3 Code 会拒绝启动，直到你去掉其中一个。

策略文件。 把 JSON 复制到对应操作系统的路径。将该文件及其所在文件夹设为仅管理员可写。

macOS 配置描述文件。 为偏好域 com.t3tools.t3code 添加一个自定义设置负载。负载的键就是策略的顶层键（schemaVersion、organization、supportUrl、settings、limits）；JSON 对象会变成字典，列表会变成数组。要从一份已经检查过的策略文件生成负载，请运行 plutil -convert xml1 -o com.t3tools.t3code.plist policy.json 并上传结果，或运行 t3 policy templates <directory> --policy policy.json 以写出完整的 macos/t3code.mobileconfig。请将其安装为设备描述文件，因为 T3 Code 会忽略用户描述文件，并且该域只部署一份描述文件。描述文件无法容纳 null，因此如果某项设置的值必须是 null，请改用策略文件。

Windows 组策略。 运行 t3 policy templates <directory>，并把 windows/t3code.admx 和 windows/en-US/t3code.adml 复制到你的 PolicyDefinitions 文件夹或中央存储，也可以把它们导入 Intune。这些策略位于「计算机配置 > 管理模板 > T3 Code」之下。只要设置了任何其他 T3 Code 策略，就要同时设置 Organization。锁定项和提供方（provider）字段放在两个 JSON 策略中，对象与策略文件里的相同。机器会在下一次组策略刷新时取得变更；运行 gpupdate /target:computer /force 可立即应用，然后重启 T3 Code。将 Allow T3 Connect、Allow webhook tasks、Allow importing browser cookies 或 Allow usage data 设为 Disabled，会关闭对应功能。将任何其他 T3 Code 策略设为 Disabled 不会施加任何限制，效果与 Not Configured 相同。

Windows 注册表值。 也可以不用模板，而通过组策略首选项或 Intune 脚本，把 Policy 值（REG_SZ）设为整份策略的单行 JSON。T3 Code 通过 Windows 注册表 API 读取该值，因此在 reg.exe 这类注册表工具对用户被阻止的环境中仍然有效。二者只能选用一个：当该键同时包含 Policy 值和模板中的设置时，T3 Code 会拒绝启动。在 PowerShell 中以管理员身份运行：

powershell

$json = (Get-Content -Raw -Encoding UTF8 policy.json) -replace '\r?\n\s*', ''
New-Item -Path HKLM:\SOFTWARE\Policies\T3Tools\T3Code -Force | Out-Null
Set-ItemProperty -Path HKLM:\SOFTWARE\Policies\T3Tools\T3Code -Name Policy -Value $json -Type String

检查服务器加载的内容

以运行 T3 Code 的用户身份运行 t3 policy show。它会打印已安装的策略及其指纹，并说明正在运行的服务器加载的是这份策略还是更早的一份。服务器只在启动时读取策略，因此如果输出 “Restart T3 Code to apply the installed policy”，就表示它仍在强制执行旧策略。在「设置」中，用户会看到你的组织正在管理该环境（environment），每一个被锁定的控件都会显示 由组织管理。

更改或移除策略

部署、更改或移除策略之后，重启机器上的 T3 Code 服务器：退出并重新打开桌面应用，或针对后台服务（background service）运行 t3 service restart。重新连接手机或浏览器并不会重新加载策略。

要移除策略，请删除该文件、移除描述文件、把组策略设置改回 Not Configured，或删除注册表值，然后重启服务器。用户会恢复自己原先选择的设置，因为 T3 Code 从不会把策略中的值写入这些设置。

T3 Code 拒绝启动时

T3 Code 会拒绝启动，而不会在无法完整强制执行策略的情况下继续运行。这类情况包括：策略无法读取或解析、出现它不认识的设置、值的类型不正确、本版本不支持的键，或同一台机器上同时存在原生策略和策略文件。错误信息会指出策略来自何处，以及具体错在哪里。

t3 policy check 能在 JSON 文件中发现同样的问题。对于描述文件或注册表值，请在转换之前先检查 JSON。对于组策略模板，先检查一份包含相同设置的完整策略文件，再把它的 settings 和 limits.providers.instances 对象粘贴到两个 JSON 策略中。为较新版本编写的策略可能使用较旧版本无法强制执行的键，因此请先升级 T3 Code，再部署使用这些键的策略。

设置

settings 下的每个键，都是某项设置在服务器 settings.json 中的路径，例如 storageCleanup.logsAfterDays。要找到路径，请在 T3 Code 中更改该项设置，然后查看 settings.json 里 ~/.t3/userdata 下的内容。

"locked": false 设置默认值。它作用于用户尚未自行选择值的地方，用户可以更改它。
"locked": true 设定该值。用户和智能体都不能更改它，无论在「设置」中还是在项目（project）的设置中都不行，「设置」会把该控件显示为由你的组织管理。移除策略后，会恢复用户自己的值。

有几项设置需要特别留意：

默认值不能新增条目，例如提供方实例（provider instance），因为用户将永远无法移除它。请改为锁定该条目，或通过 providers.instances 设置提供方字段。
可以为空的设置（例如 defaultModelSelection）是作为整体托管的。不能只托管其中的某一个字段。
defaultRuntimeMode 不能宽于 maxRuntimeMode。
项目也可以设置 worktreeCleanup，它会覆盖 storageCleanup 中的 worktree 规则。请把它与这些规则一起锁定；只锁定规则的策略会被 T3 Code 拒绝。
observability 不能被托管。它的 OTLP 端点来自每位用户的环境变量、设置文件和桌面应用的启动输入，策略无法覆盖这些来源。
请托管 idleCompaction，不要托管较旧的 compactIdleThreads。Claude 实例自己的空闲压缩选择仍然优先于 idleCompaction。
提供方实例的各个字段会互相覆盖，因此请把 providerInstances.<id> 作为整体锁定，或通过 providers.instances 固定单个字段。T3 Code 会拒绝锁定实例内部的某一个字段。整实例锁定只覆盖该实例；要覆盖某个提供方的每一个实例，请使用 providers.instances。

限制

limits 限制 T3 Code 可以执行的操作。省略某个键，即保留 T3 Code 的正常行为。

json

{
  "schemaVersion": 1,
  "organization": "Example Corp",
  "limits": {
    "maxRuntimeMode": "auto-accept-edits",
    "clients": ["desktop"],
    "connect": false,
    "webhookTasks": false,
    "browserCookieImport": false,
    "telemetry": false,
    "providers": {
      "allowedDrivers": ["claudeAgent", "codex"],
      "instances": {
        "claudeAgent": {
          "locked": true,
          "environment": [{ "name": "CLAUDE_CODE_USE_BEDROCK", "value": "1" }]
        }
      }
    },
    "updates": { "mode": "auto", "feedUrl": "https://updates.example.com/t3code/" }
  }
}

权限模式

maxRuntimeMode 是任何对话线程（thread）可以使用的最宽权限模式：approval-required（监督，Supervised）、auto-accept-edits、auto 或 full-access。它覆盖用户启动的对话线程、智能体启动的对话线程，以及计划任务启动的对话线程。已经超出该限制的对话线程，在有人降低其模式之前不能再运行下一个回合（turn）；一旦降低，其排队中的消息就会发出。当用户的默认值宽于该限制时，新的对话线程会以该限制作为起始模式。

设置了 maxRuntimeMode 之后，每个提供方的启动设置由你掌握：二进制路径、启动参数、配置主目录，以及为每个提供方设置的环境变量。它们来自 providers.instances 或 T3 Code 的默认值，用户不能更改，否则包装脚本、启动标志，或 NODE_OPTIONS 这样的变量，都可能关闭该提供方的审批。请在 providers.instances 中固定用户需要的变量，例如网关 URL。

启动 T3 Code 本身的那个环境中的变量，仍然会传到各个提供方；claude 这样的默认二进制路径，会在该环境的 PATH 上查找。桌面应用会根据用户可控的设置来构建该环境，例如用户的 shell 配置，因此用户可以把自己的 claude 放到 PATH 中更靠前的位置。请在 providers.instances 中，为你允许的每个提供方固定一个绝对的 binaryPath。

在 maxRuntimeMode 之下，ACP 智能体自己的模式菜单不起作用，Antigravity 除外，T3 Code 可以把 Antigravity 的模式置于该限制之下。用户仍然可以选择运行哪个 ACP Registry 智能体；若要禁止这一点，请不要把 acpRegistry 列入 allowedDrivers。

该限制决定 T3 Code 向提供方请求哪些模式。它并不是沙箱；参见策略不覆盖的范围。

客户端与 T3 Connect

clients 列出服务器可以怎样运行：

desktop：作为桌面应用自带的服务器。
local-browser：作为只有本机浏览器能够访问的服务器，例如 npx t3。
remote：可通过网络从手机、其他计算机以及 app.t3.codes 访问。

remote 是真正要紧的一项。可从网络访问的服务器也会接受本机上的浏览器，两种本地形态的差别只在于 T3 Code 是如何启动的。在装有桌面应用的机器上，请把 desktop 留在列表中，否则该应用无法启动。

没有 remote 时，服务器只在环回地址上监听，不会创建配对链接，并会把此前已配对的设备退出登录。如果主机不是环回地址或 localhost，它不会启动。在 T3CODE_LAN 出现之前安装的后台服务仍保留私有网络访问，因此没有 remote 时它会拒绝启动。当其 service.env 没有设置 T3CODE_HOST 时，请运行 t3 up --no-lan；或者在 service.env 中设置 T3CODE_HOST=127.0.0.1，然后运行 t3 service restart。无论用户原先如何选择，桌面应用都会以开启网络访问、关闭 Tailscale Serve 的方式启动。这也会关闭 T3 Connect。若要保留其他远程访问、只关闭 T3 Connect，请设置 "connect": false。

服务器启动时，还会关闭每一条转发到它自身的 Tailscale Serve 路由（HTTPS 或 TCP），例如由 t3 pair --tailscale 设置的那一条，其余路由则保持不变。只要这样的路由仍处于开启状态，或无法读取 Tailscale 的应答，服务器就不会启动；错误信息会给出关闭该路由的命令。目标是名称的路由也会阻止它启动，例如 localhost，或同一端口上的另一台机器，因为名称可能解析到这台服务器；请更改该路由或 T3 Code 的端口。如果已安装 Tailscale 但没有应答（例如在从未设置过的 Mac 上），则必须先设置或移除 Tailscale，服务器才会启动。当 Tailscale 未安装、未在运行或已登出时，服务器可以启动，因为此时没有任何转发；Tailscale 保留的路由会在 Tailscale 再次运行时恢复，因此请在那之后重启 T3 Code。

其他能力

webhookTasks: false：计划任务不能使用 Webhook 触发器。已有的 Webhook 任务会保留，但不会运行，也不能重新开启。用户仍然可以编辑或删除它们。
browserCookieImport: false：用户不能把其他浏览器中的 Cookie 导入 T3 Code 的浏览器。
telemetry: false：服务器和桌面应用不会发送产品使用数据或中继（relay）连接追踪。策略无法把它们打开。打开该服务器的浏览器（例如 app.t3.codes）仍会发送自己的中继追踪。

提供方

providers.allowedDrivers 按 ID 列出可以运行的提供方（provider）：codex（Codex）、claudeAgent（Claude）、cursor（Cursor）、grok（Grok）、opencode（OpenCode）、antigravity（Antigravity）、fx（fx）、kiro（Kiro）、pi（Pi）、muse（Muse Code）以及 acpRegistry（ACP Registry）。t3 policy check 会拒绝本版本不认识的 ID。其他提供方上的对话线程会保留，并标记为不可用，用户仍然可以关闭这些提供方。

providers.instances 会为某个提供方的每一个实例设置字段，例如把 Claude 经 Amazon Bedrock 路由的环境变量，或公司网关的基址 URL。binaryPath 和 launchArgs 只对具备这些设置的提供方有效。使用 "locked": true 时，用户不能更改你设置的字段。使用 "locked": false 时，这些字段只填补用户留空的部分。被锁定的 codex 条目，或 maxRuntimeMode 下的任何 codex 条目，也会排除通过 ChatGPT 连接，因为那种运行时会跳过你的字段。同样，这样的 opencode 条目会排除服务器 URL，因此 OpenCode 会启动你所设置的二进制文件。

更新

mode：auto 保持正常的更新流程。off 会阻止 T3 Code 检查更新，适用于通过设备管理获取 T3 Code 的机器。
feedUrl：T3 Code 从你自己的镜像更新，而不是从 GitHub 更新：包括桌面应用、t3 update，以及从另一台设备发起的更新。只发布你已批准的版本，布局与 GitHub Release 相同。该发布版的更新文件（latest.yml、latest-mac.yml、latest-linux.yml、latest-linux-arm64.yml，以及在你允许夜间构建时它们的 nightly 版本）和这些文件列出的桌面安装包，放在该 URL 的根路径。该发布版的 t3-* 归档和 SHA256SUMS 放在 v<version>/ 之下。通过 npx 运行的 t3 来自 npm，因此请用你的包管理工具把它固定下来。
allowNightly: false：夜间构建频道不可用。

策略不覆盖的范围

策略控制的是 T3 Code 的行为。智能体通过各个提供方（provider）自己的 CLI 运行，这些 CLI 会读取自己的配置（例如 ~/.claude），用户也可以在 T3 Code 之外运行它们。要限制这些 CLI，请使用它们自己的托管配置，例如 Claude Code 的托管设置。

在受托管的 Windows 机器上，桌面应用不会运行 WSL 环境（environment）。用户在 WSL 内启动的 T3 Code 服务器，读取的是该发行版中的 /etc/t3code/policy.json，而不是 Windows 策略。如果用户会在 WSL 中运行 T3 Code，请把策略文件也部署到那里。

没有 remote 时，T3 Code 不会把服务器暴露出去，但用户仍可以用其他工具转发它的本地端口。

拥有该机器管理员权限的用户可以编辑或移除策略。T3 Code 在自己的进程中强制执行策略，而这些进程以该用户身份运行，因此它能阻止用户在 T3 Code 内更改受托管的设置，但不能阻止修改或替换 T3 Code 本身的用户。托管策略出现之前的版本也会忽略该策略。要控制哪些构建可以运行，请使用设备管理工具的应用程序控制。

托管策略 ​

推出策略 ​

编写策略 ​

策略的存放位置 ​

检查服务器加载的内容 ​

更改或移除策略 ​

T3 Code 拒绝启动时 ​

设置 ​

限制 ​

权限模式 ​

客户端与 T3 Connect ​

其他能力 ​

提供方 ​

更新 ​

策略不覆盖的范围 ​