OpenClaw 调用本地大模型（Qwen3-32B-AWQ）完整指南

OpenClaw 调用本地模型的核心是「三对齐」：vLLM --served-model-name ≡ OpenClaw model.id（模型标识对齐）vLLM --max-model-len ≡ OpenClaw contextWindow（上下文对齐）vLLM 工具调用参数 ≡ OpenClaw 工具配置（工具调用对齐）按本文配置，你的本地 Qwen3-32B-AWQ 模型可稳定对接 Ope

小白编代码

455人浏览 · 2026-05-06 15:03:28

小白编代码 · 2026-05-06 15:03:28 发布

一、核心概念解析（必看，避坑关键）

1.1 Token（模型计数单位）

Token 是大模型处理文本的最小计算单位，≠ 纯汉字个数，换算规则如下：

中文：1 个汉字 ≈ 1.4 个 Token（例：700 个汉字 ≈ 1000 个 Token）
英文/标点/符号：2~3 个字母 = 1 个 Token（例："hello" = 2 个 Token）
核心作用：模型的“记忆力”“输出长度”均以 Token 为单位限制，超出则报错。

1.2 上下文窗口（contextWindow）

模型一次性能“记住”的所有内容总量（单位：Token），即模型的“记忆力上限”，对应 vLLM 启动参数 --max-model-len，两者必须完全一致，否则会出现上下文溢出。

关键值：contextWindow = 32768（Qwen3-32B 原生支持，适配 OpenClaw 系统提示词占用）。

1.3 关键参数换算

结合 OpenClaw 特性，你的模型 Token 分配如下（核心公式）：

模型总上限（32768） - 固定系统文案（12289） - 最大输出（8192） = 剩余自由对话（12287 Token）

模型总上限：32768 Token（Qwen3-32B 原生 32K 上下文，单卡 L20 46G 完全承载）
固定系统文案：12289 Token（OpenClaw 自带，包含工具调用规则、Agent 运行逻辑，启动即占用，不可修改）
最大输出（maxTokens）：8192 Token（AI 单次最多能回复的内容额度）
剩余自由对话：12287 Token ≈ 8776 个汉字（足够日常多轮对话、工具调用）

二、完整调用流程（从部署到可用，一步到位）

2.1 前提条件

硬件：单张 L20 46G GPU（健康可用，使用 GPU0）
软件：Docker、vLLM（最新版）、OpenClaw（≥v2026.4.8）
模型：Qwen3-32B-AWQ 量化模型

2.2 步骤1：部署本地 vLLM 模型服务（核心载体）

vLLM 是高性能本地模型服务，提供 OpenAI 兼容接口，适配 OpenClaw 调用，步骤如下：

2.2.1 创建/修改 vLLM 启动脚本（qwen-gpu0.sh）

#!/bin/bash
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

# 启动 vLLM 服务（仅使用 GPU0，开启工具调用）
docker run -d \
  --name Qwen3-32B \
  --restart=unless-stopped \
  --gpus '"device=0"' \    #指定0号显卡
  --ipc=host \
  -p 8002:8000 \
  -v /home/models/Qwen3-32B-AWQ:/models/Qwen3-32B-AWQ \
  vllm/vllm-openai:latest \
  --model /models/Qwen3-32B-AWQ \
  --served-model-name Qwen3-32B-AWQ \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.85 \
  --max-model-len 32768 \
  --max-num-seqs 4 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes \
  --enforce-eager

2.2.2 启动 vLLM 服务

# 赋予脚本执行权限
chmod +x qwen-gpu0.sh

# 启动服务
./qwen-gpu0.sh

# 验证启动是否成功（出现 Application startup complete 即为正常）
docker logs -f Qwen3-32B

2.3 步骤2：配置 OpenClaw 连接本地模型（关键配置）

修改 OpenClaw 配置文件 ~/.openclaw/openclaw.json，重点配置 models.providers 节点，确保与 vLLM 参数完全对齐。

2.3.1 完整配置文件（仅保留核心节点，其余可保留默认）

{
  "models": {
    "mode": "merge",
    "providers": {
      "vllm": {
        "baseUrl": "http://服务器IP:指定的端口/v1",  // 本地 vLLM 服务地址，必须带 /v1
        "apiKey": "vllm-local",  // 本地服务无需校验，非空即可
        "api": "openai-completions",  // 固定值，适配 OpenAI 兼容接口
        "models": [
          {
            "id": "Qwen3-32B-AWQ",  // 必须与 vLLM --served-model-name 完全一致
            "name": "Qwen3-32B-AWQ",  // 显示名称，可自定义
            "reasoning": false,  // 关闭，避免空回复、解析异常
            "input": ["text"],  // 输入类型，固定为 text
            "cost": {  // 本地模型无成本，全部设为 0
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 32768,  // 与 vLLM --max-model-len 严格一致
            "maxTokens": 8192  // 单次最大输出，与前文换算匹配
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen3-32B-AWQ"  // 默认调用本地模型，格式：提供商名称/模型ID
      },
      "models": {
        
        "vllm/Qwen3-32B-AWQ": {
          "alias": "Local-32B"  // 自定义模型别名，方便识别
        }
      }
    },
    "list": [
      {
        "id": "main",
        "model": "vllm/Qwen3-32B-AWQ"  // 主智能体指定调用本地模型
      }
      
    ]
  },
 
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "5678c847fb835812073c0840a39e3e7e6e3db893360c345"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "controlUi": {
      "allowInsecureAuth": true
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send",
        "sms.search"
      ]
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "profile": "coding"
  },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "boot-md": {
          "enabled": true
        },
        "bootstrap-extra-files": {
          "enabled": true
        },
        "command-logger": {
          "enabled": true
        },
        "session-memory": {
          "enabled": true
        }
      }
    }
  },
  "wizard": {
    "lastRunAt": "2026-04-16T02:23:37.469Z",
    "lastRunVersion": "2026.4.12",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "meta": {
    "lastTouchedVersion": "2026.4.12",
    "lastTouchedAt": "2026-04-16T02:23:37.614Z"
  },
  "auth": {
    "profiles": {
      "qwen:default": {
        "provider": "qwen",
        "mode": "api_key"
      },
      "vllm:default": {
        "provider": "vllm",
        "mode": "api_key"
      },
      "ollama:default": {
        "provider": "ollama",
        "mode": "api_key"
      },
      "vllm-vl:default": {
        "provider": "vllm-vl",
        "mode": "api_key"
      }
    }
  },
  "plugins": {
    "entries": {
      "qwen": {
        "enabled": true
      },
      "vllm": {
        "enabled": true
      },
      "ollama": {
        "enabled": true
      }
    }
  }
}

2.4 步骤3：重启 OpenClaw 生效配置

配置修改后，必须重启 OpenClaw 服务，否则配置不生效（清空缓存，避免读取旧配置）：

#重启网关
openclaw gateway restart

2.5 步骤4：验证调用是否成功

在 OpenClaw 对话窗口执行以下命令，验证本地模型是否可用：

# 1. 查看可用模型（确认 vllm/Qwen3-32B-AWQ 存在）
/models

# 2. 查看模型状态（确认上下文窗口为 32768）
/status

# 3. 发送简单提问（验证无报错）
你好，测试本地模型调用

✅ 成功标志：无 400 报错、无上下文溢出提示，AI 正常回复，vLLM 日志无异常堆栈。

三、关键配置详解（避坑核心，重中之重）

3.1 vLLM 启动关键参数（qwen-gpu0.sh）

参数	作用	配置值	错误后果
--served-model-name	模型服务名称，OpenClaw 调用的唯一标识	Qwen3-32B-AWQ	与 OpenClaw 中 model.id 不一致，导致找不到模型
--max-model-len	模型上下文上限，即 contextWindow	32768	与 OpenClaw 配置不一致，导致上下文溢出、400 报错
--gpus '"device=0"'	指定使用的 GPU，避开故障卡	device=0
--tool-call-parser hermes	工具调用解析器，适配 OpenClaw 工具格式	hermes	工具调用失败、格式不兼容
--enforce-eager	修复 AWQ 量化模型崩溃问题	启用	模型启动崩溃、日志报错

3.2 OpenClaw 核心配置（openclaw.json）

配置节点	作用	配置值	错误后果
models.providers.vllm.baseUrl	本地 vLLM 服务地址	http://服务器IP:端口/v1	地址错误、不带 /v1，导致连接超时、404 报错
models.providers.vllm.api	接口类型，适配 vLLM 接口	openai-completions	接口不兼容，导致调用失败、格式错误
models.providers.vllm.models[0].id	模型唯一标识，与 vLLM 对应	Qwen3-32B-AWQ	与 --served-model-name 不一致，找不到模型
contextWindow	模型上下文窗口，与 vLLM 对齐	32768	上下文溢出、400 报错，无法正常对话
maxTokens	AI 单次最大输出长度	8192	过大导致溢出，过小导致回复被截断
agents.defaults.model.primary	默认调用的本地模型	vllm/Qwen3-32B-AWQ	配置错误，默认调用云端模型，而非本地模型

四、常见问题排查（避坑指南）

错误现象	核心原因	解决方案
上下文溢出（input_tokens=12289，总 tokens 超 16384）	模型总上限设为 16384，不足以容纳系统文案+输出	vLLM 改 --max-model-len=32768，OpenClaw 改 contextWindow=32768
400 报错（Model context window too small）	OpenClaw contextWindow 小于 OpenClaw 最低要求（16000）	确保 contextWindow ≥ 16000，且与 vLLM --max-model-len 一致
找不到模型（requestedModel 不匹配）	OpenClaw 中 model.id 与 vLLM --served-model-name 不一致	统一改为 Qwen3-32B-AWQ，重启服务
连接超时、网页解析失败（baseUrl 相关）	baseUrl 错误、vLLM 未启动、端口未开放	确认 vLLM 正常运行，baseUrl 为 http://服务器IP:端口/v1
vLLM 启动报错（unrecognized arguments）	使用了旧版参数（如 --disable-async-output-proc）	删除无效参数，使用本文提供的最新启动脚本

五、最佳实践（稳定运行保障）

版本对齐：保持 OpenClaw ≥v2026.4.8、vLLM ≥v0.4.0，避免版本兼容问题。
显存优化：L20 46G 单卡，设置 --gpu-memory-utilization=0.85，预留部分显存，避免爆显存。
上下文管理：长对话定期执行 /reset 或 /new 清理历史，避免对话累积导致溢出。
日志排查：遇到错误时，优先查看 OpenClaw 日志（openclaw logs）和 vLLM 日志（docker logs -f Qwen3-32B）。
工具调用：确保 vLLM 启用 --enable-auto-tool-choice 和 --tool-call-parser hermes，适配 OpenClaw 工具调用格式。