端口占用错误可通过五种方法解决：一、终止占用进程；二、修改配置文件或CLI命令更改默认端口；三、清理残留服务与守护进程；四、启用自动端口探测；五、检查并配置防火墙及SELinux策略。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在启动 QoderWake 数字员工时收到端口占用错误（如 EADDRINUSE），则说明其默认监听端口已被其他进程占用。以下是多种可独立生效的实操方法：
一、终止占用端口的进程
该方法直接释放端口，适用于确认占用进程非关键服务的场景。需先定位 PID，再强制结束对应进程。
1、打开命令提示符（Windows）或终端（macOS/Linux）。
2、执行命令查看占用 QoderWake 默认端口（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 -9 12345（macOS/Linux）。
5、再次运行查询命令验证端口是否已释放，无输出即表示成功。
二、修改 QoderWake 默认端口配置
该方法避免与其他应用冲突，无需终止其他服务，推荐作为长期解决方案。修改后需重启 QoderWake Gateway 才能生效。
1、使用 CLI 命令修改端口：qoder config set gateway.port 18790（选择未被占用的端口，如 18790、18791 等）。
2、或手动编辑配置文件：~/.qoder/config.yaml（Windows 路径为 %USERPROFILE%\.qoder\config.yaml）。
3、在文件中定位到 gateway 区块，将 port 字段值改为新端口号，例如：port: 18790。
4、保存文件后执行重启命令：qoder gateway restart。
5、访问新地址确认服务启动：http://127.0.0.1:18790（需同步更新 Control UI 入口或客户端连接配置）。
三、清理残留服务实例与守护进程
该方法针对多次异常退出后残留的僵尸进程或 systemd/init.d 守护任务，常见于 Linux 服务器部署场景，表现为端口被“幽灵进程”占用但 lsof 无法列出完整命令路径。
1、检查是否存在残留 systemd 服务：systemctl list-units --type=service | grep qoder。
2、若发现状态为 activating 或 failed 的 qoder-* 服务，执行：systemctl stop qoder-gateway.service && systemctl disable qoder-gateway.service。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、清除旧版守护进程残留 socket：rm -f /run/qoder/gateway.sock /var/run/qoder-gateway.pid。
4、刷新 systemd 配置并清理进程树：systemctl daemon-reload && pkill -f "qoder.*gateway"。
5、执行 ss -tuln | grep :18789 验证端口已完全空闲。
四、启用端口自动探测与动态绑定
QoderWake 支持启动时自动跳过已被占用的端口，通过启用此模式可规避人工排查，适用于 CI/CD 自动化部署或容器编排环境。
1、编辑 config/runtime.yaml，定位至 gateway 区块。
2、将 port 字段设为 0，表示启用内核级端口自动分配。
3、添加字段：auto_port_range: [18790, 18899]，限定可选端口区间。
4、保存后执行：qoder gateway start --no-daemon，观察控制台输出的实际绑定端口。
5、通过 qoder config get gateway.port 获取当前生效端口号，并同步更新反向代理或客户端配置。
五、校验防火墙与 SELinux 策略干扰
部分 Linux 发行版（如 CentOS/RHEL）在启用 SELinux 或 firewalld 后，可能对非标准端口实施隐式拦截或上下文拒绝，导致服务看似启动成功但实际无法响应请求。
1、临时禁用 firewalld 验证：systemctl stop firewalld，再测试端口连通性。
2、若问题消失，添加永久放行规则：firewall-cmd --permanent --add-port=18790/tcp && firewall-cmd --reload。
3、检查 SELinux 端口上下文：semanage port -l | grep http_port_t。
4、若目标端口未在白名单中，执行：semanage port -a -t http_port_t -p tcp 18790。
5、确认 SELinux 当前模式：getenforce，如为 Enforcing，需完成上述策略更新后重启 QoderWake。
