常见问题

一、环境部署类

1. 运行需要哪些前置依赖？ 核心必需依赖为：Docker（沙盒隔离，无 Docker 无法运行核心功能）。uv（Python 包管理器）、Node.js（提供 npm/npx）、Git 均非部署必需，但它们是体验完整拓展功能（安装 Skill、接入 MCP、编译前端界面）的必备依赖，建议一并安装。

2. 安装很慢、超时或失败？

一般是网络问题，若持续失败，请提前配置国内镜像源（配置 uv 镜像源、Docker 镜像加速）。

3. 必须安装 Docker 吗？

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

4. 需要安装 Node.js 吗？非必须，不影响核心 Agent 部署与运行。但 Node.js 提供 npm/npx，PurrCat 的前端界面（Electron 桌面端 / Web UI）与部分 MCP 扩展工具依赖它。想完整体验界面与拓展功能时再安装即可。

5. purrcat 命令找不到？ 确保在项目根目录下执行。

6. 部署和虚拟化技术冲突？ Docker 的正常运行依赖宿主机的虚拟化支持，常见问题：

• Windows（WSL2 / Hyper-V）：Docker Desktop 需要主板开启硬件虚拟化（VT-x / AMD-V），很多笔记本出厂默认关闭，启动 Docker 会直接报错。需进 BIOS 开启。
• VMware / VirtualBox 冲突：宿主机同时运行其他虚拟机软件时，可能与 Hyper-V / WSL2 产生冲突，导致蓝屏或无法启动。
• 嵌套虚拟化（Nested Virtualization）：如果 PurrCat 本身跑在虚拟机里（如云服务器、Parallels），需要额外开启嵌套虚拟化支持，否则 Docker 容器无法启动。
• Linux：Docker 原生支持最好，几乎没有冲突问题。但如果使用了非默认的容器运行时（如 containerd），可能与沙盒初始化脚本不兼容。

二、运行与使用类

1. 任务中断后能断点续跑吗？ 支持。框架内置 Checkpoint 持久化机制，每轮对话状态实时落盘。意外退出后重启，只需让 Agent 恢复任务即可自动加载 Checkpoint 继续执行。

2. Agent 如何记住我的偏好？ 框架内置轻量级备忘录系统（Memo 工具 + PurrMemo 本地引擎）。对话中直接告知偏好即可，系统会以极低 token 消耗将其持久化。你也可以通过 Memo 工具主动写入记忆。

3. API 调用受限怎么办？ 在 .purrcat/model.json 的 api_keys 列表中添加多个 Key，系统会通过 APIKeyManager 自动进行负载均衡（最少活跃优先）。

4. Agent 为什么说 Docker 沙盒环境受限？ 大概率是没有启动 Docker 桌面软件，或首次安装后未运行 purrcat setup 构建沙盒镜像。

5. 沙盒机制足够安全吗？ 所有 Shell 执行被强制封锁在 Docker 容器内。对主机的访问通过 .purrcat/file.json 定义严格的白名单机制，未授权目录绝对不可见。导出操作自动触发 Git 快照防止覆盖灾难。请遵循最小权限原则，后果自负。

6. Agent 在沙盒里访问国外网站总是网络超时，开了 VPN 也不行？ 常规的 VPN / 代理工具工作在宿主机网络层，Docker 容器默认使用独立的网络命名空间，并不会自动继承宿主机的代理设置。容器内的网络请求走的是 Docker 的虚拟网桥，不经由宿主机的 VPN 隧道。解决办法是开启代理软件的 TUN 模式（虚拟网卡），让容器流量也被代理路由捕获。具体配置方式请参考你使用的代理软件文档。

三、安全与合规

开源协议：本项目基于 MIT 协议 开源。无论是个人学习、内部使用，还是进行商业化变现、闭源分发或二次打包，均不受任何限制。唯一的要求是：在软件的所有副本或实质性部分中，必须保留原有的版权声明和许可声明。

插件与扩展说明：基于本框架标准接口（如 Sensor 插件等）独立开发的任何插件及扩展，不受任何开源传染约束。开发者对自己的插件拥有完全的版权和分发自主权，可自由选择任何开源协议，亦可完全闭源并用于商业化。

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