Tokentap（原 Sherlock）：给 LLM 命令行装上”流量仪表盘”

用 Claude Code、Codex 这类命令行 Agent 时，一个尴尬的问题是：你不知道这一整轮到底烧了多少 token、上下文还剩多少。原名为 Sherlock、现更名为 Tokentap 的开源小工具就是来解决这件事的——它在本地起一个代理，把 LLM CLI 的流量拦下来，实时显示 token 消耗，并把每次 prompt 存档。本文基于其 GitHub 仓库 README 分析。

一、它是什么

README 顶部已经更名：“Tokentap (formerly Sherlock) — Token Tracker for LLM CLI Tools”。它是一个 Python 3.10+、MIT 协议、面向 macOS/Linux 的命令行工具：pip install tokentap 即用。

核心能力：

• 实时 token 追踪：每个请求消耗多少 token 一目了然；
• 上下文燃料表：可视化显示累计用量占上下文上限的百分比；
• Prompt 存档：每次被拦截的请求自动存成 Markdown（人读）和 JSON（原始请求体）；
• 零配置：README 自称 “No certificates, no setup - just install and go”。

二、核心机制：不是 MITM，而是改写 base URL

这里有一个值得澄清的口径。项目库点评把它描述成”通过 mitmproxy 代理 HTTPS 请求”，但 README 的架构图显示它的做法其实更轻：

Terminal 1: tokentap start
   → HTTP Proxy (localhost:8080) + Dashboard + Prompt Archive
Terminal 2: tokentap claude
   → 设 ANTHROPIC_BASE_URL=http://localhost:8080，再启动 claude
   → 代理再把请求转发到 https://api.anthropic.com

也就是说，它不需要安装根证书做 HTTPS 中间人解密，而是直接利用 CLI 本身支持的 *_BASE_URL 环境变量，把请求指向本地代理。这是它”零证书配置”的真正原因——对大多数人来说，装自签根证书才是这类工具最大的门槛。

对 OpenAI 兼容的第三方（如 MiniMax），它用路径前缀路由：

OPENAI_BASE_URL=http://localhost:8080/minimax/v1
→ 代理剥掉 /minimax 前缀，转发到 https://api.minimax.io/v1

三、仪表盘与命令

启动后终端仪表盘长这样（README 原文）：

┌─────────────────────────────────────────────────────────────┐
│  Context Usage  ████████████░░░░░░░░░░░░░░░░  42%           │
│                 (84,231 / 200,000 tokens)                   │
│  14:23:01 Anthropic  claude-sonnet-4-20250514   12,847      │
│  14:23:45 Anthropic  claude-sonnet-4-20250514    8,234      │
└─────────────────────────────────────────────────────────────┘

燃料表按使用率变色：<50% 绿、50–80% 黄、>80% 红；默认上限 200,000 token（可用 --limit 调）。退出时输出会话汇总，例如 “84,231 tokens across 12 requests”。

四、支持矩阵与已知问题

README 的 Known Issues 明确写了 Gemini CLI 目前因上游问题无法正常拦截。这与项目库点评里”主要支持 Claude Code，Codex/Gemini 在计划中”的说法需要对齐：截至 README 当前版本，Codex 已支持，Gemini 仍受上游问题阻塞。

五、口径偏差与局限

1. “成本估算”是近似：仪表盘直接显示 token 数，但 README 并未内置各模型的单价表——“成本”需要你自己按 token 算，token 计数本身也依赖响应里返回的 usage 字段，流式场景下的统计精度未说明。
2. 依赖 CLI 支持 base URL 改写：能拦的前提是 CLI 尊重 ANTHROPIC_BASE_URL / OPENAI_BASE_URL 这类环境变量；硬编码 endpoint 或自带证书校验的客户端就拦不到——这也是 Gemini CLI 被上游卡住的原因。
3. 仅 macOS/Linux：徽章明确标注平台，Windows 用户用不了。
4. “零配置”指证书零配置：它仍是一个会拦截你全部 API 流量的本地代理，prompt 会落盘——隐私上要自己注意存档目录。
5. 配图说明：README 仅含状态徽章、无独立截图，故正文直接复刻其 ASCII 仪表盘与架构图，信息无损。

六、适用 / 不适用

适合：

• 日常重度使用 Claude Code / Codex、想实时掌握上下文占用与 token 花销的开发者；
• 想留档每次发给模型的 prompt、便于复盘 Agent 行为或调试的人；
• 研究 Agent 到底发了什么请求的”逆向观察”场景（项目库点评点出的潜力）。

不适合：

• Windows 用户；
• 需要按金额精确结算、或要跨团队汇总成本的场景——它更像个人调试仪表，不是计费系统；
• 用 Gemini CLI 为主要工具的人（当前被上游问题阻塞）。

七、它意味着什么

Tokentap 这类工具的价值表面是”省 token”，实际更大的意义在可观测性：当 Agent 越来越自动地调用模型，开发者需要一个窗口去看”它到底发了什么、花了多少”。用改写 base URL 代替证书劫持，是一个聪明地降低接入门槛的工程选择——但它能拦谁，完全取决于各家 CLI 是否留了这个口子。

参考来源

• Tokentap（原 Sherlock）GitHub 仓库
• Koala 项目库条目：Sherlock