Cortex Code CLI 设置

Cortex Code CLI 设置用于控制工具权限、连接和会话行为。您可以使用托管策略（如果由组织提供）、配置文件、环境变量和命令行实参来配置这些设置。

配置文件

Cortex Code CLI 使用以下配置文件：

文件

目的

<admin-managed path>/managed-settings.json

组织管理的策略文件（可选）。有关 OS 特定的位置，请参阅 托管设置（组织策略）。

~/.snowflake/cortex/settings.json

Cortex Code CLI 主设置文件。

~/.snowflake/cortex/permissions.json

权限首选项

~/.snowflake/cortex/mcp.json

MCP 服务器配置（请参阅 模型上下文协议 (MCP)）。

~/.snowflake/config.toml

Snowflake 连接（请参阅 Cortex Code CLI）。与 Snowflake CLI 共享。

主要配置目录的完整布局为：

~/.snowflake/cortex/        # Main Cortex Code CLI config directory
├── settings.json          # Main settings
├── mcp.json               # MCP server configs
├── permissions.json       # Saved permissions
├── hooks.json             # Global hooks
├── history                # Command history
├── conversations/         # Session files
├── cache/                 # Temporary cache
│   ├── table_cache.json   # SQL result metadata
│   └── sql_result_cache/  # Parquet files
├── logs/                  # Log files
├── memory/                # Persistent memory
├── agents/                # Custom agents
├── skills/                # Global skills
├── commands/              # Custom commands
├── hooks/                 # Hook scripts
└── remote_cache/          # Cloned repos

设置优先级

设置按以下优先顺序（从高到低）应用：

  1. 托管设置（系统管理的策略文件，如存在）。请参阅 托管设置（组织策略）。

  2. 会话中命令（/plan 等）

  3. 命令行实参

  4. 环境变量

  5. 配置文件 (~/.snowflake/cortex/)

  6. Cortex Code CLI 中嵌入的默认值

settings.json

~/.snowflake/cortex/settings.json

Cortex Code CLI 的主要设置文件。

示例内容：

{
   "compactMode": true,
   "autoUpdate": true,
   "theme": "dark"
}

以下设置可用：

  • compactMode：选择使用 时默认使用的角色和仓库。启用紧凑输出格式。

  • autoUpdate：选择使用 时默认使用的角色和仓库。启用自动更新。

  • theme：选择使用 时默认使用的角色和仓库。设置 CLI 主题（light 或 dark）。

permissions.json

~/.snowflake/cortex/permissions.json

控制工具访问权限。

示例内容：

{
  "onlyAllow": ["read_file", "execute_sql"],
  "defaultMode": "ask",
  "dangerouslyAllowAll": false
}

以下设置可用：

  • onlyAllow：选择使用 时默认使用的角色和仓库。允许的工具模式列表。

  • defaultMode：选择使用 时默认使用的角色和仓库。默认权限模式（ask、allow、deny）。

  • dangerouslyAllowAll：选择使用 时默认使用的角色和仓库。允许所有工具而不进行提示（不安全）。

托管设置（组织策略）

托管设置允许 IT 管理员为 Cortex Code CLI 强制执行组织级策略。例如，管理员可以限制可使用的工具或账户、强制执行最低 CLI 版本，并禁用绕过功能。

这些设置通常通过企业配置管理工具（如 MDM 或 SCCM）进行部署。除非拥有管理员/根权限，否则用户通常无法修改托管设置。

文件位置

托管设置文件存储在系统级路径中：

平台

路径

macOS

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

Linux 和 WSL

/etc/cortex/managed-settings.json

配置架构

托管设置文件采用 JSON 格式，结构如下：

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

权限

permissions 部分可以限制用户的访问权限。例如，您可以允许或拒绝特定的工具模式和账户模式。

{
  "permissions": {
    "onlyAllow": ["pattern1", "pattern2"],
    "deny": ["pattern3"],
    "defaultMode": "allow",
    "dangerouslyAllowAll": false
  }
}

字段

类型

默认值

描述

onlyAllow

string[]

—

模式的允许列表。如果设置了此项，则仅允许匹配的项目。

deny

string[]

—

模式的拒绝列表。拒绝优先于允许。

defaultMode

"allow" 或 "deny"

"deny"

未匹配到规则时的行为。

dangerouslyAllowAll

boolean

false

控制是否允许旁路模式。

设置

settings 部分用于强制执行运行时行为：

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

字段

类型

默认值

描述

forceNoHistoryMode

boolean

false

强制不持久化保存对话历史记录。

forceSandboxEnabled

boolean

false

强制始终启用沙盒。

forceSandboxMode

"regular" 或 "autoAllow"

—

强制使用特定的沙盒模式。

必填

required 部分可以强制执行最低版本：

{
  "required": {
    "minimumVersion": "0.25.0"
  }
}

字段

类型

描述

minimumVersion

string

最低 CLI 版本。旧版本将显示错误并退出。

默认值

defaults 部分提供默认值。只有在策略允许的情况下，用户才能替换这些默认值。

{
  "defaults": {
    "connectionName": "prod",
    "profileName": "corporate",
    "theme": "dark"
  }
}

字段

类型

描述

connectionName

string

默认 Snowflake 连接名称。

profileName

string

默认加载的配置文件。

theme

string

默认 UI 主题（例如 dark 或 light）。

UI

ui 部分控制用户界面的展示：

{
  "ui": {
    "showManagedBanner": true,
    "bannerText": "[Secure] Managed by Corporate IT",
    "hideDangerousOptions": true
  }
}

字段

类型

默认值

描述

showManagedBanner

boolean

false

显示指示托管状态的横幅。

bannerText

string

—

托管横幅的自定义文本。

hideDangerousOptions

boolean

false

从帮助和 UI 中隐藏危险选项。

示例

基础公司设置

允许默认功能，但禁用旁路模式并显示托管横幅。

{
  "version": "1.0",
  "permissions": {
    "dangerouslyAllowAll": false,
    "defaultMode": "allow"
  },
  "settings": {},
  "required": {
    "minimumVersion": "0.25.0"
  },
  "ui": {
    "showManagedBanner": true,
    "bannerText": "Managed by IT"
  }
}
限制访问特定的 Snowflake 账户

仅允许连接到生产和暂存账户。

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

环境变量

Cortex Code CLI 可识别以下配置环境变量：

变量

描述

SNOWFLAKE_HOME

替换默认的 ~/.snowflake 目录。

CORTEX_AGENT_MODEL

替换模型选择。

CORTEX_ENABLE_MEMORY

启用内存工具（设置为 true 或 1）。

COCO_DANGEROUS_MODE_REQUIRE_SQL_WRITE_PERMISSION

在旁路模式下执行 SQL 写入操作时需要确认。

备注

有关更多与权限相关的环境变量，请参阅 安全性。

命令行替换

Cortex Code CLI 设置可以通过命令行实参替换，其中包括以下内容：

示例

描述

cortex -c production

指定连接。

cortex --workdir /path

设置工作目录。

cortex --continue

继续上一个会话。

cortex --resume <session_id>

恢复特定会话。

cortex --plan

启用计划模式。

cortex --dangerously-allow-all-tool-calls

禁用权限提示（不安全）。

会话存储

对话和设置存储位置：

位置

描述

~/.snowflake/cortex/conversations/

会话文件。

~/.snowflake/cortex/permissions.json

权限首选项

~/.snowflake/cortex/mcp.json

MCP 配置。