qoderwake连接知识库失败时，需依次检查服务进程、配置地址、网络通路及api密钥：先用ps/tasklist确认qdrant是否运行，未运行则执行qoder knowledge start启动；再通过curl或telnet/nc验证6333端口连通性；接着核对config.json中host/port/https设置及hosts文件；最后检查qdrant_config.yaml是否启用api密钥并同步至config.json。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
QoderWake连接知识库失败时，系统无法加载文档向量、检索历史记录或执行RAG推理，表现为任务卡在“加载知识源”阶段、日志中持续出现Connection refused或Failed to connect to vector store提示，且qoder knowledge status命令返回offline状态。
确认知识库服务进程是否存活
QoderWake默认通过gRPC协议连接本地向量数据库（如Qdrant或Chroma），若服务未启动或崩溃，连接必然失败。
第一步：在终端执行ps aux | grep qdrant（Linux/macOS）或tasklist | findstr qdrant（Windows），检查进程是否存在。
第二步：若无输出，说明服务未运行；直接执行qoder knowledge start启动内置知识库服务——该命令会自动拉起Qdrant容器并配置端口映射。
第三步：等待10秒后，运行curl -s http://localhost:6333/health | jq .status验证Qdrant健康状态；返回"status":"green"才表示服务已就绪。
【关键操作】若返回curl: (7) Failed to connect to localhost port 6333: Connection refused，说明Qdrant未监听或端口被占用——此时必须先执行qoder knowledge stop再重试启动，避免残留进程锁死端口。
校验知识库连接配置与网络通路
即使Qdrant进程存活，若QoderWake配置指向错误地址或中间网络策略拦截，仍会连接超时。
方法一：检查配置文件中的向量库地址
打开~/.config/qoderwake/config.json（macOS/Linux）或%USERPROFILE%\.config\qoderwake\config.json（Windows），定位"vector_store"节点，确认"host"值为"localhost"、"port"为6333，且"https"设为false——QoderWake内置Qdrant仅支持HTTP明文通信。
方法二：绕过DNS直连测试连通性
Qoder Linux版是由阿里推出的智能体自主开发工作台，支持开发者通过定义需求即可让Agent团队“自动驾驶”，自主完成代码执行、验证与交付的全流程。其全新的Quest独立视窗集成了任务管理与状态追踪能力，并支持跨项目多任务并行处理，显著提升开发效率。此外，Qoder还提供专家团模式与团队级知识引擎，适配复杂开发场景。
在终端执行telnet localhost 6333（Windows需先启用Telnet客户端）或nc -zv 127.0.0.1 6333（macOS/Linux）；若显示Connection refused，证明端口未开放；若卡住无响应，则可能是防火墙拦截或Qdrant绑定到了0.0.0.0但被NAT策略过滤。
方法三：强制刷新本地hosts解析
编辑C:\Windows\System32\drivers\etc\hosts（Windows）或/etc/hosts（macOS/Linux），删除所有含qdrant或vector的行——某些安全软件会注入虚假解析导致localhost失效。
排查知识库认证凭据与权限状态
当启用了Qdrant API密钥认证（非默认配置）时，QoderWake若未携带正确token，将被拒绝连接。
第一步：检查Qdrant是否启用API密钥
查看Qdrant配置文件qdrant_config.yaml中是否存在service_api_key字段；若存在且值非空，则进入下一步。
第二步：同步密钥到QoderWake配置
在config.json的vector_store节点下添加"api_key": "your_actual_key_here"字段，注意key值必须与Qdrant配置完全一致，包括大小写和特殊字符。
第三步：重启QoderWake服务
执行qoder restart使新配置生效；若仍失败，临时将Qdrant配置中的service_api_key设为空字符串并重启Qdrant，验证是否为密钥问题。
