Cube Sandbox

简体中文

English

简体中文

English

Appearance

数字助手 ​

数字助手（AgentHub）基于 Cube Sandbox 创建和管理 OpenClaw 助手，支持助手实例、存档、回档、创建分身、发布助手模板和操作流水。

预览版

当前数字助手能力是 Preview 版本，主要用于演示和早期试用。API、数据库 schema、部署参数和交互细节仍可能在后续版本中调整，生产环境使用前建议先在测试环境验证。

数字助手模板 ​

AgentHub 会基于 CubeSandbox 模板创建数字助手。部署前需要先制作数字助手模板（见下方命令），然后将自动生成的 tpl- 前缀模板 ID 写入 .env：

env
AGENTHUB_DS_OPENCLAW_TEMPLATE=<your-digital-assistant-template-id>

自定义模板必须使用和 wecom-ds-openclaw 相同的数字助手 / OpenClaw 镜像构建。该镜像需要包含 OpenClaw 运行时、supervisorctl 服务配置，以及 AgentHub 使用的端口：

  • OpenClaw Gateway UI：18789
  • 助手环境 UI：8080

默认模板基于 all-in-one OpenClaw 镜像制作，镜像体积较大。首次制作或重建模板时，需要预留充足的下载、解压、快照和分发空间；在常见演示环境中，模板制作时间约为 15 分钟，具体耗时取决于镜像缓存、磁盘性能和节点数量。部署前建议确认宿主机和 Cubelet 数据盘有足够可用空间，避免模板构建中途因为磁盘不足失败。

磁盘空间可以按以下方式粗略估算：

  • 单模板约 3 GB（rootfs 1G + memory 2G）。
  • 单 snapshot 约 2~3 GB（memory 必定 2G + rootfs 增量）。
  • 单运行实例主要是 reflink 增量，通常约几十 MB。
  • Docker 基础设施约 3.2 GB，属于固定开销。

因此，如果只保留 1 个模板、2 个 snapshot 和几个运行实例，建议至少预留约 12~15 GB 可用磁盘空间。

可以使用 cubemastercli tpl create-from-image 基于相同镜像构建或重建模板：

bash
OPENCLAW_IMAGE=cube-sandbox-image.tencentcloudcr.com/demo/aio-sandbox-envd-openclaw:latest

cubemastercli tpl create-from-image \
  --image "${OPENCLAW_IMAGE}" \
  --writable-layer-size 20Gi \
  --expose-port 18789 \
  --expose-port 8080 \
  --probe 18789 \
  --probe-path /

如果明确需要 DeepSeek 预置版本，可以在确认 tag digest 符合预期后使用 cube-sandbox-image.tencentcloudcr.com/demo/aio-sandbox-envd-openclaw-deepseek:latest。

该命令会输出构建任务和 template_id；需要等待模板构建完成后再使用 AgentHub。如果集群需要分发到指定节点，可以重复传入 --node <node-id-or-ip>，或在初始构建后执行已有的模板 redo 流程。

从模板创建 sandbox 后，可以在 sandbox 内验证镜像布局：

bash
supervisorctl status openclaw
curl -fsS http://127.0.0.1:18789/ >/dev/null

如果模板不存在、使用了不同镜像，或没有包含 OpenClaw 服务布局，创建数字助手时可能在 setup、restart、读取 token 或生成 gateway URL 阶段失败。

环境变量 ​

AgentHub 数据库 ​

CubeAPI 使用 MySQL 保存数字助手的元数据，包括助手实例、存档、模板和操作流水。配置方式如下：

bash
DATABASE_URL=mysql://cube:cube_pass@127.0.0.1:3306/cube_mvp

在 one-click 部署中，如果没有显式设置 DATABASE_URL，启动脚本会根据 CUBE_SANDBOX_MYSQL_* 自动拼接。

LLM API Key ​

创建数字助手前，请在 WebUI 的 AgentHub 设置 中填写 LLM API Key（以及 provider、Base URL、模型）。

未配置时无法创建或重新配置助手，页面会提示先完成设置。

配置完成后，CubeAPI 会自动把 key 注入 sandbox 内的 OpenClaw，并写入相关配置文件（如 auth-profiles.json），用于连接 LLM 服务。

凭证交付方式与模型命名空间 ​

凭证交付支持两种方式：

  • 凭证托管（推荐）：托管的只是 API Key。出站请求由 CubeEgress 仅对配置的 LLM Base URL 注入 Authorization 头，真实 Key 不进入沙箱，OpenClaw 配置里只保存一个占位 Key。
  • 环境变量注入（兼容旧版）：把真实 API Key 直接写入 OpenClaw 环境与配置，仅建议在未启用 CubeEgress 的环境使用。

无论哪种方式，模型 ID 注入 OpenClaw 时都会归一化为 {Provider}/{模型ID} 的命名空间：{Provider} 取自 AgentHub 设置中的 Provider，斜杠后的部分作为真实模型名发往上游。使用自定义上游时，请确保 Provider 与模型 ID 与上游一致，否则 OpenClaw 可能报 Unknown model。例如 Provider 为 openai-compatible、模型为 deepseek-v4-flash 时，OpenClaw 内部解析为 openai-compatible/deepseek-v4-flash，上游收到的模型名为 deepseek-v4-flash。

模板快路径 ​

如果从已发布的助手模板创建新助手，并且不需要重新绑定企业微信，CubeAPI 会使用模板快路径：新 sandbox 直接沿用模板快照里已有的 OpenClaw 配置，不会重新注入 LLM API Key。

安全建议 ​

  • 请妥善保管 LLM API Key，不要提交到 Git 仓库。
  • 请妥善保护数据库备份与访问权限（Key 保存在数据库中）。