# 沙箱 沙箱（Sandbox）为智能体生成的指令提供**隔离且受限的执行空间**。通过严格的权限管控，确保命令在安全隔离的环境内运行，有效阻断对未经授权资源（文件、网络等）的访问或者高风险命令（权限修改等）。对于被拦截的命令，智能体会在对话流中发出风险提示，经由用户二次确认后，命令才会在沙箱外被执行。 #### 约束与限制 表1约束与操作限制 | 限制类别 | 具体说明 | |:---|:---| | 操作系统 | - Windows操作系统：**推荐使用** **Windows 11 (x64)**；如果使用Windows 10 (x64)，系统版本需为2019年及以上，建议升级至最新稳定版本。 - macOS操作系统：macOS 11及以上版本，兼容ARM64（Apple Silicon）架构。 - Linux：Huawei Cloud EulerOS 2.0、SUSE Linux Enterprise Server 12 SP5、Ubuntu 18.04/20.04/22.04/24.04 LTS、Debian 10/11/12、CentOS 8、RHEL 8/9。 | #### 文件访问控制 启用沙箱后，码道CLI对文件目录的访问权限配置如下。您也可以根据实际业务需求，自定义码道CLI对文件目录的访问权限，详细介绍请参见[启用沙箱]。 表2文件访问控制 | 操作系统 | 权限类型 | 目录类型 | 目录列表 | |:---|:---|:---|:---| | Windows | 只读 | - | 除**Windows系统关键目录** 及**用户敏感目录**外，其余所有目录均开放读权限。 | | Windows | 读写 | 工作空间和额外设置的读写目录 | - 临时目录：C:\\Windows\\Temp - 缓存目录：%APPDATA%，%LOCALAPPDATA%，%TMP%，%TEMP% - 常用语言的工具链及其依赖目录 - %USERPROFILE%\\go - %USERPROFILE%\\.m2\\repository（Maven缓存） - %USERPROFILE%\\.gradle（Gradle缓存） - %USERPROFILE%\\AppData\\Local\\Programs\\Python（全局第三方包） - %USERPROFILE%\\AppData\\Roaming\\Python\\（用户级包） - %USERPROFILE%\\AppData\\Roaming\\npm\\（全局npm包） - %USERPROFILE%\\AppData\\Local\\npm-cache\\（npm缓存） - %USERPROFILE%\\.cargo\\（crate索引和缓存） - %USERPROFILE%\\.gem\\（Gem缓存） | | Windows | 不可读不可写 | Windows系统关键目录 | - C:\\Windows\\System32\\config - C:\\Windows\\System32\\drivers\\etc - C:\\Windows\\SysWOW64\\config - C:\\ProgramData\\Microsoft\\Crypto - C:\\Windows\\System32\\GroupPolicy - C:\\Windows\\System32\\GroupPolicyUsers - C:\\ProgramData\\Microsoft\\Windows\\WER | | Windows | 不可读不可写 | 用户敏感目录 | - C:\\Users\\\*\\AppData\\Local\\Microsoft\\Credentials - C:\\Users\\\*\\AppData\\Roaming\\Microsoft\\Credentials - C:\\Users\\\*\\AppData\\Local\\Microsoft\\Protect - C:\\Users\\\*\\NTUSER.DAT - C:\\Users\\\*\\ntuser.dat.LOG | | macOS | 只读 | - | 除**系统敏感目录**外，其余所有目录均开放读权限。 | | macOS | 读写 | 工作空间和额外设置的读写目录 | - 临时目录：/tmp、/var/folders、TMPDIR环境变量路径 - 缓存目录：\~/Library/Caches、\~/.cache - 通用工具依赖目录：\~/.local/lib、\~/.local/bin、\~/.local/share - 常用开发语言的工具链及其依赖目录 - $HOME/go/（编译缓存/二进制目录） - $HOME/.m2/repository/（Maven本地仓库） - $HOME/.gradle/（Gradle缓存） - $HOME/.local/lib/pythonX.X/site-packages/（用户级包） - $HOME/Library/Caches/pip/（pip缓存） - $HOME/.npm/（用户级npm包） - $HOME/Library/Caches/npm（npm缓存） - $HOME/.cargo/（crate索引和缓存） - $HOME/.gem/ruby/（用户级gem） | | macOS | 不可读不可写 | 文档/桌面/下载（隐私） | - \~/Desktop - \~/Documents - \~/Downloads - \~/Pictures - \~/Movies - \~/.ssh - \~/.zsh_history | | macOS | 不可读不可写 | 密码/钱包/钥匙链相关 | \~/Library/Keychains | | macOS | 不可读不可写 | 系统级敏感配置 | - /etc/passwd - /private/etc/passwd - /etc/group - /private/etc/group - /etc/hosts - /private/etc/hosts - /etc/resolv.conf - /private/etc/resolv.conf - /etc/pam.d - /private/etc/pam.d | | Linux | 只读 | - | 除**系统敏感目录**外，其余所有目录均开放读权限。 | | Linux | 读写 | 工作空间和额外设置的读写目录 | - 临时目录：/tmp、TMPDIR环境变量路径 - 缓存目录：\~/.cache、XDG_CACHE_HOME环境变量路径 - 通用工具依赖目录：\~/.local/lib、\~/.local/bin、\~/.local/share - 常用开发语言的工具链及其依赖目录 - $HOME/go/（编译缓存/二进制目录） - $HOME/.m2/repository/（Maven本地仓库） - $HOME/.gradle/（Gradle缓存） - $HOME/.local/lib/pythonX.X/site-packages/（用户级包） - $HOME/.npm/（用户级npm包） - $HOME/Library/Caches/npm（npm缓存） - $HOME/.cargo/（crate索引和缓存） - $HOME/.gem/ruby/（用户级gem） | | Linux | 不可读不可写 | Linux系统关键目录 | - /etc/shadow - /etc/passwd - /etc/group - /etc/gshadow - /etc/resolv.conf - /etc/sudoers | #### 启用沙箱 下面以在TUI开发环境中启用沙箱为例。在CLI开发环境中，请直接执行"codearts run "输入的指令" --sandbox"命令即可。 1. 进入TUI开发环境。 1. 打开目标项目的根目录。 2. 鼠标右键单击空白处，选择"在终端中打开"。 3. 在终端中输入"codearts"并回车，即可进入TUI开发环境。 2. 启用沙箱运行模式。 1. 在TUI对话框中，输入"/run-mode"并回车，进入"选择运行模式"页面。 2. 单击"Sandbox沙箱"，进入"沙箱配置"页面。 图1选择SandBox沙箱 ![](https://support.huaweicloud.com/usermanual-cli/zh-cn_image_0000002640932526.png "点击放大") 3. 配置命令白名单。 根据实际需求将特定命令的前缀添加到白名单。被加入白名单的命令将绕过沙箱机制，直接在沙箱外执行。 4. 选择网络访问策略。 表3网络访问策略说明 | 参数 | 说明 | |:---|:---| | 全网访问 | 允许访问所有内部及外部网络资源。 | | 本地网络访问 | 仅允许访问本地服务网络（局域网/内网），禁止通过TCP协议访问外部互联网。 | | 禁止网络访问 | 阻断所有通过TCP协议建立的网络连接，禁止访问任何内部或外部资源。 | | 网络自定义访问 | 通过修改策略配置Json文件，自定义当前项目沙箱环境中进程的文件与网络访问范围。具体操作，请参见[5]。 | 5. 自定义网络访问策略。 1. 在"网络访问策略"中，选择"网络自定义访问"，单击"确认"，进入"自定义策略"页面。 2. 在策略配置Json文件中，根据您的需求修改配置。 该文件的初始结构如下所示： ``` { "filesystem": { "readWrite": [], "readOnly": [] }, "network": { "default": "Allow", "allow": [], "deny": [] }, "resources": { "cpu": 50, "memory": 8 } } ``` 表4策略配置Json文件参数说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | filesystem | 否 | [filesystem] Object | 用于精确控制沙箱对本地文件系统的访问权限。 如果未设置（filesystem字段为空或不存在），则采用沙箱内置的文件系统安全策略。 | | network | 否 | [network] Object | 用于控制沙箱内进程的网络访问策略，支持配置允许或阻止对特定网络资源的访问。 如果未设置，默认允许网络访问 | | resources | 否 | [resources] Object | 用于定义沙箱运行时的计算资源上限，确保业务稳定并防止资源滥用。 如果未设置，系统将共享宿主机资源。 | 表5filesystem字段参数说明 | 参数 | 参数类型 | 默认值 | **支持路径格式** | **优先级规则** | 描述 | |:---|:---|:---|:---|:---|:---| | readWrite | Array | \[ \] | - 绝对路径：如/home/user/project、C:\\Projects - 相对路径：如./src、./config - 环境变量：$HOME（Linux/Mac)、%USERPROFILE%（Windows） - Home目录简写：\~ | readOnly \> readWrite \> 系统默认策略 如果某个路径同时匹配readOnly和readWrite，则以readOnly为准。 | 可读写路径列表。 | | readOnly | Array | \[ \] | - 绝对路径：如/home/user/project、C:\\Projects - 相对路径：如./src、./config - 环境变量：$HOME（Linux/Mac)、%USERPROFILE%（Windows） - Home目录简写：\~ | readOnly \> readWrite \> 系统默认策略 如果某个路径同时匹配readOnly和readWrite，则以readOnly为准。 | 只读路径列表。 | 表6network字段参数说明 | 参数 | 参数类型 | 默认值 | **优先级规则** | 描述 | |:---|:---|:---|:---|:---| | default | String | Allow | deny \> allow \> default 如果allow和deny同时配置同一规则时，则以deny为准。 | 默认的网络访问策略。 - Allow：允许访问 - Deny：禁止访问 说明： 该字段支持"域名:端口"和"IP:端口"两种配置格式，其中域名部分支持通配符，IP地址支持CIDR表示法。多个端口可通过逗号分隔进行配置。若未指定具体端口，则默认对所有端口生效。 | | allow | Array | \[ \] | deny \> allow \> default 如果allow和deny同时配置同一规则时，则以deny为准。 | 允许访问的网络规则列表。 | | deny | Array | \[ \] | deny \> allow \> default 如果allow和deny同时配置同一规则时，则以deny为准。 | 拒绝访问的网络规则列表。 | 表7resources字段参数说明 | 参数 | 参数类型 | 默认值 | 最小值 | 描述 | |:---|:---|:---|:---|:---| | cpu | Integer | 50 | 20 | CPU占比，单位为%。 | | memory | Integer | 8 | 1 | 内存大小，单位为GB。 | 策略配置Json文件配置示例如下： ``` { "filesystem": { "readWrite": [ "/home/user/project/output", "~/workspace/temp" ], "readOnly": [ "/etc/systemd", "%USERPROFILE%/.ssh" ] }, "network": { "default": "Allow", "deny": [ "10.0.0.0/8", "192.168.0.0/16" ] }, "resources": { "cpu": 50, "memory": 8 } } ``` 3. 单击"确认"，退出当前设置界面，完成沙箱模式的启用。 #### 高风险命令执行策略 当智能体检测到高风险命令时，AI将会在对话流中发出提示（**TUI开发环境会弹框是否被拦截，CLI开发环境直接被拦截**）。请评估风险后，按需选择执行方式。 - Allow once，仅允许本次执行，下次遇到相同命令会再次询问。 - Allow always，本次会话中，此类命令将不再询问，直接执行。 - Reject，不执行此命令，继续对话。适合您认为有风险或不必要的操作。 ![](https://support.huaweicloud.com/usermanual-cli/public_sys-resources/note_3.0-zh-cn.png) 如果需要关闭沙箱功能，请参考[关闭沙箱模式]。 图2高危命令被拦截示例 ![](https://support.huaweicloud.com/usermanual-cli/zh-cn_image_0000002670896259.png "点击放大") #### 关闭沙箱模式 以在TUI开发环境中关闭沙箱为例。在CLI开发环境中，请直接执行"codearts run "输入的指令" --auto"命令即可。 1. 进入TUI开发环境。 1. 打开目标项目的根目录。 2. 鼠标右键单击空白处，选择"在终端中打开"。 3. 在终端中输入"codearts"并回车，即可进入TUI开发环境。 2. 关闭沙箱运行模式。 关闭沙箱模式就是将运行模式设置为手动或者自动。 1. 在TUI对话框中，输入"/run-mode"并回车，进入"选择运行模式"页面。 2. 在"Auto 自动"或"Manual 手动"上，单击Enter键，即可退出沙箱运行模式。 - **Auto 自动** ：智能体直接执行所有命令，无需征得您的同意。 **为了确保安全，建议只在必要时启用"自动运行"模式。此模式会绕过所有安全检查，可能在未经提醒的情况下执行高风险操作。** - **Manual 手动** ：智能体执行任何命令前，都会向用户发送确认提示，用户需手动确认后，命令才会继续执行。 图3切换沙箱运行模式 ![](https://support.huaweicloud.com/usermanual-cli/zh-cn_image_0000002673719411.png "点击放大")