ClawdBot审计追踪：记录所有翻译请求、模型选择与fallback决策链

1. ClawdBot 是什么：你的本地化AI网关中枢

ClawdBot 不是一个传统意义上的“聊天机器人”，而是一个可完全掌控的本地AI网关系统。它像一位沉默但严谨的交通调度员，运行在你自己的设备上（笔记本、服务器甚至树莓派），统一接收来自不同渠道（Telegram、Web UI、API调用）的请求，再根据预设规则分发给后端模型服务，并全程记录每一步关键决策。

它的核心价值不在于“能做什么”，而在于“怎么做的每一步都可追溯”。当你在 Telegram 群里发送一条中文消息，@moltbot 要求翻译成西班牙语时，背后发生的过程远比“输入→输出”复杂得多：系统需要自动识别源语言、判断是否启用 OCR（如果是图片）、选择主翻译引擎、在 LibreTranslate 失败时切换到 Google Translate、记录 fallback 的具体原因、甚至还要决定是否调用 Whisper 转写语音——而这一切，ClawdBot 都会以结构化方式完整存档。

这种能力，正是“审计追踪”的本质：不是事后查日志，而是事中留痕、事事可证。它让 AI 行为从黑箱走向白盒，尤其适合对合规性、可复现性和问题定位有明确要求的个人开发者与小团队。

2. 审计追踪的核心三要素：请求、模型、决策链

ClawdBot 的审计能力围绕三个不可分割的维度构建：谁发来的请求？用了哪个模型？为什么选它？ 这三者共同构成一条完整的决策链（Decision Chain），而非孤立的日志条目。

2.1 请求溯源：不只是文本，更是上下文快照

每条审计记录首先锁定请求本身。但 ClawdBot 记录的远不止原始消息内容：

• 来源通道：是 Telegram 私聊？群聊中的 @ 提及？还是 Web UI 手动提交？
• 用户标识：Telegram 用户 ID 或匿名会话 ID（隐私模式下不存储真实用户名）
• 时间戳（毫秒级）：精确到请求进入网关的瞬间，而非响应返回时刻
• 输入模态标记：text / voice / image / document —— 决定后续处理路径的关键开关
• 元数据快照：包括当前启用的代理配置、OCR 置信度阈值、语音转写模型版本等运行时参数

这意味着，当你发现某次图片翻译结果异常模糊时，审计记录能立刻告诉你：当时 PaddleOCR 的识别置信度只有 0.62（低于默认阈值 0.75），因此系统跳过了文字提取，直接将整张图送入多模态模型——问题根源一目了然。

2.2 模型选择：动态路由，而非静态绑定

ClawdBot 不把“模型”当作一个固定选项，而是一套可编程的路由策略。审计记录中清晰呈现模型选择的完整逻辑：

• 主模型（Primary）：如 vllm/Qwen3-4B-Instruct-2507，由 /app/clawdbot.json 中 agents.defaults.model.primary 指定
• 备选模型（Fallback）：当主模型超时、报错或输出质量不达标（如含大量乱码）时，自动触发备用路径
• 专用模型（Specialized）：语音转写强制使用 whisper-tiny，OCR 固定调用 paddleocr-v4，与大语言模型解耦

更重要的是，审计记录会标注选择依据。例如：

Model selected: vllm/Qwen3-4B-Instruct-2507 (reason: ctx_len=195k > required 8k, local_auth=yes)
Fallback triggered: libretranslate (reason: google_translate returned HTTP 429, retry_after=32s)

这种“带理由的模型日志”，彻底告别了“为什么这次用了A模型，上次却用了B模型”的困惑。

2.3 Fallback 决策链：从失败到恢复的完整路径

Fallback 不是简单的“换一个试试”，而是一条有状态、可回溯的决策链。ClawdBot 将每次降级行为拆解为原子步骤并逐条记录：

1. 触发条件：检测到主引擎超时（>1200ms）/ HTTP 错误（4xx/5xx）/ 输出校验失败（如非目标语言占比 >30%）
2. 候选池评估：列出所有可用 fallback 引擎及其实时健康状态（如 LibreTranslate 响应延迟 840ms，Google Translate 延迟 1120ms）
3. 策略执行：按预设优先级（providers.priority）或动态评分（响应速度 × 可用性权重）选择下一个
4. 结果反馈：记录 fallback 是否成功、耗时、以及是否再次触发下一级 fallback

这种链式记录，让运维人员能精准回答：“本次翻译为何耗时 3.2 秒？”——答案可能是：主模型超时 → 切换 LibreTranslate（+0.8s）→ LibreTranslate 返回空结果 → 再切 Google Translate（+1.4s）→ 最终成功。

3. 如何查看与利用审计数据

ClawdBot 提供三种互补的审计数据访问方式，覆盖从快速排查到深度分析的不同需求。

3.1 Web 控制台：可视化决策流图

打开 http://localhost:7860（需先完成设备授权），进入 Audit → Trace Explorer 页面。这里不显示原始日志，而是以交互式流程图呈现单次请求的全生命周期：

• 左侧节点：Input Received → Language Detected → Model Router → vllm/Qwen3-4B → Fallback Triggered → libretranslate
• 每个节点标注耗时（如 vllm/Qwen3-4B: 1.24s）和状态（ 成功 / 警告 / ❌ 失败）
• 点击节点可展开原始请求体、模型响应、错误堆栈等详情
• 右侧提供筛选器：按时间范围、通道类型、模型ID、fallback次数等快速定位异常链

这种图形化呈现，让非技术人员也能直观理解一次翻译背后的复杂协作。

3.2 CLI 审计命令：精准检索与导出

对于自动化分析或批量检查，ClawdBot CLI 提供强大查询能力：

# 查看最近10条含 fallback 的记录（按时间倒序）
clawdbot audit list --fallback-only --limit 10

# 检索所有 Telegram 群聊中，OCR 识别失败的请求
clawdbot audit search --channel telegram --input-type image --status "ocr_failed"

# 导出过去24小时所有模型选择日志为 CSV（用于 Excel 分析）
clawdbot audit export --format csv --since "24h" > model_selection_24h.csv

导出的 CSV 包含结构化字段：timestamp, request_id, channel, input_type, primary_model, fallback_model, fallback_reason, total_latency_ms, is_success —— 直接支持 PivotTable 统计各模型成功率、平均延迟、fallback 触发率等关键指标。

3.3 文件日志：原始审计事件流

所有审计事件实时写入结构化 JSONL 日志文件（默认路径 ~/.clawdbot/logs/audit.log），每行一个 JSON 对象：

{
  "id": "req_8a2f1c4e",
  "timestamp": "2026-01-24T15:32:18.427Z",
  "channel": "telegram",
  "input_type": "text",
  "source_lang": "zh",
  "target_lang": "es",
  "primary_model": "vllm/Qwen3-4B-Instruct-2507",
  "fallback_chain": [
    {"model": "libretranslate", "reason": "timeout", "latency_ms": 1280},
    {"model": "google_translate", "reason": "success", "latency_ms": 940}
  ],
  "total_latency_ms": 3420,
  "is_success": true
}

该格式天然兼容 ELK 栈、Grafana Loki 等日志分析平台，可轻松构建实时监控看板，例如：

• 折线图：每小时 fallback 触发次数趋势
• 热力图：各模型组合（主+备）的成功率矩阵
• 告警规则：连续5次 fallback 到同一备选引擎时触发通知

4. 实战案例：用审计追踪定位并优化翻译体验

我们通过一个真实场景，展示审计追踪如何从“发现问题”走向“闭环优化”。

4.1 问题现象：群聊翻译偶发延迟，用户抱怨“有时要等很久”

用户反馈：在 500 人 Telegram 群中，@moltbot 翻译消息时，多数情况 <1s 返回，但偶尔长达 4–5 秒，且无明显规律。

4.2 审计追踪分析：三步定位根因

第一步：筛选慢请求
在 Web 控制台 Trace Explorer 中，设置 total_latency_ms > 3000，发现所有慢请求均发生在下午 2–4 点间，且 fallback_chain 字段显示：
[{"model":"libretranslate","reason":"timeout"},{"model":"google_translate","reason":"success"}]

第二步：关联网络状态
导出该时段所有审计日志，用 jq 提取 LibreTranslate 响应时间：

jq -r 'select(.fallback_chain[0].model == "libretranslate") | .fallback_chain[0].latency_ms' audit.log | sort -n | tail -5
# 输出：1280, 1320, 1350, 1410, 1480

确认 LibreTranslate 平均超时在 1.4s 左右，接近其默认 timeout 阈值（1.5s）。

第三步：交叉验证服务健康度
检查 LibreTranslate 服务日志（独立部署），发现同一时段 CPU 使用率持续 >95%，原因为：

• 群聊高频触发图片 OCR → OCR 结果被误送入 LibreTranslate（本应只处理纯文本）
• 原因：ClawdBot 的 input_type 识别逻辑存在缺陷，对某些 PNG 图片未正确标记为 image

4.3 闭环优化：从日志到代码修复

基于审计证据，实施两项改进：

1. 配置层：在 /app/clawdbot.json 中提高 LibreTranslate timeout 至 2000ms，并添加 input_filter 规则：

   "filters": {
     "libretranslate": ["text", "document"]  // 明确禁止 image 类型流入
   }
   

2. 代码层：提交 PR 修复 OCR 后的 input_type 判定逻辑（已合并至 main 分支）

效果验证：优化后 48 小时内，审计日志显示：

• LibreTranslate timeout 事件归零
• 平均总延迟从 2.1s 降至 0.87s
• fallback 触发率下降 92%

这正是审计追踪的价值：它不只告诉你“哪里坏了”，更精确指出“为什么坏”和“怎么修”。

5. 总结：审计追踪不是功能，而是信任基础设施

ClawdBot 的审计追踪能力，本质上是在构建一种新型的 AI 信任基础设施。它不依赖厂商承诺的“我们很安全”，而是用可验证的数据证明：

• 每一次翻译，都经过你定义的模型策略；
• 每一次 fallback，都有据可查的触发逻辑；
• 每一次异常，都能在毫秒级时间戳中定位源头。

这种能力，让个人开发者拥有了企业级的可观测性——无需昂贵的 APM 工具，无需复杂的日志管道，只需一个 clawdbot audit 命令，就能掌握整个 AI 流程的脉搏。

当你开始认真对待每一次模型调用的来龙去脉，AI 就不再是一个令人兴奋又隐隐不安的黑箱，而成为你手中可调试、可优化、真正属于你的智能伙伴。

---

获取更多AI镜像

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