跳到主要内容

安全沙箱

SkillFlaw 在涉及代码执行的场景下，会通过沙箱运行时处理任务，而不是让这些逻辑直接在后端主进程中执行。

在本地开发中，和开发者最相关的两条路径是：

  • Skill 运行时执行
  • MCP stdio 沙箱执行

对这两类能力，都应把沙箱视为本地开发环境的一部分，而不是可选附加项。

为什么要关注沙箱​

SkillFlaw 可以运行用户编写的逻辑、解析依赖、创建临时运行工作目录，并和运行时环境交换文件。

因此，本地开发不应假设这些能力会在 SkillFlaw 主进程内部无限制执行，而应显式验证沙箱连接、运行镜像和资源限制是否符合预期。

Skill 沙箱​

Skill 执行通过 Skill 沙箱服务运行，当前默认后端为 opensandbox。

本地开发至少应让以下连接配置与后端实际可访问的 OpenSandbox 服务保持一致：


_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN=localhost:8080
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL=http
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY=
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=false
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS=600

如果你还要验证依赖安装、导出文件或长时间运行脚本，也建议把运行限制显式写入 .env：


_10
SKILLFLAW_SKILL_SANDBOX_CPUS=1.0
_10
SKILLFLAW_SKILL_SANDBOX_MEMORY_MB=512
_10
SKILLFLAW_SKILL_SANDBOX_PIDS_LIMIT=256
_10
SKILLFLAW_SKILL_SANDBOX_TIMEOUT_SECONDS=60
_10
SKILLFLAW_SKILL_SANDBOX_NETWORK=none
_10
SKILLFLAW_SKILL_SANDBOX_READ_ONLY_ROOT=true
_10
SKILLFLAW_SKILL_SANDBOX_TMPFS_ENABLED=true
_10
SKILLFLAW_SKILL_SANDBOX_WORKSPACE_ACCESS=rw
_10
SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST=[]

这些值应和你的本地验证目标一致。例如某个 Skill 在调试时必须访问外部服务，就不要默认假设沙箱已开放网络，而应显式调整沙箱网络模式。

MCP 沙箱​

MCP 的 stdio 沙箱执行会复用 Skill 沙箱的 OpenSandbox 连接配置，因此本地后端必须能访问同一个 OpenSandbox 服务。

除此之外，MCP 还需要独立配置自己的沙箱镜像，因为运行镜像会按服务语言选择。

你可以按以下任一方式配置 MCP 沙箱镜像：

  • 使用共享镜像：SKILLFLAW_MCP_SANDBOX_IMAGE
  • 使用按语言拆分的镜像：SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE、SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE
  • 使用镜像 repository/tag 组合：例如 SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_REPOSITORY 与 SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_TAG

示例：


_10
SKILLFLAW_MCP_SANDBOX_BASE_DIR=~/.skillflaw/mcp-sandboxes
_10
SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE=ghcr.io/cwinux/skillflow_mcp_python:v1.0.1
_10
SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE=ghcr.io/cwinux/skillflow_mcp_ts:v1.0.1

MCP 沙箱镜像值必须是 Docker 镜像引用，不能填写 HTTP URL。

沙箱配置要求​

在本地测试 Skill 或 MCP 行为前，请至少确认以下事项：

  1. OpenSandbox 已部署完成，并且 SkillFlaw 后端可以访问。
  2. .env 中的 OpenSandbox 域名、协议和 API Key 与真实服务一致。
  3. 沙箱镜像与要验证的运行语言一致。
  4. CPU、内存、进程数、超时、文件系统和网络限制与验证范围匹配。
  5. 任何需要传入 Skill 沙箱的环境变量，都应显式写入 SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST。
  6. 如果你修改了沙箱镜像、镜像 repository/tag 配置，或 OpenSandbox 的 execd_image，都应先重启沙箱服务再重新测试。

建议的本地验证顺序​

当开发范围包含沙箱能力时，建议按以下顺序执行：

  1. 启动或确认 OpenSandbox 服务可用。
  2. 在执行 make backend 前完成 .env 中的沙箱配置。
  3. 确认目标语言对应的运行镜像已准备好。
  4. 确认后端到沙箱连通后，再进行 Skill 或 MCP 联调。
  5. 每次修改沙箱镜像或运行时配置后重新验证。

相关文档​