1flowbase
← 文档

使用场景

Claude Code Agent 的 Token BOM：看清一次运行的钱花在哪里

English

从外面看，Claude Code 的一次 agent run 像是一次普通请求。

但真实运行里，它可能包含模型调用、缓存命中、工具回调、路由到子模型、重试、文件读取、图片理解、branch LLM 调用和最终总结。最终回答只是收据，真正值得调试的是执行路径。

这就是 Token Bill of Materials，也可以简称 Token BOM：

Token BOM = 一次 agent run 里模型调用、输入 tokens、输出 tokens、
cache-hit tokens、工具回调、延迟、失败状态和路由执行的明细表。

对 AI agent 来说，只看最终回答不够。你需要知道 tokens 花在了哪里。

为什么 Claude Code agent 需要 Token BOM

现在的 coding agent 已经不是简单聊天。一次请求可能触发：

  • planning
  • 文件搜索和文件读取
  • tool calls
  • branch model calls
  • 图片或 UI 截图理解
  • retries 和 fallback
  • final answer synthesis

如果只看最终回复，你很难回答这些问题：

哪个模型花了 tokens？
哪个 tool call 造成了 token 峰值？
请求慢是因为模型、工具，还是路由路径？
简单任务有没有交给便宜模型？
强模型是不是只用在必要步骤？
失败发生在哪里，还是被藏在最终回答之前？

1flowbase 把 agent run 变成可观测的 workflow-backed virtual model endpoint。Claude Code、Codex、Cursor、OpenCode、Cline、Continue、LibreChat 或 SDK 仍然只调用一个模型端点，但 1flowbase 会记录背后的执行路径。

Run list 是第一层 BOM

Log 表格展示每次运行的 total tokens、input tokens、output tokens、cache-hit tokens、cache hit rate、更新时间，以及 run details 入口。

1flowbase log table showing total tokens, input tokens, output tokens, cache-hit tokens, and cache hit rate

这是发现异常运行最快的视图。

比如：

从 prompt 看，一次请求可能很短。
但 run table 里可能出现数百万 total tokens，
因为成本来自 cache-hit context、路由工作或重复 agent 步骤。

它不只是成本统计。它会告诉你哪一次运行值得打开细看。

Monitor 视图展示整体成本形状

Token BOM 有两个层次：

  • 单次运行：这次请求发生了什么
  • 多次运行：一段时间内什么模式在增长

Monitor dashboard 展示 total tokens、input tokens、output tokens、cache-hit tokens、new tokens、tool callbacks、protocol distribution、source distribution 和 token trend。

1flowbase monitor dashboard showing token trend, protocol distribution, source distribution, and tool callback count

它可以回答：

tokens 主要来自 Public API 还是 console？
cache-hit tokens 是否占主导？
tool callbacks 是否在增加？
哪个协议承载了主要流量？
是哪一天或哪个 endpoint 造成峰值？

对 agent 团队来说，这就是“Claude Code 好像很贵”和“这条 route 产生了 7.5M total tokens、7.3M cache-hit tokens、99 次 tool callbacks”之间的差别。

API endpoint 让客户端保持简单

1flowbase 可以把 workflow 发布成常见模型 API。客户端只需要调用普通 endpoint：

  • OpenAI-compatible Chat Completions API
  • OpenAI-compatible Responses API
  • OpenAI-compatible Models API
  • Claude-compatible Messages API
  • Claude-compatible token counting API

1flowbase public API page showing OpenAI-compatible and Anthropic-compatible endpoints

也就是说，客户端不需要理解内部 workflow。

Claude Code / Codex / Cursor / SDK
  -> 一个 1flowbase virtual model endpoint
  -> workflow-backed model path
  -> observable run log
  -> Token BOM

这和普通 model router 不一样。普通 router 选择上游模型；1flowbase 可以把一个 workflow 暴露成模型，并展示 workflow 内部发生了什么。

Track 视图把一次运行变成执行树

打开 run，切到 Track tab，就能看到嵌套的执行步骤，而不是一个黑盒响应。

1flowbase conversation log Track tab showing tools, agents, failed steps, successful steps, and run details

在 Track 视图里，Token BOM 会变得非常具体：

  • tool steps
  • agent steps
  • LLM calls
  • 成功或失败状态
  • 每一步 token 数
  • 每一步耗时
  • input 和 output payloads
  • final run details

这在 agent “看起来只是回答了一句”，但中间其实委托、重试或失败过时特别重要。

Smart routing 让被路由的工作也可见

很多 agent 团队想做 model routing 来降成本。这是有用的，但仅仅 routing 不够。

如果你的 model endpoint 实际上是一个 workflow，你就需要看到被路由的工作。

在 1flowbase 里，mounted LLM tool 可以使用 Smart routing mode。主模型可以把一个子任务委托给 branch LLM。branch LLM 可以使用允许的外部工具，然后把结果作为 tool result 返回给主模型。

1flowbase smart routing trace showing image_llm intercepted and executed successfully with media input

Log 里可以看到：

  • image_llm Smart routing Intercepted
  • image_llm Smart routing Executed successfully
  • tool input
  • media references
  • branch model result
  • final answer

这样 route 就不是黑盒。你可以看到为什么请求离开主模型路径，被路由模型收到了什么，以及它返回了什么。

Mounted tool 定义 BOM 边界

Mounted tool 配置定义了什么时候使用 branch model，以及它能做什么。

1flowbase mounted LLM tool configuration showing tool description, Smart routing mode, branch LLM, and external tools

比如 tool description 可以写：

Do not use Read to view images. When you need to view images, call this tool.

然后工具可以配置：

  • Allow branch LLM
  • Smart routing mode
  • open external tools
  • task-specific branch model
  • 受控的 context 和 tool access

成本控制和安全边界在这里变得实际。你不是简单说“用便宜模型”，而是在定义哪个子任务可以被路由、它能看到什么上下文、能使用哪些工具。

一个实用的 Token BOM schema

对每次 run，有用字段包括：

run_id
client
protocol
virtual_model
total_tokens
input_tokens
output_tokens
cache_hit_tokens
cache_hit_rate
new_tokens
tool_callback_count
latency
slow_request_rate
source
route_decisions
failed_steps
successful_steps
final_status

对每个 step，有用字段包括：

step_id
step_type
model_or_tool
input_tokens
output_tokens
cache_hit_tokens
latency
status
error
input_payload
output_payload
parent_step

不是每个 dashboard 都需要展示所有字段。但当一次 agent run 变贵或出错时，这就是你希望拥有的证据形状。

看完 BOM 后该优化什么

Token BOM 可见之后，你可以做更好的 routing 和 workflow 决策：

  • 把简单提取或格式化交给便宜模型。
  • 把复杂 coding 或 reasoning 留给强模型。
  • 把图片理解路由给多模态 branch model。
  • 不需要工具的 route 关闭 external tools。
  • 只在容易出错的 provider 路径上加 fallback。
  • 修复导致重复 tool calls 的 prompt。
  • 分开观察 cache-hit tokens 和 new tokens。
  • 定位失败步骤，而不是直接怪最终模型。

核心区别是：

没有 Token BOM：
  这个 agent 太贵了。

有 Token BOM：
  这个 branch model 调用了 99 次工具，大部分 tokens 来自 cache-hit context，
  慢路径是 routed image inspection，失败发生在 final synthesis 之前。

什么时候用这个模式

适合使用 Token BOM 的场景：

  • Claude Code 或其他 agent client 接入 custom endpoint
  • 多模型之间做 routing
  • 挂载多模态或可使用工具的 branch LLM
  • 需要按 run 查看 cost 和 latency
  • 需要调试失败的 agent steps
  • 希望对外只有一个 model name，内部却是更丰富的 workflow

如果你只需要静态 proxy，普通 router 可能够用。只要 endpoint 背后是 workflow，就应该有 workflow trace。

这篇教程覆盖的搜索词

如果你在搜索下面这些问题，这篇教程就是对应场景：

Claude Code token cost
Claude Code token usage
Claude Code cost tracking
Claude Code 成本追踪
Claude Code token 用量
AI agent cost tracing
hidden token spend
workflow token breakdown
LLM routing cost attribution
agent trace token usage
cache-hit token cost
tool callback token cost

用 1flowbase 试试

1flowbase 是面向本地 AI agent clients 的开源 AI gateway。它可以把 workflow 发布成 virtual model endpoint，并观察 model calls、node inputs/outputs、tool callbacks、tokens、latency、failures 和 cost。

Repository: https://github.com/taichuy/1flowbase

相关教程：

如果这篇帮你看清 agent 成本或 routing 问题，欢迎 star 这个仓库，然后试着把一个 workflow 发布成 virtual model endpoint。