需确认四方面环境配置：一、操作系统（Win10+/macOS12+/Ubuntu20.04+）、硬件（i5-8250U/8GB内存/2GB磁盘）；二、系统权限（Win授权UAC、macOS开启完整磁盘访问、Linux配置sudo与dialout组）；三、网络（直连公网、正确设置代理、关闭SSL劫持软件）；四、后台服务（释放3001/3002端口、清理残留进程、禁用强制沙盒）。
如果您准备在本地电脑上运行workbuddy，但启动后无法正常加载技能或连接外部平台，则可能是由于系统权限、网络环境或基础依赖未就绪。以下是完成部署前必须确认的环境配置步骤：
一、操作系统与硬件兼容性检查
WorkBuddy为桌面端AI Agent工具，需确保运行环境满足最低要求，否则将导致核心功能不可用或进程异常退出。
1、确认操作系统版本：Windows 10/11（64位，无需WSL）、macOS 12及以上（支持Intel与Apple Silicon芯片）、Ubuntu 20.04+或CentOS 8+。
2、检查CPU与内存：推荐Intel i5-8250U或同等性能以上处理器；最低内存要求为8GB，低于此值可能导致多Agent并行任务卡顿或崩溃。
3、验证磁盘空间：安装包约150–180MB，但运行时需预留至少2GB可用空间用于缓存、临时文件及模型加载。
二、系统级权限授权
WorkBuddy需直接操作本地文件、调用系统API及启用辅助功能，未授予权限将导致文件读写失败、自动化操作中断或界面响应无反馈。
1、Windows用户：首次启动时，在弹出的“用户账户控制”窗口中点击“是”；随后在设置向导中手动开启“文件和文件夹访问权限”，重点勾选桌面、文档、下载、工作目录等常用路径。
2、macOS用户：打开“系统设置 → 隐私与安全性 → 完整磁盘访问”，点击右下角锁形图标解锁后，将WorkBuddy.app拖入列表；若提示“已阻止打开”，需进入“安全性与隐私 → 通用”，点击“仍要打开”。
3、Linux用户：确保当前用户属于sudo组，并在终端执行sudo usermod -aG dialout $USER（如需串口类Skill）；同时确认/tmp目录具有可写权限。
三、网络与代理环境准备
WorkBuddy在初始化阶段需联网校验许可证、拉取默认模型路由、同步Claw插件索引及注册MCP Server，断网或代理配置错误会导致配置卡在“正在加载技能市场”状态。
1、确认设备可直连公网：访问https://www.codebuddy.cn/work/ 应能正常加载官网页面；禁止使用仅允许内网访问的DNS（如10.0.0.x、192.168.x.x等私有地址段作为主DNS）。
2、如企业网络启用了代理：在WorkBuddy启动前，于终端/命令提示符中设置系统级代理变量——Windows执行set HTTP_PROXY=http://proxy.example.com:8080，macOS/Linux执行export HTTP_PROXY="http://proxy.example.com:8080"。
3、关闭可能干扰HTTPS证书校验的安全软件：部分国产杀毒软件或上网行为管理工具会劫持SSL连接，导致API请求返回ERR_CERT_AUTHORITY_INVALID错误。
四、后台服务与冲突进程排查
WorkBuddy依赖本地MCP Server通信及多进程沙盒调度，若存在同端口占用、旧实例残留或安全策略拦截，将造成Claw模块初始化失败或指令无响应。
1、检查端口占用：WorkBuddy默认使用本地端口3001（MCP通信）与3002（WebUI服务），Windows执行netstat -ano | findstr :3001，macOS/Linux执行lsof -i :3001，终止冲突PID进程。
2、清理残留进程：Windows在任务管理器中结束所有名为workbuddy、claw-server、mcp-server的进程；macOS/Linux执行pkill -f "workbuddy\|claw\|mcp"。
3、禁用强制沙盒策略：某些企业IT策略会限制非签名应用创建子进程，需联系管理员将WorkBuddy加入白名单，或临时关闭Windows Defender“基于声誉的保护”。
