1. 为什么能跑的模型不等于能用的Agent——工具链适配的本质1.1 大模型服务只是嘴Agent 还需要手前两篇把 vLLM 服务跑起来之后模型能流畅对话很多人就以为大功告成结果一接 OpenClaw 就翻车助手回复正常但没有任何工具调用或者工具调用返回了一堆 JSON 却解析失败或者 Agent 循环跑两轮就直接上下文爆炸。这不是模型不行而是工具链没适配。vLLM 本质上是一个文本进、文本出的推理服务它只负责把 token 高效地算出来。而 OpenClaw 这类 Agent 框架需要的是一种约定好的结构化交互什么时候调用工具、调用哪个工具、参数怎么传、工具结果怎么回填。这两者之间隔着一层工具协议也就是本篇文章标题里的工具链适配。打个比方。你招了一个能力很强的实习生他满肚子知识但他不会填你公司的工单系统。你要么教他填工单的固定格式要么给他配一个助理帮他转述。工具链适配做的就是教格式 配助理这两件事缺一件再好用的模型也变不成一个能干活的大脑。1.2 本地化部署的真正收益点多轮工具调用恰恰是本地化收益最大的场景。云 API 按 token 计费Agent 每轮工具调用都会把完整历史重新发一遍上下文很快堆到几万 token一次任务跑下来费用相当可观本地 vLLM 没有这个计费压力数据也不出内网可以放开跑多轮链路。对比维度云 API本地 vLLM数据隐私需要脱敏和额外的数据合规约束数据留在本机或内网单任务成本随 token 线性增长只花电费和硬件折旧工具调用可控性依赖平台策略可以自定义 template、parser 和结构化输出运维成本低需要自己处理显存、并发、模型版本代价也明显协议兼容、函数调用格式、上下文管理这些工程问题全落在自己身上。前两篇解决了模型能不能跑这一篇解决的是模型跑起来之后OpenClaw 能不能把它当大脑用。这一步如果没打通vLLM 部署得再好也只是一个昂贵的聊天机器人。1.3 适配发生在三个层面我习惯把适配拆成三层排查问题也按这个顺序来协议层OpenClaw 通过 OpenAI 兼容的 Chat Completions 接口访问 vLLMbase_url、模型名、鉴权字段必须完全对得上。模型能力层模型要能输出符合规范的 tool_call 结构或者至少能输出稳定的 JSON这依赖 vLLM 的 tool-call-parser 和 chat template。策略层系统提示词要说明工具的使用边界工具描述要写得让模型看得懂工具结果回传时要给模型足够的上下文。这三个层面只要有一层没对齐表象都是Agent 不会用工具但根因完全不同。后面几个章节就是按这条链路逐层拆开来讲这也是我实际排查问题时的标准路径。2. OpenClaw接入vLLM的接口规范与配置骨架2.1 vLLM侧先约定三件事接 OpenClaw 之前vLLM 启动参数里要先敲定三件事否则后面全是隐性坑。第一是模型对外暴露的名字。vLLM 默认用模型权重目录名作为 model 名但本地模型经常是自命名的所以用--served-model-name指定一个干净的别名方便 OpenClaw 引用。这个别名同时也是后面排错时最容易出问题的地方。第二是工具调用开关。新版 vLLM 支持--enable-auto-tool-choice配合--tool-call-parser指定解析器模型才会在需要时输出标准 tool_call 结构。解析器选型跟模型有关第三节会专门展开。第三是 chat template。很多开源模型自带的 Jinja 模板只处理普通对话遇到 tools 字段直接忽略工具调用就会静默失败。所以要用--chat-template指定一个支持工具渲染的模板。一个典型的启动命令长这样vllm serve /data/models/your-llm \ --served-model-name openclaw-llm \ --port 8000 \ --max-model-len 32768 \ --gpu-memory-utilization 0.88 \ --enable-auto-tool-choice \ --tool-call-parser hermes \ --chat-template ./tool_chat_template.jinja注意--tool-call-parser和--chat-template不是所有模型都能随便配配错了轻则工具调用格式不对重则直接报错。我的建议是先用模型原生支持的 parser 跑通再考虑自定义模板不要一上来就两头都改否则出了问题都不知道该查哪边。2.2 OpenClaw侧Provider配置OpenClaw 的 LLM 连接配置通常长这样YAML 格式字段名因版本略有差异llm: provider: openai-compatible base_url: http://127.0.0.1:8000/v1 api_key: EMPTY default_model: openclaw-llm temperature: 0.1 max_tokens: 4096几个关键说明api_key填EMPTY或任意字符串即可vLLM 默认不校验鉴权但这个字段不能省否则有些客户端请求会因缺少鉴权头而直接失败。base_url最后要带/v1OpenClaw 内部会在它后面拼接/chat/completions路径。default_model必须和 vLLM 的--served-model-name完全一致大小写、连字符都不能差。这里错了最常见的表现是返回404 model not found而不是一个容易理解的模型名不正确。2.3 先做裸验证再上Agent我强烈建议先把 OpenClaw 晾在一边用 curl 和一段小脚本直接验证 vLLM 接口。这样做的核心好处是隔离故障面模型层的问题先解决再怀疑 Agent 层不会两头互相甩锅。裸对话验证curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: openclaw-llm, messages: [{role: user, content: 你好}], max_tokens: 512 }然后单独验证工具调用from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, ) resp client.chat.completions.create( modelopenclaw-llm, messages[{role: user, content: 帮我查一下当前时间}], tools[{ type: function, function: { name: get_current_time, description: 获取当前日期和时间, parameters: { type: object, properties: { timezone: {type: string, description: 时区名称默认Asia/Shanghai} }, required: [] } } }], tool_choiceauto, ) print(resp.choices[0].message)如果这一步能看到tool_calls字段里有完整的 name 和 arguments JSON说明模型层已经通了问题基本锁定在 OpenClaw 配置侧。如果连裸测试都出不来工具调用那先去检查 parser 和 template别急着改 Agent 代码。这个顺序我每次都会强调先裸测再集成。省掉的都是排查时间。3. 工具调用Function Calling的适配细节3.1 vLLM的Tool Calling开关是分模型的--tool-call-parser的取值不是随便选的它对应不同模型家族输出工具调用的格式习惯。常见选项包括hermes、llama3_json、mistral、qwen25、internlm、jamba、granite等。举例来说Hermes 系模型用hermesLlama 3.1 及后续支持原生工具调用的版本从llama3_json开始试比较顺Qwen 系建议看模型版本选qwen25Mistral 系用mistral。具体以你当前 vLLM 版本vllm serve --help列出的支持列表为准。怎么确定你的模型该用哪个最简单的方法查模型文档有没有提到原生支持 OpenAI 风格的 function calling如果没有明确说明就从hermes解析器开始试因为它的容错性相对好。如果你用的模型完全不支持原生工具调用还有一个折中路线不用 vLLM 的 tool-call-parser而是让模型以纯文本方式输出一个 JSON 块再用正则或 JSON 解析器把结果抽出来。这种方式对模型能力要求低但稳定性一般每换一个模型都得调提示词只适合临时过渡。我把 vLLM 的 tool_call 链路理解为一条流水线模型在解码时根据 template 的指引生成一段文本vLLM 再用 parser 把这段文本切分成工具名 参数 JSON。template 是给模型看的parser 是给 vLLM 用的两者缺一就会错位。这也是为什么很多对话正常、工具不通的案例最后都定位在 template 或 parser 上。3.2 Chat Template是绕不开的坎很多开源模型的 chat template 只处理 user/system/assistant 三种角色遇到 tools 字段直接忽略。结果就是模型根本没看见你提供的工具描述自然不知道该调工具。如果你的模型模板不支持工具渲染必须自己写一个 Jinja 模板。核心内容就三部分把 tools 列表渲染进系统消息、按标准格式输出 assistant 的工具调用、把工具结果以 tool 角色回填。一个精简的自定义模板骨架命名为tool_chat_template.jinja{%- for message in messages %} {%- if message[role] system %} ### System: {{ message[content] }} {%- if tools %} You have access to the following tools: {{ tools | tojson }} {%- endif %} {%- elif message[role] user %} ### User: {{ message[content] }} {%- elif message[role] assistant %} {%- if message.tool_calls is defined and message.tool_calls | length 0 %} ### Assistant: |tool_call| {%- for tool_call in message.tool_calls %} {{ {name: tool_call.function.name, arguments: tool_call.function.arguments} | tojson }} {%- endfor %} /|tool_call| {%- else %} ### Assistant: {{ message[content] }} {%- endif %} {%- elif message[role] tool %} ### Tool Result: {{ message[content] }} {%- endif %} {%- endfor %} ### Assistant:这个模板故意写得非常简单主要给初学者一个结构参考。实际使用时我会把分隔符改成模型微调时用的特殊 token而不是随便拿来就用。这里有个很容易踩的坑如果你从网上套了一个开源模板必须确认它的特殊 token 和你的模型 tokenizer 一致否则会解码出乱码或者模型生成一堆无意义的|im_start|之类的内容tool_call 边界完全对不上。3.3 工具Schema设计与Agent侧注册OpenClaw 侧的每个工具最终都会变成 tools 数组里的一项 function schema。schema 写得好不好直接影响模型能不能正确触发。我的几条原则工具名用动词名词比如query_order_status不要用抽象的get_data。description 里写清楚什么时候用而不是做了什么。例如当用户询问订单配送进度时调用比查询订单状态好用得多。参数尽量平铺不要嵌套太深。嵌套对象一旦超过两层很多模型生成 JSON 时就会出现键名错误或引号错位。required字段只保留真正必需的其余都给默认值。模型面对 required 很多的 schema 更容易漏填。一个直观的对比{ name: query_shipping_status, description: 当用户询问订单配送进度、物流轨迹时调用, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号形如SO2025001} }, required: [order_id] } }这个 schema 只有一层嵌套、一个必填字段我实测下来触发率和参数正确率都比大而全的 schema 高很多。另外要保证 OpenClaw 工具注册名和 schema 里的 name 完全一致否则模型会生成一个看起来对但注册表里不存在的调用OpenClaw 会抛 unknown tool 错误。提示如果工具较多建议在系统提示词里附上一句话优先使用提供的工具完成任务不要编造工具不存在的功能。这能显著减少模型硬答的概率。4. 实测踩坑从对话正常到工具调不通的完整排查链路这一节所有坑都是我在实际接入中反复遇到的。我按症状→排查→修复的顺序写方便你对着排查。4.1 症状一该调工具却用自然语言回复现象提示词里明确要求调用工具模型却回了一大段根据我的知识我现在无法获取……之类的自然语言完全没有tool_calls字段。排查链路先裸测确认是不是模型层问题。如果 curl 裸测同样不输出tool_calls跳过 OpenClaw直接查 vLLM。检查--tool-call-parser是否与模型匹配。不匹配时 vLLM 不会把模型输出解析成tool_calls。检查 chat template 是否渲染了 tools。把请求日志里的完整 prompt 打印出来看系统消息里有没有工具列表如果 tools 字段根本没进 prompt模型确实看不到工具。检查模型版本是否真的支持 function calling。部分模型发布时砍掉了工具能力模板和 parser 配得再对也没用。我遇到最多的是第三种。好多人直接套了一个网上找的模板但模板里压根没有渲染 tools 的分支。解决方法是回到 3.2 的自定义模板确认 tools 被完整渲染进系统消息。4.2 症状二工具名正确参数却总是解析失败现象模型输出了工具调用name 是对的但 OpenClaw 报 JSON decode error或者参数里出现明显多余的字段。排查链路先把max_tokens调大。工具调用往往出现在推理文本之后输出长度不够时 JSON 会被截断这是最常见的解析失败原因。把temperature降到 0.2 以下。温度高时模型会在 JSON 里加入解释性文字比如以下是参数一旦混入纯文本严格 JSON 解析器必挂。检查 schema 嵌套深度。如果参数对象超过两层考虑平铺重设计。在 vLLM 日志里看原始生成的文本。很多问题看日志一眼就明白是模型根本没按 JSON 格式输出还是解析器切错了边界。修复之后我习惯给这类工具加一个宽松解析兜底在工具执行端包一层容错逻辑比如把单引号替换成双引号、去掉尾逗号、提取第一个{到最后一个}之间的内容。这不算优雅但能救回一部分本可正确执行的调用。4.3 症状三多轮工具循环后上下文溢出或失忆现象Agent 跑第一个工具正常到第三四轮就开始答非所问或者 OpenClaw 报 context length exceeded。排查链路看 vLLM 的--max-model-len。如果只有 8192而每轮工具调用都塞完整历史几轮就满了。看 OpenClaw 是否默认保留全部对话历史。Agent 循环和普通对话不同工具结果通常几百字起步累积速度远超想象。检查有没有历史压缩或摘要机制。没有的话要么换更大的上下文窗口要么在 Agent 层做截断。我推荐的做法是给 vLLM 留出足够的窗口比如 32K同时在 OpenClaw 配置里开启消息摘要当历史超过阈值时把早前的工具往返压缩成一段 summary 再继续跑。注意摘要是给模型大脑看的历史笔记不是给用户的对话记录两者要分开存否则用户看到的对话会变得莫名其妙。4.4 把排查链路固化成一张表症状优先检查点通常解决动作不输出 tool_callsparser、template、模型能力换 parser、补模板渲染输出了但 JSON 解析失败max_tokens、temperature、schema 复杂度调大输出、降温、平铺 schema上下文溢出/失忆max-model-len、历史保留策略扩窗口、开摘要、做截断404 model not foundserved-model-name 与 OpenClaw 模型名对齐名字unknown tool 报错注册工具名与 schema name统一命名这张表我打印了一份贴在工位上每次接入新模型都先过一遍能省掉大半的瞎试。5. 工具调用场景下vLLM与Agent的参数平衡5.1 vLLM侧的参数取舍接入 OpenClaw 之后vLLM 不再是单发对话而是面对一串串有依赖关系的请求。这时候几个参数要重新权衡。--max-model-len不是越大越好。它直接决定 KV cache 显存占用。同样一块 24GB 的卡8192 长度可以很宽裕32768 长度可能就明显紧张。我的经验是先看 Agent 任务实际需要多少上下文按需设置不要无脑拉满。--gpu-memory-utilization我一般设在 0.85~0.9。留出一点余量给模型权重加载的波动和并行调度不要顶着 0.98实测容易触发 OOM。--max-num-seqs控制一次批量处理的序列数。Agent 场景请求频率不高但每个请求都可能带很长的历史这个值不用调很大设 4~8 足够调太大会挤压单序列的显存份额反而拖慢速度。5.2 Agent侧采样参数工具调用是精确任务不是创意任务采样参数要往保守了调temperature0~0.3。我发现 0.1 是个很稳的起点既能保持一定多样性又不会让 JSON 输出飘。top_p0.9 左右一般不用动。max_tokens单次工具调用给 1024 起步涉及长文本总结的工具要给到 4096 以上。输出截断的危害比参数错误更大因为很多解析错误追根溯源都是截断。还有个细节OpenClaw 里不同工具可以给不同的max_tokens覆盖值比如代码生成工具给大一点查天气工具给小的。这样避免把单个上限调太高导致模型疯狂输出无关内容。5.3 多Agent并发时的吞吐如果你不只有一个 OpenClaw 实例而是多个 Agent 共用同一个 vLLM就有并发调度的问题。vLLM 的 continuous batching 会自动把多个请求拼在一个 batch 里这是它比朴素推理快的核心原因。但 Agent 请求大多是长输入批起来对显存压力大。我实测单卡部署时两个 Agent 实例并发已经能看到排队延迟三个以上建议拆卡或用多机。如果显存紧张优先考虑量化模型权重。常见方案是 AWQ 或 GPTQ 4bit 量化能让大参数模型塞进单卡工具调用能力损失在可接受范围内。注意量化后依然要重新验证 tool calling因为量化会改变模型的输出分布偶尔会出现之前正常的 parser 突然失配的情况。6. 从能聊到能干活的最后一公里6.1 结构化输出的取舍工具调用跑通之后你会发现还有一类任务不适合走 function calling比如从一段文本里提取三个关键字段这类任务本质是信息抽取工具调用的工具语义反而是累赘。这时候可以用 vLLM 的结构化输出能力直接约束模型生成合法 JSON。OpenClaw 侧可以把这类能力封装成一个通用工具收到输出后用 JSON Schema 校验。好处是输出稳定坏处是灵活性差固定 schema 没办法覆盖模型临时想返回一段文本的场景。我的习惯是确定性强的抽取任务用结构化输出开放性强的任务走自由文本只有需要触发外部动作的任务才走 tool calling。三者混合使用Agent 的可靠性最高。6.2 一套可落地的参考配置对照场景vLLM 关键参数OpenClaw 关键参数轻量单 Agentmax-model-len 16Kgpu-util 0.85temperature 0.1max_tokens 2048强工具调用开启 auto-tool-choice 匹配 parser工具描述精简必填字段少多 Agent 并发max-num-seqs 4~8尽量量化开启历史摘要控制并发数长文档处理max-model-len 32Kmax_tokens 4096分层总结这张表是起点不是终点。换模型、换任务都得重新微调但至少给了一个可以抄作业的基准。6.3 接下来可以扩展的方向工具链适配完成后我认为值得再往前走三步。第一步是模型路由简单问答走小模型复杂工具调用走大模型。OpenClaw 支持按工具或按会话指定模型可以利用这一点把算力成本进一步压下来。第二步是工具观测把每次工具调用的 name、参数、结果、耗时记下来很快就知道哪些工具是模型最常瞎调的。工具描述写得烂不烂统计数据会告诉你。第三步是回归测试准备一组固定的测试问题每次换模型、换模板后都自动跑一遍检查工具调用触发率和参数正确率。没有这套测试你永远不知道一次升级是不是引入了隐性退化。我在实际使用中的体会是工具链适配这件事80% 的收益来自把工具描述写清楚 把模板渲染调对剩下的 20% 才是参数调优。很多人急着调参数却忘了先把基础链路打牢。按上面这个顺序一步步来从裸测到集成、从单工具到多工具你会少走很多弯路。