ClawdBot实操手册：修改clawdbot.json实现多模型动态切换

1. ClawdBot 是什么：你的本地AI助手核心引擎

ClawdBot 不是一个云端服务，而是一个真正属于你自己的个人 AI 助手运行时环境。它不依赖外部API密钥，也不把你的对话上传到任何远程服务器——所有推理、记忆、工具调用都在你自己的设备上完成。

它的后端由 vLLM 驱动，这意味着你能享受到工业级的推理吞吐和极低的首字延迟。vLLM 的 PagedAttention 技术让 ClawdBot 在消费级显卡（比如 RTX 4070 或 A10）上也能稳定并发处理多个请求，同时保持响应速度在亚秒级。

但 ClawdBot 的价值远不止于“跑得快”。它是一个可编程的 AI 工作流中枢：你可以定义智能体（Agents）、配置多模态输入（文本/图片/语音）、接入外部工具（天气、汇率、维基），甚至把整个系统嵌入 Telegram 群聊中，变成一个随时待命的“数字同事”。

它不像传统聊天界面那样只做问答，而是像一个操作系统——你通过 clawdbot.json 这个配置文件，来声明“谁来干活”、“怎么干活”、“用什么工具干”，最终形成一套可复用、可调试、可协作的本地AI工作流。

换句话说：ClawdBot 是你设备上的 AI 操作系统，而 clawdbot.json 就是它的启动参数表与服务注册中心。

2. 为什么必须修改 clawdbot.json：从单模型到多模型的跃迁

默认安装的 ClawdBot 只预置了一个模型，比如 vllm/Qwen3-4B-Instruct-2507。它足够轻量、启动快、适合日常问答，但实际使用中你会发现：

• 写技术文档时，需要更强逻辑和代码能力的模型（如 DeepSeek-R1 或 Qwen2.5-Coder）；
• 处理中文长文本摘要时，上下文窗口更大的模型（如 Qwen2.5-72B）更可靠；
• 做多轮角色扮演或创意写作时，偏好更“有性格”的微调版本（如 Yi-1.5-9B-Chat-GGUF）；
• 有些任务根本不需要大模型——用 TinyLlama 做快速意图识别，既省显存又提速。

这时候，硬编码式地改代码、重编译、重启服务，就完全违背了 ClawdBot “零停机配置即生效”的设计哲学。

而 clawdbot.json 正是为此而生：它不是启动脚本，也不是环境变量集合，而是一份声明式模型服务注册表。你只需在这里添加新模型的地址、名称、能力标签，ClawdBot 启动时会自动发现、验证、注册，并在 UI 和 API 层统一暴露。

更重要的是：修改 clawdbot.json 后无需重启服务。只要执行 clawdbot models reload，新模型就会热加载上线——就像给操作系统动态插入一块新硬件，驱动自动识别，即插即用。

3. 修改前必读：clawdbot.json 的结构本质与安全边界

clawdbot.json 看似是普通 JSON 文件，实则承担三重职责：

• 模型注册中心：告诉 ClawdBot “有哪些模型可用”，包括地址、认证方式、支持格式；
• 路由策略表：定义不同场景下该调用哪个模型（如 /agent/research 走 Qwen2.5-72B，/agent/quick 走 TinyLlama）；
• 资源调度契约：声明每个模型的显存占用、最大并发数、上下文长度等硬约束，防止 OOM 崩溃。

因此，修改它不是“改个名字就行”，而是一次轻量级的系统配置操作。我们先看它的核心骨架：

{
  "agents": { ... },
  "models": { ... },
  "channels": { ... }
}

其中，models 是本次操作的核心区块；agents 中的 defaults.model.primary 则决定了当前默认使用的模型 ID；channels（如 Telegram）虽不直接影响模型切换，但其 streamMode 和 proxy 设置会影响模型调用链路的稳定性——尤其在国内网络环境下，这点必须前置确认。

安全提醒：

• clawdbot.json 默认映射在容器内 /app/clawdbot.json，宿主机路径为 ~/.clawdbot/clawdbot.json；
• 修改前请务必备份原文件（cp clawdbot.json clawdbot.json.bak）；
• 所有模型 URL 必须指向本地可访问的 vLLM / Ollama / OpenAI 兼容服务（如 http://localhost:8000/v1），不支持直接填 HuggingFace 模型 ID；
• apiKey 字段仅用于身份校验，ClawdBot 不存储或透传该密钥至外部服务，本地部署时可设为任意字符串（如 "sk-local"）。

4. 实操步骤：从零开始添加第二个模型并验证切换

4.1 准备工作：确认 vLLM 服务已就绪

ClawdBot 本身不托管模型，它只做“调度员”。所以第一步，确保你要接入的第二个模型已在本地运行。以启动 Qwen2.5-7B-Instruct 为例：

# 启动 vLLM 服务（监听 8000 端口）
vllm serve \
  --model Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 1 \
  --max-model-len 32768 \
  --enable-prefix-caching

等待终端输出 INFO: Uvicorn running on http://0.0.0.0:8000 即表示服务就绪。

验证方式：在浏览器打开 http://localhost:8000/v1/models，应返回包含 id: "Qwen2.5-7B-Instruct" 的 JSON 列表。

4.2 编辑 clawdbot.json：添加新模型 Provider

打开 /app/clawdbot.json（容器内）或 ~/.clawdbot/clawdbot.json（宿主机），定位到 "models" 区块。原始内容类似：

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

现在，我们在 "models" 数组中追加第二项（注意逗号分隔）：

{
  "id": "Qwen2.5-7B-Instruct",
  "name": "Qwen2.5-7B-Instruct",
  "tags": ["reasoning", "cn", "longctx"]
}

完整更新后的 providers.vllm.models 应为：

"models": [
  {
    "id": "Qwen3-4B-Instruct-2507",
    "name": "Qwen3-4B-Instruct-2507"
  },
  {
    "id": "Qwen2.5-7B-Instruct",
    "name": "Qwen2.5-7B-Instruct",
    "tags": ["reasoning", "cn", "longctx"]
  }
]

关键说明：

• "id" 必须与 vLLM /v1/models 返回的模型 ID 完全一致（区分大小写）；
• "tags" 是可选字段，用于后续在 Agent 配置中做语义路由（例如："reasoning" 模型自动分配给需要逻辑推演的任务）；
• 不要改动 "baseUrl" 和 "apiKey" —— 它们对同一 Provider 下所有模型通用。

4.3 热重载模型列表：无需重启服务

保存文件后，在容器内终端执行：

clawdbot models reload

你会看到类似输出：

🦞 Clawdbot 2026.1.24-3 (885167d) — Model registry reloaded: 2 providers, 2 models active.
→ vllm/Qwen3-4B-Instruct-2507 (default)
→ vllm/Qwen2.5-7B-Instruct

成功标志：命令无报错，且提示“2 models active”。

再执行验证命令：

clawdbot models list

输出应包含两行模型信息，其中第二行为：

vllm/Qwen2.5-7B-Instruct         text       32k      yes   yes   -

注意：Ctx 列显示 32k，正是我们启动 vLLM 时设置的 --max-model-len 32768 的简写，证明模型能力已正确识别。

4.4 切换默认模型：两种方式任选其一

方式一：全局默认（推荐新手）

编辑 clawdbot.json，将 agents.defaults.model.primary 的值改为新模型 ID：

"agents": {
  "defaults": {
    "model": {
      "primary": "vllm/Qwen2.5-7B-Instruct"
    },
    ...
  }
}

然后再次执行 clawdbot models reload，所有未显式指定模型的 Agent 将自动使用 Qwen2.5-7B。

方式二：按 Agent 指定（推荐进阶用户）

在 agents 下新增一个专用 Agent，例如 researcher：

"researcher": {
  "model": {
    "primary": "vllm/Qwen2.5-7B-Instruct"
  },
  "workspace": "/app/workspace/research",
  "maxConcurrent": 2
}

之后在 UI 或 API 中调用 /agent/researcher，即可独享该模型能力，不影响其他 Agent。

5. 进阶技巧：用 tags + rules 实现智能模型路由

ClawdBot 支持基于语义标签的自动模型分发，这比手动切换更符合真实工作流。

5.1 给模型打标：补充能力维度

回到 clawdbot.json 的 models.providers.vllm.models，为两个模型分别添加差异化标签：

[
  {
    "id": "Qwen3-4B-Instruct-2507",
    "name": "Qwen3-4B-Instruct-2507",
    "tags": ["fast", "light", "chat"]
  },
  {
    "id": "Qwen2.5-7B-Instruct",
    "name": "Qwen2.5-7B-Instruct",
    "tags": ["reasoning", "cn", "longctx", "code"]
  }
]

5.2 编写路由规则：让系统自己做选择

在 clawdbot.json 根层级添加 modelRouting 区块（ClawdBot 2026.1+ 版本支持）：

"modelRouting": {
  "rules": [
    {
      "match": {
        "intent": ["summarize", "analyze", "debug"],
        "tags": ["reasoning", "code"]
      },
      "target": "vllm/Qwen2.5-7B-Instruct"
    },
    {
      "match": {
        "intent": ["greet", "smalltalk", "translate"],
        "tags": ["fast", "chat"]
      },
      "target": "vllm/Qwen3-4B-Instruct-2507"
    }
  ]
}

效果：当用户发送“帮我分析这段 Python 报错日志”，ClawdBot 自动识别 intent 为 analyze，匹配第一条规则，调用 Qwen2.5-7B；而发送“你好呀”，则走轻量模型，响应更快。

5.3 验证路由是否生效

启用 debug 日志模式启动 ClawdBot：

clawdbot --log-level debug

发起一次请求后，观察日志中是否出现：

[ROUTER] Matched rule #0 → vllm/Qwen2.5-7B-Instruct (intent=analyze, tags=[reasoning,code])

有此日志，即代表智能路由已激活。

6. 常见问题排查：从“看不到模型”到“调用失败”的全链路诊断

即使严格按步骤操作，仍可能遇到模型“存在却不可用”的情况。以下是高频问题与对应解法：

6.1 问题：clawdbot models list 显示模型，但 UI 中不出现

• 检查点：UI 是否缓存了旧配置？强制刷新浏览器（Ctrl+F5），或尝试隐身窗口；
• 检查点：clawdbot.json 文件权限是否为 644？ClawdBot 进程需有读取权限；
• 检查点：JSON 格式是否合法？用 JSONLint 在线校验，特别注意末尾逗号、引号闭合。

6.2 问题：模型显示为 Local Auth: no 或 Tags: -

• 原因：vLLM 服务未返回完整模型元数据；
• 解法：在 vLLM 启动命令中添加 --served-model-name 参数，确保与 clawdbot.json 中 id 一致：

vllm serve --model Qwen/Qwen2.5-7B-Instruct --served-model-name Qwen2.5-7B-Instruct ...

6.3 问题：调用时报错 Gateway not reachable 或 Connection refused

• 原因：ClawdBot 容器无法访问宿主机的 localhost:8000；
• 解法：将 vLLM 服务绑定到 0.0.0.0（已做），并在 ClawdBot 容器中将 baseUrl 改为宿主机 IP（非 localhost）：

"baseUrl": "http://172.17.0.1:8000/v1"

Docker 网络中，172.17.0.1 通常是宿主机在 bridge 网络中的网关地址（可通过 ip route | grep default 查看）。

6.4 问题：模型能列出来，但 Agent 调用时返回空或超时

• 检查点：vLLM 是否启用了 --enable-chunked-prefill？ClawdBot 当前版本要求该参数关闭（默认关闭，无需额外操作）；
• 检查点：GPU 显存是否不足？运行 nvidia-smi，确认 vLLM 进程显存占用未达上限（Qwen2.5-7B 约需 12GB）；
• 检查点：ClawdBot 日志中是否有 HTTP 400 Bad Request？常见于模型 ID 不匹配，检查 id 字段是否含空格或特殊字符。

7. 总结：掌握配置即掌握本地 AI 的主动权

修改 clawdbot.json 实现多模型切换，表面看是改几行 JSON，背后却是对本地 AI 架构认知的一次升级：

• 你不再把模型当作“黑盒 API”，而是可注册、可打标、可路由的第一类公民；
• 你不再被单一模型能力所束缚，而是根据任务类型、响应速度、成本开销，动态组合最优解；
• 你不再需要为每个新需求重装系统，而是通过声明式配置，在分钟级完成能力扩容。

更重要的是，这种能力完全属于你——没有厂商锁定，没有用量限制，没有隐私泄露风险。当你在 clawdbot.json 中亲手写下 "id": "Qwen2.5-7B-Instruct" 并成功调用时，你获得的不仅是一个新模型，更是对 AI 工具链真正的掌控感。

下一步，你可以尝试：

• 将 Ollama 模型（如 llama3:8b）通过 openai-compatible 模式接入；
• 为不同模型配置独立的 maxConcurrent，实现资源隔离；
• 结合 channels.telegram，让群友通过 /model qwen2 指令临时切换模型。

真正的本地 AI，从来不是“能跑就行”，而是“想换就换，换完就用”。

---

获取更多AI镜像

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