ClawdBot参数详解：修改clawdbot.json切换Qwen3-4B模型与vLLM配置

1. ClawdBot是什么：你的本地AI助手，开箱即用

ClawdBot 是一个真正属于你自己的个人 AI 助手——它不依赖云端API，不上传对话，所有推理都在你自己的设备上完成。你可以把它理解成一个“装在本地的智能大脑”，既安全又可控。

它不是简单的聊天界面，而是一套完整的本地AI服务框架：前端提供直观的Web控制台，后端通过 vLLM 高效调度大语言模型，中间有灵活的代理层和多通道接入能力。整个系统轻量、可定制、可扩展，适合开发者、技术爱好者甚至对隐私有高要求的普通用户。

最关键的是，它把原本需要写脚本、配环境、调参数的复杂流程，压缩成几个清晰的配置项。你不需要懂CUDA内存优化，也不用研究vLLM的tensor-parallelism参数，只要改好一个JSON文件，就能让Qwen3-4B这样的高性能模型为你所用。

这背后是工程化思维的胜利：把前沿技术封装成“可配置的服务”，而不是“需编译的项目”。

2. 核心配置文件clawdbot.json：一切控制的起点

2.1 配置文件位置与加载逻辑

ClawdBot 的行为完全由 clawdbot.json 文件驱动。这个文件默认位于用户主目录下的隐藏路径：

~/.clawdbot/clawdbot.json

但在容器化部署中（比如Docker或docker-compose），该路径通常被映射为：

/app/clawdbot.json

这意味着你只需编辑容器内 /app/clawdbot.json，重启服务（或热重载，视版本而定），配置就会生效。无需重新构建镜像，也无需改动代码。

重要提示：ClawdBot 启动时会优先读取该文件；如果文件不存在，它会自动生成一个最小可用配置。但要启用Qwen3-4B + vLLM组合，必须手动补全模型与provider部分。

2.2 配置结构总览：agents、models、channels三大支柱

整个配置文件采用模块化设计，主要分为三大部分：

• agents：定义AI助手的行为策略——用哪个模型、工作区在哪、并发数多少、是否启用子智能体等；
• models：定义模型来源、访问方式、支持的模型列表——这是本文重点；
• channels：定义消息入口，如Telegram、WebUI、CLI等通道的开关与参数。

它们彼此解耦：你可以只改模型不碰通道，也可以只开Telegram不启WebUI。这种设计让调试和灰度上线变得非常简单。

3. 切换至Qwen3-4B-Instruct-2507：从配置到验证全流程

3.1 为什么选Qwen3-4B？轻量与能力的平衡点

Qwen3-4B-Instruct-2507 是通义千问系列中极具代表性的4B级别指令微调模型。它不是“缩水版”，而是经过深度蒸馏与强化训练的精悍选手：

• 在中文理解、代码生成、逻辑推理等任务上，接近Qwen2-7B水平；
• 显存占用仅约6GB（FP16），可在24GB显存的消费级显卡（如RTX 4090）上轻松运行；
• 支持195K上下文长度，远超多数4B模型，适合处理长文档摘要、会议纪要整理等场景；
• 指令遵循能力强，对“请用表格对比”“分三点说明”“生成Python函数”等明确指令响应准确。

对大多数本地部署用户来说，它是在性能、速度、成本与效果之间最务实的选择。

3.2 修改clawdbot.json：两处关键改动

要让ClawdBot使用Qwen3-4B-Instruct-2507，并通过vLLM提供服务，你需要同时修改两个配置块。

3.2.1 在agents.defaults.model中指定主模型

找到 agents.defaults.model.primary 字段，将其值设为：

"primary": "vllm/Qwen3-4B-Instruct-2507"

注意格式：vllm/ 是provider前缀，后面紧跟模型ID，二者用斜杠连接。这个字符串就是ClawdBot内部路由模型请求的“钥匙”。

3.2.2 在models.providers.vllm中声明vLLM服务地址与模型

确保 models.providers 下存在 vllm 条目，并完整填写以下字段：

"vllm": {
  "baseUrl": "http://localhost:8000/v1",
  "apiKey": "sk-local",
  "api": "openai-responses",
  "models": [
    {
      "id": "Qwen3-4B-Instruct-2507",
      "name": "Qwen3-4B-Instruct-2507"
    }
  ]
}

逐项说明：

• baseUrl：vLLM服务的OpenAI兼容API地址。如果你的vLLM运行在另一台机器，请将 localhost 替换为对应IP；
• apiKey：vLLM默认启用API密钥校验，sk-local 是其内置的测试密钥，无需额外配置；
• api：指定响应格式为 openai-responses，确保ClawdBot能正确解析流式输出；
• models[].id：必须与 agents.defaults.model.primary 中的模型ID后半部分完全一致（即去掉 vllm/ 前缀）。

小技巧：如果你还部署了其他模型（如Phi-3-mini），只需在 models 数组中追加新对象，无需修改其他配置。

3.3 验证模型是否加载成功

配置保存后，执行以下命令检查模型是否被ClawdBot识别：

clawdbot models list

正常输出应包含类似这一行：

vllm/Qwen3-4B-Instruct-2507                text       195k     yes   yes   default

各列含义：

• 第一列：模型标识符（即你配置的 primary 值）；
• 第二列：输入类型（text 表示纯文本模型）；
• 第三列：上下文长度（195k 即195,000 tokens）；
• 第四、五列：是否支持本地加载、是否启用认证（yes 表示已按配置启用）；
• 最后列：是否为默认模型（default）。

如果看到这一行，说明ClawdBot已成功关联vLLM服务，并将Qwen3-4B注册为可用模型。

4. vLLM服务配置要点：让Qwen3-4B跑得稳、跑得快

ClawdBot本身不运行模型，它只是“调度员”。真正的推理引擎是独立部署的vLLM服务。因此，clawdbot.json 中的 baseUrl 必须指向一个正在运行且已加载Qwen3-4B的vLLM实例。

4.1 启动vLLM服务的标准命令

假设你已下载Qwen3-4B-Instruct-2507模型到本地路径 /models/Qwen3-4B-Instruct-2507，推荐使用以下命令启动：

python -m vllm.entrypoints.openai.api_server \
  --model /models/Qwen3-4B-Instruct-2507 \
  --dtype auto \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 256 \
  --port 8000 \
  --host 0.0.0.0

关键参数解读：

• --model：模型路径，必须与Hugging Face仓库结构一致（含config.json、pytorch_model.bin等）；
• --dtype auto：自动选择精度（在A100上用bfloat16，在RTX系列上用float16），兼顾速度与显存；
• --tensor-parallel-size 1：单卡部署，无需多卡并行；
• --gpu-memory-utilization 0.95：显存利用率设为95%，留出余量避免OOM；
• --max-num-seqs 256：最大并发请求数，匹配ClawdBot的 maxConcurrent: 4 设置，避免队列积压。

4.2 常见连接问题排查

当 clawdbot models list 不显示模型，或WebUI报“Gateway not reachable”时，请按顺序检查：

1. vLLM是否在运行？
   执行 curl http://localhost:8000/health，返回 {"healthy": true} 即正常。

2. 网络是否可达？
   如果ClawdBot与vLLM不在同一容器，确认 baseUrl 中的IP和端口可从ClawdBot容器内访问（docker exec -it clawdbot curl http://vllm-host:8000/health）。

3. 模型路径是否正确？
   查看vLLM启动日志，确认没有 OSError: Can't find file 类错误。

4. API密钥是否匹配？
   clawdbot.json 中的 apiKey 必须与vLLM启动时的 --api-key 参数（如有）一致；若未指定，则默认接受任意密钥（包括 sk-local）。

5. 进阶配置建议：让Qwen3-4B发挥更大价值

5.1 调整agent行为策略，适配4B模型特性

Qwen3-4B虽强，但相比7B+模型，其长程推理与多步规划能力稍弱。可通过 agents.defaults 微调其工作方式：

"agents": {
  "defaults": {
    "model": {
      "primary": "vllm/Qwen3-4B-Instruct-2507",
      "temperature": 0.7,
      "top_p": 0.9,
      "max_tokens": 2048
    },
    "workspace": "/app/workspace",
    "compaction": {
      "mode": "safeguard"
    },
    "maxConcurrent": 4,
    "subagents": {
      "maxConcurrent": 8
    }
  }
}

• temperature: 0.7：适度增加随机性，避免回答过于刻板；
• top_p: 0.9：保留90%概率质量的词元，平衡多样性与准确性；
• max_tokens: 2048：限制单次生成长度，防止因上下文过长导致延迟升高。

这些值不是固定标准，而是基于大量实测的推荐起点。你可以根据实际对话风格（如偏正式报告 or 偏轻松闲聊）动态调整。

5.2 启用模型别名，简化日常使用

如果你常在不同场景切换模型（如写作用Qwen3-4B，编程用CodeLlama），可在 models.providers.vllm.models 中添加别名：

{
  "id": "Qwen3-4B-Instruct-2507",
  "name": "Qwen3-4B-Instruct-2507",
  "alias": ["writing", "zh-instruct"]
},
{
  "id": "codellama/CodeLlama-34b-Instruct-hf",
  "name": "CodeLlama-34b-Instruct-hf",
  "alias": ["coding", "python"]
}

随后在agent配置中直接引用别名：

"primary": "vllm/writing"

这样，即使模型ID很长或带特殊字符，你也能用简洁名称管理。

6. 总结：一次配置，长期受益

修改 clawdbot.json 切换Qwen3-4B与vLLM，本质上是在做三件事：

• 声明意图：告诉ClawdBot“我要用这个模型”；
• 建立连接：告诉ClawdBot“这个模型在哪里、怎么找”；
• 验证通路：用 clawdbot models list 确认指令已被正确接收与解析。

整个过程不涉及代码编译、不依赖外部服务、不修改系统环境。它回归了本地AI部署最本真的状态：配置即能力，文件即接口。

当你第一次在WebUI中输入“请用表格对比Qwen3与Qwen2的主要差异”，看到Qwen3-4B以流畅的中文、清晰的结构、准确的数据给出回答时，那种掌控感与即时反馈，正是本地AI最迷人的地方。

下一步，你可以尝试：

• 为Qwen3-4B添加RAG插件，接入本地知识库；
• 配置Telegram通道，让群友也能享受你的私有AI；
• 或者，就静静地用它写周报、理思路、学新知——毕竟，最好的AI，是那个你随时能唤起、永远听你指挥的伙伴。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。