端口被占用时应先终止进程或修改QClaw端口配置。可执行netstat/lsof查PID后taskkill/kill结束进程；或用qclaw configset gateway.port修改端口并重启服务；还可清理残留配置、以管理员权限重启。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在安装 QClaw 时收到端口被占用提示（如 EADDRINUSE 错误），则说明本地 18789 端口（QClaw 默认 gateway 端口）已被其他进程占用。以下是解决此问题的步骤：
一、终止占用端口的进程
该方法直接释放端口，适用于确认占用进程非关键服务的场景。需先定位 PID，再强制结束对应进程。
1、打开命令提示符（Windows）或终端（macOS/Linux）。
2、执行命令查看占用 18789 端口的进程：netstat -ano | findstr :18789（Windows）或 lsof -i :18789（macOS/Linux）。
3、从输出中提取 PID（进程标识号），例如显示为 TCP 127.0.0.1:18789 0.0.0.0:0 LISTENING 12345，则 PID 为 12345。
4、执行终止命令：taskkill /PID 12345 /F（Windows）或 kill 12345（macOS/Linux）。
5、再次运行查询命令验证端口是否已释放，无输出即表示成功。
二、修改 QClaw 默认端口配置
该方法避免与其他应用冲突，无需终止其他服务，推荐作为长期解决方案。修改后需重启 QClaw Gateway 才能生效。
1、使用 CLI 命令修改端口：qclaw configset gateway.port 18790（选择未被占用的端口，如 18790、18791 等）。
2、或手动编辑配置文件：~/.qclaw/qclaw.json（Windows 路径为 %USERPROFILE%\.qclaw\qclaw.json）。
3、在文件中定位到 gateway 对象，将 port 字段值改为新端口号，例如："port": 18790。
4、保存文件后执行重启命令：qclaw gateway restart。
5、访问新地址确认服务启动：http://127.0.0.1:18790（需同步更新浏览器书签或 Control UI 入口）。
三、清理残留环境与配置冲突
该方法针对 Cladbot、OpenClaw 或旧版 QClaw 配置残留导致的伪占用现象，常见于多次混装后 daemon 状态异常但无真实进程监听。
1、清除用户级环境变量：[Environment]::SetEnvironmentVariable("CLADBOT_HOME", $null, "User") 及 [Environment]::SetEnvironmentVariable("QCLAW_HOME", $null, "User")（PowerShell）。
2、重命名旧配置目录以隔离干扰：Rename-Item "$env:USERPROFILE\.cladbot" "$env:USERPROFILE\.cladbot.backup"（Windows）或 mv ~/.cladbot ~/.cladbot.backup（macOS/Linux）。
3、执行全新初始化：qclaw onboard，确保生成干净的配置结构。
4、若此前使用 OpenClaw 关联模式，需在 QClaw 启动前确认 openclaw gateway status 返回非 running 状态，否则先执行 openclaw gateway stop。
四、以管理员权限重启 QClaw 服务
该方法解决 Windows 系统下因权限不足导致端口绑定失败的问题，尤其在 1024 以下端口或系统策略限制时有效。
1、右键点击“Windows PowerShell”或“命令提示符”，选择以管理员身份运行。
2、在提权窗口中执行：qclaw gateway restart。
3、若仍报错，可尝试临时切换至高编号端口（如 18795）后再执行重启，排除权限与端口双重限制叠加影响。
