qoder启动失败因端口冲突，可采取五种解决方法：一、终止占用端口的进程；二、修改qoder配置文件中的qos_port值；三、用socat代理转发请求；四、清理dns缓存及.lingma目录；五、禁用或修改dubbo qos端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动 Qoder 服务时遇到“启动失败”提示，且日志中出现 Address already in use 或 socket bind failed 等错误信息，则极可能由端口冲突导致。以下是多种可立即执行的解决方法：
一、终止占用端口的进程
该方法适用于已确认占用端口的进程非关键服务，可安全终止。通过系统命令定位并强制结束对应 PID，释放端口资源。
1、在终端中执行命令查询指定端口（默认为 Qoder 所需端口，如 22222）占用情况：
Windows：netstat -ano | findstr ":22222"
macOS/Linux：lsof -i :22222 或 netstat -tulnp | grep :22222
2、从输出结果中提取占用该端口的进程 ID（PID）
3、根据操作系统执行终止命令：
Windows：taskkill /f /pid PID数值
macOS/Linux：kill -9 PID数值
4、再次运行端口检查命令，确认无输出即表示端口已释放
二、修改 Qoder 服务监听端口
该方法避免影响其他运行中的服务，无需终止任何进程，通过配置变更使 Qoder 使用未被占用的替代端口。
1、定位 Qoder 配置文件路径：C:\Users\用户名\AppData\Local\.lingma\config.json（Windows）或 ~/.lingma/config.json（macOS/Linux）
2、用文本编辑器打开 config.json 文件
3、查找是否存在 "qos_port" 字段；若不存在，则在根对象内新增该字段
4、将值设为一个未被占用的端口号，例如："qos_port": 22223
5、保存文件后，彻底结束所有 qoder cn 进程（包括后台残留），再重新启动 IDE 及插件
三、通过代理中转规避端口绑定
该方法适用于无法修改 Qoder 配置、亦不能终止占用进程的受限环境，利用本地端口转发将请求导向实际可用端口。
1、确认一个空闲端口（如 22224），并确保 Qoder 已配置为监听该端口（参考方法二完成配置）
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、在终端中启动 socat 转发（需提前安装 socat）：
macOS/Linux：socat TCP-LISTEN:22222,fork TCP:localhost:22224 &
Windows（WSL 或 Git Bash）：同上；原生 CMD 不支持，建议使用 WSL
3、验证转发是否生效：curl http://localhost:22222/ping 应返回响应
4、保持 socat 进程运行，后续 Qoder 相关工具仍可向 22222 发起请求
四、清理 DNS 缓存与本地配置残留
该方法针对因 DNS 解析异常或旧配置残留引发的伪端口冲突现象，尤其在切换网络环境或代理策略后易出现。
1、清除系统 DNS 缓存：
Windows：以管理员身份运行 cmd，执行 ipconfig /flushdns
macOS：执行 sudo killall -hup mDNSResponder
Linux（systemd-resolved）：sudo systemctl restart systemd-resolved
2、删除 Qoder 本地状态目录：
Windows：删除 C:\Users\用户名\AppData\Local\.lingma
macOS/Linux：删除 ~/.lingma
3、重启 IDE，并以管理员/Root 权限重新打开一个非空项目文件夹
4、首次启动时，Qoder 将重建配置目录并尝试绑定默认端口
五、检查并禁用 Dubbo QoS 服务干扰
该方法专用于同时运行 Dubbo 应用与 Qoder 的开发场景，因 Dubbo 默认启用 QoS Server（端口 22222）造成隐性冲突。
1、检查项目中是否引入 dubbo-spring-cloud-starter 或类似依赖
2、在 application.properties 或 dubbo.properties 中显式关闭 QoS：
dubbo.application.qos-enable=false
3、若需保留 Dubbo QoS 但更换端口，添加配置：
dubbo.application.qos-port=22225
4、清理 IDE 缓存：File → Invalidate Caches and Restart → Invalidate and Restart
