QClaw 模型接入实战：E14-04CD 上的三个致命坑点

dctc_shouhuzhe

## 测试环境

机型：ThinkPad E14-04CD（Intel Core 5-220H / 16G+16G / 1T SSD / 集显 / Win11）
测试对象：QClaw 本地部署版本 v2.4.x
系统环境：Windows 11 家庭版 + WSL2 Ubuntu 22.04

---

## 前置条件

在 E14-04CD 上部署 QClaw 前，需确保 WSL2 已开启虚拟化支持并分配足够内存。建议分配 8GB 以上，否则模型加载时会触发 OOM。PowerShell 执行：

```powershell
wsl --shutdown
wsl --update
```

WSL2 内存分配需要在 `.wslconfig` 中手动设置，默认会动态占用高达 50% 的物理内存，这对于只有 16GB 内存的 E14-04CD 来说会导致主机系统swap频繁。推荐配置如下：

```ini
[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true
```

---

## 坑点一：API Base URL 末尾斜杠

QClaw 接入第三方模型时，配置文件中 `api_base` 字段最常被写错。这个坑之所以危险，是因为它不会触发任何报错，QClaw 正常启动、正常连接，但模型推理永远返回空响应。

错误写法：

```yaml
api_base: "http://192.168.0.66:11434/v1/"
```

正确写法：

```yaml
api_base: "http://192.168.0.66:11434/v1"
```

末尾的 `/` 会导致 QClaw 拼接路径时出现双重斜杠，Ollama 返回 404。实测中，E14-04CD 的 WSL2 网络栈对这类路径问题尤为敏感，直连 Windows 宿主机时反而能复现。

排查方式：开启 QClaw debug 模式，观察请求日志中的 actual URL。

```bash
qclaw --log-level debug
```

### 原理分析

Ollama 的 API 设计严格遵循 REST 规范，其路由定义为 `/api/chat`、`/api/generate` 等。当 QClaw 拼接 `api_base + "/v1/chat/completions"` 时，若 `api_base` 末尾已带 `/`，结果变成 `//v1/chat/completions`，这是无效路径。Windows 原生网络栈对这类路径有容错处理，而 WSL2 的轻量化网络实现则严格执行规范，导致请求直接被拒绝。

---

## 坑点二：ollama run 与 API 模型名不匹配

E14-04CD 硬件限制决定了只能跑量化后的模型。接入时模型名需与 `ollama list` 输出一致。

常见错误：在 QClaw 配置里写 `model: "qwen2.5-7b"`，但实际模型标签是 `qwen2.5-7b-q4_0`。

```bash
ollama list
```

配置文件中必须填写完整标签名，否则 QClaw 会尝试拉取新模型，耗尽 E14 并不宽裕的磁盘空间（1T SSD 但分区后D盘常只剩 100GB 左右）。

推荐量化模型（适配 E14-04CD 集显 8GB 共享显存上限）：

| 模型 | 量化等级 | 体积 | 适用场景 | 首token延迟 |
|------|----------|------|----------|-------------|
| qwen2.5-3b-q4_0 | Q4_0 | 2.1GB | 开发调试、快速迭代 | 1.8s |
| phi-3-mini-q4_0 | Q4_0 | 2.3GB | 中英双语、轻量级任务 | 2.1s |
| llama3.2-3b-q4_0 | Q4_0 | 2.0GB | 英文为主、长文本处理 | 1.9s |
| qwen2.5-1.5b-q4_0 | Q4_0 | 1.1GB | 边缘部署、极致轻量化 | 0.9s |

### 量化原理简述

量化（Quantization）是通过降低模型权重精度来减少显存占用的技术。Q4_0 表示 4-bit 量化，原始 FP16 的 7B 模型需要约 14GB 显存，量化后仅需 4GB 左右。代价是模型输出质量会有轻微下降，但在 E14-04CD 这种集显机型上，量化是唯一可行的运行方案。

---

## 坑点三：环境变量代理冲突

E14-04CD 多数时间挂在内网，但偶尔需要通过代理访问外部 API。QClaw 对 `HTTP_PROXY` / `HTTPS_PROXY` 的处理存在已知顺序问题。

症状：配置检查全部通过，但模型推理超时。

根因：QClaw 启动时优先读取系统环境变量，若代理地址填写为 `http://127.0.0.1:7890` 而 Clash 未以 TUN 模式运行，流量根本出不去。

解决方案：在 QClaw 的 `config.yaml` 中显式声明 `no_proxy` 排除内网段：

```yaml
environment:
  HTTP_PROXY: "http://192.168.0.31:7890"
  HTTPS_PROXY: "http://192.168.0.31:7890"
  NO_PROXY: "localhost,127.0.0.1,192.168.0.0/24"
```

E14-04CD 的 Realtek 蟹蟹网卡对 UDP 代理支持一般，建议 HTTP 代理走 TCP 直连。

### 内网穿透特殊注意事项

E14-04CD 经常需要同时访问内网 Ollama 服务（192.168.0.66）和外部 API。若代理配置不当，所有流量都会被劫持到代理服务器，内网请求将完全失败。建议在 `NO_PROXY` 中明确列出所有内网段：

```yaml
NO_PROXY: "localhost,127.0.0.1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12"
```

---

## 性能实测

E14-04CD 的 Core 5-220H 在纯 CPU 模式下运行 qwen2.5-3b-q4_0，首 token 延迟约 1.8s，生成速度 12-15 tokens/s。集显参与计算后（OpenVINO 加速），生成速度可提升至 20 tokens/s 左右，但 CPU 占用率会瞬间飙到 95%+，风扇噪音明显。

| 测试场景 | CPU模式 | OpenVINO加速 |
|----------|---------|--------------|
| 首token延迟 | 1.8s | 1.5s |
| 生成速度 | 12-15 tok/s | 18-22 tok/s |
| CPU占用率 | 75-85% | 95%+ |
| 风扇噪音 | 可接受 | 明显 |

结论：E14-04CD 适合跑 3B 以内的量化模型做开发调试，生产级使用建议上独立显卡机型。

### Core 5-220H 集显性能分析

Intel Core 5-220H 是 Raptor Lake 架构的移动端处理器，集成的 Intel UHD Graphics 虽然支持 OpenVINO 加速，但在实际模型推理中受限于内存带宽（DDR5 5200 单通道约 40GB/s），无法完全释放量化模型的推理速度。若必须使用集显模式，建议将 WSL2 内存降低至 6GB，让主机保留更多内存给 OpenVINO 缓存。

---

## 总结

QClaw 在 E14-04CD 上跑模型接入，三个高频坑分别是 URL 斜杠、模型名不一致、代理变量冲突。排查顺序建议按「配置 → 模型列表 → 网络」来走，大概率能在 10 分钟内定位问题。

快速排查清单：

1. [ ] 确认 api_base 末尾无斜杠
2. [ ] 确认模型名与 `ollama list` 完全一致
3. [ ] 确认代理变量已排除内网段
4. [ ] 确认 WSL2 内存分配 ≥ 8GB
5. [ ] 确认 Ollama 服务正常响应 `/api/tags`

遵循以上检查流程，可有效避免在 E14-04CD 这类资源受限机型上浪费时间，快速进入模型调试阶段。

---

相关阅读：QClaw 与 Ollama 共存配置方案（待续）

---

有什么具体踩坑经历，评论区见。

---

【标签】
Thinkpad, IBM, X1 Carbon, AI开发, Ollama部署, 本地大语言模型, VSCode配置, 华强北, 选购指南

【相关阅读】
- Thinkpad T14 深度评测：商务本的性能极限在哪里
- OpenClaw多模型集成配置指南
- 华强北Thinkpad港版购买防坑指南