ClawdBot参数详解：agents.defaults.model.primary字段配置说明
你是否曾为ClawdBot中那个看似简单却影响全局的agents.defaults.model.primary字段困惑过？改完配置后模型不生效、UI里看不到新模型、命令行clawdbot models list输出空空如也……别急，这不是你的操作问题，而是这个字段背后藏着三层关键逻辑：模型标识规范、服务端注册机制、客户端默认路由策略。本文不讲抽象概念，只说你真正需要知道的——怎么配、为什么这么配、配错会怎样、怎么快速验证。
我们从一个真实场景切入：你想把默认模型从Qwen3-4B换成本地部署的Phi-3-mini-4K-instruct，但改完clawdbot.json后，聊天界面依然调用旧模型。问题不在JSON语法，而在于你漏掉了models.providers里的对应注册，以及primary字段对模型ID格式的严格要求。接下来，我会带你一层层拆解，每一步都附可立即执行的验证命令和典型错误反馈。
1.primary字段的本质：不是模型名，而是“模型路由地址”
agents.defaults.model.primary看起来像在指定一个模型名称，比如"vllm/Qwen3-4B-Instruct-2507"，但它实际是一个带命名空间的模型路由标识符（namespace/model-id）。它不直接指向文件或权重，而是告诉ClawdBot：“当用户没特别指定模型时，请向哪个服务、用哪个ID去请求”。
1.1 字段结构解析：{provider}/{model-id}
"primary": "vllm/Qwen3-4B-Instruct-2507"vllm：这是providers下的键名，必须与models.providers中定义的provider名称完全一致（大小写敏感）Qwen3-4B-Instruct-2507：这是该provider下models[].id字段的值，不是文件夹名，也不是Hugging Face模型ID
常见误区：有人把这里写成
"Qwen3-4B-Instruct"或"Qwen/Qwen3-4B-Instruct"，结果模型列表为空——因为ClawdBot在models.providers.vllm.models数组里根本找不到匹配的id。
1.2 为什么必须是vllm/xxx这种格式？
ClawdBot采用“多后端统一网关”设计。primary字段的斜杠前缀决定了：
- 请求发往哪个后端（
vllm、ollama、openai等） - 使用哪种API协议（
vllm走OpenAI兼容接口，ollama走Ollama原生接口） - 认证方式（
vllm用apiKey: "sk-local"，openai用真实API Key）
如果你部署的是Ollama模型，primary就必须是"ollama/phi3"；如果是自建OpenAI兼容服务，则应为"openai/gpt-4o"。前缀不匹配，请求直接被网关拒绝，不会报错，只会静默 fallback 到内置兜底模型。
1.3 验证字段是否生效的黄金三步法
不要依赖UI刷新，用命令行直击核心：
# 步骤1：确认配置已加载（检查是否有语法错误） clawdbot config validate # 步骤2：列出所有已注册模型（关键！看primary是否出现在default标签下） clawdbot models list # 步骤3：模拟一次默认模型调用（不发消息，只查路由） clawdbot agents info --default-model正确输出示例（注意Tags列含default）：
Model Input Ctx Local Auth Tags vllm/Qwen3-4B-Instruct-2507 text 195k yes yes default❌ 错误信号（Tags列为空或无default）：说明primary字段未被识别，立即检查providers注册是否完整。
2. 配置生效的三大前提：缺一不可
改一个JSON字段就能切换模型？现实要复杂得多。primary要真正起作用，必须同时满足以下三个条件，任一缺失都会导致“配置写了，但没用”。
2.1 前提一：models.providers中必须存在同名provider
primary中的前缀（如vllm）必须在models.providers对象中作为键存在，且其值必须是合法的provider配置对象。
"models": { "mode": "merge", "providers": { "vllm": { // ← 必须与primary前缀完全一致 "baseUrl": "http://localhost:8000/v1", "apiKey": "sk-local", "api": "openai-responses", "models": [ ... ] } } }检查方法：运行
clawdbot models providers list，输出应包含vllm且状态为ready。若显示unavailable，说明baseUrl不可达或认证失败。
2.2 前提二：provider下的models[].id必须与primary后缀精确匹配
这是新手踩坑最多的地方。primary后半部分（Qwen3-4B-Instruct-2507）必须等于providers.vllm.models[0].id，不能多一个空格、不能少一个连字符、不能大小写混用。
"providers": { "vllm": { "models": [ { "id": "Qwen3-4B-Instruct-2507", // ← 必须一字不差 "name": "通义千问3-4B指令版" } ] } }小技巧：复制
models[].id的值，粘贴到primary字段中，避免手误。
2.3 前提三：provider服务必须健康在线，且模型已加载
即使JSON全对，如果vLLM服务没启动、模型没加载成功，primary也会失效。ClawdBot不会主动报错，而是返回model_not_found或fallback到空响应。
验证命令：
# 检查vLLM服务是否响应（替换为你的真实地址） curl -s http://localhost:8000/v1/models | jq '.data[].id' # 查看vLLM日志中模型加载状态 docker logs vllm-server 2>&1 | grep -i "loaded.*Qwen3"正常日志应含：INFO 01-24 10:23:45 llm_engine.py:234] Loaded model 'Qwen3-4B-Instruct-2507'
❌ 若无此日志，说明模型未加载，需检查vLLM启动命令中的--model参数是否指向正确路径。
3. 实战配置指南：从零部署Phi-3-mini并设为primary
现在，我们以部署Phi-3-mini-4K-instruct为例，走一遍完整流程。所有命令均可直接复制执行，无需修改。
3.1 步骤一：启动vLLM服务（支持Phi-3）
# 拉取官方镜像（已预装Phi-3权重） docker run -d \ --name vllm-phi3 \ --gpus all \ -p 8000:8000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ ghcr.io/vllm-project/vllm-cuda:latest \ --model microsoft/Phi-3-mini-4K-instruct \ --dtype bfloat16 \ --tensor-parallel-size 1 \ --max-model-len 40963.2 步骤二：修改clawdbot.json（关键字段标★）
{ "agents": { "defaults": { "model": { "primary": "vllm/Phi-3-mini-4K-instruct" // ★ 注意：必须与下方id完全一致 }, "workspace": "/app/workspace", "maxConcurrent": 4 } }, "models": { "mode": "merge", "providers": { "vllm": { "baseUrl": "http://localhost:8000/v1", "apiKey": "sk-local", "api": "openai-responses", "models": [ { "id": "Phi-3-mini-4K-instruct", // ★ 必须与primary后缀完全一致 "name": "Phi-3 Mini 4K 指令版" } ] } } } }3.3 步骤三：重启ClawdBot并验证
# 重启服务（根据你的部署方式调整） docker restart clawdbot # 等待10秒后验证 clawdbot models list成功输出：
Model Input Ctx Local Auth Tags vllm/Phi-3-mini-4K-instruct text 4k yes yes default此时，在Web UI中新建对话，无需选择模型，系统将自动使用Phi-3-mini。
4. 常见故障排查：5分钟定位90%的问题
配置总出错？别反复重试，按这个清单逐项检查，90%的问题5分钟内解决。
| 现象 | 可能原因 | 快速验证命令 | 解决方案 |
|---|---|---|---|
clawdbot models list输出为空 | models.providers未正确定义或baseUrl不可达 | clawdbot models providers list | 检查providers键名、baseUrl格式（必须含/v1）、网络连通性 |
列表有模型但无default标签 | primary字段格式错误（前缀不匹配或后缀不精确） | clawdbot config show | grep primary | 复制models[].id值，粘贴覆盖primary后半部分 |
| 模型列表正常，但聊天仍用旧模型 | Agent未重启或配置缓存未刷新 | clawdbot agents restart | 重启agents子系统，或重启整个ClawdBot容器 |
聊天报错model_not_found | vLLM服务未加载该模型 | curl http://localhost:8000/v1/models | 检查vLLM启动日志，确认--model参数正确 |
| UI中模型下拉菜单无选项 | models.mode设为override但providers未完整覆盖 | clawdbot config show | grep mode | 改为"mode": "merge"，保留内置模型 |
终极验证：在ClawdBot Web UI中打开浏览器开发者工具（F12），切换到Network标签，发送一条消息。查看
/v1/chat/completions请求的model字段值——它必须与你设置的primary完全一致。
5. 进阶技巧：让primary更灵活、更安全
primary不只是一个静态字符串，合理利用它可以提升稳定性与体验。
5.1 设置fallback链：避免单点故障
ClawdBot支持primary为数组，实现模型降级：
"primary": [ "vllm/Phi-3-mini-4K-instruct", "ollama/llama3", "openai/gpt-3.5-turbo" ]当第一个模型不可用时，自动尝试下一个。注意：需确保所有provider均已配置且健康。
5.2 动态切换：不重启即可更新primary
通过API实时修改（需启用管理API）：
curl -X POST http://localhost:7860/api/v1/config \ -H "Content-Type: application/json" \ -d '{"agents":{"defaults":{"model":{"primary":"vllm/Qwen2-7B-Instruct"}}}}'5.3 安全加固：限制primary可选范围
在生产环境，可通过models.allowed白名单防止意外调用高成本模型：
"models": { "allowed": ["vllm/Phi-3-mini-4K-instruct", "vllm/Qwen3-4B-Instruct-2507"] }任何不在白名单的primary值将被拒绝，强制使用第一个白名单模型。
总结
agents.defaults.model.primary不是一句简单的配置，而是ClawdBot模型调度系统的“总开关”。它的正确配置依赖于三个环环相扣的环节：字段格式合规、provider注册完整、后端服务健康。记住这三点，你就掌握了90%的配置主动权。
- 格式上：永远用
{provider}/{model-id}，且model-id必须精确复制自providers.{provider}.models[].id - 注册上：
providers对象必须存在，baseUrl必须可访问，models[].id必须已加载 - 验证上：用
clawdbot models list看default标签，用curl直查vLLM服务，用浏览器Network面板确认实际请求
现在，你可以自信地切换模型、添加fallback、甚至动态更新——不再被一个JSON字段卡住半天。真正的掌控感，就来自对这些细节的透彻理解。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
