常见问题

一、环境部署类

1. 运行需要哪些前置依赖？ 核心依赖为：Miniconda（Python 环境）、Node.js（前端 UI）、Docker（沙盒隔离）。

• 注：Windows 的 setup.bat 会自动下载缺失的 Node/Miniconda，macOS/Linux 需手动预装基础环境。

2. 脚本执行无权限报错怎么办？

• Windows：首次安装及后续启动，请右键选择**“以管理员身份运行”**。这对于环境变量写入和 Docker 挂载是必需的。
• macOS/Linux：终端执行 chmod +x scripts/setup.sh scripts/start.sh 赋予执行权限。

3. 安装超时或失败？

自带重试逻辑，若持续失败，请提前配置国内镜像源（Conda 清华源、npm 淘宝源、Docker 镜像加速），或离线安装基础依赖后再运行脚本。

4. 必须安装 Docker 吗？

必须安装。框架的本地沙盒、Shell 命令执行、系统级读写隔离均强依赖 Docker 容器，无 Docker 无法运行核心功能。

二、运行与使用类

1. 任务中断后能断点续跑吗？ 支持。框架内置断点重连与数据备份。因 API 阻断或系统重启导致的意外退出，重新启动后只需在对话中让 Agent 恢复任务，它会读取备份上下文继续执行。

2. Agent 如何记住我的偏好？ 框架内置轻量级备忘录。对话中直接告知偏好即可，系统会以极低 token 消耗将其持久化。你也可以手动编辑 src/agent/core/memory.md。

3. API 调用受限怎么办？ 在配置中为单一模型添加多个不同账户的 API Key，系统会自动进行轮询调度。

4. Agent 为什么说 Docker 沙盒环境受限？ 大概率是没有启动 Docker 桌面软件或者首次安装本框架时没有构建容器。

5. 沙盒机制足够安全吗？ 所有 Shell 和代码执行被强制封锁在 Docker 容器内。对主机的访问采用严格的白名单机制，未授权目录绝对不可见。但若你主动将高危目录（如系统盘根目录）加入白名单，仍有误操作风险。请遵循最小权限原则，后果自负。

三、安全与合规

• 开源协议： 本项目核心框架基于 GNU GPL-3.0 协议。内部使用无需开源；任何针对核心框架本身的对外分发（含 SaaS 化交付或二次打包）必须完整开源衍生代码，并保留版权声明。

• 插件/扩展豁免声明：任何基于本框架标准接口（如 Harness/Expert、Plugin等）独立开发的插件、扩展模块及外部挂载代理，均不受 GPL-3.0 协议的传染约束。插件开发者拥有完全的版权和分发自主权，可以自由选择任何开源协议（如 MIT、Apache 等），亦可完全闭源并用于商业化变现。

• 绝对免责：代码“按原样”提供，作者不提供任何明示或暗示的担保。因误操作导致的数据丢失、API 扣费、沙箱逃逸或违规引发的法律纠纷，作者概不负责。请自觉遵守相关法律法规，严禁将本框架用于非法数据爬取、系统入侵或其他恶意用途。