沙盒通用配置 - Fastgpt

本文说明 Agent Sandbox 的通用配置，适用于 opensandbox 和 sealosdevbox。Provider 自身的接入参数请参考对应 Provider 文档；无论选择哪种 Provider，都需要部署 fastgpt-agent-sandbox-proxy，并按需配置沙盒内依赖源。

部署 sandbox-proxy

1. 添加 yml

可以参考 agent-sandbox-proxy.yml，将 service 加到 yml 文件里。并开放外网访问端口。并记录 AGENT_SANDBOX_PROXY_SECRET 环境变量，下一步需要使用。

FastGPT 服务里访问沙盒内部文件系统，会通过 proxy 去代理访问。

proxy 服务环境变量

变量	默认值	说明
`PORT`	`1006`	`fastgpt-agent-sandbox-proxy` 监听端口。
`AGENT_SANDBOX_PROXY_SECRET`	无	与 FastGPT 主服务共用的密钥，至少 32 位。
`FASTGPT_APP_URL`	`http://fastgpt-app:3000`	代理回源 FastGPT 主服务的内网地址，要求两个服务在一个互通网络。
`FASTGPT_APP_REQUEST_TIMEOUT_SECS`	`10`	代理回源 FastGPT 主服务的请求超时时间，单位秒。沙盒冷启动较慢时建议调大。
`RUST_LOG`	`info,fastgpt_agent_sandbox_proxy=debug`	代理服务日志级别。

2. 修改 FastGPT 环境变量

在 fastgpt-app 和 fastgpt-pro 中增加下面环境变量：

dotenv

# 对应 fastgpt-agent-sandbox-proxy 的变量 AGENT_SANDBOX_PROXY_SECRET。生产环境请改为 32 位以上随机密钥
AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
# 浏览器可访问的 agent-sandbox-proxy WebSocket 地址；如已通过 HTTPS 域名代理，请使用 wss://
AGENT_SANDBOX_PROXY_URL=wss://sandbox-proxy.example.com

3. 启动验证

重启 fastgpt-app、fastgpt-pro 和 fastgpt-agent-sandbox-proxy。
访问 https://agent-proxy域名/health，正常返回 OK。

4. 部署沙盒服务

部署完 proxy 服务后，还需接入沙盒控制服务，目前系统支持以下两种方案：

更多配置

自定义源

如果沙盒内需要安装 npm 或 Python 依赖，可以在 fastgpt-app 和 fastgpt-pro 中配置依赖源。配置后，Agent Sandbox 初始化时会写入 npm、yarn、pnpm、bun、pip 和 uv 的源配置。

dotenv

# Agent Sandbox 内 npm/yarn/pnpm/bun 使用的 npm registry
AGENT_SANDBOX_NPM_REGISTRY=https://registry.npmmirror.com
# Agent Sandbox 内 pip/python -m pip/uv 使用的 PyPI index URL
AGENT_SANDBOX_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

资源限制变量

fastpgt-app 和 fastgpt-pro 中你可以通过以下变量控制资源限制：

变量	默认值	说明
`AGENT_SANDBOX_DISK_MB`	`1024`	Agent 沙盒磁盘大小基准，单位 MB；会影响冷归档包、Skill 包和 IDE 单文件大小限制。
`AGENT_SANDBOX_WS_MAX_MESSAGE_BYTES`	`67108864`	IDE Agent WebSocket 单消息大小上限，单位字节。
`AGENT_SANDBOX_WS_MAX_FRAME_BYTES`	`16777216`	IDE Agent WebSocket 单帧大小上限，单位字节。

常见问题

提示 AGENT_SANDBOX_PROXY_URL is required

启用 Agent Sandbox 后，必须配置 AGENT_SANDBOX_PROXY_URL。该地址是浏览器访问 fastgpt-agent-sandbox-proxy 的 WebSocket 地址，例如 wss://sandbox-proxy.example.com，不是 FastGPT 主站地址。

浏览器 WebSocket 连接失败

检查代理服务是否能被浏览器访问，并确认反向代理已支持 WebSocket Upgrade。如果 FastGPT 通过 HTTPS 访问，AGENT_SANDBOX_PROXY_URL 也应使用 wss://，避免浏览器拦截混合内容。

proxy 校验失败或返回 401

确认 FastGPT 主服务和 fastgpt-agent-sandbox-proxy 中的 AGENT_SANDBOX_PROXY_SECRET 完全一致，并且长度不少于 32 位。