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