# OpenClaw + vLLM 本地部署踩坑实录：从能跑到能用
{{< music auto="https://music.163.com/#/playlist?id=12472829847" >}}
> 这篇文章记录的是我从今天早上开始，一路把 **Cherry Studio + OpenClaw + vLLM + Qwen2.5-7B-Instruct-AWQ** 真正跑通的全过程。它不是那种“官方教程式一把过”的文章，而是一篇完整的踩坑日志：从模型连不上、速度慢得离谱、上下文爆掉，到最后能正常做 Agent 对话，我基本把本地部署里最常见的坑都踩了一遍。
## 一、我的目标到底是什么
一开始我的目标其实并不是“本地能聊就行”，而是想做成这样一条完整链路：
```text
Cherry Studio
↓
OpenClaw
↓
vLLM API Server
↓
Qwen 本地模型
```
也就是说，Cherry Studio 只是前端；OpenClaw 负责 Agent、工具调用和自动化；真正的大脑由 vLLM 提供推理服务。
这和直接在 Cherry Studio 里连一个模型最大的区别是：
- 直连模型，只是聊天。
- 接上 OpenClaw，才是“AI 能帮你做事”。
## 二、硬件和环境
我的本地环境：
- Windows + WSL Ubuntu 24.04
- NVIDIA RTX 4070 12GB
- Cherry Studio
- OpenClaw Gateway
- vLLM
- Qwen2.5-7B-Instruct / Qwen2.5-7B-Instruct-AWQ
后面踩坑以后我才真正意识到：**12GB 显存跑原版 7B，不等于能舒服地跑 Agent 场景。**
## 三、第一阶段：模型接通了，但体验一塌糊涂
最开始我做的事情，其实是先把 Cherry Studio 直接接到 vLLM。
这一步不难，关键有两个点：
1. Cherry Studio 里新增一个 OpenAI 兼容服务。
2. API 地址填 `http://127.0.0.1:8001/v1`。
但很快就发现一个大坑：**Cherry Studio 能连上，不代表 OpenClaw 能用。**
原因是 vLLM 返回的模型名和 Cherry Studio / OpenClaw 发送的模型名不一致。
比如：
- vLLM 实际模型 ID 可能是完整路径：
```text
/home/administrator/models/Qwen2.5-7B-Instruct-AWQ
```
- 但前端可能发送的是：
```text
Qwen2.5-7B-Instruct-AWQ
```
结果就是 Cherry Studio 直接聊天正常，OpenClaw 调用时报 400 或 404。
后来我的解决方式是：在 vLLM 启动时加上 `--served-model-name`，让它认前端发送的模型名。
## 四、第二阶段：为什么 7B 会慢成 1 tokens/s
最初跑原版 Qwen2.5-7B-Instruct 的时候，速度慢到让我怀疑人生。
日志里经常出现这样的情况：
```text
Avg generation throughput: 1.1 tokens/s
```
这时候我一度非常崩溃，因为理论上 vLLM 是高性能推理框架，按理说不应该这样。
后来排查才发现，问题并不是 vLLM 本身，而是下面几个因素叠在一起：
### 1. 原版 7B 权重太大
原版模型权重装载时，显存占用太高，12GB 显卡非常吃紧。
### 2. 我一开始用了 CPU offload
为了让它能启动，我用过这样的参数：
```bash
python -m vllm.entrypoints.openai.api_server --model "/mnt/d/model/Qwen/Qwen2.5-7B-Instruct" --host 0.0.0.0 --port 8001 --max-model-len 3072 --gpu-memory-utilization 0.6 --cpu-offload-gb 8 --enforce-eager
```
它确实能跑，但代价就是：**GPU 没有真正把活全干掉，部分权重和缓存被甩到 CPU / 内存上去了。**
于是，能用，但极慢。
### 3. 模型放在 `/mnt/d/`
这一步也很伤。因为 `/mnt/d/` 是 WSL 访问 Windows 文件系统，I/O 性能不如 Linux 原生目录。
所以后来我把量化模型下载到：
```text
/home/administrator/models/
```
这一步对启动速度和稳定性都有帮助。
## 五、第三阶段：真正的分水岭，是换成 AWQ
这一整天里最关键的决定，不是继续死磕原版 7B，而是换成：
```text
Qwen2.5-7B-Instruct-AWQ
```
换 AWQ 的意义非常直接：
- 权重显著变小。
- 12GB 显存终于能真正装得下。
- 给 KV cache 留出空间。
- 响应速度开始进入“可用区间”。
下载模型时，我还遇到了 WSL 外网不稳、Hugging Face 大文件中断的问题。最后改用国内镜像和更稳的下载方式，才顺利把模型放到本地 Linux 目录。
## 六、第四阶段：vLLM 能跑，不等于 OpenClaw 能用
把模型跑起来后，我以为任务结束了，实际上真正的坑才刚开始。
### 坑 1：模型名不匹配
OpenClaw 报错：
OpenClaw 发给 vLLM 的模型名是完整路径！而不是短名字：
```text
/home/administrator/models/Qwen2.5-7B-Instruct-AWQ
```
但 vLLM 当前只认短名字 Qwen2.5-7B-Instruct-AWQ（因为我们加了 --served-model-name Qwen2.5-7B-Instruct-AWQ）。
```text
The model '/home/administrator/models/Qwen2.5-7B-Instruct-AWQ' does not exist.
```
解决方法是：--served-model-name 改成完整路径（和 OpenClaw 保持一致）
```bash
--served-model-name "/home/administrator/models/Qwen2.5-7B-Instruct-AWQ"
```
### 坑 2：工具调用没打开
接着又遇到：
```text
"auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set
```
这说明 OpenClaw 并不是普通聊天，它会给模型传 `tool_choice: auto`。
因此 vLLM 还必须加上：
```bash
--enable-auto-tool-choice --tool-call-parser hermes
```
两个参数解释：
* --enable-auto-tool-choice：允许 vLLM 处理 tool_choice: "auto" 请求。
* --tool-call-parser hermes：告诉 vLLM 用 hermes 格式来解析工具调用。Qwen2.5 系列模型使用 Hermes 格式的 Function Call，所以填 hermes 即可。
这两个参数加上之后，OpenClaw 就能发工具调用请求了，这是 Agent 自动干活（比如帮你新建文件、打开浏览器）的核心能力。
### 坑 3：上下文爆炸
当 OpenClaw 带着系统提示词、工具定义、历史消息一起请求时，日志里直接出现了典型的上下文溢出：
```text
You passed 62513 input characters and requested 8192 output tokens.
However, the model's context length is only 8192 tokens...
```
这时候我才意识到，**Agent 场景和普通聊天完全不是一个级别的上下文压力。**
于是又把：
```bash
--max-model-len 8192
```
提升成了：
```bash
--max-model-len 32768
```
## 七、最终能用的启动命令
折腾到最后，对我这套环境来说，真正能用的一条命令大概是这样：
```bash
VLLM_USE_V1=0 vllm serve /home/administrator/models/Qwen2.5-7B-Instruct-AWQ --host 0.0.0.0 --port 8001 --quantization awq --dtype float16 --gpu-memory-utilization 0.90 --max-model-len 32768 --enforce-eager --served-model-name "/home/administrator/models/Qwen2.5-7B-Instruct-AWQ" --enable-auto-tool-choice --tool-call-parser hermes
```
这里有几个关键点：
- `VLLM_USE_V1=0`：回退旧引擎，避免某些版本下 AWQ 慢得离谱。
- `--quantization awq`：真正让 12GB 显存可用。
- `--served-model-name`：解决前端与后端模型名不一致。
- `--enable-auto-tool-choice`：让 OpenClaw 的工具调用逻辑生效。
- `--max-model-len 32768`：防止 Agent 上下文一轮就炸。
## 八、跑通之后，我对这套方案的真实评价
### 1. Cherry Studio 直连 vLLM：能用，而且还不错
如果只是普通聊天、简单代码、小任务，本地 7B-AWQ 足够用了。
### 2. OpenClaw + 7B：能连上，但不适合当“总指挥”
这也是今天最现实的结论。
OpenClaw 场景下，模型不只是回答问题，它还要：
- 理解系统提示词
- 维护长上下文
- 解析工具定义
- 判断何时调用工具
- 多轮保持角色与记忆一致
这些要求叠加起来，对一个 7B 模型来说太勉强了。
表现出来就是：
- 人设飘
- 指代混乱
- 记忆不稳
- 明明连通了，但“智商”不够像一个可靠 Agent
所以最后我的判断是：
> **7B 适合做执行层，不适合做 Agent 主脑。**
## 九、我最后给自己的架构建议
如果你和我一样，手上只有一张 12GB 显存的 4070，那么最合理的方案其实是双轨制：
### 方案 A：本地高速小模型
用途：
- Cherry Studio 普通聊天
- 文本改写
- 简单代码
- 轻量工具调用
模型：
- vLLM + Qwen2.5-7B-Instruct-AWQ
### 方案 B：更强模型做 OpenClaw 主脑
用途：
- 真正的 Agent 工作流
- 多轮复杂工具调用
- 稳定记忆和更强逻辑
模型：
- LM Studio / 线上 API 上的更强模型
也就是说，不必执着于“一套配置解决所有问题”。
## 十、顺手想到的一条路：把 OpenClaw 放到云上
我手里还有一台已经续费三年的京东云，配置不高：2 核 CPU、4GB 内存、Ubuntu 24.04.3，上面还跑着 WordPress 导航站。
分析之后，我也想明白了：
- 它不适合跑 vLLM 或本地模型。
- 但可以考虑跑一个 **接线上 API 的 OpenClaw**。
这样的话，本地电脑继续跑需要 GPU 的事情；云服务器负责 OpenClaw 网关、轻量逻辑、对接线上模型，可能反而更稳。
这条路线，我准备后面再继续折腾。
## 十一、今天最大的收获
今天这一整天，说白了不是“我把一个模型跑起来了”，而是我把整套链路真正理解了：
- Cherry Studio 是前端。
- OpenClaw 是 Agent / 编排层。
- vLLM 是模型 API 服务。
- 小模型和大模型不是替代关系，而是分工关系。
折腾的过程中最让我改观的一点是：
**本地部署真正难的，从来不是把模型启动，而是把“能跑”变成“能用”。**
如果只是截图发朋友圈，“本地大模型已部署成功”很容易；
但想让它真的变成一套自己每天愿意用的工具，那才是工程开始的地方。
## 十二、给后来者的一些建议
如果你也准备走这条路，我建议你少走弯路：
1. 12GB 显存不要硬磕原版 7B 当 Agent 主脑。
2. 先上量化模型，再谈体验。
3. OpenClaw 场景一定要考虑工具调用和长上下文。
4. Cherry Studio 能聊通，不代表 OpenClaw 能跑通。
5. 如果你要的是“真正好用的 Agent”，优先升级模型质量，而不是一味抠参数。
## 结尾
今天这套链路最终确实打通了。
但比“打通”更重要的是，我终于知道了每一层到底在干什么，也知道了 7B 在这套体系里的边界。
所以这篇文章，就当作一次完整的踩坑备忘：
- 哪些坑一定会踩；
- 哪些参数必须改；
- 哪些期待应该尽早放下；
- 以及，什么样的架构才真的适合我自己。
如果你也在折腾 Cherry Studio、OpenClaw、vLLM 或本地 Agent，希望这篇记录能帮你少熬一点夜。
***
--全文完--
***
{{< admonition type=question title="若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊： 《内容已折叠，点击展开》 " open=false >}}
{{< typeit tag=h4 >}}
**“同频之人，终会相遇；同行之路，终有光亮。愿与身处同境、灵魂同频、砥砺前行的你相遇相伴，倾听彼此的故事与困惑，分享心路与感悟，在逆境中自救破局的路上彼此陪伴、相互照亮、同行向前,一起走向重生与新生。”**...
{{< /typeit >}}
点击跳转：关于我
{{< /admonition >}}
***
{{< admonition type=success title="希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。 《内容已折叠，点击展开》" open=false >}}
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
转载请注明来自https://oklife.me。
{{< /admonition >}}
{{< /admonition >}}