1. 项目概述：一个为Claude开发者设计的代码使用量追踪工具

最近在折腾Claude API做项目时，我遇到了一个挺实际的问题：怎么才能清晰地知道我的代码到底调用了多少次API、花了多少钱、每个功能模块的消耗占比如何？官方后台的数据太笼统，而且延迟高，对于需要精细成本控制和性能优化的团队来说，远远不够用。就在我四处寻找解决方案时，发现了GitHub上一个名为“claude-code-usage”的项目，作者是brucechou1983。这个工具的核心目标很明确——为使用Claude（特别是其代码相关能力，如Claude Code）的开发者，提供一个轻量级、可自部署的API使用量追踪与分析系统。

简单来说，它就像一个为你专属的Claude API“仪表盘”。你不再需要频繁登录官方后台，去在一堆混杂的请求日志里手动筛选；而是通过这个工具，自动收集、聚合并可视化你的每一次API调用。无论是个人开发者测试新想法，还是团队在正式产品中集成Claude，都能通过它实时掌握使用情况，及时发现异常调用（比如某个循环里的提示词写错了，导致每秒被调用上百次），从而避免月底收到“惊喜账单”。这个项目解决的不是“能不能用”的问题，而是“怎么用得明明白白、用得划算”的问题，对于所有将大模型API投入实际生产的团队来说，这都是一个刚需。

2. 核心设计思路：从日志收集到可视化分析的全链路拆解

2.1 为什么需要独立的用量追踪？

Claude官方提供的用量统计存在几个天然的短板。首先，数据粒度不够细。你只能看到某个API Key在某个时间段内的总请求数、总token消耗和总费用，但无法区分这些请求具体来自哪个应用、哪个用户、甚至哪个功能模块。其次，数据延迟可能高达数小时，无法实现实时监控。最后，缺乏自定义分析能力。你无法按照自己的业务维度（如项目ID、用户等级、模型版本）进行聚合查询。

“claude-code-usage”项目的设计哲学，正是为了填补这些空白。它的核心思路是“中间件拦截+本地存储+灵活分析”。工具本身作为一个轻量级的代理服务，部署在你的应用和Claude官方API之间。所有发往Claude API的请求，都会先经过这个代理。代理在转发请求的同时，会同步记录下本次请求的“元数据”——包括但不限于请求时间、使用的模型、提示词（Prompt）和补全（Completion）的token数、请求状态、响应时间，以及你自定义的标签（如 project_id , user_id , feature_name ）。这些数据被实时写入一个本地数据库（如SQLite或PostgreSQL），然后通过一个内置的Web仪表盘进行查询和可视化。

2.2 架构选型与技术栈考量

作者在技术栈的选择上体现了实用主义。项目主要使用Python，这是自然语言处理和大模型领域最主流的语言，生态丰富，与Claude的官方SDK无缝集成。Web框架很可能选择了FastAPI或Flask，因为它们轻量、异步支持好，适合构建高性能的API代理。数据库方面，为了降低部署复杂度，默认可能采用了SQLite，它无需单独服务，单文件即可运行，非常适合个人或小团队使用；同时，项目很可能也支持连接更强大的PostgreSQL，以满足团队协作和更大数据量的需求。

前端仪表盘部分，考虑到项目的工具属性，大概率使用了简单的模板引擎（如Jinja2）配合一些轻量级图表库（如Chart.js或ECharts）来渲染，避免了复杂前端框架带来的额外依赖和构建步骤。整个架构追求的是“开箱即用”：开发者克隆项目，配置好API Key和数据库连接，启动服务，然后将自己应用的API端点从 https://api.anthropic.com 改为本工具的代理地址，追踪就自动开始了。

注意 ：这种代理模式意味着你的所有API请求流量都会经过自部署的服务。因此，务必确保该服务部署在安全、可靠的环境中，并做好访问权限控制，防止API Key泄露和请求数据被窃取。

3. 核心功能模块深度解析

3.1 请求拦截与元数据记录

这是工具的基石。其核心是一个HTTP代理服务器，它需要精准地识别出指向Claude API的请求。通常，它会监听特定路径，例如 /v1/messages （对应Claude的消息API）。当请求到达时，代理会执行以下关键操作：

  1. 请求验证与转发 ：首先，它会从请求头中提取出你配置的Claude API Key，将其替换或添加到转发给官方API的请求头中（这里通常采用添加 x-api-key 头的方式）。同时，它需要保留用户原始请求的Body（即提示词和参数）。
  2. 异步日志记录 ：在将请求转发给官方API的同时， 不会 等待官方响应回来再记录。而是会立即提取并记录那些在转发时就能确定的信息，例如：
    • request_id : 生成一个唯一ID用于追踪。
    • timestamp : 请求发起时间。
    • model : 请求指定的模型（如 claude-3-opus-20240229 ）。
    • prompt_tokens : 通过计算请求Body中的消息内容估算出的token数（这里需要集成类似 tiktoken 的库来精确计算）。
    • custom_tags : 从请求头或URL参数中解析出自定义标签。这是非常关键的功能，允许你通过类似 X-Project-ID: my_awesome_app 这样的请求头来打标。
  3. 响应处理与补全记录 ：收到Claude API的响应后，代理再将响应体原样返回给你的应用。同时，在后台异步完成日志记录的补充：
    • response_id : 记录官方返回的响应ID。
    • status_code : HTTP状态码。
    • completion_tokens : 从响应体中提取出AI生成的文本，并计算其token数。
    • total_tokens : prompt_tokens + completion_tokens 。
    • response_time_ms : 整个请求的耗时。
    • cost : 根据当前模型的定价（如 claude-3-opus 每百万tokens输入$15，输出$75）和本次使用的token数，计算出本次请求的估算成本。这一步需要工具内置一个模型价格表，并定期更新。

3.2 数据存储与聚合模型设计

记录下来的海量请求数据需要被高效存储和查询。数据库表的设计至关重要。一个核心的 api_requests 表可能包含以下字段：

CREATE TABLE api_requests (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    request_id TEXT UNIQUE,
    timestamp DATETIME,
    model TEXT,
    prompt_tokens INTEGER,
    completion_tokens INTEGER,
    total_tokens INTEGER,
    status_code INTEGER,
    response_time_ms INTEGER,
    estimated_cost REAL,
    project_id TEXT,
    user_id TEXT,
    feature_name TEXT,
    -- ... 其他自定义标签字段
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

为了支持快速分析，通常还需要创建索引，例如在 timestamp 、 project_id 、 model 上创建索引，这样按时间范围、按项目、按模型筛选查询时会非常快。

除了原始记录，工具可能还会定期（例如每小时或每天）运行聚合任务，生成汇总数据到另一张 usage_summary 表。这张表可以存储按小时/天/项目/模型维度聚合的总请求数、总token、总成本、平均响应时间等。这样，在查询历史趋势图表时，就不需要每次都去扫描庞大的原始数据表，极大提升了仪表盘的加载速度。

3.3 可视化仪表盘与查询接口

数据有了，如何直观地看？仪表盘的设计应围绕几个核心场景：

  • 实时监控 ：一个大屏，显示当前小时/分钟的请求速率、成功/失败率、平均响应时间、实时成本消耗。这有助于快速发现服务异常。
  • 成本分析 ：这是重中之重。需要提供按项目、按模型、按时间（日/周/月）维度的成本柱状图或曲线图。一眼就能看出哪个项目是“耗电大户”，哪个模型升级导致了成本激增。
  • 用量明细 ：一个可筛选、可分页的表格，列出所有历史请求。支持按时间、状态码、项目、用户等条件筛选，方便定位某一次具体的调用。
  • Token效率分析 ：统计平均每次请求的Prompt Token和Completion Token比例。如果一个功能的Prompt非常长但Completion很短，可能就需要优化提示词工程；反之，如果Completion很长，则可能需要考虑是否输出过于冗余。

此外，工具还应提供简单的RESTful API，允许你将用量数据集成到自己的监控系统（如Grafana）或财务系统中。

4. 部署与配置实操指南

4.1 环境准备与快速启动

假设你已经在开发机上准备好了Python 3.8+的环境和Git。部署的第一步是获取代码。

git clone https://github.com/brucechou1983/claude-code-usage.git
cd claude-code-usage

接下来是安装依赖。项目根目录下应该有一个 requirements.txt 文件。

pip install -r requirements.txt

安装的依赖通常包括： fastapi (Web框架), uvicorn (ASGI服务器), sqlalchemy (ORM), pydantic (数据验证), httpx (异步HTTP客户端，用于转发请求), tiktoken (Token计算)等。

安装完成后，你需要复制或重命名配置文件模板。通常项目会提供一个 .env.example 或 config.yaml.example 文件。

cp .env.example .env

然后，用你喜欢的编辑器打开 .env 文件，进行关键配置：

# 你的Claude API Key，从Anthropic控制台获取
CLAUDE_API_KEY=sk-ant-xxx...
# 代理服务监听的端口，你的应用将请求发往这个地址
PROXY_HOST=0.0.0.0
PROXY_PORT=8000
# 数据库连接字符串，默认使用SQLite，文件位于项目目录内
DATABASE_URL=sqlite:///./claude_usage.db
# 仪表盘访问的密钥（可选但强烈建议设置），用于基础认证
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=your_strong_password_here

配置完成后，就可以启动服务了。启动命令可能类似：

python main.py
# 或者，如果使用uvicorn直接运行ASGI应用
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

看到服务成功启动在 http://localhost:8000 后，你可以先访问 http://localhost:8000/dashboard （具体路径看项目文档）登录仪表盘。此时还没有数据，因为还没有流量经过代理。

4.2 集成到你的应用：修改API端点

这是最关键的一步。假设你原来使用Python anthropic SDK调用Claude的代码是这样的：

import anthropic
client = anthropic.Anthropic(api_key="your-api-key")
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Hello, Claude"}]
)

为了让流量经过用量追踪代理，你不需要修改SDK调用逻辑，只需要改变API的基地址（base URL）。 anthropic SDK通常支持通过 base_url 参数来指定。

import anthropic
# 将base_url指向你本地部署的代理服务
client = anthropic.Anthropic(
    api_key="your-api-key", # 这里可以填任意值或留空，因为代理会替换它
    base_url="http://localhost:8000/v1" # 注意，代理服务模拟了Claude API的/v1路径
)
# 其余的调用代码完全不变
response = client.messages.create(...)

重要 ：此时，你传递给 Anthropic 客户端的 api_key 参数实际上不会被发送到官方API（因为请求被代理拦截了）。代理服务会使用你在其配置文件（ .env ）中设置的 CLAUDE_API_KEY 来替换它。这样做的好处是，你的应用代码中可以不写或写一个假的API Key，真正的密钥安全地保存在代理服务器的配置里。

对于其他语言或直接使用HTTP请求的场景，只需将请求的URL从 https://api.anthropic.com/v1/messages 改为 http://你的代理地址:端口/v1/messages 即可，请求头和Body保持不变。

4.3 为请求打上业务标签

为了让数据分析更有意义，你需要为不同的请求打上业务标签。最常用的方式是通过HTTP请求头传递。代理服务会识别特定的请求头，并将其值作为标签存入数据库。

例如，你想标记当前请求属于“项目A”的“总结摘要”功能，由“用户123”发起：

import anthropic
client = anthropic.Anthropic(
    api_key="dummy_key",
    base_url="http://localhost:8000/v1",
    # 关键：通过default_headers设置自定义标签头
    default_headers={
        "X-Project-ID": "project_a",
        "X-Feature-Name": "summarization",
        "X-User-ID": "user_123"
    }
)
response = client.messages.create(...)

代理服务会解析 X-Project-ID 、 X-Feature-Name 、 X-User-ID 这些头（具体的头名称需要查看项目文档），并将它们的值记录到数据库的对应字段中。这样，在仪表盘里你就可以轻松地筛选出“项目A”在“总结摘要”功能上的所有花费了。

5. 仪表盘使用与数据分析实战

5.1 核心面板解读与日常监控

登录仪表盘后，你通常会看到几个核心面板：

  1. 概览面板 ：显示最近24小时或7天的关键指标趋势图。包括：

    • 请求量 ：折线图，观察调用频率是否有异常峰值。
    • Token消耗 ：通常分为输入Token和输出Token两条线，帮助你了解成本构成。
    • 估算成本 ：折线图，直观显示每天花了多少钱。
    • 平均响应延迟 ：折线图，监控API性能是否稳定。如果延迟突然飙升，可能意味着网络问题或官方API负载过高。
    • 成功率 ：饼图或指标卡，显示成功请求与失败（如429限流、5xx错误）请求的比例。

  2. 成本分析面板 ：这是财务关注的重点。你可以在这里：

    • 按 项目 分组查看成本排行，快速定位成本最高的项目。
    • 按 模型 分组（如Claude 3 Opus vs Sonnet vs Haiku），分析不同模型带来的成本差异，为模型选型提供数据支持。
    • 选择不同的时间粒度（日、周、月），查看成本变化趋势。

  3. 请求日志面板 ：一个功能强大的数据表格，列出了每一笔请求的详细记录。支持：

    • 时间范围筛选 ：精确查看某一时刻的请求。
    • 状态码筛选 ：快速找出所有失败的请求，便于排查问题。
    • 项目/功能/用户筛选 ：进行多维度的下钻分析。
    • 查看详情 ：点击单条记录，可以展开查看其完整的请求提示词（Prompt）和AI回复（Completion）内容。 这是一个非常强大的调试功能 ，当AI输出不符合预期时，你可以直接在这里回溯当时的“对话现场”。

5.2 基于数据进行优化决策

数据本身没有价值，基于数据的行动才有。以下是一些基于仪表盘数据可以进行的优化：

  • 识别并优化“低效”提示词 ：在请求日志中，按 prompt_tokens 从高到低排序。你会发现一些提示词异常长的请求。点开详情，分析这些长提示词是否必要。是否包含了过多无关的上下文？是否可以通过更精炼的指令达到相同效果？优化提示词是降低输入Token成本最直接的方法。
  • 调整模型策略 ：通过成本分析面板，对比不同模型在相似任务上的成本和效果。也许对于简单的文本校对任务，使用更便宜的Claude 3 Haiku模型已经足够，而不必一直使用昂贵的Opus模型。你可以据此制定一个模型路由策略：简单任务用便宜模型，复杂任务再用强模型。
  • 设置用量告警 ：虽然工具本身可能不直接提供告警功能，但你可以定期查看成本趋势。如果发现某个项目或功能的成本在短期内急剧上升，应立即介入检查。是否是代码出现了循环调用BUG？还是该功能突然迎来了大量用户？你可以基于数据库，自己写一个简单的脚本，当每日成本超过阈值时发送邮件或Slack通知。
  • 评估功能ROI ：结合业务数据（如某个AI功能带来的用户活跃度或收入提升），与它产生的API成本进行对比，可以清晰地评估该AI功能的投资回报率，为产品决策提供依据。

6. 生产环境部署与高阶配置

6.1 从开发环境到生产环境

在本地开发测试没问题后，你需要将 claude-code-usage 部署到一台稳定的服务器上，供团队所有应用调用。

  1. 服务器选择 ：选择一台网络稳定、有公网IP（如果需要从外部调用）的云服务器。配置无需太高，初期2核4GB内存足够。
  2. 使用进程守护 ：不能直接通过 python main.py 在终端运行，终端关闭服务就停了。需要使用像 systemd 或 supervisor 这样的进程管理工具。以下是一个 systemd 服务文件的示例（ /etc/systemd/system/claude-usage.service ）： 
    [Unit]
Description=Claude Code Usage Tracker
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/path/to/claude-code-usage
Environment="PATH=/usr/local/bin"
EnvironmentFile=/path/to/claude-code-usage/.env.production # 生产环境配置文件
ExecStart=/usr/local/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
    然后使用 sudo systemctl start claude-usage 启动， sudo systemctl enable claude-usage 设置开机自启。
  3. 数据库升级 ：生产环境建议将SQLite更换为PostgreSQL。PostgreSQL更稳定，支持并发连接数更高，且便于后期做数据备份和迁移。只需修改 .env.production 中的 DATABASE_URL 为PostgreSQL连接串即可，例如 DATABASE_URL=postgresql://user:password@localhost:5432/claude_usage 。工具使用的ORM（如SQLAlchemy）通常能自动处理表结构迁移。
  4. 安全加固 ：
    • 防火墙 ：在服务器防火墙中，只开放代理服务端口（如8000）和必要的SSH端口。
    • HTTPS ：如果你的应用通过公网调用此代理， 必须 配置HTTPS。可以使用Nginx作为反向代理，配置SSL证书。
    • 访问控制 ：确保仪表盘的访问密码足够复杂，并考虑限制访问IP（通过Nginx或应用自身配置）。

6.2 性能调优与数据维护

随着请求量增大，需要注意以下问题：

  • 数据库性能 ：确保 api_requests 表在 timestamp , project_id 等常用查询字段上建立了索引。定期清理过期数据，可以写一个定时任务（cron job），每月删除3个月前的原始请求日志，只保留聚合后的统计数据。
  • 代理服务性能 ：代理服务本身是I/O密集型（网络转发和数据库写入）。使用异步框架（如FastAPI+ httpx ）能很好地处理并发。如果请求量极大（每秒数百次），可以考虑将日志写入先放入一个内存队列（如Redis），然后由后台工作者批量写入数据库，避免数据库写入成为瓶颈。
  • 高可用考虑 ：对于关键业务，可以考虑部署两个代理实例，前面用负载均衡器（如Nginx）做分流。两个实例连接同一个PostgreSQL数据库。需要确保自定义的 request_id 在分布式环境下也能保持全局唯一。

7. 常见问题与故障排查实录

在实际部署和使用过程中，你肯定会遇到各种问题。以下是我和社区遇到的一些典型情况及其解决方案。

7.1 代理服务相关

问题1：应用修改API端点后，调用Claude全部超时或失败。

  • 排查步骤 ：
    1. 检查代理服务状态 ：在服务器上运行 sudo systemctl status claude-usage ，查看服务是否正在运行。检查日志 sudo journalctl -u claude-usage -f 是否有错误信息。
    2. 检查网络连通性 ：从代理服务器本身，尝试用 curl 命令直接调用Claude官方API，确保服务器能访问 api.anthropic.com 。 curl -X POST https://api.anthropic.com/v1/messages -H "x-api-key: YOUR_KEY" ... 。如果连不上，检查服务器网络和防火墙规则。
    3. 检查配置 ：确认代理服务的 .env 文件中 CLAUDE_API_KEY 配置正确且未过期。
    4. 检查应用配置 ：确认你的应用中将 base_url 修改成了正确的代理服务器地址和端口。 特别注意 ：如果你的应用在Docker容器内，而代理服务在宿主机上，不能使用 localhost ，需要使用宿主机的局域网IP或服务名。

问题2：仪表盘可以打开，但看不到任何数据。

  • 排查步骤 ：
    1. 确认流量经过代理 ：检查你的应用代码，确保 base_url 已正确修改。
    2. 检查数据库 ：登录到数据库（如 sqlite3 claude_usage.db ），执行 SELECT COUNT(*) FROM api_requests; ，看是否有记录。如果没有，说明代理没有成功写库。检查代理日志，看是否有数据库连接错误或写入错误。
    3. 检查时间筛选 ：仪表盘默认可能只显示“今天”的数据。如果你刚刚开始使用，请将时间筛选范围调整到包含你开始测试的时间点。

7.2 数据与标签相关

问题3：自定义的业务标签（如Project ID）没有在仪表盘中显示或无法筛选。

  • 原因与解决 ：这通常是因为代理服务没有正确解析你设置的自定义请求头。你需要：
    1. 查阅 claude-code-usage 项目的文档，确认它支持哪些自定义请求头字段。常见的命名可能是 X-Usage-Tag-Project 、 X-Tag-Project 等。
    2. 在你的应用代码中，确保设置了正确的请求头名称。
    3. 检查代理服务的配置，看是否需要显式启用或配置自定义标签的解析功能。

问题4：仪表盘中估算的成本和Claude官方后台显示的成本有细微差异。

  • 原因 ：这是正常现象。差异可能来自：
    1. Token计算方式 ：代理使用 tiktoken 库计算Token，与Anthropic官方计算方式可能存在极其细微的差异（通常可忽略）。
    2. 定价数据延迟 ：代理内置的模型价格表可能没有及时更新到最新的价格。你需要定期关注项目更新，或手动更新代理服务中存储定价的配置文件。
    3. 数据聚合时间差 ：官方后台的数据有数小时延迟，且结算周期可能以UTC时间零点为准，而你的代理统计的是本地时间。建议以官方账单为准，代理数据主要用于实时监控和趋势分析。

7.3 扩展与集成

问题5：我想把用量数据推送到我们公司自己的数据仓库（如Snowflake）或BI工具（如Tableau）里，怎么做？

  • 方案 ： claude-code-usage 项目通常专注于收集和提供基础可视化。对于高级集成，你有几个选择：
    1. 直接查询数据库 ：因为所有数据都存在数据库里（SQLite或PostgreSQL），你可以直接用你熟悉的BI工具连接这个数据库，进行更复杂的分析和报表制作。
    2. 使用内置API ：检查项目是否提供了查询用量数据的REST API。如果有，你可以写一个定时脚本，调用这些API将数据同步到你的数据仓库。
    3. 修改源码，增加导出功能 ：这是最灵活的方式。你可以在代码中增加一个功能，定期将聚合数据以CSV格式导出到指定目录，或直接调用你公司数据平台的API进行推送。这需要一定的开发能力。

问题6：团队多人使用，如何区分不同成员或不同团队的用量？

  • 方案 ：核心机制就是利用 自定义标签 。
    1. 为每个团队/项目分配唯一ID ：在代理配置或一个共享配置中心，定义好团队和项目的映射关系。
    2. 在应用层注入标签 ：每个团队在调用代理时，必须在请求头中带上自己团队或项目的唯一ID（如 X-Team-ID: data_science ）。
    3. 仪表盘权限（高级） ：基础的仪表盘可能所有数据都可见。如果需要数据隔离，就需要修改前端和后端代码，实现基于标签的数据过滤和用户登录权限系统。例如，团队A的用户登录后，只能看到 team_id 为A的数据。这属于二次开发范畴。

经过这样一番从原理到实践，从部署到排查的深度折腾，你会发现 brucechou1983/claude-code-usage 这类工具的价值远超一个简单的计数器。它把大模型API从“黑盒消费”变成了“透明运营”，让你在享受AI能力的同时，牢牢握住了成本与效能的缰绳。对于任何严肃的AI应用项目，这样一层可观测性建设，不是可选项，而是必选项。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

AI动态简报之算力基建篇

avatar DeepSeek技术社区
cover

端侧小模型 vs 云端大模型双轨部署：规则分流还是训练路由器的工程选择

avatar DeepSeek技术社区
cover

Agent 工具权限爆炸？最小权限原则与 DeepSeek 多租户隔离实践

avatar DeepSeek技术社区