Sherlock LLM Token 追踪工具技术分析一、概述1. 简介A. 是什么Sherlock 是一个专为 LLM CLI 工具设计的 Token 追踪器，通过实时终端仪表盘拦截和可视化 LLM API 流量，帮助开发者跟踪成本、调试提示词并监控上下文窗口使用情况。B. 为什么需要随着 LLM 应用开发日益普及，开发者面临以下挑战：Token 消耗难以精确跟踪，导致成本超预算上下文窗口使用情况不透明，容易超出限制提示词调试缺乏有效工具，难以优化性能需要零配置的解决方案，避免复杂的证书设置C. 能做什么实时追踪每次请求的 Token 消耗量可视化显示上下文窗口使用率的燃料仪表盘自动保存所有提示词为 Markdown 和 JSON 格式无需证书或复杂配置，安装即用2. 前置知识A. 必备技能基本的终端命令行操作Python 环境管理和包安装了解 LLM API 基本概念（Token、上下文窗口）B. 推荐知识HTTP 代理原理Claude Code、Gemini CLI 等 LLM CLI 工具的使用二、环境准备1. 系统要求Python 3.10 或更高版本macOS、Linux 或 Windows 操作系统支持的 LLM CLI 工具：Claude Code、OpenAI Codex、Gemini CLI2. 安装步骤通过 Git 克隆并安装：git clone https://github.com/jmuncor/sherlock.git cd sherlock pip install -e .3. 验证安装sherlock --help三、核心概念1. 基本术语Token：LLM 处理文本的基本单位，消耗与计费依据上下文窗口：单次对话允许的最大 Token 数量HTTP 代理：拦截和转发 LLM API 请求的中介服务燃料仪表盘：可视化显示 Token 使用率的进度条2. 工作原理Sherlock 通过本地 HTTP 代理拦截 LLM CLI 工具的 API 请求，解析 Token 使用情况，并在终端仪表盘实时展示。graph TB A[终端1: sherlock start] --> B[HTTP代理 localhost:8080] B --> C[仪表盘] B --> D[提示词归档] E[终端2: sherlock claude] --> F[设置环境变量] F --> G[运行claude命令] G --> B B -->|HTTPS转发| H[api.anthropic.com]3. 架构设计graph LR A[LLM CLI工具] -->|HTTP请求| B[Sherlock代理] B -->|解析Token| C[仪表盘显示] B -->|保存| D[Markdown文件] B -->|保存| E[JSON文件] B -->|转发| F[LLM API] F -->|响应| B B -->|返回| A四、快速上手1. 启动仪表盘在第一个终端启动 Sherlock：sherlock start首次运行时会提示选择提示词保存目录，然后显示仪表盘：┌─────────────────────────────────────────────────────────────┐ │ SHERLOCK - LLM Traffic Inspector │ ├─────────────────────────────────────────────────────────────┤ │ Context Usage ████████████░░░░░░░░░░░░░░░░ 42% │ │ (84,231 / 200,000 tokens) │ ├─────────────────────────────────────────────────────────────┤ │ Time Provider Model Tokens│ │ 14:23:01 Anthropic claude-sonnet-4-20250514 12,847│ │ 14:23:45 Anthropic claude-sonnet-4-20250514 8,234│ │ 14:24:12 Anthropic claude-sonnet-4-20250514 15,102│ ├─────────────────────────────────────────────────────────────┤ │ Last Prompt: "Can you help me refactor this function..." │ └─────────────────────────────────────────────────────────────┘2. 运行 LLM 工具在第二个终端运行支持的 LLM CLI 工具：Claude Code：sherlock claudeOpenAI Codex：sherlock codexGemini CLI（存在上游问题）：sherlock gemini3. 实时监控仪表盘会实时更新，显示：当前 Token 使用量和百分比每次 API 调用的详细记录燃料仪表盘颜色变化：绿色（<50%）、黄色（50-80%）、红色（>80%）五、核心功能1. 实时仪表盘A. 燃料仪表盘可视化显示 Token 使用率，颜色编码：绿色：使用率低于 50%黄色：使用率 50-80%红色：使用率超过 80%B. 请求历史表格显示每次 API 调用的详细信息：时间戳服务提供商模型名称Token 消耗量2. 提示词归档所有拦截的请求自动保存到指定目录：Markdown 格式：人类可读的格式包含元数据（时间、模型、Token 数）便于审查和分享JSON 格式：原始 API 请求体完整的请求和响应数据用于调试和分析3. 会话摘要退出时显示总体使用情况：Session complete. Total: 84,231 tokens across 12 requests.六、命令详解1. 启动命令sherlock start [OPTIONS]选项：-p, --port NUM：代理端口（默认：8080）-l, --limit NUM：燃料仪表盘的 Token 限制（默认：200000）2. Claude Code 命令sherlock claude [OPTIONS] [ARGS]...选项：-p, --port NUM：代理端口（默认：8080）说明：自动设置 ANTHROPIC_BASE_URL 环境变量并运行 claude 命令。3. 通用运行命令sherlock run --provider <name> <cmd>说明：运行任何命令并配置代理环境变量。七、支持的服务商服务商命令状态Anthropic (Claude Code)sherlock claude支持Google (Gemini CLI)sherlock gemini受上游问题阻拦OpenAI (Codex)sherlock codex支持1. Gemini CLI 已知问题Gemini CLI 存在已知问题，在使用 OAuth 认证时会忽略自定义基础 URL。该问题由上游项目导致，详情参考：https://github.com/google-gemini/gemini-cli/issues/15430八、技术实现1. 代理机制Sherlock 使用 HTTP relay proxy 替代原有的 mitmproxy，实现更轻量级的流量拦截：sequenceDiagram participant U as 用户命令 participant S as Sherlock代理 participant L as LLM API U->>S: HTTP请求 S->>S: 解析Token S->>S: 更新仪表盘 S->>S: 保存提示词 S->>L: 转发请求 L-->>S: API响应 S-->>U: 返回结果2. 环境变量注入Sherlock 通过设置特定环境变量将 LLM CLI 工具的请求路由到本地代理：Claude Code：ANTHROPIC_BASE_URL=http://localhost:8080OpenAI Codex：OPENAI_API_BASE=http://localhost:8080Gemini CLI：GEMINI_API_BASE=http://localhost:80803. Token 解析Sherlock 解析 API 响应中的 Token 使用信息：输入 Token 数量输出 Token 数量总计 Token 数量九、使用场景1. 成本追踪实时监控 Token 消耗，避免超预算：设置 Token 限制提醒统计会话总消耗分析不同模型的成本差异2. 提示词优化通过归档的提示词进行优化：对比不同提示词的效果分析 Token 效率复用高效提示词模板3. 上下文管理监控上下文窗口使用情况：避免超出上下文限制优化对话历史长度提升响应准确性十、最佳实践1. 开发工作流建议的开发流程：启动 Sherlock 仪表盘在独立终端运行 LLM 工具实时监控 Token 使用定期审查提示词归档根据数据优化提示词2. 成本控制设置合理的 Token 限制：开发环境：50,000-100,000 tokens测试环境：100,000-200,000 tokens生产环境：根据实际需求调整3. 团队协作共享提示词归档：建立团队提示词库标注高效提示词定期分享最佳实践十一、故障排除1. 代理无法启动检查端口占用：lsof -i :8080使用其他端口：sherlock start --port 88882. LLM 工具无法连接确认环境变量设置：echo $ANTHROPIC_BASE_URL手动设置环境变量：export ANTHROPIC_BASE_URL=http://localhost:80803. Token 统计不准确某些服务商可能不返回详细的 Token 使用信息，Sherlock 会显示可用数据。十二、开发与贡献1. 开发环境设置git clone https://github.com/jmuncor/sherlock.git cd sherlock python -m venv venv source venv/bin/activate pip install -e .2. 贡献流程Fork 项目仓库创建功能分支：git checkout -b feature/amazing-feature提交更改：git commit -m 'Add amazing feature'推送分支：git push origin feature/amazing-feature创建 Pull Request3. 项目结构sherlock/ ├── sherlock/ # 核心代码 ├── pyproject.toml # 项目配置 ├── LICENSE # MIT 许可证 └── README.md # 项目文档十三、技术特点1. 零配置设计无需安装证书或修改系统配置：自动启动本地代理自动注入环境变量自动保存提示词归档2. 轻量级实现使用 HTTP relay proxy 替代重量级方案：更少的依赖更快的启动速度更低的资源占用3. 终端原生界面使用 Rich 库构建美观的终端界面：实时更新颜色编码响应式布局十四、未来展望1. 支持更多服务商计划添加对以下服务的支持：更多 LLM 提供商自定义 API 端点本地部署的模型2. 增强分析功能计划添加：Token 消耗趋势图表成本预测提示词效率分析3. 团队协作功能计划添加：共享提示词库团队使用统计成本分摊计算参考资料Sherlock GitHub 仓库Claude Code 官方文档Gemini CLI 已知问题