vLLM服务连接问题排查与解决方案

1. 问题现象与初步分析

最近在部署OpenClaw对接本地vLLM服务时，遇到了经典的"Connection error"报错。这个错误表面看起来简单，但实际上可能涉及网络配置、服务状态、协议兼容性等多个层面的问题。作为经历过多次类似问题的老手，我决定把这次完整的排查过程和解决方案记录下来。

具体现象是：当OpenClaw尝试连接本地部署的vLLM服务时，立即返回"Connection error"错误，没有任何其他详细信息。服务端日志也没有显示任何接入请求。这种情况通常意味着连接在TCP层就已经失败了，甚至还没有到达应用层协议交互的阶段。

2. 基础环境检查

2.1 网络连通性验证

首先需要确认最基本的网络连通性。我使用telnet工具测试了vLLM服务端口是否可达：

bash复制telnet 127.0.0.1 8000

如果连接被拒绝，说明服务可能没有正常运行；如果超时，则可能是防火墙拦截。在我的案例中，telnet连接直接被拒绝，这表明服务可能没有监听预期的端口。

2.2 服务状态确认

接下来检查vLLM服务是否正常运行：

bash复制ps aux | grep vllm
netstat -tulnp | grep 8000

发现vLLM进程确实在运行，但没有监听8000端口。这提示我们可能需要检查服务的启动参数。

3. 配置深度检查

3.1 vLLM启动参数验证

vLLM服务通常通过以下方式启动：

bash复制python -m vllm.entrypoints.api_server --model [model_name] --port 8000

检查实际使用的启动命令，发现确实指定了8000端口。但为什么netstat看不到监听呢？

3.2 服务绑定地址检查

进一步检查发现，vLLM默认只绑定到127.0.0.1地址。这意味着只有本机可以访问。而OpenClaw可能是通过容器或另一台机器访问的。修改启动参数：

bash复制python -m vllm.entrypoints.api_server --model [model_name] --port 8000 --host 0.0.0.0

这样服务就会监听所有网络