FastGPT Agent V2虚拟机的配置、使用与运行限制说明

核心功能与设计逻辑

FastGPT Agent V2的虚拟机是为每个对话会话分配的物理隔离轻量Linux沙箱，可为Agent提供代码执行、文件读写与环境自定义能力，支持在独立的/workspace目录下创建、修改和读取文件。虚拟机与对话会话强绑定，不同用户、不同会话的运行环境完全物理隔离，系统通过心跳机制维持活动容器存活，会话长时间闲置时会自动销毁实例释放资源。同一会话生命周期内虚拟机持续存活，可保留上一轮的依赖、临时文件与环境变量，支持多轮交互连续性。沙箱采用严格的CPU、内存、磁盘IO资源配额与网络防火墙策略，所有执行命令通过base64编码在容器内解码运行，规避Shell拼接导致的命令注入风险。

配置与使用步骤

在Agent配置面板的"虚拟机配置"中开启"启用虚拟机"选项，调试窗口将自动激活专属调试能力：包括顶部及虚拟机操作对话气泡下方的"虚拟机文件管理器"入口，可实时浏览、编辑、上传下载容器内文件。
如需自定义运行环境，可在启动脚本(sh)编辑器中编写Shell脚本，脚本最大支持16384个字符，超出保存时会自动截断。复杂初始化逻辑可通过拉取远程脚本实现。
若关联技能包，技能自带的entrypoint.sh会在应用启动脚本执行完成后，在技能部署目录自动运行；技能包解压时会先在临时目录完成部署，再以原子操作替换正式目录，避免损坏。
对话输入框上传的测试文件会自动注入到虚拟机的user_files/目录，Agent可通过本地路径直接读取处理。点击"重开对话"会销毁旧虚拟机，为下一次交互分配全新纯净容器。

边界与易错注意事项

虚拟机的状态去重机制依托虚拟机内部的~/.fastgpt/agent-skill-entrypoints/state.json文件运行：针对自定义应用启动脚本，系统会计算其SHA256哈希值与记录比对，未修改则跳过执行；针对技能入口脚本，则基于技能版本ID比对去重，避免重复执行导致启动延迟，去重状态随虚拟机实例生命周期管理，重建实例时会重新执行初始化脚本。当前版本虚拟机为会话级隔离，未来将调整为用户级隔离以减少资源消耗。启动脚本执行受系统规则约束，包含字符长度限制与超时终止保护，需注意脚本执行超时会被强制终止。