OpenShell CLI（openshell）是管理 OpenShell 平台的主要命令行界面，覆盖沙箱、提供商、策略、设置、暴露服务以及网关注册等对象。网关服务本身的生命周期由软件包、systemd 或 Helm 在 CLI 之外处理。本技能用于指导智能体编排常见与复杂的 CLI 工作流。
用途与定位 该 CLI 面向需要以命令行方式操作 OpenShell 沙箱平台的用户与智能体。配套技能 generate-sandbox-policy 负责编写或修改沙箱策略 YAML 内容（网络规则、L7 检查、访问预设）；本技能则覆盖策略生命周期的 CLI 命令。CLI 内置完整帮助，遇到未覆盖的命令或选项时，可逐层查看帮助树：openshell --help、openshell <group> --help、openshell <group> <cmd> --help，帮助输出是权威且始终最新的主要回退手段。
前置条件 openshell 需在 PATH 中，未安装时按已发布的安装指南操作；需要可访问的 OpenShell 网关，其后端可为 Docker、Podman、Kubernetes 或实验性 VM 驱动；仅在使用 BYOC 本地构建或 Docker 后端网关时需要 Docker 运行；Kubernetes 部署需要 kubectl 与 Helm 访问目标集群。
主要能力
- 网关管理：注册网关（如 openshell gateway add http://127.0.0.1:8080 --local --name local），http:// 端点仅用于可信本地端口转发或受保护的私有路径，位于认证反向代理后的网关应注册其 HTTPS 端点。使用 openshell status 与 openshell whoami 验证连通性与身份，可加 --output json 便于自动化。
- 沙箱生命周期：openshell sandbox create 创建沙箱，默认主进程为 /bin/bash -l 并附加终端；--detach 在就绪后返回；显式尾随命令以前台方式运行并流式输出；退出码 0 使保留沙箱处于 Completed，非零则处于 Error 并标记 MainProcessFailed；--no-keep 在输出排空后删除，--detach --no-keep 组合用于无主机附加的服务。--name 需使用可移植的 DNS-1123 标签（最多 63 个字符，小写字母数字或 -，首尾为字母数字）。提供商附加是显式的，需用 --provider 指定；若指定提供商不存在但存在同 ID 的配置文件，CLI 可从本地凭证创建。创建选项还包括 --policy、--upload、--label、--gpu、--cpu、--memory、--driver-config-json、--template 等。
- 提供商管理：提供商向沙箱提供凭证与特定配置。提供商配置文件为仅导入式，网关只提供操作员导入的内容，新网关目录为空；--type 精确匹配配置文件 ID，不应依赖硬编码类型列表或旧别名。可用 openshell profile list 发现可用配置文件。创建方式包括 --from-existing（从本地状态发现凭证）、显式凭证（如 --credential OPENAI_API_KEY，裸 KEY 从同名环境变量读取以避免写入 shell 历史）、--from-gcloud-adc、--runtime-credentials。支持 --label KEY=VALUE 标签与 --label-selector 选择器，标签创建后不可更改或删除。配置文件操作包括 describe、export、lint、import，--url 接受单个 HTTP/HTTPS 的 YAML 或 JSON 配置文件（路径须以 .yaml、.yml 或 .json 结尾，下载限制 1 MiB 与 15 秒）。
- 凭证刷新：仅在提供商配置文件与网关支持可刷新凭证时使用。命令包括 provider refresh status/configure/rotate。优先使用 --secret-material-env 传递秘密刷新材料。网关通过活动凭证驱动存储秘密材料；选择 Vault 时刷新令牌等存放于 Vault，刷新状态仅含不透明句柄。OAuth 刷新失败时查看 RECOVERY 与 FAILURE_CODE 列，不要从 HTTP 状态推断补救措施。
适用场景 适用于首次接入网关并运行沙箱、管理提供商凭证与配置文件、配置凭证刷新、以及沙箱创建与清理等常见与多步工作流。
限制与注意事项 网关服务生命周期不由 CLI 管理；提供商配置文件为仅导入式；标签不可修改；--name 受 DNS-1123 约束；静态提供商凭证仅对配置文件声明的 host、port、path 生效；无配置文件的静态提供商会失败关闭；请求出现 request_authority_mismatch 时需核对 HTTP authority 与 CONNECT 隧道端点的主机和有效端口；出现 CONFIG_OPERATION_STORAGE_UNCERTAIN 时不要盲目重试变更；升级或更换凭证后端前需重新配置受影响的授权，不要对同一刷新记录运行混合网关版本。