使用AgentSphere智能体沙箱部署OpenClaw

准备OpenClaw基础镜像

OpenClaw官方提供了基础Docker镜像，自定义镜像将以此为基础进行构建。

1. 在本地或构建服务器上执行以下命令，拉取OpenClaw最新镜像。

   docker pull ghcr.io/openclaw/openclaw:latest

2. 验证镜像拉取成功。

   docker images | grep openclaw

   回显结果中能看到ghcr.io/openclaw/openclaw且TAG为latest，说明镜像拉取成功。

准备OpenClaw配置文件

OpenClaw启动时需要读取openclaw.json配置文件，用于定义Agent工作空间、消息渠道等运行参数。

1. 创建openclaw.json文件，最简化配置如下：

   {
     "agents": {
       "defaults": {
         "workspace": "~/.openclaw/workspace"
       }
     },
     "channels": {
       "whatsapp": {
         "allowFrom": ["+155xxxxx"]
       }
     }
   }

   配置参数说明：

   参数	说明	示例值
   agents.defaults.workspace	Agent工作空间目录路径，用于存储Agent运行时产生的文件和数据。	~/.openclaw/workspace
   channels.whatsapp.allowFrom	允许通过WhatsApp渠道发起对话的手机号码列表。请替换为实际需要授权的号码。	["+155xxxxx"]

2. 如需配置大模型对话能力，请在配置文件中补充模型相关参数。

   详细配置方法请参考OpenClaw官方文档：https://docs.openclaw.ai/gateway/configuration

编译ENVD二进制

ENVD需要作为容器内的常驻进程运行，因此需要先编译ENVD二进制文件，再集成到自定义镜像中。

前提条件：已安装Go语言编译环境，版本建议1.21+。

1. 拉取ENVD代码。

   git clone git@github.com:e2b-dev/infra.git 

2. 进入envd目录，根据目标镜像的CPU架构构建二进制。

   cd packages/envd
   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o envd main.go 

   如果需要构建ARM64架构的镜像，请将其中的GOARCH=amd64改为GOARCH=arm64。

3. 验证编译结果。执行目录下应生成envd二进制文件。

   ls -la envd

编写健康检查脚本

ENVD启动后需要一定时间完成初始化。健康检查脚本通过轮询ENVD的状态接口，确保ENVD完全就绪后再启动业务应用，避免后续操作因ENVD未就绪而失败。

创建envd-healthcheck.sh文件，内容如下：

#!/bin/bash
# Custom health check for ENVD Server
# Verifies the server is responsive via the /health endpoint
MAX_RETRIES=50
RETRY_INTERVAL=0.2
for i in $(seq 1 $MAX_RETRIES); do
    status_code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:49983/health")
    if [ "$status_code" -eq 204 ]; then
        echo "ENVD Server is healthy"
        exit 0
    fi
    if [ $((i % 10)) -eq 0 ]; then
        echo "Waiting for ENVD Server to become healthy... (attempt $i/$MAX_RETRIES)"
    fi
    sleep $RETRY_INTERVAL
done
echo "ENVD Server health check failed after $MAX_RETRIES attempts"
exit 1

编写entrypoint.sh启动脚本

entrypoint.sh是容器的启动入口脚本，负责按正确顺序启动ENVD守护进程和OpenClaw网关服务。

#!/bin/bash
set -euo pipefail

# 设置默认配置路径（若环境变量未指定则使用默认值）
: "${OPENCLAW_CONFIG_PATH:=/home/node/.openclaw/openclaw.json}"
: "${OPENCLAW_WORKSPACE_DIR:=/home/node/.openclaw/workspace}"
: "${OPENCLAW_BOOTSTRAP_DIR:=/home/node/.openclaw/bootstrap}"
bootstrap_config="${OPENCLAW_BOOTSTRAP_DIR}/openclaw.json"

# 启动ENVD守护进程并进行健康检查
function start_envd() {
        sudo -n /opt/openclaw/bin/envd -isnotfc -port 49983 -verbose  &
        /opt/openclaw/bin/envd-healthcheck.sh
        if [ $? -ne 0 ]; then
                echo "ENVD Server failed to start, aborting."
                exit 1
        fi
}
echo "Starting ENVD server..."
start_envd

# 等待下发bootstrap配置文件
while [[ ! -s "${bootstrap_config}" ]]; do
  sleep 1
done

# 将下发的配置复制到OpenClaw配置路径
cp "${bootstrap_config}" "${OPENCLAW_CONFIG_PATH}"

# 启动OpenClaw网关服务，绑定局域网
node /app/dist/index.js gateway run --bind lan

脚本执行流程说明：

编写Dockerfile并构建镜像

自定义镜像需要在OpenClaw基础镜像上集成ENVD守护进程和启动脚本，使OpenClaw能够在AgentSphere沙箱环境中正常运行。由于OpenClaw镜像以非root用户（node）运行，而ENVD必须以root权限运行，因此需要通过sudoers进行权限适配。

1. 在构建目录下创建Dockerfile文件，内容如下：

   FROM ghcr.io/openclaw/openclaw:latest
   USER root
   
   # 复制ENVD守护进程及相关脚本到容器内
   COPY --chown=node:node  envd-healthcheck.sh  /opt/openclaw/bin/envd-healthcheck.sh
   COPY --chown=node:node  envd   /opt/openclaw/bin/envd
   COPY --chown=node:node  entrypoint.sh /opt/openclaw/bin/entrypoint.sh
   
   # 设置OpenClaw运行环境变量
   ENV OPENCLAW_GATEWAY_TOKEN="your-custom-gateway-token"
   ENV OPENCLAW_STATE_DIR="/home/node/.openclaw"
   ENV OLLAMA_API_KEY="ollama-local"
   
   # 安装tini（轻量级init进程，负责信号转发和僵尸进程回收）
   RUN apt-get update \
       && apt-get install -y --no-install-recommends \
           tini \
       && rm -rf /var/lib/apt/lists/*
   
   # 创建OpenClaw运行所需的目录并设置权限
   RUN install -d -m 0700 -o node -g node  /home/node/.openclaw 
   RUN install -d -m 0700 -o node -g node  /home/node/.openclaw/workspace
   RUN install -d -m 0700 -o node -g node  /home/node/.openclaw/bootstrap
   
   # 配置sudoers，允许node用户以root权限运行ENVD
   RUN mkdir -p /etc/sudoers.d
   RUN echo 'node ALL=(root) NOPASSWD: /opt/openclaw/bin/envd -isnotfc -port 49983 -verbose' \
           > /etc/sudoers.d/envd \
       && chmod 0440 /etc/sudoers.d/envd
   
   # 切回node用户，OpenClaw应用以node身份运行
   USER node
   EXPOSE 49983
   ENTRYPOINT ["tini", "-s", "--", "/bin/bash", "/opt/openclaw/bin/entrypoint.sh"]

   Dockerfile关键配置说明：

   配置项	说明	注意事项
   OPENCLAW_GATEWAY_TOKEN	OpenClaw网关访问令牌，用户在浏览器中访问OpenClaw时需输入此令牌进行认证。	请将your-custom-gateway-token替换为自定义的令牌值，建议使用高强度随机字符串，该令牌后续在浏览器访问时需要使用。
   OPENCLAW_STATE_DIR	OpenClaw状态数据存储目录。	保持默认值即可，需与下方创建的目录路径一致。
   OLLAMA_API_KEY	Ollama本地大模型的API密钥。	如使用Ollama作为模型后端，请替换为实际密钥；如使用其他模型服务，请在openclaw.json中配置对应的模型参数。
   envd-healthcheck.sh	ENVD健康检查脚本，用于验证ENVD服务是否正常启动。	由前述步骤编写。
   envd	ENVD守护进程二进制文件，沙箱环境管理核心组件。	由前述步骤编译生成。
   entrypoint.sh	容器启动脚本，负责启动ENVD和OpenClaw网关。	由前述步骤编写。
   sudoers配置	允许node用户以root权限运行ENVD，遵循最小权限原则。	请勿配置node ALL=(ALL) NOPASSWD:ALL，仅授予启动ENVD所需的最小权限。如果修改了ENVD路径或启动参数，需同步更新sudoers配置。
   EXPOSE 49983	声明ENVD监听端口。	该端口用于沙箱内部通信，浏览器访问时需要通过此端口。
   ENTRYPOINT	使用tini作为init进程启动entrypoint.sh。	tini确保容器正确处理信号，避免僵尸进程问题。

2. 执行以下命令构建自定义镜像。

   docker build -t openclaw-custom:latest .

3. 建议在推送前本地运行验证。

   docker run --rm -p 49983:49983 openclaw-custom:latest

   验证启动日志中出现“ENVD Server is healthy”，且OpenClaw网关正常启动。

推送镜像到SWR

构建并验证通过后，需要将镜像推送到华为云容器镜像服务（SWR），供创建沙箱模板时使用。

以基础版SWR为例，步骤如下：

1. 登录SWR控制台，选择左侧导航栏的“组织管理”，单击页面右上角的“创建组织”，创建一个组织。

   如已有组织可跳过此步骤。

2. 在左侧导航栏选择“我的镜像”，单击右侧“客户端上传”，在弹出的页面中单击“生成登录指令”，单击复制临时登录指令。
3. 在集群节点上执行上一步复制的登录指令，登录成功会显示“Login Succeeded”。
4. 给镜像打上SWR标签。

   docker tag openclaw-custom:latest swr.<region>.myhuaweicloud.com/<namespace>/openclaw-custom:latest

   其中，swr.<region>.myhuaweicloud.com为镜像仓库地址可在SWR控制台上查询，登录指令中末尾的域名即为镜像仓库地址；<namespace>为SWR中已创建的组织名称。

5. 推送镜像到 SWR：

   docker push swr.<region>.myhuaweicloud.com/<namespace>/openclaw-custom:latest

   推送完成后，可在SWR控制台对应组织的镜像列表中查看到该镜像。

创建自定义沙箱模板

本步骤在AgentSphere控制台创建基于上一步推送至SWR的自定义镜像的沙箱模板。

1. 登录AgentSphere控制台。
2. 在左侧导航栏中选择“沙箱模板”，并单击右上角的“创建沙箱模板”。
3. 选择沙箱模板类型为自定义沙箱（基于自定义镜像的完全可控开发环境）。
4. 填写基础配置。

   参数	参数说明	示例
   沙箱模板名称	自定义名称，需以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为1-48个字符。	openclaw-template
   描述	您可以添加该沙箱模板的描述信息，最多1000字符。	OpenClaw AI Agent网关沙箱模板
   选择镜像	单击选择镜像，选择SWR中已推送的自定义镜像。也可直接输入镜像地址。	选择阶段一推送的openclaw-custom:latest
   资源配额	选择沙箱实例使用的CPU和内存配比。资源配额过小可能导致沙箱运行失败，过大则导致资源浪费。	根据OpenClaw运行需求选择，建议2vCPU/4GB及以上
   沙箱实例配额	设置此沙箱模板创建实例的上限，所有模板实例配额总数上限为10000。	10
   启动命令	沙箱实例启动时执行的命令。由于已在Dockerfile中通过ENTRYPOINT指定，此处可留空。	留空
   环境变量	通过键值对为沙箱设置环境变量。已在Dockerfile中通过ENV设置，此处可按需补充。	可选

5. 填写网络与权限配置。

   参数	参数说明	示例
   入站（Inbound）网关	入站网关用于接收外部请求，配置后可通过网关访问沙箱内的服务。 如果没有可选网关，请单击“新建入站网关实例”进行创建，完成创建后单击刷新按钮。 必填，浏览器可通过网关域名访问OpenClaw。	选择已有网关实例
   出站（Outbound）网络配置	选择公网模式（沙箱可通过公网对外访问，适用于调用第三方API、下载依赖等场景）或VPC模式（沙箱访问VPC内其他服务）。	公网模式（OpenClaw需访问外部大模型API）
   运行时信任委托	用于授予OBS桶的访问权限。当配置了OBS对象存储时，此项必填。	选择已配置的信任委托

6. 填写日志监控配置（可选）。建议开启日志对接LTS，方便后续排查问题。
7. 完成上述配置后，单击“创建”。

   模板创建成功后，在模板列表中记录沙箱模板ID，后续创建沙箱时需要使用。

获取API Key

API Key是调用AgentSphere API和SDK的认证凭证，所有通过API或SDK操作沙箱资源的请求均需携带API Key进行身份鉴权。

1. 登录AgentSphere控制台。
2. 在左侧导航栏中选择“API Key管理”，并单击右上角的“创建API Key”。
3. 设置API Key参数。

   参数	参数说明
   有效期	根据需求设置API Key的有效期，过期后该API Key将不可用。
   描述	您可以添加该API Key的描述信息。

4. 单击“确定”，系统将自动为您生成API Key。
   

   为保障安全，生成的API Key将仅显示一次，请务必保存，关闭该页面后将无法再次查看。

   您可以单击“下载API Key凭证”将API Key保存至本地。

使用E2B SDK创建沙箱

完成自定义模板和API Key准备后，通过E2B SDK的Python接口创建沙箱实例，并将OpenClaw配置文件注入沙箱。

1. 确保本地已安装E2B SDK和满足版本要求的Python，版本要求详见e2b-code-interpreter。若未安装SDK，请执行以下命令安装：

   pip install e2b-code-interpreter==2.9.1

2. 创建Python脚本create_sandbox.py，内容如下：

   import os
   from e2b_code_interpreter import Sandbox
   from time import sleep
   
   # ====== 请替换为AgentSphere控制台获取的真实值 ======
   E2B_SANDBOX_URL = "https://<your-sandbox-url>.huaweicloud-agentnetwork.com"
   E2B_API_URL = "https://agentsphere.<region>.myhuaweicloud.com"
   E2B_API_KEY = "<your_api_key>"
   TEMPLATE = "<template_id>"
   # ================================================ 
   
   # 创建沙箱实例，指定自定义模板和环境变量
   sbx =  Sandbox.create(
       api_key=E2B_API_KEY,
       api_url=E2B_API_URL,
       sandbox_url=E2B_SANDBOX_URL,
       template=TEMPLATE_ID,
   # 环境变量
       envs={  
           "MY_VAR": "hello",
           "MY_SECRET": "12345",
       },
   )
   print("Sandbox created:", sbx.sandbox_id)
   print("Sandbox envd_access_token:",sbx._envd_access_token)
   print("Sandbox traffic_access_token:",sbx.traffic_access_token)
   
   # 等待沙箱内部服务启动完成
   sleep(10)
   
   # 设置流量访问令牌到请求头，用于后续浏览器访问时的身份验证
   sbx.connection_config._ConnectionConfig__extra_sandbox_headers["E2b-Traffic-Access-Token"] = sbx.traffic_access_token
   
   # 将本地openclaw.json配置文件写入沙箱的bootstrap目录
   with open("/home/user/openclaw-app/openclaw.json" , "rb") as fileA:
       sbx.files.write('/home/node/.openclaw/bootstrap/openclaw.json',fileA, user="node")
   print("已将配置写入沙箱")
   
   # 验证沙箱环境变量是否正确注入
   print(sbx.run_code("import os; print(os.environ)").logs.stdout)

   代码关键参数说明：

   参数	说明	注意事项
   E2B_SANDBOX_URL	沙箱服务网关地址，用于浏览器访问时的流量入口。	请替换为AgentSphere控制台中实际分配的网关地址，可在控制台“沙箱模板”详情页查看其入站网关的“公网域名”获取。
   E2B_API_KEY	沙箱服务API密钥，用于API调用身份认证。	请替换为实际密钥，注意妥善保管，避免泄露。
   E2B_API_URL	沙箱服务API地址，用于SDK与AgentSphere平台通信。	请替换为实际API地址，请通过《AgentSphere SDK参考》“配置本地E2B SDK执行环境”章节查询当前区域的API访问地址。
   template	自定义模板ID，决定沙箱的基础镜像和运行环境。	请替换为创建沙箱模板后获取的模板ID。
   envs	沙箱环境变量，可在沙箱内部通过os.environ读取。	根据业务需要自定义，非必填。
   sleep(10)	等待沙箱内部ENVD和OpenClaw服务启动。	若沙箱启动较慢，可适当增加等待时间。
   sbx.files.write(...)	将本地配置文件写入沙箱指定路径。	路径需与entrypoint.sh中bootstrap_config路径一致，user="node"确保文件属主正确。

3. 执行脚本创建沙箱。

   python create_sandbox.py

4. 验证沙箱创建成功。脚本执行后，控制台将输出Sandbox ID和Traffic Access Token，后续浏览器访问时需要使用。