Cortex Code CLI 沙盒¶

Cortex Code CLI 可以在沙盒内运行 shell 命令，以限制文件系统访问、网络访问和进程功能。沙盒增加了一层隔离，因此代理不会意外修改文件或访问项目外部的资源。

重要

对此功能的支持处于实验阶段，可能会发生变化。

平台支持¶

沙盒使用操作系统的内置隔离功能来限制命令。


平台	实现	依赖关系
macOS	``sandbox-exec``（内置）	`ripgrep`
Linux	`bubblewrap`	`bubblewrap`、`socat` 和 `ripgrep`
Windows	原生受限令牌	无

安装依赖项¶

macOS：选择使用时默认使用的角色和仓库。

brew install ripgrep

Debian/Ubuntu：

sudo apt-get install bubblewrap socat ripgrep

Fedora/RHEL：

sudo dnf install bubblewrap socat ripgrep

启用沙盒¶

使用 Cortex Code CLI 中的 /sandbox 斜杠命令：

/sandbox                          # Interactive selector
/sandbox runtime on               # Enable sandbox
/sandbox runtime off              # Disable sandbox
/sandbox runtime status           # Show sandbox status
/sandbox status                   # Show current sandbox status

您还可以在设置文件中启用沙盒。将 sandbox 对象添加到 ``~/.snowflake/cortex/settings.json``（用户级）或 ``.snowflake/cortex/settings.json``（项目级）：

{
  "sandbox": {
    "enabled": true
  }
}

默认权限模式为 "regular"。要使用自动允许模式，请显式设置 "mode": "autoAllow"。请参阅权限模式。

权限模式¶

沙盒有两种权限模式，用于控制命令的批准方式：


模式	设置值	行为
自动允许	`"autoAllow"`	可沙盒化的命令会自动运行，无需提示。无法沙盒化的命令（例如，需要网络访问非允许域的命令）将回退到正常权限流。
常规	`"regular"`	所有命令都会提示批准，即使在沙盒内运行也是如此。

通过 /sandbox 命令或在设置中设置模式：

/sandbox mode auto                # Set auto-allow mode
/sandbox mode regular             # Set regular mode

文件系统限制¶

沙盒控制命令可以读取和写入的路径。

默认行为¶

工作目录：始终允许读取和写入。
技能目录 (~/.snowflake/cortex/skills)：已允许。
上下文目录 (~/.snowflake/cortex/.ctx)：当 ctxAvailable 启用时允许。

受保护的路径（始终拒绝写入）¶

无论配置如何，以下路径始终受到保护：

Shell 配置文件：~/.bashrc、~/.bash_profile、~/.zshrc、~/.zprofile、~/.profile、~/.bash_login、~/.bash_logout
Git Hook：~/.git/hooks、.git/hooks
SSH 配置：~/.ssh/authorized_keys、~/.ssh/config
托管设置目录和文件：/Library/Application Support/Cortex/ (macOS)、/etc/cortex/ (Linux)、%ProgramData%\Cortex\ (Windows)

自定义文件系统规则¶

在设置中配置文件系统访问权限：

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowRead": [],
      "denyRead": ["/private/secrets"],
      "allowWrite": ["/tmp", "~/projects"],
      "denyWrite": ["/etc", "/var"]
    }
  }
}


设置	默认值	描述
`allowRead`	``[]``（允许全部）	沙盒可以读取的路径。空数组表示允许所有路径（`denyRead` 中的路径除外）。
`denyRead`	`[]`	沙盒无法读取的路径。优先于 `allowRead`。
`allowWrite`	``[]``（仅限工作目录）	沙盒可以写入的路径。
`denyWrite`	`[]`	沙盒无法写入的路径。优先于 `allowWrite`。

重要

拒绝规则始终优先于允许规则。如果路径与 allowWrite 和 denyWrite 都匹配，路径会被拒绝。

网络限制¶

沙盒可以限制命令可以通过网络访问哪些域。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["*.internal.company.com"],
      "allowLocalBinding": false
    }
  }
}


设置	默认值	描述
`allowedDomains`	``[]``（允许全部）	沙盒可以访问的域。空数组表示允许所有域（`deniedDomains` 中的域除外）。支持通配符 (`*.example.com`)。
`deniedDomains`	`[]`	沙盒无法访问的域。优先于 `allowedDomains`。支持通配符。
`allowLocalBinding`	`false`	沙盒命令是否可以绑定到本地端口。

非沙盒命令回退¶

某些命令可能与沙盒不兼容。allowUnsandboxedCommands 设置用于控制当命令无法在沙盒内运行时的处理方式。


设置	行为
``true``（默认）	代理可以请求在主机上运行命令。系统会提示您批准。
`false`	命令必须在沙盒内运行，或者被列入 `excludedCommands` 列表中。如果两者都不适用，则命令失败。

排除的命令¶

您可以指定应始终在沙盒外部的主机上运行的命令：

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": true,
    "excludedCommands": ["docker", "kubectl"]
  }
}

排除的命令绕过沙盒并遵循正常的权限流程。

设置参考¶

完整的 sandbox 设置对象：

{
  "sandbox": {
    "enabled": false,
    "mode": "regular",
    "allowUnsandboxedCommands": true,
    "excludedCommands": [],
    "permissions": {
      "allow": [],
      "deny": []
    },
    "network": {
      "allowedDomains": [],
      "deniedDomains": [],
      "allowLocalBinding": false
    },
    "filesystem": {
      "allowRead": [],
      "denyRead": [],
      "allowWrite": [],
      "denyWrite": []
    },
    "ctxAvailable": true
  }
}


设置	默认值	描述
`enabled`	`false`	启用或禁用沙盒。
`mode`	`"regular"`	权限模式：`"regular"` 或 `"autoAllow"`。
`allowUnsandboxedCommands`	`true`	当命令无法沙盒化时，允许回退到主机执行。
`excludedCommands`	`[]`	始终在沙盒外部的主机上运行的命令。
`permissions.allow`	`[]`	高级权限允许规则。支持 `WebFetch(domain:example.com)`、`Edit(path)`、`Read(path)`、`Bash(command)` 等模式。
`permissions.deny`	`[]`	高级权限拒绝规则。与 `permissions.allow` 相同的模式语法。优先于允许规则。
`network.allowedDomains`	`[]`	网域允许列表（空 = 全部允许）。支持通配符。
`network.deniedDomains`	`[]`	网域拒绝列表。优先于允许列表。
`network.allowLocalBinding`	`false`	允许沙盒命令绑定到本地端口。
`filesystem.allowRead`	`[]`	读取允许列表（空 = 允许除拒绝之外的所有项）。
`filesystem.denyRead`	`[]`	读取拒绝列表。优先。
`filesystem.allowWrite`	`[]`	写入允许列表。
`filesystem.denyWrite`	`[]`	写入拒绝列表。优先。
`ctxAvailable`	`true`	允许沙盒访问上下文目录 (`~/.snowflake/cortex/.ctx`)，用于存储对话上下文和会话数据。

配置范围¶

沙盒设置与其他 Cortex Code 设置具有相同的优先级：

**项目级**（最高优先级）：.snowflake/cortex/settings.json
用户级：~/.snowflake/cortex/settings.json
托管/强制执行：管理员可以通过托管设置文件强制执行沙盒策略。请参阅托管设置（组织策略）。