端口被占用时应先确认冲突端口号，再通过系统命令定位并终止非关键占用进程，或修改workbuddy配置文件切换至备用端口，并同步更新外部依赖中的端口引用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在安装 WorkBuddy 时收到端口被占用的提示，则说明其默认尝试绑定的端口（如8080、3000、8089或18789等）已被系统中其他进程占用。以下是解决此问题的步骤：
一、确认被占用的具体端口号
错误信息中通常会明确显示冲突端口，例如“Address already in use :::8080”或日志中出现“EADDRINUSE”。该数字是后续所有排查操作的关键依据。
1、查看 WorkBuddy 安装日志或控制台输出，提取冒号后紧跟的四位或五位数字（如8080、8089、18789）。
2、若日志未显式指出，可检查 WorkBuddy 默认端口配置：OAuth回调端口默认为8089，OpenClaw 服务端口默认为18789，Web 服务端口常见为8080或3000。
二、使用系统命令定位占用进程
通过终端命令识别当前监听该端口的进程PID及其名称，避免误杀关键服务。
1、Windows 用户打开命令提示符（以管理员身份运行），执行：netstat -ano | findstr :[端口号]（将[端口号]替换为上一步确认的数字）。
2、macOS/Linux 用户打开终端，执行：lsof -i :[端口号] 或 ss -tuln | grep :[端口号]。
3、若提示 command not found，macOS 用户请先运行 brew install util-linux（含 lsof），Linux 用户运行 sudo apt install lsof（Debian/Ubuntu）或 sudo yum install lsof（CentOS/RHEL）。
三、终止冲突进程（仅限非关键服务）
当确认占用进程非系统守护进程或生产服务时，可安全终止以释放端口。
1、从上一步命令输出中获取 PID（如12345），Windows 执行：taskkill /F /PID 12345。
自动备份 OpenClaw 整体配置到远程存储（支持任意 rclone 后端：COS、S3、FTP、SFTP、WebDAV等）。 触发场景： - 创建/配置自动备份任务 - 设置备份周期、保留份数、目标目录 - 手动触发备份 - 查看/恢复备份 - OpenClaw 运行异常时的提醒
2、macOS/Linux 执行：kill -9 12345；若权限不足，加 sudo：sudo kill -9 12345。
3、再次运行对应查询命令验证输出为空，即表示端口已释放。
四、修改 WorkBuddy 配置文件切换至备用端口
当无法终止占用进程（如 Docker、Nginx、Zoom 或 Chrome 插件常驻服务），应优先调整 WorkBuddy 自身端口配置，而非强行干预系统服务。
1、定位配置文件：Windows 查找 %WORKBUDDY_HOME%\config.yaml 或 %WORKBUDDY_HOME%\.env；macOS/Linux 查找 $WORKBUDDY_HOME/config.yaml。
2、编辑文件，修改以下字段（根据实际冲突端口选择对应项）：
— 若为 OAuth 回调端口冲突，修改 oauth2_redirect_port: 8089 为未占用值（如8090）；
— 若为 OpenClaw 服务端口冲突，修改 openclaw.port: 18789 为18790；
— 若为 Web 主服务端口冲突，修改 server.port: 8080 为8081。
3、保存文件后重启 WorkBuddy 安装流程或服务进程。
五、同步更新外部依赖中的端口引用
WorkBuddy 端口变更后，若存在外部系统与其交互，必须同步更新对应地址，否则仍会连接失败。
1、若企业 IM（飞书/企微）OAuth 设置中重定向 URI 为 http://localhost:8089/callback，需登录后台修改为新端口，如 http://localhost:8090/callback。
2、若自定义技能配置中调用 OpenClaw 接口，原 URL 为 http://localhost:18789/v1/chat/completions，需改为 http://localhost:18790/v1/chat/completions。
3、若通过 Postman、curl 或 Python 脚本直连 WorkBuddy Web API，需同步更新请求地址中的端口号。
