这个决定什么时候必须做
当工作流需要执行自定义数据处理、格式转换或逻辑计算代码，或Agent需要动态规划执行代码、处理上传文件时，该决定成为必须考虑的事项。若在需求未明确时提前选择方案，会增加不必要的部署复杂度与资源消耗。若延迟决策，当现有环境无法满足新增需求时，需重构工作流、迁移现有代码，可能导致业务运行中断。当出现以下场景时，需立即推进决策：需要在会话间保留代码执行的环境状态，需要读写本地文件生成或处理数据，需要安装自定义第三方依赖，或需要通过启动脚本配置专属运行环境。代码运行节点的文档适用于 4.14.8 及以上版本，沙箱相关配置参数随版本调整，需结合当前部署版本确认可用能力。
判据矩阵
| 候选方案 | 支持的编程语言范围 | 允许使用的模块范围 | 文件系统访问能力 | 网络访问限制 | 会话环境存续特性 | 自定义启动脚本配置 | 沙箱资源限制配置 | 沙箱提供方部署方式 |
|---|---|---|---|---|---|---|---|---|
| 代码运行节点（FastGPT内置沙箱） | JavaScript（基于Bun运行时）、Python 3 | JavaScript：白名单npm模块（lodash、moment等）；Python：白名单标准库与第三方库（math、pandas等），禁止系统/网络模块 | 无法读写容器文件系统 | 自动拦截内网IP，单次最多30个请求，响应体最大2MB | 每次执行在独立沙盒进程，无会话级存续 | 不支持 | 默认最大运行60s，可配置调整；单个沙箱内存默认256MB | 私有化部署需部署fastgpt-sandbox镜像，配置CODE_SANDBOX_URL环境变量 |
| Agent虚拟机（OpenSandbox沙箱） | Python、Node.js、Shell脚本 | 可通过启动脚本安装 Python 依赖（pip）与系统级工具；装 apt 依赖需使用 fastgpt-agent-sandbox-root 镜像并配置 AGENT_SANDBOX_APT_MIRROR | 可读写/workspace目录，支持上传文件注入到user_files/ | 默认未做网络隔离，可自行补充策略 | 同一会话内环境持续存活，文件、依赖保留 | 支持，超时由 AGENT_SANDBOX_ENTRYPOINT_TIMEOUT_SECONDS 控制，默认 30 秒 | 可配置AGENT_SANDBOX_CPU_COUNT、AGENT_SANDBOX_MEMORY_MIB、AGENT_SANDBOX_STORAGE_SIZE_GI | 需部署OpenSandbox Server、Volume Manager、Agent Sandbox Proxy服务 |
| Agent虚拟机（Sealos Devbox沙箱） | Python、Node.js、Shell脚本 | 可通过启动脚本安装 Python 依赖（pip）与系统级工具 | 可读写/workspace目录，支持上传文件注入到user_files/ | 文档未明确，需按部署环境实测 | 同一会话内环境持续存活，文件、依赖保留 | 支持，超时由 AGENT_SANDBOX_ENTRYPOINT_TIMEOUT_SECONDS 控制，默认 30 秒 | 可配置AGENT_SANDBOX_CPU_COUNT、AGENT_SANDBOX_MEMORY_MIB、AGENT_SANDBOX_STORAGE_SIZE_GI | 仅商业版支持；需申请密钥，沙箱由 Sealos 托管，仍需配置 Agent Sandbox Proxy 相关变量 |
每个判据为什么重要
支持的编程语言范围
该判据决定了可实现的代码逻辑边界。若业务需求仅需简单的数据格式转换，JavaScript或Python即可满足，代码运行节点的支持范围足够。若需要执行Shell脚本完成系统级操作，或需要结合多种语言实现复杂逻辑，代码运行节点无法覆盖，需选择Agent虚拟机。不同语言的适配能力直接影响代码的可移植性与开发效率，未匹配的语言范围会导致现有代码无法直接复用，需重写核心逻辑。
允许使用的模块范围
该判据决定了代码可调用的工具能力边界。代码运行节点采用固定白名单机制，仅允许预设的模块，若需使用未纳入白名单的第三方库，无法通过常规方式实现。Agent虚拟机支持通过启动脚本安装自定义依赖，可灵活适配各类业务需求。若业务需要使用特定的数据分析库或加密工具，未匹配的模块范围会导致代码执行失败，需额外开发替代逻辑，增加开发成本与周期。
文件系统访问能力
该判据决定了代码处理本地文件的能力。代码运行节点无法读写容器文件系统，仅适用于无文件交互的简单计算场景。若业务需要处理上传的Excel、CSV等文件，或生成临时文件用于后续步骤，代码运行节点无法满足需求。Agent虚拟机支持读写/workspace目录，且可自动注入用户上传的文件到user_files/目录，可用于文件处理类场景。未支持文件系统访问会导致无法完成依赖文件读取或结果输出，直接阻断业务流程。
网络访问限制
该判据决定了代码发起外部请求的安全边界。代码运行节点默认拦截内网IP，可有效防止SSRF攻击，适用于需安全访问外部公共接口的场景。Agent虚拟机的OpenSandbox方案默认未做网络隔离，需自行补充安全策略，适用于可自主控制网络访问的部署环境。Sealos Devbox 方案的网络策略文档未明确，需按部署环境实测。未合理配置网络限制会带来安全风险，导致内部网络被非法访问，引发数据泄露或系统被入侵。
会话环境存续特性
该判据决定了代码执行的环境状态保留能力。代码运行节点每次执行都在独立沙盒进程，无会话级存续，适用于单次无状态的代码执行。若业务需要在同一会话的多个步骤间保留文件、依赖或环境变量，代码运行节点无法满足需求。Agent虚拟机的会话级存续特性可支持多轮交互的连续调试与数据传递，适用于需要多步骤协作的复杂任务。未具备环境存续能力会导致每一步代码执行都需要重新初始化环境，增加执行耗时与资源消耗。
自定义启动脚本配置
该判据决定了运行环境的自定义能力。代码运行节点不支持启动脚本配置，仅能使用预设的沙箱环境。若业务需要安装特定的软件源、Python依赖或系统级工具，代码运行节点无法实现。Agent虚拟机支持配置启动脚本，可在沙盒拉起后自动执行初始化命令，适配专属的运行环境。未支持启动脚本配置会导致无法预配置业务所需的依赖，需在代码中手动安装依赖，增加代码复杂度与执行耗时。
沙箱资源限制配置
该判据决定了沙箱的资源使用上限。代码运行节点的单个沙箱最大内存由 SANDBOX_MAX_MEMORY_MB 控制（默认 256 MB），运行超时默认 60 秒，可通过配置调整。Agent虚拟机支持自定义CPU、内存与存储容量的限制，可根据业务需求调整资源分配。未合理配置资源限制会导致沙箱因资源不足被强制终止，或浪费多余的服务器资源，影响业务运行效率与成本。
沙箱提供方部署方式
该判据决定了沙箱的部署与维护成本。代码运行节点的私有化部署仅需部署fastgpt-sandbox镜像与配置环境变量，复杂度较低。Agent虚拟机的OpenSandbox方案需部署多个服务，维护复杂度较高。Sealos Devbox 方案仅商业版支持，沙箱由 Sealos 托管，需申请密钥并配置 Proxy 相关变量。未匹配的部署方式会导致部署周期过长或维护难度过大，影响项目上线进度。
换的代价
从代码运行节点切换至Agent虚拟机，需迁移现有代码并调整执行逻辑。现有代码需适配Agent虚拟机的变量传递与环境存续机制，例如将无状态的单次执行调整为支持会话级状态保留。若选择OpenSandbox方案，需部署额外的沙箱服务与配置环境变量，涉及服务重启与网络策略调整，可能需要短暂的停机窗口。若选择Sealos Devbox方案，需完成商业版权限申请与接入配置，调整现有沙箱相关的环境变量。迁移过程中需验证所有代码的执行结果，包括依赖安装、文件读写、网络访问等功能，确保业务逻辑不受影响。此外，原代码运行节点的无状态特性与Agent虚拟机的会话存续特性存在差异，需调整工作流的节点编排逻辑，适配新的环境状态传递方式。
什么情况下这个决定可以先不做
当工作流仅需调用内置工具完成标准化任务，无需执行自定义代码时，该决定可暂时搁置。当代码执行需求仅为简单的数据格式转换，且无需处理文件、自定义依赖或会话级环境存续时，可优先使用代码运行节点，待后续需求明确后再考虑升级。当部署环境尚未完成沙箱相关服务的准备工作，例如未部署OpenSandbox或未申请Sealos Devbox的接入权限时，可暂时使用代码运行节点作为过渡方案。当项目处于早期验证阶段，需求尚未稳定，提前选型可能导致后续频繁调整，增加不必要的工作量。此时可先通过代码运行节点完成基础功能验证，待需求明确后再进行正式选型与部署。
继续阅读
参考资料
需要进一步确认时
上述判据可依据公开文档与部署实测逐项核对。若需要结合具体业务规模、数据边界与运维条件确定选型，可通过商务咨询获取评估支持；云服务形态可直接开始使用，先验证业务可行性再决定部署形态。
- 商务咨询：结合业务条件做选型评估
- 立即开始：先用云服务验证可行性
- 定价：对比不同形态的适用范围