OpenSandbox 实战：在沙箱内启动 OpenClaw Gateway 并暴露 HTTP 端点-平芜编程栈

OpenSandbox 实战：在沙箱内启动 OpenClaw Gateway 并暴露 HTTP 端点

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

本指南以 OpenSandbox 官方示例 examples/openclaw 及其完整文档 docs/examples/openclaw.md 为主体，讲解如何在一个 OpenSandbox 安全沙箱中启动 OpenClaw Gateway，通过 Python SDK 的SandboxSync完成创建、健康检查与端点暴露。读完本文，你将掌握 OpenSandbox Python SDK 的核心用法：自定义容器 entrypoint、设置 egress 网络策略、注入环境变量、编写自定义健康检查，以及如何在本地 Docker 运行时下快速跑通整个流程。

示例目标与整体思路

OpenClaw 是一个面向 AI Agent 的开源网关项目，其 Gateway 组件通过 HTTP 对外提供服务。本示例做的事情非常聚焦：把 OpenClaw Gateway 放进 OpenSandbox 沙箱里运行，并把它的 HTTP 端点安全地暴露给外部调用。

整个流程可以分为三个阶段：

创建沙箱：通过 SDK 的SandboxSync.create()用ghcr.io/openclaw/openclaw:latest镜像创建沙箱，并指定启动命令直接拉起 Gateway 进程；
健康检查：脚本以固定轮询方式探测网关 HTTP 端口，直到返回200才认为就绪；
暴露端点：调用sandbox.get_endpoint(port)获取映射后的访问地址并打印给用户。

核心实现位于 examples/openclaw/main.py，全文约 100 行，没有多余依赖，适合作为 OpenSandbox SDK 的入门级实战参考。

快速开始

在项目根目录安装依赖并直接运行：

# Install dependencies uv pip install opensandbox requests # Run with default settings uv run python examples/openclaw/main.py

前提是本地已经有一个可达的 OpenSandbox server（默认地址http://localhost:8080），且该 server 的运行时能拉取ghcr.io/openclaw/openclaw:latest镜像。如何启动 server 见下文「启动本地 OpenSandbox server」一节。

配置项总览：环境变量即参数

示例脚本把所有可调参数都做成了环境变量，方便在不改代码的情况下覆盖默认值。原始文档给出的配置表如下：

变量	默认值	说明
`OPENCLAW_SERVER`	`http://localhost:8080`	OpenSandbox server 地址
`OPENCLAW_TOKEN`	`dummy-token-for-sandbox`	Gateway 认证 token
`OPENCLAW_IMAGE`	`ghcr.io/openclaw/openclaw:latest`	容器镜像
`OPENCLAW_TIMEOUT`	`3600`	沙箱超时时间（秒）

对照源码 main.py 可以看到，每个环境变量在模块加载时就被解析为常量：

DEFAULT_SERVER = os.getenv("OPEN_SANDBOX_SERVER", "http://localhost:8080") DEFAULT_API_KEY = os.getenv("OPEN_SANDBOX_API_KEY", "") DEFAULT_IMAGE = os.getenv("OPENCLAW_IMAGE", "ghcr.io/openclaw/openclaw:latest") DEFAULT_TIMEOUT = int(os.getenv("OPENCLAW_TIMEOUT", "3600")) DEFAULT_TOKEN = os.getenv("OPENCLAW_TOKEN", "dummy-token-for-sandbox") DEFAULT_PORT = int(os.getenv("OPENCLAW_PORT", "18789"))

需要特别说明两点与原始文档表格的差异：

OPEN_SANDBOX_SERVER/OPEN_SANDBOX_API_KEY：这两个变量实际控制 SDK 连接 OpenSandbox server 的地址与认证密钥，是示例真正生效的 server 配置变量；文档表格中的OPENCLAW_SERVER是语义上的别名，实际代码以OPEN_SANDBOX_SERVER为准。
OPENCLAW_PORT：默认网关端口18789，文档表格未列出，但源码已支持通过该变量覆盖。

脚本启动时会把生效的配置打印出来（API Key 与 Token 会脱敏显示），便于排查：

Creating openclaw sandbox with image=ghcr.io/openclaw/openclaw:latest on OpenSandbox server http://localhost:8080... API Key: [REDACTED] (set) Token: [REDACTED] (set) Port: 18789 Timeout: 3600s

核心逻辑拆解：SandboxSync.create 的完整参数

创建沙箱的调用集中在 main.py，这一小节把每个参数与 SDK 定义逐一对应，方便你直接改造复用。

镜像与生命周期

sandbox = SandboxSync.create( image=image, timeout=timedelta(seconds=timeout_seconds), metadata={"example": "openclaw"}, ... )

image：可以是字符串，SDK 内部会包装为SandboxImageSpec；从源码 sync/sandbox.py 可以看到if isinstance(image, str): image = SandboxImageSpec(image=image)的转换逻辑；
timeout：沙箱最大存活时间，传timedelta，默认是 10 分钟，示例显式设置为 3600 秒；传入None则要求手动清理；
metadata：自定义元数据，服务端会原样存储，可用于标识沙箱用途。

容器启动命令 entrypoint

entrypoint=["node", "dist/index.js", "gateway", "--bind=lan", "--port", str(port), "--allow-unconfigured", "--verbose"],

SDK 中entrypoint的默认值是["tail", "-f", "/dev/null"]（见 sync/sandbox.py），即默认沙箱是一个"空转"容器。本例将其替换为 OpenClaw Gateway 的实际启动命令：

gateway：启动网关子命令；
--bind=lan：绑定局域网地址，使沙箱外的代理可以访问；
--port 18789：网关监听端口；
--allow-unconfigured：允许未配置的 provider 启动，便于快速体验；
--verbose：输出详细日志。

连接配置 ConnectionConfigSync

connection_config=ConnectionConfigSync(domain=server, api_key=api_key),

ConnectionConfigSync是 SDK 的同步连接配置模型，定义在 config/connection_sync.py。它的关键字段包括：

domain：OpenSandbox 管理 API 的基础地址；
api_key：服务端认证密钥；
protocol：协议，默认http；
request_timeout：管理 API 的 HTTP 请求超时，默认 30 秒；
debug：是否开启请求级调试日志。

自定义健康检查 health_check

health_check=lambda sbx: check_openclaw(sbx, port),

SDK 的create()支持传入自定义同步健康检查函数（health_check: Callable[[SandboxSync], bool]，见 sync/sandbox.py），默认以 200ms 为轮询间隔（health_check_polling_interval，默认timedelta(milliseconds=200)，见 sync/sandbox.py），直到函数返回True或超过ready_timeout（默认 30 秒）。

示例中的check_openclaw（main.py）做的是最直白的可用性探测：

endpoint = sbx.get_endpoint(port) url = f"http://{endpoint.endpoint}" for _ in range(150): # max for ~30s resp = requests.get(url, timeout=1) if resp.status_code == 200: return True time.sleep(0.2)

即：先拿到该端口的映射地址，然后最多轮询 150 次（约 30 秒），一旦 HTTP 返回200即认为网关就绪，并打印实际耗时[check] sandbox ready after X.Xs。注意 SDK 文档中的提醒：自定义健康检查无法被ready_timeout中断，必须自行约束阻塞时间（本示例用timeout=1+sleep(0.2)的组合实现了这一点）。

环境变量注入 env

env={ "OPENCLAW_GATEWAY_TOKEN": token },

env是注入沙箱进程的环境变量字典。文档进一步给出了扩展示例，例如配置 OpenClaw 使用的模型：

env={ "OPENCLAW_GATEWAY_TOKEN": token, "OPENCLAW_MODEL": "claude-sonnet-4-20250514", # Add more env vars as needed },

OPENCLAW_GATEWAY_TOKEN的取值来自环境变量OPENCLAW_GATEWAY_TOKEN，未设置时回退到dummy-token-for-sandbox（见 main.py）。

资源限制（可选）

SDK 的create()还支持resource参数（CPU、内存限制，默认{"cpu": "1", "memory": "2Gi"}，见 sync/sandbox.py）。本示例未显式指定，若需限制网关占用可在调用中补充，例如：

resource={"cpu": "1", "memory": "1Gi"},

网络策略：默认拒绝外联，仅放行必要域名

OpenSandbox 的沙箱支持精细的 egress 网络策略。本示例采用**默认拒绝（default deny）**的安全模型：

network_policy=NetworkPolicy( defaultAction="deny", egress=[ NetworkRule(action="allow", target="pypi.org"), NetworkRule(action="allow", target="pypi.python.org"), NetworkRule(action="allow", target="github.com"), NetworkRule(action="allow", target="api.github.com"), ], )

defaultAction="deny"：没有任何规则匹配时默认拒绝出站流量；
显式放行pypi.org、pypi.python.org（供沙箱内安装 Python 依赖）以及github.com、api.github.com（供 OpenClaw 拉取仓库/调用相关 API）。

对应的 SDK 数据模型定义在 models/sandboxes.py：

NetworkRule：一条规则，action取allow/deny，target是 FQDN 或通配域名（如example.com、*.example.com），空 target 会被校验器拒绝；
NetworkPolicy：default_action默认值为deny（支持别名defaultAction），egress为按顺序求值的规则列表。

文档明确说明这是可定制的：把不需要的目标从egress列表中去掉，或按需追加新域名，即可收紧/放宽网关的网络边界。这套策略在 egress 组件（components/egress）与 OSEP 提案（0001-fqdn-based-egress-control.md、0022-multi-sandbox-egress-control-plane.md）中有完整的架构支撑。

启动本地 OpenSandbox server

运行示例前需要一个 OpenSandbox server。文档特别提示：server 默认使用runtime.type = "docker"，因此必须能访问一个正在运行的 Docker daemon。

Docker Desktop：确保已启动，用docker version验证；
Colima（macOS）：先colima start，再导出 socket：

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

接着预拉取 OpenClaw 镜像（避免创建沙箱时等待拉取）：

docker pull ghcr.io/openclaw/openclaw:latest

初始化配置并启动 server（日志保持在终端前台）：

uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server

init-config会生成一份基于 Docker 运行时示例的配置文件（保存到~/.sandbox.toml），opensandbox-server读取该配置并启动服务。关于配置的完整说明可参考 docs/getting-started/configuration.md 与 docs/getting-started/installation.md。

运行示例与预期输出

本示例为快速上手做了硬编码默认值，汇总如下：

OpenSandbox server：http://localhost:8080
镜像：ghcr.io/openclaw/openclaw:latest
网关端口：18789
超时：3600s
Token：OPENCLAW_GATEWAY_TOKEN（默认dummy-token-for-sandbox）

安装依赖并运行（如需认证访问，请先设置一个真实 token）：

uv pip install opensandbox requests

export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)" uv run python examples/openclaw/main.py

预期输出与文档给出的样例一致：

Creating openclaw sandbox with image=ghcr.io/openclaw/openclaw:latest on OpenSandbox server http://localhost:8080... [check] sandbox ready after 7.1s Openclaw started finished. Please refer to 127.0.0.1:56123

[check] sandbox ready after 7.1s表示健康检查在约 7 秒后通过；最后一行打印的127.0.0.1:56123是sandbox.get_endpoint(18789)返回的映射地址（main.py）。端点的具体形式取决于 server 的代理模式：走 server 代理时通常是可访问的 HTTP 地址，get_endpoint的实现见 sync/sandbox.py。

拿到该地址后，即可像访问普通 HTTP 服务一样调用 OpenClaw Gateway 的接口（携带OPENCLAW_GATEWAY_TOKEN进行认证）。

进阶：自定义网关端口

若18789端口不可用或需要调整，修改两处即可（文档明确给出的步骤）：

1. 修改 entrypoint 中的端口，例如改为19999：

entrypoint=["node dist/index.js gateway --bind=lan --port 19999 --allow-unconfigured --verbose"],

2. 同步更新 get_endpoint 的端口：

endpoint = sandbox.get_endpoint(19999)

同时建议把端口变量化（示例已提供OPENCLAW_PORT环境变量），使端口可通过环境变量动态控制。注意check_openclaw内部的探测端口同样需要与get_endpoint保持一致，否则健康检查会一直失败。

安全与最佳实践小结

回顾整个示例，可以提炼出在 OpenSandbox 中托管网关类服务的三条可复用经验：

把网络收口到白名单：使用defaultAction="deny"的NetworkPolicy，只放行网关真正依赖的域名，从源头降低出站风险；
用 entrypoint 把服务直接"拉起来"：SDK 默认空转 entrypoint 适合交互式调试，生产场景应像本例一样直接启动目标进程，再配合同步健康检查确认就绪；
敏感信息走环境变量：OPENCLAW_GATEWAY_TOKEN、API Key 均通过环境变量注入，脚本输出时会自动脱敏（[REDACTED]）。