WorkBuddy本地部署需满足五方面要求：一、操作系统兼容性（Win10 2004+/Win11、macOS 12+、Ubuntu/CentOS指定版本）；二、硬件资源（最低4GB RAM、推荐8GB+、CPU支持AVX2）；三、磁盘与文件系统（≥2GB空间、NTFS/APFS/ext4格式、路径无特殊字符）；四、网络与依赖（需访问api.codebuddy.cn等域名、开放57891端口、避免低版Node.js冲突）；五、系统权限（Windows勾选四项位置、macOS授权完全磁盘访问/辅助功能/屏幕录制、Linux加入video/audio用户组）。
如果您尝试在本地设备上部署 workbuddy，但安装失败或运行卡顿，则可能是由于硬件或系统环境未满足基础资源配置要求。以下是满足稳定运行所需的各项资源说明：
一、操作系统与架构兼容性
WorkBuddy 官方明确支持特定操作系统版本及底层架构，不兼容的系统会导致启动报错或功能缺失。必须确保当前设备运行的是受支持的发行版与内核版本。
1、Windows 用户需使用 Windows 10 版本 2004 及以上（含 Windows 11 全版本），且系统为 64 位架构。
2、macOS 用户需运行 macOS 12 Monterey 或更高版本，Apple Silicon（M1/M2/M3）与 Intel x86_64 均被官方支持。
3、Linux 用户仅限 Ubuntu 20.04 LTS、Ubuntu 22.04 LTS、CentOS 8+，其他发行版（如 Arch、Debian、Fedora）未通过兼容性测试，可能触发权限异常或沙箱崩溃。
二、内存与处理器最低阈值
WorkBuddy 启动后默认加载多 Agent 协同引擎与本地模型路由模块，内存占用具有阶段性峰值。低于阈值将导致任务中断、日志无响应或 UI 冻结。
1、最低要求为 4GB RAM，但仅适用于单次轻量指令（如“重命名三个文件”），连续执行多步骤任务时会触发 OOM Killer 强制终止进程。
2、推荐配置为 8GB RAM 及以上，其中 2GB 预留供 Claw 远程控制子系统独占，确保企业微信指令接收不丢包。
3、CPU 需支持 AVX2 指令集（Intel 第 4 代 Core 起，AMD Ryzen 1000 系列起），缺少 AVX2 将无法加载内置混元 Lite 推理引擎，自动降级至纯 API 模式。
三、磁盘空间与文件系统限制
WorkBuddy 在首次运行时会解压核心运行时、缓存技能包、生成本地知识索引，并保留执行沙箱快照。磁盘空间不足将阻断初始化流程。
1、安装包本体约 150–180MB，但完整部署后占用空间不低于 2GB，含临时工作区与日志归档目录。
2、必须使用 NTFS（Windows）、APFS（macOS）、ext4（Linux）等支持硬链接与 POSIX 权限的文件系统，FAT32 或 exFAT 格式移动硬盘不可作为主安装路径。
3、安装路径中不得包含中文、空格或特殊符号（如 &、#、%），否则技能市场下载会返回 403 错误。
四、网络与依赖服务准入条件
WorkBuddy 的部分能力依赖本地服务代理与云端策略同步，网络策略或防火墙拦截将导致功能模块静默失效。
1、首次启动需访问 https://api.codebuddy.cn 与 https://claw.codebuddy.cn 完成设备绑定与能力鉴权。
2、若使用企业微信远程控制，本地需开放 TCP 端口 57891（Claw Webhook 监听端口），该端口被防火墙拦截时，手机指令无法抵达桌面客户端。
3、Node.js 不再作为用户手动安装依赖，但运行时内嵌 Node.js 22.x LTS 二进制，系统 PATH 中存在低版本 Node.js（如 v16）可能导致 CLI 工具冲突。
五、图形与输入输出权限授权清单
WorkBuddy 执行本地操作需操作系统级权限许可，未完成授权将导致文件读写失败、截图黑屏、键盘模拟无响应等现象。
1、Windows 平台需在安装后首次启动时勾选「允许此应用访问下列位置」，并手动启用「桌面」、「文档」、「下载」、「图片」四项。
2、macOS 平台需进入「系统设置 → 隐私与安全性 → 完全磁盘访问」，将 WorkBuddy.app 拖入授权列表；同时在「辅助功能」与「屏幕录制」中重复添加。
3、Linux 平台需执行 sudo usermod -aG video,audio $USER 并重启会话，否则无法调用 ffmpeg 截图与 pulseaudio 录音模块。
