# 使用 Agent Skill 管理沙箱 `ucloud-sandbox` skill 可以让 Codex、Claude Code、Gemini CLI 等支持 skill 的 AI Agent 理解 UCloud Sandbox CLI。安装后，您可以直接用自然语言让 Agent 创建和管理沙箱、执行命令、传输文件，以及管理快照和模板，无需记忆完整的 CLI 参数。 该 skill 支持的常见操作包括： - 安装和配置 `ucloud-sandbox-cli` - 创建、查询、连接、暂停和终止沙箱 - 在沙箱内执行命令，查看端口访问地址和资源指标 - 浏览沙箱文件，以及在本地与沙箱之间上传或下载文件 - 创建和管理快照、构建和管理模板 > Skill 会指导 Agent 调用 UCloud Sandbox CLI，但不会替代 UCloud Sandbox 账号和 API Key。执行实际的沙箱操作前，仍需完成认证。 ## 前置准备 开始前，请确保本机已安装： - Node.js 和 `npx`，用于安装 skill - 一款支持 skill 的 AI Agent，例如 Codex、Claude Code 或 Gemini CLI ## 安装 skill 进入需要使用该 skill 的项目目录，执行： ```bash npx skills add ucloud/ucloud-sandbox-cli -s ucloud-sandbox ``` 根据命令行提示选择需要安装到的 Agent。安装完成后，重新启动 Agent 或新建一个会话，使其加载 `ucloud-sandbox` skill。 Skill 的源文件和最新说明可以在 [ucloud-sandbox-cli GitHub 仓库](https://github.com/ucloud/ucloud-sandbox-cli/tree/main/skills/ucloud-sandbox)中查看。 ## 配置认证 首次使用时，请在真实终端中执行交互式登录： ```bash ucloud-sandbox-cli login ``` API Key 可以从[星图平台密钥管理](https://astraflow.ucloud.cn/modelverse/api-keys)获取。也可以按照[前置条件与认证](/docs/agent-sandbox/product/prerequisites.md)中的说明，通过环境变量配置 API Key 和地域。 > 不要把 API Key 写进提示词、代码仓库或聊天记录。登录命令需要读取交互式输入，请在自己的终端中完成，不要让 Agent 代为输入或保存 API Key。 ## 提示词示例 安装完成后，可以直接向 Agent 描述目标。下面的提示词可以按需替换沙箱 ID、文件路径、端口和模板名称。 ### 检查环境 ```text 检查本机是否已安装最新版 ucloud-sandbox-cli，并确认当前配置的地域。不要输出 API Key。 ``` 如果尚未安装 CLI，Agent 会根据 skill 中的说明完成安装或给出适合当前系统的安装步骤。 ### 创建沙箱并执行命令 ```text 使用 base 模板创建一个超时时间为 1 小时的沙箱，在其中执行 python --version，然后把沙箱 ID 和执行结果告诉我。 ``` 也可以让 Agent 在已有沙箱内完成一组操作： ```text 连接沙箱 ，查看 /home/user 目录，并在沙箱中输出当前工作目录和磁盘使用情况。 ``` ### 上传和下载文件 ```text 把本地的 ./app.py 上传到沙箱 的 /home/user/app/app.py，然后在沙箱中运行它。 ``` ```text 把沙箱 中的 /home/user/app/output.csv 下载到本地 ./downloads/output.csv。 ``` ### 访问沙箱中的服务 ```text 在沙箱 中启动这个 Web 项目，监听 0.0.0.0:3000，确认服务正常后把外部访问地址告诉我。 ``` ### 查看运行状态 ```text 列出当前所有运行中的沙箱，并查看沙箱 最近 1 小时的 CPU 和内存指标。 ``` ### 使用快照复用环境 ```text 为沙箱 创建一个快照。创建成功后，使用这个快照启动一个新沙箱，并把新沙箱 ID 告诉我。 ``` ### 构建自定义模板 ```text 帮我初始化一个名为 python-data-env 的模板，使用 2 核 CPU 和 2048 MB 内存，并预装 pandas 和 requests。先向我展示构建配置，确认后再开始构建。 ``` ### 暂停或终止沙箱 ```text 暂停沙箱 ，完成后确认它的最新状态。 ``` 终止沙箱和删除文件、快照或模板属于破坏性操作。建议在提示词中要求 Agent 先核对目标： ```text 我想终止沙箱 。请先显示它的基本信息并等待我确认，不要立即执行终止操作。 ``` ## 使用建议 - 提示词中尽量给出明确的沙箱 ID、远端路径、端口和期望结果。 - 让 Agent 在操作完成后验证结果，例如检查进程、服务地址或文件是否存在。 - 读取 `.env`、配置文件等可能包含凭证的文件时，明确要求不要回显敏感信息。 - 执行终止沙箱、删除文件、删除快照或删除模板等操作前，先核对目标并确认影响范围。