qoderwake启动失败主因是端口占用或环境冲突，解决方法包括：一、终止8443/8080端口占用进程；二、修改config.json中https_port/http_port为可用端口；三、清理残留配置目录并重置权限；四、windows下禁用快速启动与bios中aspm节能；五、用socat代理转发至空闲端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在完成 QoderWake 环境搭建后尝试启动服务，但出现“启动失败”提示，且日志中包含 Address already in use、Failed to bind port 或 listen EADDRINUSE 等关键词，则极可能由端口占用或环境初始化冲突导致。以下是多种可立即执行的解决方法：
一、终止占用 QoderWake 默认端口的进程
该方法适用于已确认占用端口的进程非系统关键服务，可安全终止以释放端口资源。QoderWake 默认监听端口为 8443（HTTPS）与 8080（HTTP），需同步检查二者。
1、在终端中执行命令查询 8443 端口占用情况：
Windows：netstat -ano | findstr ":8443"
macOS/Linux：lsof -i :8443 或 netstat -tulnp | grep :8443
2、对 8080 端口执行相同检查命令，确保两个端口均无活跃监听进程。
3、从输出结果中分别提取两个端口对应的进程 ID（PID）。
4、根据操作系统执行终止命令：
Windows：taskkill /f /pid PID数值
macOS/Linux：kill -9 PID数值
5、再次运行端口检查命令，确认两个端口均无输出即表示已完全释放。
二、修改 QoderWake 服务监听端口配置
该方法避免影响其他正在运行的服务，无需终止任何进程，通过修改配置使 QoderWake 使用未被占用的替代端口组合。适用于企业内网或开发机长期共存多套服务的场景。
1、定位 QoderWake 配置文件路径：
Windows：%USERPROFILE%\.config\qoderwake\config.json
macOS/Linux：~/.config/qoderwake/config.json
2、用文本编辑器打开 config.json 文件，确认是否存在 "https_port" 与 "http_port" 字段。
3、若不存在，需在根对象内新增字段；若存在，将其值分别修改为未被占用的端口号，例如：
"https_port": 8444,
"http_port": 8081
4、保存文件后，执行命令彻底结束所有 qoderwake 进程：
Windows：taskkill /f /im qoderwake.exe
macOS/Linux：pkill -f qoderwake
5、重新启动 QoderWake 服务，并使用新端口访问验证：
https://localhost:8444/status 与 http://localhost:8081/status 应返回 200 响应。
三、清理残留配置目录并重置初始化状态
该方法针对多次安装/卸载后配置文件残留、权限锁死或 XDG 目录结构损坏导致的伪启动失败。QoderWake 1.0+ 版本强制使用 ~/.config/qoderwake 路径，旧版残留的 ~/.qoderwake 将引发路径冲突与权限拒绝。
1、关闭所有 QoderWake 相关进程及 IDE 插件。
2、删除遗留配置目录：
Windows：rd /s/q "%USERPROFILE%\.qoderwake"
macOS/Linux：rm -rf ~/.qoderwake
Qoder Linux版是由阿里推出的智能体自主开发工作台，支持开发者通过定义需求即可让Agent团队“自动驾驶”，自主完成代码执行、验证与交付的全流程。其全新的Quest独立视窗集成了任务管理与状态追踪能力，并支持跨项目多任务并行处理，显著提升开发效率。此外，Qoder还提供专家团模式与团队级知识引擎，适配复杂开发场景。
3、确认新路径存在且权限正确：
macOS/Linux：mkdir -p ~/.config/qoderwake && chmod 700 ~/.config/qoderwake
Windows：手动创建 %USERPROFILE%\.config\qoderwake 目录，并右键→属性→安全→编辑→赋予当前用户完全控制权限
4、清空系统级环境变量中可能干扰的路径：
Windows：在 PowerShell 中执行 [Environment]::SetEnvironmentVariable("QODERWAKE_HOME", $null, "User")
macOS/Linux：在 shell 中执行 unset QODERWAKE_HOME 并从 ~/.zshrc 或 ~/.bashrc 中移除相关 export 行
5、首次重启时，系统将弹出三项权限请求窗口，必须全部勾选并点击「允许」：
— 允许访问剪贴板
— 允许后台运行
— 允许读取当前活动应用
四、禁用快速启动与 BIOS 中的 ASPM 节能策略
该方法适用于 Windows 平台启动失败伴随黑屏、卡在白点动画或服务进程瞬间退出的情形。快速启动（Hybrid Boot）与主板 ASPM/L1 Substates 设置会导致 PCIe 设备（含集成显卡与 USB 控制器）在唤醒阶段无法正确重初始化，从而阻断 QoderWake 所依赖的 Qt 图形子系统与本地 IPC 通道。
1、进入 Windows 控制面板 → 电源选项 → 选择电源按钮的功能 → 更改当前不可用的设置 → 取消勾选「启用快速启动」。
2、重启进入 BIOS/UEFI（开机时反复按 F2/Del/Esc），定位到 Advanced → Chipset Configuration 或 Power Management → 找到 ASPM（Active State Power Management）选项，将其设为 Disabled。
3、继续查找 L1 Substates、PCIe ASPM Control 或类似的节能子项，一并设为 Disabled。
4、保存 BIOS 设置并重启，在 Windows 中执行 shutdown /r /t 0 强制完整重启（非快速启动）。
5、启动 QoderWake 前，先以管理员身份运行 CMD，执行命令：
bcdedit /set {current} bootmenupolicy standard
以禁用 Windows 启动菜单压缩模式，确保图形驱动加载完整性。
五、使用 socat 进行端口代理转发规避绑定冲突
该方法适用于无法修改 QoderWake 配置、亦不能终止占用进程的受限环境（如企业终端管理策略锁定配置文件、或端口被系统服务占用）。利用本地端口转发，将外部请求导向 QoderWake 实际监听的空闲端口，实现逻辑解耦。
1、确认一个空闲端口（如 8445），并按方法二完成 QoderWake 配置变更，使其实际监听该端口。
2、在终端中启动 socat 转发（需提前安装 socat）：
macOS/Linux：socat TCP-LISTEN:8443,fork TCP:localhost:8445 &
Windows（WSL 或 Git Bash）：同上；原生 CMD 不支持，须启用 WSL2
3、验证转发是否生效：
curl -k https://localhost:8443/status 应返回 JSON 响应体，且 HTTP 状态码为 200。
4、保持 socat 进程持续运行，后续所有客户端（包括浏览器、IDE 插件、CLI 工具）仍可向标准端口 8443 发起请求。
5、将 socat 启动命令写入系统服务或开机脚本，确保其优先于 QoderWake 启动：例如 Linux 下创建 /etc/systemd/system/socat-qoderwake.service，启用并启动该服务。
