OpenSandbox 配置
FastGPT OpenSandbox 与 Agent Sandbox Proxy 配置
OpenSandbox 方案默认未做网络隔离。如有安全隔离要求，请自行补充网络隔离策略。
OpenSandbox 适合需要自托管 Agent/Skill 沙盒运行环境的场景。FastGPT 通过 OpenSandbox Server 创建沙盒，并通过 Agent Sandbox Proxy 为浏览器提供文件、终端和预览访问能力。
Docker Compose 配置
最新版 Docker Compose 已经包含 OpenSandbox Server、Volume Manager、Agent Sandbox Proxy 和沙盒运行时镜像配置，无需再单独合并其他 YAML 文件。
查看最新版 docker-compose.yml（PgVector，中国大陆镜像源）
其他向量数据库和全球镜像源版本见 Docker Compose 部署。
环境变量配置
Docker compose yml 文件里均已带默认值，这里补充做每个变量的说明。该文档始终是最新配置，旧版的配置可能存在差异，需找旧版的 yml 来看实际变量值。
OpenSandbox 服务
根据实际部署环境检查 Compose 文件中的以下配置：
| 配置 | 说明 |
|---|---|
x-volume-manager-auth-token | Volume Manager 的认证 Token，需要与 FastGPT 的 AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN 一致。 |
[server].api_key | OpenSandbox Server API Key，需要与 FastGPT 的 AGENT_SANDBOX_OPENSANDBOX_API_KEY 一致。 |
[docker].host_ip | 沙盒端点对 Proxy 可访问的宿主机地址，通常使用宿主机内网 IP 或 host.docker.internal。 |
| Docker socket 挂载 | Docker runtime 需要挂载宿主机 Docker socket，默认是 /var/run/docker.sock；OrbStack 等环境需替换为实际 socket。 |
如果服务器配置了 HTTP_PROXY / HTTPS_PROXY，建议给 OpenSandbox Server 和 Volume Manager 显式配置 NO_PROXY / no_proxy。至少包含 localhost,127.0.0.1,127.0.0.0/8,fastgpt-app,fastgpt-opensandbox-server,fastgpt-volume-manager,fastgpt-agent-sandbox-proxy,host.docker.internal，避免内部服务调用经过代理。
Agent Sandbox Proxy 服务
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT | 1006 | Proxy 容器监听端口，默认映射到宿主机 3006。 |
PREVIEW_PORT | 与 PORT 相同 | 4.16 可单独指定 HTTP 预览监听端口；修改后需同步调整宿主机端口映射和 AGENT_SANDBOX_PREVIEW_PROXY_URL。 |
AGENT_SANDBOX_PROXY_SECRET | 无 | 与 FastGPT 主服务共用的密钥，至少 32 位。 |
FASTGPT_APP_URL | http://fastgpt-app:3000 | Proxy 回源 FastGPT 主服务的内网地址。 |
FASTGPT_APP_REQUEST_TIMEOUT_SECS | 10 | Proxy 回源请求超时时间，单位秒；沙盒冷启动较慢时可适当调大。 |
RUST_LOG | info,fastgpt_agent_sandbox_proxy=debug | Proxy 服务日志级别。 |
4.16 默认使用同一个端口提供 WebSocket 和 HTTP 预览。如果网关不支持同端口转发，可设置 PREVIEW_PORT 为其他容器端口（例如 1007），并将 Compose 端口映射改为 3007:1007，同时把 AGENT_SANDBOX_PREVIEW_PROXY_URL 指向新的 3007 端口。
fastgpt-app 服务
在 Compose 文件的 x-agent-sandbox-config 中配置以下变量，使 fastgpt-app 和 fastgpt-pro 共用 OpenSandbox 配置：
AGENT_SANDBOX_PROVIDER=opensandbox
# FastGPT 访问 OpenSandbox Server 的内网地址和密钥
AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://fastgpt-opensandbox-server:8090
AGENT_SANDBOX_OPENSANDBOX_API_KEY=replace_with_opensandbox_api_key
AGENT_SANDBOX_OPENSANDBOX_RUNTIME=docker
AGENT_SANDBOX_OPENSANDBOX_IMAGE=registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox:v0.2.0
AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=true
# Volume Manager 地址、Token 和持久卷名称前缀
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL=http://fastgpt-volume-manager:3000
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN=replace_with_volume_manager_token
AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX=fastgpt-session
# Agent Sandbox Proxy 配置
AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
AGENT_SANDBOX_PROXY_URL=wss://sandbox-proxy.example.com
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# 单个沙盒的资源限制
AGENT_SANDBOX_CPU_COUNT=1
AGENT_SANDBOX_MEMORY_MIB=2048
AGENT_SANDBOX_STORAGE_SIZE_GI=1AGENT_SANDBOX_OPENSANDBOX_API_KEY 必须与 [server].api_key 一致，AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN 必须与 x-volume-manager-auth-token 一致，AGENT_SANDBOX_PROXY_SECRET 必须与 Agent Sandbox Proxy 中的同名变量一致。
fastgpt-pro 不提供 Sandbox Editor 和 WebSocket Proxy 链路，因此不要求 AGENT_SANDBOX_PROXY_SECRET 和 AGENT_SANDBOX_PROXY_URL，但必须配置 AGENT_SANDBOX_PREVIEW_PROXY_URL。
预览代理应部署在与 FastGPT 主站不同的 origin（协议、域名或端口至少一项不同）。Sandbox 中的 HTML 可能包含用户生成的脚本；如果预览地址与主站同源，脚本可能访问主站凭证或接口。
预览链接是短期只读 bearer capability。获得链接的人可以在链接有效期内通过修改 URL 路径读取同一 Sandbox Workspace 中的其他文件，请勿将链接分享给无权访问该 Workspace 的用户。
从旧版 Volume Manager 升级时，请将原 VM_VOLUME_NAME_PREFIX 的值配置到 AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX，避免历史持久卷无法按原名称清理。
更多配置
自定义依赖源
如果沙盒内需要安装 npm 或 Python 依赖，可以在 fastgpt-app 和 fastgpt-pro 中配置依赖源：
AGENT_SANDBOX_NPM_REGISTRY=https://registry.npmmirror.com
AGENT_SANDBOX_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple资源与生命周期
| 变量 | 默认值 | 说明 |
|---|---|---|
AGENT_SANDBOX_CPU_COUNT | 1 | 单个 Agent Sandbox 的 CPU 核数上限。 |
AGENT_SANDBOX_MEMORY_MIB | 2048 | 单个 Agent Sandbox 的内存上限，单位 MiB。 |
AGENT_SANDBOX_STORAGE_SIZE_GI | 1 | 沙盒存储容量，单位 Gi。 |
AGENT_SANDBOX_WS_MAX_MESSAGE_BYTES | 67108864 | IDE Agent WebSocket 单消息大小上限。 |
AGENT_SANDBOX_WS_MAX_FRAME_BYTES | 16777216 | IDE Agent WebSocket 单帧大小上限。 |
AGENT_SANDBOX_SUSPEND_MINUTES | 60 | 运行中的沙盒持续未活跃多少分钟后自动暂停。 |
AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS | 7 | 已暂停的沙盒持续未活跃多少天后自动归档。 |
常见问题
提示 Sandbox provider apiKey is required for opensandbox
检查 AGENT_SANDBOX_OPENSANDBOX_API_KEY 是否已配置，并确认它与 opensandbox-config 中的 [server].api_key 一致。
提示 AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL is required
检查 AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL 和 AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN，并确认 Volume Manager 服务正常运行。
提示 AGENT_SANDBOX_PROXY_URL 或 AGENT_SANDBOX_PREVIEW_PROXY_URL is required
fastgpt-app 必须配置 AGENT_SANDBOX_PROXY_SECRET、AGENT_SANDBOX_PROXY_URL 和 AGENT_SANDBOX_PREVIEW_PROXY_URL；fastgpt-pro 必须配置 AGENT_SANDBOX_PREVIEW_PROXY_URL。
浏览器 WebSocket 连接失败
检查 Proxy 是否可从浏览器访问，并确认反向代理支持 WebSocket Upgrade。如果 FastGPT 使用 HTTPS，AGENT_SANDBOX_PROXY_URL 也应使用 wss://。
Proxy 校验失败或返回 401
确认 FastGPT 主服务和 Agent Sandbox Proxy 中的 AGENT_SANDBOX_PROXY_SECRET 完全一致，且长度不少于 32 位。
沙盒创建成功，但文件树或终端连接失败
确认 AGENT_SANDBOX_PROXY_URL 是浏览器可访问的 ws:// 或 wss:// 地址，并检查宿主机 3006 端口或对应域名是否已开放。
Proxy 无法连接沙盒 endpoint
检查 opensandbox-config 的 [docker].host_ip。沙盒 endpoint 中的 localhost 或 127.0.0.1 对 Proxy 容器不可达，通常应改为宿主机内网 IP 或 host.docker.internal。