ClawdBot子Agent配置中maxConcurrent与subagents资源分配策略如何优化？

ClawdBot 是一款完全运行在本地设备的个人 AI 助手框架，无需依赖云端服务，所有推理、调度和交互逻辑都在你的设备上完成。它强调“可控、可查、可调”的设计理念，特别适合开发者、技术爱好者和注重隐私的用户。

ClawdBot 的核心动力来自 vLLM——当前最成熟的开源大模型推理引擎。它以高吞吐量、低延迟和 PagedAttention 内存优化闻名。ClawdBot 将 vLLM 深度集成，不仅作为模型后端，还承担子任务调度角色。每一次用户查询、Telegram 消息或 OCR 请求，都会被拆解成多个子任务，在 GPU 上并行或串行执行。而 maxConcurrent 与 subagents.maxConcurrent 正是协调并发数量、资源抢占和优先级的关键配置项。本文将详细拆解这两个参数的工作原理，并分享实战优化策略，帮助你实现稳定、高效的本地 AI 体验。

ClawdBot 采用分层代理（Hierarchical Agent）架构，不会简单地把用户输入直接扔给模型，而是自动拆解成多个协同子任务。这种设计既能轻松处理“写一封英文邮件”这样的单步任务，也能应对“分析财报截图、提取数据、对比去年同期并生成中文总结”的复杂多模态流程。

主 Agent（Primary Agent）：你在 UI 或 CLI 中直接交互的对象。它负责接收原始输入、理解意图、规划执行路径，并协调所有子任务，就像整个系统的“项目经理”。
子 Agent（Subagent）：主 Agent 派出的“执行专员”。每个子 Agent 专注一项能力，例如：
ocr 子 Agent 调用 PaddleOCR 解析图片文字；
whisper 子 Agent 调用 Whisper tiny 进行语音转写；
translate 子 Agent 调用翻译引擎；
weather、wiki 等子 Agent 负责外部 API 查询。

这些子 Agent 共享同一套 vLLM 运行时，但拥有独立的任务队列、超时策略和资源配额。

想象 5 位 Telegram 用户同时发消息：2 条语音（需 Whisper + Translate）、2 条截图（需 OCR + Translate）、1 条纯文本翻译。7 个子任务瞬间涌向 GPU，极易导致显存 OOM、任务排队、用户体验断崖式下降。

ClawdBot 因此设计了两级流量闸门：
– 第一级 maxConcurrent：控制主 Agent 同时处理的完整用户请求数；
– 第二级 subagents.maxConcurrent：控制所有子 Agent 加起来最多能并行执行的原子任务数。

两者相互制衡，才能实现高效资源分配。

maxConcurrent 位于 agents.defaults 下，是最直观的并发控制参数。它限制同一时刻“活跃处理中”的用户请求总数（包括等待子任务或正在调用模型的状态）。

设置值需结合硬件和场景：
– 笔记本（RTX 4060 / 8GB VRAM）：推荐 2–3，避免显存压力和整体延迟；
– 工作站（A10 / 24GB VRAM）：推荐 4–6，支持更高吞吐；
– 树莓派 4（4GB RAM，无 GPU）：严格设为 1，否则系统易假死。

实用技巧：从保守值 2 开始，观察 ClawdBot dashboard 的“Active Requests”曲线。若长期低于设定值且响应迅速，可逐步 +1 测试；若排队时间超过 1 秒，则立即下调。

很多人混淆两者：
– maxConcurrent 是应用层的逻辑并发，决定多少请求同时走流程；
– –tensor-parallel-size 是 vLLM 运行时的物理并行度，决定张量如何切分到多个 GPU。

正确搭配示例：
– maxConcurrent=4 + tensor-parallel-size=1 → 4 个请求轮流使用整块 GPU；
– maxConcurrent=2 + tensor-parallel-size=2 → 2 个请求各占一半 GPU，更稳定。

盲目调高 maxConcurrent 极易引发 OOM，必须先确认 vLLM 显存余量。

如果 maxConcurrent 是“项目立项数”，那么 subagents.maxConcurrent 就是“公司总人力预算”。它为所有子任务提供全局并发池，不区分类型。

ClawdBot 维护一个长度为 N 的“子任务许可证池”。主 Agent 启动子任务前必须申请许可证：
– 有空闲 → 立即执行；
– 池满 → 进入等待队列（先进先出）。

许可证用完后立即归还，支持跨类型共享，避免资源碎片。

subagents.maxConcurrent ≈ maxConcurrent × 1.5～2.0

理由：
– 一个用户请求平均触发 1～3 个子任务；
– 乘以 2 可覆盖 90% 场景，同时留出缓冲应对峰值；
– 受 vLLM 实际承载能力限制，不可盲目拉高。

实测参考（基于 Qwen3-4B）：
– 显存 <6GB → 4；
– 6–10GB → 6–8；
– >12GB → 10–12（需配合 vLLM 参数微调）。

警告：若 subagents.maxConcurrent 超过 vLLM 极限，会出现大量 CUDA OOM，但主 Agent 仍显示“正常”——必须及时下调。

理论落地最重要。下面以真实案例演示优化过程。

用户反馈：Telegram 群聊中 3 人同时发截图时，OCR 响应慢至 8 秒且偶尔失败。

查看当前配置：
cat ~/.clawdbot/clawdbot.json | jq '.agents.defaults.maxConcurrent, .agents.defaults.subagents.maxConcurrent'（输出 4 和 8）
检查 vLLM 负载：访问 http://localhost:8000/monitor，发现 num_requests_running 峰值 7、gpu_cache_usage_perc 达 92%。
调整配置为：
json { "agents": { "defaults": { "maxConcurrent": 3, "subagents": { "maxConcurrent": 6 } } } }
重启服务后验证：OCR 响应时间降至 1.2～1.8 秒，GPU 使用率稳定在 75%，子任务队列不再堆积。

通过降低两级并发上限，系统从“过载抖动”恢复到“平稳高效”。

ClawdBot 支持多套 agents 模板，可在运行时切换，实现智能弹性管理。

"agents": {
  "daytime": {
    "maxConcurrent": 5,
    "subagents": { "maxConcurrent": 10 }
  },
  "nightly": {
    "maxConcurrent": 2,
    "subagents": {
      "maxConcurrent": 3,
      "disabled": "ocr", "whisper"
    }
  }
}

配合 cron 脚本定时切换，白天全力服务群聊，深夜降低功耗。