托管设置（组织策略）

托管设置允许 IT 管理员在整个组织范围内强制执行 Cortex Code CLI 行为。设置将部署到系统文件中，用户无法修改。这些设置的优先级高于所有用户级配置。

当存在托管设置时，CLI 在启动时会显示一个横幅，指示其正在托管模式下运行。

托管设置的工作原理

托管设置读取自放置在特定平台系统目录下的 JSON 文件，该位置需要管理员权限或 Root 权限才能写入。由于用户无法修改这些位置中的文件，因此用户配置文件、环境变量或命令行参数（除非另有明确说明）均无法覆盖托管设置。

管理员通常使用 MDM 工具（Jamf、Intune、SCCM）、配置管理系统（Ansible、Chef、Puppet）或在设备初始化期间手动部署该托管设置文件。

文件位置

请将 managed-settings.json 文件放置在对应操作系统的以下系统目录中：

平台

路径

macOS

/Library/Application Support/Cortex/managed-settings.json

Linux 和 WSL

/etc/cortex/managed-settings.json

Windows

%ProgramData%\Cortex\managed-settings.json

如果该文件不存在，则 CLI 在非托管模式下运行，所有用户级默认值均适用。

备注

如果文件存在但包含无效的 JSON 或未通过模式验证，CLI 将应用限制性的回退配置，并显示“Enforcement config error - restricted mode”横幅。这可以防止由于策略文件格式错误而导致静默授予无限制访问权限。

配置架构

managed-settings.json 文件必须包含 version 字段。所有顶级部分都是可选的。

{
  "version": "1.0",
  "permissions": { },
  "settings":    { },
  "required":    { },
  "defaults":    { },
  "files":       { },
  "ui":          { }
}

version 字段必须为 "1.0"。

permissions

控制 CLI 可以使用哪些工具、技能、MCP 服务器和 Snowflake 账户。有关完整的模式语法，请参阅 权限模式。

{
  "permissions": {
    "onlyAllow": ["read", "write", "bash(git:*)", "skill(bundled:*)"],
    "deny": ["bash(rm:*)", "skill(remote:*)"],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  }
}

字段

类型

默认值

描述

onlyAllow

string[]

—

权限模式的允许列表。如果设置了此项，则仅允许匹配的项目。除非 defaultMode 为 "allow"，否则未被任何模式匹配的项目将被阻止。

deny

string[]

—

权限模式的拒绝列表。拒绝优先于允许。无论 onlyAllow 如何设置，此处匹配的项目将始终被阻止。

defaultMode

"allow" 或 "deny"

"allow"

无模式匹配时的行为。使用 "deny" 可实现严格的允许列表态势。

dangerouslyAllowAll

boolean

false

控制用户是否可以使用 --dangerously-allow-all-tool-calls 标志。在托管模式下，默认值为 false。仅在明确信任的环境中设置为 true。

settings

强制执行特定的运行时行为，用户无法对其进行覆盖。

{
  "settings": {
    "forceNoHistoryMode": true,
    "forceSandboxEnabled": true,
    "forceSandboxMode": "regular"
  }
}

字段

类型

默认值

描述

forceNoHistoryMode

boolean

false

当设为 true 时，将禁用所有对话历史记录持久化存储。会话文件不会写入磁盘。适用于不得存储聊天历史记录的高安全性或合规性环境。

forceSandboxEnabled

boolean

false

当设为 true 时，无论用户设置如何，系统都会强制启用沙盒。沙盒会在工具执行期间限制文件系统访问。

forceSandboxMode

"regular" 或 "autoAllow"

—

强制使用特定的沙盒模式。"regular" 会在允许新的文件系统路径之前提示用户；"autoAllow" 会静默允许沙盒边界内的所有路径。仅在启用沙盒时生效。

沙盒限制了 CLI 在会话期间可以读写的目录。在工具访问预先批准集合以外的路径前，系统会增加确认步骤。"regular" 模式要求用户对每个新目录进行确认；"autoAllow" 模式则会默认信任工作树中的所有目录而不进行提示。沙盒是一项实验性功能。有关详细信息，请参阅 沙盒。

required

强制执行最低 CLI 版本。如果安装的版本不符合要求，CLI 将退出并报错。

{
  "required": {
    "minimumVersion": "0.26.0"
  }
}

字段

类型

描述

minimumVersion

string

语义化版本格式的最低 CLI 版本（例如 "0.26.0"）。使用旧版本的用户将看到错误，提示他们更新后才能继续。

使用此字段确保所有用户使用的版本均支持您的策略所依赖的安全修复或功能。

defaults

设置组织推荐的默认值，用户可以在自己的 settings.json 中替换这些值。与 settings 部分不同，这些只是建议而非强制执行。

{
  "defaults": {
    "connectionName": "prod",
    "profileName": "data-analyst",
    "theme": "dark"
  }
}

字段

类型

描述

connectionName

string

来自 connections.toml 的默认 Snowflake 连接名称。用户可以通过 -c 或更改自己的设置来替换此项。

profileName

string

启动时加载的默认配置文件。

theme

"dark"、"light" 或 "pro"

默认 UI 颜色主题。

files

将 CLI 指向管理员提供的配置文件。这些文件将作为用户个人配置的补充进行加载，或者直接替换用户配置。

{
  "files": {
    "connectionsFile": "/etc/cortex/connections.toml",
    "mcpFile": "/etc/cortex/mcp.json"
  }
}

字段

类型

描述

connectionsFile

string

管理员提供的 connections.toml 的绝对路径。使用此项可为所有用户预配置 Snowflake 连接，无需个人手动设置。

mcpFile

string

管理员提供的 mcp.json 的绝对路径。使用此项可向所有用户部署经组织批准的 MCP 服务器。

ui

自定义 UI 元素以指示托管状态。

{
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by Acme IT - support: helpdesk@acme.com",
    "hideDangerousOptions": true
  }
}

字段

类型

默认值

描述

showManagedBanner

boolean

false

当设为 true 时，在欢迎屏幕上显示横幅，指示这是一个托管安装环境。帮助用户理解某些功能可能受限的原因。

bannerText

string

"This device is managed by your organization"

托管横幅的自定义文本。使用此项包含支持联系信息或策略参考。

hideDangerousOptions

boolean

false

当设为 true 时，系统会在帮助输出和 UI 菜单中隐藏危险选项。

权限模式

permissions 部分中的 onlyAllow 和 deny 数组接受两种形式的模式：

  • 简单名称：精确匹配命名的工具或功能类别。例如，"bash" 或 "read"。

  • 筛选名称：type(filter)。这会匹配某个类别中的特定工具调用或资源。例如，"bash(git:*)" 或 "account(myorg-prod)"。

两种形式均支持 ``*``（任意字符）和 ``?``（单个字符）的 Glob 通配符。匹配不区分大小写。

模式参考

模式

控制内容

"read"

``read``（文件读取）工具

"write"

``write``（文件写入）工具

"edit"

``edit``（文件编辑）工具

"bash"

所有 Bash Shell 调用

"bash(git:*)"

限制为仅使用 git 命令的 Bash

"bash(dbt:*)"

限制为仅使用 dbt 命令的 Bash

"bash(ls:*)"

限制为仅使用 ls 命令的 Bash

"bash(rm:*)"

Bash rm 命令（通常被拒绝）

"snowflake_sql_execute"

针对 Snowflake 执行的 SQL

"mcp(*)"

所有 MCP 服务器

"mcp(https://*.company.com/*)"

匹配 URL Glob 的 MCP 服务器

"skill(bundled:*)"

内置（捆绑）技能

"skill(profile:*)"

来自任何已加载配置文件的技能

"skill(profile:my-profile)"

来自特定命名配置文件的技能

"skill(user:*)"

安装在用户主目录下的技能

"skill(project:*)"

项目 .cortex/skills/ 目录下的技能

"skill(remote:*)"

远程安装的技能（通过 Git 或 Tarball）

"plugin(*)"

所有插件

"plugin(bundled:*)"

仅限内置插件

"account(myorg)"

确切的 Snowflake 账户名称

"account(myorg-*)"

匹配 Glob 的 Snowflake 账户

bash(command:*) 筛选

使用 Bash 筛选模式时，筛选器会匹配 Shell 命令的第一个令牌。例如，"bash(git:*)" 允许 git status、git commit 及任何其他 git 子命令，但会阻止 curl、python 及任何其他命令。

备注

如果 onlyAllow 中出现了 "bash"``（且不带任何筛选器），则该规则允许执行任何 Bash 命令。如果出现了 ``"bash(git:*)" 但没有普通的 "bash"，则仅允许执行 git 命令，所有其他 Bash 命令都将被阻止。

权限评估

当 CLI 决定是否允许使用工具、技能、MCP 服务器或 Snowflake 账户时，它会按顺序评估以下规则：

  1. 托管 ``deny`` 匹配：阻止。 如果托管设置 deny 数组中的任意模式匹配，则会拒绝访问。此设置无法被配置文件或用户设置覆盖。

  2. 配置文件 ``deny`` 匹配：阻止。 如果当前配置文件的拒绝列表中有任何模式匹配，则会拒绝访问。

  3. 已设置托管 ``onlyAllow`` 且无模式匹配：阻止。 如果托管设置中配置了 onlyAllow，且该项不匹配任何列出的模式，则会拒绝访问。

  4. 已为该类型设置配置文件 ``onlyAllow`` 且无模式匹配：阻止。 配置文件 onlyAllow 具有类型作用域：它仅限制被显式列出的类型。如果配置文件列出了 skill(bundled:*) 但未提及 bash，则 Bash 访问不受该配置文件的影响。

  5. ``defaultMode`` 决定结果。 如果 defaultMode 为 "deny"，则访问被阻止。如果为 ``"allow"``（默认值），则允许访问。

关键保证：

  • 配置文件无法授予已被托管设置明确拒绝的权限。

  • 配置文件无法扩展托管设置的允许列表。

  • 配置文件只能进一步收紧限制：它们只能在托管设置定义的边界内生效。

常见策略示例

基础公司设置

允许所有默认工具，但阻止绕过模式并显示托管横幅。

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  },
  "required": {
    "minimumVersion": "0.26.0"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by Corporate IT - helpdesk@example.com"
  }
}

限制为已批准的 Snowflake 账户

仅允许连接到特定账户。尝试连接到任何其他账户的用户将看到错误提示。

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "account(mycompany-prod)",
      "account(mycompany-staging)"
    ],
    "defaultMode": "allow"
  }
}

仅限使用已批准的工具

仅允许文件读取、SQL 执行和捆绑技能。阻止所有 Bash、MCP 及用户自行安装的技能。

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "read",
      "write",
      "edit",
      "snowflake_sql_execute",
      "skill(bundled:*)",
      "skill(profile:*)"
    ],
    "defaultMode": "deny"
  }
}

允许使用 Bash 但阻止危险命令

允许访问 Bash，但明确禁止使用 rm、curl 和 wget。

{
  "version": "1.0",
  "permissions": {
    "deny": [
      "bash(rm:*)",
      "bash(curl:*)",
      "bash(wget:*)"
    ],
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  }
}

高安全性部署

强制不保留历史记录、强制启用沙盒、阻止绕过模式、限制为特定账户和 MCP 服务器，并阻止远程技能安装。

{
  "version": "1.0",
  "permissions": {
    "onlyAllow": [
      "read", "write", "edit", "bash", "snowflake_sql_execute",
      "skill(bundled:*)", "skill(profile:*)",
      "mcp(https://*.mycompany.com/*)",
      "account(mycompany-*)"
    ],
    "deny": [
      "bash(rm:*)",
      "bash(curl:*)",
      "skill(remote:*)"
    ],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  },
  "settings": {
    "forceNoHistoryMode": true,
    "forceSandboxEnabled": true,
    "forceSandboxMode": "regular"
  },
  "required": {
    "minimumVersion": "0.26.0"
  },
  "files": {
    "connectionsFile": "/etc/cortex/connections.toml",
    "mcpFile": "/etc/cortex/mcp.json"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by IT Security - policy questions: security@mycompany.com",
    "hideDangerousOptions": true
  }
}

验证

要确认托管设置已生效并查看已应用的限制，请检查启动时的欢迎横幅。当存在托管设置且 showManagedBanner 为 true 时，会话输出的顶部将显示横幅。

要检查您平台的强制执行配置路径，请验证文件是否存在于 文件位置 中列出的 OS 特定路径下。