当前位置：首页 > news >正文

OpenClaw错误排查手册：Qwen3-14b_int4_awq接口连接问题解决

news 2026/6/14 2:58:41

OpenClaw错误排查手册：Qwen3-14b_int4_awq接口连接问题解决

1. 问题背景与典型场景

上周在本地部署Qwen3-14b_int4_awq模型时，我遇到了OpenClaw连接失败的棘手问题。当时模型服务明明已经启动，端口监听也正常，但OpenClaw就是无法建立稳定连接。经过两天断断续续的排查，终于梳理出一套完整的解决方案。

这类问题通常发生在以下场景：

本地部署的Qwen3-14b_int4_awq模型服务已启动（如vllm服务）
OpenClaw配置了正确的模型地址和端口
但实际调用时出现连接超时、认证失败或响应异常

2. 基础环境检查

2.1 模型服务健康状态验证

首先需要确认模型服务本身是否正常运行。在终端执行：

curl -X POST http://localhost:8000/v1/completions \ -H "Content-Type: application/json" \ -d '{"model": "Qwen3-14b_int4_awq", "prompt": "你好"}'

预期应返回类似如下的JSON响应：

{ "id": "cmpl-3qTm4wQX3X7X", "object": "text_completion", "created": 1689382791, "model": "Qwen3-14b_int4_awq", "choices": [ { "text": "你好！有什么我可以帮助你的吗？", "index": 0, "logprobs": null, "finish_reason": "length" } ] }

如果这一步就失败，说明问题出在模型服务本身，需要检查：

vllm服务是否正常启动（ps aux | grep vllm）
端口是否被正确监听（netstat -tulnp | grep 8000）
模型路径是否正确（检查vllm启动命令中的--model参数）

2.2 OpenClaw配置检查

确认模型服务正常后，检查OpenClaw配置文件（通常位于~/.openclaw/openclaw.json）：

{ "models": { "providers": { "qwen-local": { "baseUrl": "http://localhost:8000/v1", "apiKey": "EMPTY", "api": "openai-completions", "models": [ { "id": "Qwen3-14b_int4_awq", "name": "Local Qwen3", "contextWindow": 32768 } ] } } } }

特别注意：

baseUrl必须包含/v1路径（vllm的标准接口路径）
apiKey可留空或填任意值（除非服务端启用了认证）
models.id必须与模型服务注册的名称完全一致

3. 常见错误与解决方案

3.1 连接超时（ConnectionTimeout）

现象：OpenClaw日志显示ETIMEDOUT或ECONNREFUSED

排查步骤：

检查网络连通性：
```
telnet localhost 8000
```
如果无法连接，可能是：
- 防火墙阻止了端口（检查ufw或iptables规则）
- 服务绑定到了127.0.0.1而非0.0.0.0
测试curl请求延迟：
```
time curl -X POST http://localhost:8000/v1/completions...
```
如果响应时间超过30秒，可能需要：
- 调整vllm的--max-num-seqs参数减少并发
- 检查GPU显存是否不足（nvidia-smi）

3.2 认证失败（401 Unauthorized）

现象：日志显示401状态码

解决方案：

如果服务端启用了API Key认证：
- 在vllm启动时添加--api-key your-key
- 在OpenClaw配置中填写相同的apiKey
临时解决方案（不推荐生产环境）：
```
# vllm启动参数 --disable-api-key-auth
```

3.3 模型未找到（404 ModelNotFound）

现象：错误提示"error": "Model Qwen3-14b_int4_awq not found"

排查重点：

检查vllm启动命令中的--model参数路径是否正确
确认模型文件夹包含：
- config.json
- model-00001-of-00002.safetensors等权重文件
在OpenClaw配置中检查models.id是否与config.json中的_name_or_path完全一致

4. 高级调试技巧

4.1 详细日志获取

在OpenClaw网关启动时添加调试参数：

openclaw gateway start --log-level debug

关键日志线索：

[ModelRouter]开头的模型路由记录
[HTTPClient]显示的完整请求/响应
[Error]标记的异常堆栈

4.2 流量抓包分析

对于复杂网络问题，可以使用mitmproxy：

mitmproxy --mode reverse:http://localhost:8000 -p 8080

然后将OpenClaw的baseUrl改为http://localhost:8080/v1，所有流量将通过代理中转，方便查看原始报文。

5. 配置优化建议

经过实践验证的稳定配置方案：

{ "models": { "providers": { "qwen-optimized": { "baseUrl": "http://localhost:8000/v1", "apiKey": "EMPTY", "api": "openai-completions", "requestTimeout": 300000, "retry": { "attempts": 3, "delay": 1000 }, "models": [ { "id": "Qwen3-14b_int4_awq", "name": "Optimized Qwen3", "contextWindow": 32768, "parameters": { "temperature": 0.7, "max_tokens": 1024 } } ] } } } }

关键优化点：