# 企业管理设置
了解 Copilot 客户端使用的企业管理设置架构。
使用此参考了解 `managed-settings.json` 中当前支持的密钥。
有关部署方法和支持的客户端，请参阅 [配置企业管理设置](/zh/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings)。
## 优先规则
当存在多个设置源时，此列表中的前面设置优先于列表中的设置：
1. 受 MDM 管理的设置
2. 由服务器管理的设置
3. 基于文件的配置
4. 用户级设置
例外的是，以下键在不同交付方式中按限制最严格的方向进行组合：
* `sandbox`
* `permissions.deny`、 `permissions.ask`和 `permissions.allow`
## 支持的密钥
## 将不同的设置应用于企业团队
对于服务器管理的部署，企业可以根据其企业团队成员身份将不同的治理应用于用户组。 企业定义所有设置 - 团队成员身份仅确定哪些用户会收到一组给定的值。
要使某个键符合团队特定值的条件，请使用 `{ "overridable": }` 语法在 `managed-settings.json` 中将其标记为可替代。 可替代的键使用设置后的团队值，或者在团队未设置时恢复为企业默认值。 语法`{ "overridable": }`适用于 `model`、、`permissions.disableBypassPermissionsMode`、`permissions.deny``permissions.ask`、 `permissions.allow``allowedMcpServers`和`deniedMcpServers`键。 未标记为可重写的密钥仍然是团队无法修改的企业级决策。
`enabledPlugins` 和 `extraKnownMarketplaces` 以累加方式起作用。 企业 `managed-settings.json` 设定了基准，而企业团队文件可以在此基础上添加更多插件和应用市场。 有关完整设置步骤，请参阅 [配置企业管理设置](/zh/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/configure-enterprise-managed-settings#overriding-settings-for-specific-teams)。
## 配置示例
以下示例在一个托管设置文件中显示这些密钥。
```json
{
"model": "auto",
"permissions": {
"disableBypassPermissionsMode": "disable",
"deny": [
"Shell(rm -rf *)",
"Read(~/.ssh/**)",
"Edit(//etc/**)",
"Domain(*.unapproved.example)"
],
"ask": [
"Shell(git push *)",
"Edit(/src/**)",
"Domain(api.github.com)"
],
"allow": [
"Shell(npm test *)",
"Read(/src/**)",
"Domain(registry.npmjs.org)"
]
},
"enabledPlugins": {
"my-plugin@agent-skills": true
},
"extraKnownMarketplaces": {
"agent-skills": {
"source": {
"source": "github",
"repo": "OWNER/REPO"
},
"autoUpdate": true
}
},
"strictKnownMarketplaces": [
{
"source": "github",
"repo": "OWNER/REPO"
}
],
"telemetry": {
"enabled": true,
"endpoint": "https://otel-collector.example.com",
"protocol": "http/protobuf",
"captureContent": false,
"lockCaptureContent": true,
"serviceName": "copilot",
"resourceAttributes": {
"deployment.environment": "production"
},
"headers": {
"Authorization": "Bearer TOKEN"
}
},
"remoteControl": {
"mode": "requireSSO",
"githubDotComOrganizations": ["ORG-NAME"]
},
"allowedMcpServers": [
{ "serverUrl": "https://api.githubcopilot.com/*" },
{ "serverCommand": ["npx", "@playwright/mcp@latest"] },
{ "serverCommand": ["cmd", "/c", "uvx", "markitdown-mcp"] }
],
"deniedMcpServers": [
{
"serverCommand": [
"npx",
"-y",
"@modelcontextprotocol/server-filesystem",
"/"
]
}
],
"sandbox": {
"enabled": true,
"allowBypass": false,
"sandboxMcpServers": true,
"sandboxLspServers": true
}
}
```
## enabledPlugins
定义为所有企业用户自动安装或禁止的插件。 每个条目使用格式 `PLUGIN-NAME@MARKETPLACE-NAME` 作为键，并带有布尔值： `true` 要求启用插件或 `false` 要求禁用插件。 请参阅“[关于企业管理的插件标准](/zh/copilot/concepts/agents/about-enterprise-plugin-standards)”。
## extraKnownMarketplaces
定义可供用户使用的其他插件市场。 每个条目都是一个命名的市场对象，其中包含一个 `source` 属性和一个可选的 `autoUpdate` 布尔值。
将 `autoUpdate` 设置为 `true`，以要求客户端定期刷新该市场并更新从该市场安装的插件。 将其设置为 `false`，以使该市场的自动更新保持禁用状态。 如果省略 `autoUpdate`，客户端将使用其现有的默认或用户配置行为。
由于托管设置优先，用户无法替代定义的 `autoUpdate` 值。 该设置仅适用于该市场，并且在刷新和更新操作之前，`strictKnownMarketplaces` 中的任何限制仍然适用。
支持以下源类型：
* `"github"` - 需要 `repo` 格式的 `OWNER/REPO`；可选的 `ref`（分支、标记或 SHA）和 `path`（子目录）
* `"git"` — 需要 `url`;可选 `ref` 和 `path`
* `"directory"` — 需要 `path`
请参阅“[关于企业管理的插件标准](/zh/copilot/concepts/agents/about-enterprise-plugin-standards)”。
## strictKnownMarketplaces
将插件安装限制为仅可从企业明确指定的应用市场进行安装。 空数组表示完全锁定。 每个条目都是一个市场对象，其中包含一个 `source` 指示源类型的属性。 支持以下源类型：
* `"github"` - 需要 `OWNER/REPO` 格式的 `repo`，可选 `ref` 和 `path`
* `"git"` — 需要 `url`;可选 `ref` 和 `path`
* `"url"` — 需要 `url`;可选 `headers` 对象
* `"npm"` — 需要 `package`
* `"file"` — 需要 `path`
* `"directory"` — 需要 `path`
* `"hostPattern"` - 需要 `hostPattern`（用于匹配市场主机的正则表达式）
* `"pathPattern"` - 需要 `pathPattern`（用于匹配市场路径的正则表达式）
## 模型
将自动模型选择设置为新对话的默认值。 请参阅“[关于 Copilotauto model selection](/zh/copilot/concepts/models/auto-model-selection)”。
* 如果设置为`model``"auto"`，则新会话将使用自动模型，除非用户为每个会话指定不同的模型。
* 企业团队映射可以替代此键。 在你的 `managed-settings.json` 中，使用 `{ "overridable": "auto" }` 语法按团队分别定制该密钥的配置。 然后，您可以在团队设置文件中设置 `"model": "unmanaged"`，为该主题团队的成员提供优先于 `managed-settings.json` 的特化配置。
> \[!NOTE]
> `model` 最初记录为 `permissions.model`. 客户端在缺少顶级`model`密钥时仍会读取嵌套`permissions.model`值，但应在新配置中使用顶级`model`密钥。
## 权限
### 拒绝、询问、允许
`permissions.deny`、`permissions.ask` 和 `permissions.allow` 键采用 **拒绝 > 询问 > 允许** 的优先级顺序。 如果 MDM 托管的、服务器托管的或基于文件的源定义了任何权限规则，或者任何适用的源声明了 `allow` 列表，则任何未匹配的受支持操作默认需要获得批准。 否则，它遵循普通的权限流。
* `deny`阻止特定操作，无论它们是否也与规则`ask``allow`匹配。 任何托管设置源设置的拒绝规则都会阻止所有用户的操作，而不考虑其他源中的规则。
* `ask` 需要重新获得一次性批准后，特定操作才能继续进行，即使该操作在其他情况下原本会被允许。 托管的 `ask` 规则不能通过绕过模式（也称为 allow-all 或 YOLO 模式）、自动审批设置、钩子或其他审批快捷方式，或先前审批中保留的授权来满足。 下次请求时，同一操作会再次提示。
* `allow` 允许特定操作在没有提示的情况下继续。 有效允许列表是声明一个而不是联合的所有源的交集。 不声明 `allow` 列表的源对此密钥没有限制。
规则使用以下选择器：
| Selector | Matches |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| `Shell(...)` | Shell 命令。 使用 ` *`（例如 `git push *`）来匹配命令前缀；否则，该规则匹配精确文本。 |
| `Bash(...)` 是 `Shell(...)` 的兼容别名。 | |
| `PowerShell(...)` 使用同一选择器系列，并采用命令不区分大小写的匹配方式。 | |
| `Read(...)` | 文件读取和查看路径。 支持 glob 模式和以下根路径：`//` 表示文件系统根目录，`/` 表示工作区根目录，`~/` 表示主目录，`./` 表示当前工作目录。 |
| `Edit(...)` | 文件写入和编辑路径，其匹配方式与 `Read(...)` 相同。 |
| `Write(...)` 是 `Edit(...)` 的别名。 | |
| `Domain(...)` | 网络源。 裸主机默认为 HTTPS，主机匹配不区分大小写。 使用 `*.` 以包含子域；例如，`*.example.com` 同时匹配 example.com 及其子域。 |
对于企业团队，每个子项都是可重写的。 将企业值设置为 `{ "overridable": }`，并用规则数组替换 ``。 然后使用常规语法在每个团队的文件中定义替换规则。
### 禁用绕过权限模式
阻止用户启用绕过模式（也称为“YOLO 模式”）。 绕过模式允许代理在不请求批准的情况下运行命令、访问文件和提取 URL。
当您将 `disableBypassPermissionsMode` 设置为 `"disable"` 时，用户无法启用绕过模式：
* 在Copilot CLI中，用于允许所有权限的所有命令行选项（`--yolo`、`--allow-all`以及单独的`--allow-all-tools`、`--allow-all-paths`和`--allow-all-urls`选项）都会在启动时被禁用，且无法授予更高权限。
`/yolo` 和 `/allow-all` 斜杠命令也被阻止了。
* 在中 VS Code，全局自动批准设置（`chat.tools.global.autoApprove`）已关闭，无法重新启用。
* 在 GitHub Copilot app 的会话设置中，“工具权限”的“允许所有”设置被禁用。
* 企业团队映射可以替代此键。 在你的 `managed-settings.json` 中，使用 `{ "overridable": "disable" }` 语法按团队分别定制该密钥的配置。 然后，您可以在团队设置文件中设置 `"disableBypassPermissionsMode": "unmanaged"`，为该主题团队的成员提供优先于 `managed-settings.json` 的特化配置。
## 遥测
配置 OpenTelemetry 导出，将使用情况数据路由 Copilot 到所选收集器。
Copilot CLI 和 VS Code 支持此属性。
设置 `telemetry` 属性时， Copilot 遥测数据将发送到指定的终结点。 支持以下子属性：
* `enabled`：设置为 `true` 打开遥测导出，或 `false` 将其关闭。
* `endpoint`：OTLP 收集器的 URL（例如 `https://otel-collector.example.com`）。
* `protocol`：用于遥测导出的传输协议。 接受的值是 `"http/json"` 和 `"http/protobuf"`。
* `captureContent`：设置为 `true` 时，在遥测有效负载中包含提示和响应内容；设置为 `false` 时，则不包含这些内容。
* `lockCaptureContent`：设置为 `true` 阻止用户更改 `captureContent` 设置。
* `serviceName`：遥测服务名称的标签（例如 `"copilot"`）。
* `resourceAttributes`：一个包含 OpenTelemetry 资源属性的对象，用于附加到所有导出的遥测数据（例如 `{"deployment.environment": "production"}`）。
* `headers`：要随附于每个遥测请求的 HTTP 头的对象（例如，适用于收集器的 `Authorization` 头）。
## 远程控制
限制设备上托管的 Copilot 会话是否可被远程控制。 这不会影响用户远程控制在其他设备上托管的会话的能力。
* `mode`：设置为 `"disabled"` 以防止对设备上的会话进行远程控制，设置为 `"requireSSO"` 以仅允许来自已获得 `githubDotComOrganizations` 中所列组织的 SSO 授权的客户端的远程控制，或设置为 `"enabled"` 以不受限制地允许远程控制。
* `githubDotComOrganizations`：由组织登录名组成的数组。 当 `mode` 是 `"requireSSO"` 时为必需项。
## 允许的MCP服务器
定义允许运行的 MCP 服务器的允许列表。 设置后，仅允许与至少一个条目匹配的服务器。 任何不匹配的服务器都将被阻止。
完全省略此键即可允许所有服务器，但仍受 `deniedMcpServers` 中任何条目的限制。 将其设置为空数组，以阻止除内置默认服务器之外的所有服务器。
当多个设置来源定义了 `allowedMcpServers` 时，生效的允许列表是所有来源的交集。 服务器必须获得每个源的许可才能运行。
每个条目必须恰好包含一个匹配器属性。
| 财产 | 匹配行为 | 适用的服务器 |
| --------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `serverName` | 与用户分配的服务器标签完全匹配。 不支持通配符。 由于服务器名称由用户自行选择，因此当您需要强制验证服务器身份时，请使用 `serverUrl` 或 `serverCommand`。 | 任意服务器。 内存中服务器只能使用 `serverName`。 |
| `serverUrl` | 匹配远程服务器的 URL。 支持 `*` 子域或路径前缀的通配符，例如或 `https://mcp.example.com/*``https://*.internal.example.com/*`。 | 通过 HTTP 或服务器发送事件（SSE）连接的远程服务器。 此属性不适用于本地服务器，即使它们具有 URL 也是如此。 |
| `serverCommand` | 匹配本地服务器的确切命令和每个参数，例如 `["npx", "-y", "my-mcp-server"]`。 不支持通配符和命令行扩展。 | 使用标准输入和输出的本地服务器（`stdio`）。 此属性不适用于远程服务器，即使它们具有命令也是如此。 |
对于企业团队，此键是可替代的。 在企业级将 `overridable` 下的匹配器对象包装起来，然后使用常规语法在每个团队的文件中定义允许列表和拒绝列表。
### URL 规范化
在将 `serverUrl` 模式与服务器 URL 进行比较之前，客户端会先将这两个值规范化：
* 将协议和主机名转换为小写。
* 将国际化域名或 Unicode 主机名转换为 Punycode。
* 删除 HTTP 的默认端口 `:80` 或 HTTPS 的默认端口 `:443`。
* 解码百分比编码的主机八进制数。 例如，`%65vil` 将变为 `evil`。
* 从 DNS 名称中删除 URL 片段和尾随点。
* 防止权限组件中的通配符跨越 `/` 边界匹配到路径中。
## deniedMcpServers
定义无条件阻止的 MCP 服务器。 与任何条目匹配的服务器会被阻止，即使它也与 `allowedMcpServers` 中的条目匹配也不例外。 拒绝规则始终优先于允许规则。
第一方 Copilot 服务器（如内置 GitHub MCP 服务器）不受拒绝规则的豁免，并且无法阻止。
当多个设置源定义 `deniedMcpServers` 时，有效的拒绝名单是所有源的并集。 被任何源阻止的服务器也会被所有源阻止。
每个条目都使用了 [`allowedMcpServers`](#allowedmcpservers) 中所述的相同 `serverName`、`serverUrl` 或 `serverCommand` 属性。
## `sandbox`
对 Copilot CLI 强制执行最小本地沙盒限制。 托管沙盒设置设置的是限制，而不是默认值：
* 对于强制启用设置，受管控值为 `true` 时会强制执行该设置。
`false` 或遗漏会使用户的配置保持不变。
* 对于功能项设置，受管理的值 `false` 会禁用该功能项。
`true` 或遗漏会使用户的配置保持不变。
* 受管理的读/写和只读路径列表会限制用户配置的授权，而受管理的拒绝路径则会增加到用户配置的拒绝项中。
支持以下子属性：
* `enabled`：`true` 要求使用沙盒，并阻止用户将其禁用。
* `allowBypass`： `false` 阻止模型请求单个命令在沙盒外部运行。
* `addCurrentWorkingDirectory`： `false` 防止 Copilot CLI 自动将当前工作目录添加到沙盒的读/写路径。
* `sandboxMcpServers`：`true` 要求由 Copilot CLI 启动的本地 MCP 服务器在沙盒中运行。 远程 MCP 服务器不会在本地沙盒中运行。
* `sandboxLspServers`：`true` 要求由 Copilot CLI 启动的语言服务器在沙盒中运行。
* `gitAuth`： `false` 防止 Copilot CLI 在沙盒中为经过身份验证的 Git HTTPS 操作注入 GitHub 令牌。
* `ghAuth`：`false` 可防止 Copilot CLI 在沙盒中为 GitHub CLI 注入 GitHub 令牌。
* `allowDevToolAccess`： `false` 防止自动访问开发工具配置、缓存、注册表和工具链。 这些位置中可能包含软件包注册表凭据或令牌。 禁用访问可能会导致程序包还原、需要身份验证的注册表操作或使用共享缓存的构建失败，除非你显式授予对所需路径的访问权限。
* `userPolicy`：配置文件系统、网络和 macOS 特定安全带限制的对象。 以下各节介绍了支持的属性。
### `sandbox.userPolicy.filesystem`
为沙盒进程配置文件系统访问。 路径应为绝对路径。 托管授权列表与用户配置的列表按精确的路径字符串进行匹配，而不是按父路径或子路径的覆盖关系进行匹配。
* `readwritePaths`：沙盒进程可以读取和写入的路径数组。 仅当用户配置的确切字符串也出现在指定此属性的每个托管源中时，用户配置的路径才可用。 空的托管数组会移除所有用户配置的读/写路径授权，但不会移除单独授予的访问权限，例如对临时目录或当前工作目录的访问权限。
* `readonlyPaths`：沙盒进程可以读取但不写入的路径数组。 仅当用户配置的确切字符串也出现在指定此属性的每个托管源中时，用户配置的路径才可用。 空的托管数组会移除所有用户配置的只读路径授权，但不会移除另行组装的访问权限。
* `deniedPaths`：沙盒进程无法访问的路径数组。 托管值会添加到用户现有的拒绝路径列表中，而不是替换它们。
### `sandbox.userPolicy.network`
为沙盒进程配置网络访问。
* `allowOutbound`： `false` 阻止出站网络访问。
* `allowLocalNetwork`： `false` 阻止访问本地网络。
网络行为因操作系统而异。 具体而言，代理不是完整的出口控制边界，因为某些应用程序可以忽略代理设置。
### `sandbox.userPolicy.seatbelt`
配置 macOS 特有的 Seatbelt 选项。
* `keychainAccess`： `false` 阻止沙盒进程访问 macOS 密钥链。