语言模型连接失败时，应依次验证Lingma服务进程、检查lingma-api与devops域名连通性、重置Lingma配置并清除证书缓存、切换MCP通信模式为STDIO、禁用冲突安全软件并重置网络栈。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 Qoder 进行智能补全时发现建议完全不出现、提示“模型不可用”、长时间显示“Loading…”或控制台报错包含“Connection failed”“Failed to connect to model service”等字样，则很可能是语言模型连接失败所致。以下是针对该问题的多种独立解决方案：
一、验证 Lingma 本地服务进程状态
Lingma 是 Qoder CN 调用本地大模型的核心后台服务，若其未启动、崩溃或监听端口异常，将直接导致模型连接失败。该服务需持续运行并绑定至 127.0.0.1 上的有效端口。
1、打开任务管理器（Windows）或活动监视器（macOS），搜索进程名 Lingma 或 qoder-agent。
2、若进程不存在，进入对应安装路径：C:\Users\[用户名]\AppData\Local\.lingma\bin\x.x.x\CPU架构_64_系统\（Windows）或 ~/.lingma/bin/x.x.x/CPU架构_64_系统/（macOS）。
3、执行 Lingma start（macOS/Linux）或双击 Lingma.exe start（Windows）。
4、观察终端输出是否包含 "Service started on http://127.0.0.1:XXXX"，并确认端口未被其他程序占用。
二、检查模型 API 域名连通性与白名单策略
Qoder CN 在启用云端模型模式时，必须成功访问 lingma-api.tongyi.aliyun.com 和 devops.aliyun.com。任一域名被防火墙拦截、DNS 污染或 TLS 握手失败，均会触发连接失败错误。
1、在终端中执行：curl -I https://lingma-api.tongyi.aliyun.com/algo/api/v1/ping，预期返回 HTTP 200 及响应体 "pong"。
2、执行：curl -I https://devops.aliyun.com，预期返回 HTTP 302 状态码。
3、若任一命令超时或报 "Connection refused" 或 "SSL certificate problem"，需联系 IT 部门将上述域名加入企业防火墙与代理白名单。
三、强制重置 Lingma 配置并清除证书缓存
Lingma 客户端依赖本地 TLS 证书信任链及 config.json 中的 endpoint、auth_token 字段完成安全连接。配置字段为空、过期或证书缓存损坏时，会导致握手阶段静默失败。
1、关闭所有 IDE 实例，确保无残留 lingma.exe 或 qoder-agent 进程。
2、备份后删除配置文件：C:\Users\[用户名]\AppData\Local\.lingma\config.json（Windows）或 ~/.lingma/config.json（macOS/Linux）。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、清除系统级证书缓存：Windows 执行 certmgr.msc → 个人 → 证书 → 删除所有以 "Lingma" 或 "Qoder" 开头的条目；macOS 执行 sudo security find-certificate -p /System/Library/Keychains/SystemRootCertificates.keychain | grep -A 1 "Qoder" 并移除匹配项。
4、重启 IDE，触发 Qoder 自动重建初始配置并重新发起鉴权流程。
四、切换模型通信协议为 STDIO 模式
当 HTTP/S 连接因代理策略、SSL 中间件或网关限制持续失败时，可临时切换至 STDIO 协议——该模式通过标准输入/输出流与本地模型进程直连，绕过网络栈与 TLS 层，适用于强管控内网环境。
1、进入 IDE 设置 → Qoder CN → MCP 服务 → 选择当前启用的模型服务。
2、将通信模式由 HTTP 改为 STDIO。
3、点击 Restart Service，观察日志是否输出 "STDIO server launched successfully"。
4、在代码编辑器中输入任意变量名后按 Ctrl+Space，验证补全是否即时响应。
五、禁用冲突安全软件并重置网络栈
部分终端安全软件（如 CrowdStrike、深信服 EDR、奇安信天擎）会主动拦截未知进程的 outbound 连接，尤其对未签名的 Lingma.exe 或动态端口监听行为实施静默阻断，表现为无错误日志但连接始终失败。
1、临时退出所有第三方安全客户端，仅保留系统自带防火墙。
2、重置网络协议栈：Windows 执行 netsh int ip reset 与 netsh winsock reset；macOS 执行 sudo ifconfig en0 down && sudo ifconfig en0 up。
3、清空本地 DNS 缓存：Windows 执行 ipconfig /flushdns；macOS 执行 sudo dscacheutil -flushcache。
4、以管理员权限重启 IDE，并在设置中手动指定 114.114.114.114 为首选 DNS 服务器进行验证。
