GitHub Copilot Usage Metrics API 完整教程：OpenCode、Claude Code、Codex Token统计与企业成本分析

一、GitHub 为什么开始统计更多 AI 编程工具？

2026 年 10 月 23 日，GitHub 宣布 Copilot Usage Metrics API 增加更细致的客户端统计能力。

此次新增字段名称为：

totals_by_client

它能够帮助企业判断，开发者通过哪些工具使用了 Copilot 提供的模型服务。

过去，企业可能主要关注 VS Code、JetBrains 等 IDE 中的 Copilot 使用情况。

但随着 AI 编程工具快速发展，越来越多开发者会在终端中使用 OpenCode、Claude Code、Codex 或其他 Agent 工具。

这些工具如果将 GitHub Copilot 作为模型供应渠道，可能产生真实模型费用和调用量。

但它们未必会像传统 IDE 一样提供完整编辑器遥测信息。

因此，仅依赖按 IDE 分类的统计，可能无法覆盖实际使用流量。

GitHub 此次新增服务端客户端分类，目的就是让企业能够更全面地观察 Copilot 模型消费情况。

不过，GitHub 只能统计通过其 Copilot 服务产生的对应模型流量，而不是自动读取所有独立 AI 编程平台的账户。

二、totals_by_client 是什么？

totals_by_client 是 Copilot Usage Metrics 报告中新增加的客户端维度数组。

数组中每个对象对应一种客户端来源。

例如，某家公司使用 VS Code、OpenCode 和 Codex。

如果这些工具均通过 GitHub Copilot 发送模型请求，企业就可能在相应报告中看到不同客户端的流量统计。

官方公布的主要字段包括：

这种结构可以帮助企业理解模型流量来自哪些开发工具。

但是，需要注意 request_count 记录的是模型调用，不是用户输入了多少次 Prompt。

一个用户问题可能导致多个模型请求。

因此，二者并不能直接等同。

三、GitHub 现在识别哪些客户端？

官方列出了多个代表性客户端标识。

这里的 client 代表工具发送请求时提供的集成标识。

GitHub 说明，该分类属于尽力识别，并不是经过独立身份验证的工具身份。

因此，如果客户端传递的标识不正确，统计分类也可能存在偏差。

不能仅凭某条记录显示 codex，就证明某个用户一定使用了特定官方版本的 Codex 客户端。

四、为什么 OpenCode、Claude Code 和 Codex 可以出现在同一份统计中？

这些工具虽然来自不同开发生态，但某些集成方式允许它们使用 GitHub Copilot 作为模型供应方。

例如，客户端在执行任务时需要访问语言模型。

它可以通过支持的 Copilot 集成路径提交请求。

此时模型调用实际经过 GitHub Copilot 的服务体系。

GitHub 因而有机会在服务端记录这些请求来自哪个客户端。

但如果开发者在 Claude Code 中使用的是 Anthropic 原厂 API Key，那么这部分请求并不会因为工具名称相同，就自动进入 Copilot Usage Metrics。

同样，使用 OpenAI 官方账户的 Codex 流量，也不能直接推断会出现在 GitHub 统计中。

这是此次更新最重要的适用范围。

五、为什么过去的 IDE 统计不够准确？

传统 IDE 通常能够记录编辑器相关活动。

例如，代码补全、聊天和其他开发操作。

但终端 Agent 的工作方式有所不同。

一个 Agent 可能在后台反复调用模型。

它可能执行文件搜索、规划修改、运行测试，然后继续调用模型。

其中许多活动并不直接对应 IDE 中的普通交互事件。

因此，如果只依赖编辑器遥测数据，可能遗漏部分真实的模型调用流量。

GitHub 选择在服务端统计模型请求，有助于补足这一缺口。

但服务端统计仍然不能解释每项请求的全部业务价值。

例如，某个 Agent 进行了十次模型调用，可能是因为任务复杂。

也可能是因为它反复尝试失败。

因此，企业还应结合任务结果判断实际效率。

六、request_count 与 Prompt 数量有什么区别？

假设一名开发者向 AI 编程工具输入：

“检查这个项目的测试失败原因并修复。”

这在用户界面中只是一条指令。

但 Agent 可能进行以下工作：

第一次模型调用：理解任务。

第二次调用：决定读取哪些文件。

第三次调用：根据文件内容设计修复。

第四次调用：修改代码。

第五次调用：解释测试结果。

第六次调用：根据失败信息继续修改。

因此，一条用户 Prompt 可能产生多次模型调用。

GitHub 官方明确提醒，request_count 统计的是成功模型请求，而不是用户交互次数。

企业如果把它当作 Prompt 次数计算员工使用频率，可能得出错误结论。

七、session_count 有什么意义？

session_count 代表独立会话数量。

它可以帮助企业区分短会话和长时间持续使用的情况。

例如，一名开发者可能每天创建多个短会话。

另一名开发者可能在同一个会话中完成大量任务。

两者的会话数量可能不同，但模型请求量和 Token 消耗未必有相同关系。

因此，建议同时观察三个指标：

会话数量。

请求数量。

Token 消耗。

例如，请求数除以会话数，可以得到平均每个会话产生的请求数量。

但这只能描述使用模式，不能直接评价工作效率。

任务复杂程度和客户端执行策略同样会影响结果。

八、token_usage 提供哪些信息？

GitHub 官方说明，新字段可以展示输入 Token、输出 Token 以及平均每请求 Token 用量等统计。

这对企业成本管理非常重要。

因为不同工具使用模型的方式可能不同。

例如，某些 Agent 每轮都会携带大量上下文。

另一些工具可能更加积极地压缩历史信息。

因此，即使请求数相近，Token 消耗也可能差距明显。

但不能仅使用输入与输出 Token 数量计算全部财务成本。

不同模型的价格可能不同。

此外，缓存、特殊服务档位或 Copilot 的产品计费规则可能影响最终费用。

因此，Usage Metrics 应与实际账单进行核对。

九、totals_by_model 如何帮助定位高消耗模型？

totals_by_model 用于进一步按模型拆分客户端用量。

例如，企业发现某个工具产生大量请求。

通过模型分布，可以进一步检查它主要调用了哪些型号。

如果旗舰模型承担了大量简单任务，团队可以考虑是否需要更合理的模型选择策略。

但不能仅根据旗舰模型占比高，就认定存在资源浪费。

例如，某个团队可能主要负责复杂的系统架构和代码迁移任务。

这类工作使用较强模型可能具有实际价值。

因此，真正的分析应该结合任务类型、完成质量和业务效果。

十、什么是 model_selection_mode？

GitHub 还新增模型选择方式信息。

主要包含：

user_selected

auto

product_selected

以及其他无法直接分类的状态。

其中，user_selected 表示用户直接选择了模型。

auto 表示系统通过自动选择机制确定模型。

product_selected 表示产品自身决定使用什么模型。

例如，Copilot 代码审查或 Cloud Agent 可能由产品自动确定具体模型。

这对管理人员有实际意义。

如果某项模型费用增加，可以进一步判断是否与用户主动选择有关，还是来自平台自动路由。

但不能因此认为所有产品都允许管理员精确固定每一次内部模型调用。

实际控制能力仍取决于具体产品设置。

十一、哪些报表支持 totals_by_client？

GitHub 官方列出了四个统计范围。

第一，企业整体。

第二，组织整体。

第三，企业用户级。

第四，组织用户级。

对应支持单日和最近 28 日报告。

需要注意，28 日汇总报告中的 totals_by_client 出现在各个 day_totals 记录中。

因此，开发者如果希望计算完整 28 日的客户端请求总量，需要对每天的数据进一步聚合。

不能简单假设数组只存在于报告顶层。

同时，报告的生成和更新存在处理周期。

不能将历史用量报告等同于实时毫秒级监控系统。

十二、如何启用 Copilot Usage Metrics？

GitHub 官方文档要求，企业需要启用相关 Copilot Usage Metrics 政策。

此外，调用者需要具备对应管理权限。

例如：

企业所有者。

具备权限的账单管理人员。

组织所有者。

拥有自定义 View Copilot Metrics 权限的授权用户。

不同 API 端点对身份和 Token 权限的要求可能不同。

因此，不能随便使用普通个人访问令牌就假设拥有全部企业统计数据。

对于需要处理用户级报告的系统，还应考虑员工隐私和内部数据访问制度。

建议通过专用、最小权限的管理身份获取数据。

十三、如何通过 REST API 获取企业报告？

GitHub 官方提供单日和 28 日报告端点。

例如，企业单日报告可以使用：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/enterprises/ENTERPRISE/copilot/metrics/reports/enterprise-1-day?day=2026-10-23"

这里的 YOUR_TOKEN 和 ENTERPRISE 为占位符。

该请求使用 GitHub 官方 REST API 的报告形式。

需要注意，返回的通常不是完整统计数据本身。

而是带有下载地址的响应。

例如：

{
  "download_links": [
    "https://example.com/copilot-usage-report.ndjson"
  ],
  "report_day": "2026-10-23"
}

其中下载地址在这里仅为示例，并非真实可下载文件。

实际地址由 GitHub 服务返回，并具有有限有效期。

十四、组织级报表怎样获取？

如果企业只需要查询某一个 GitHub Organization，可以使用组织级端点。

例如：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/orgs/ORG/copilot/metrics/reports/organization-1-day?day=2026-10-23"

调用前需要确认组织开启相应统计政策，当前 Token 拥有适当权限。

组织级报表可能更适合按团队职责进行管理。

例如，一个企业可能拥有前端、后端和基础设施三个组织。

不同组织能够分别记录 Copilot 模型用量。

但企业仍需要避免重复汇总不同统计层级的数据。

例如，同时统计企业总量和其下属组织总量时，不能直接相加。

否则可能出现重复计算。

十五、NDJSON 与普通 JSON 有什么区别？

GitHub 用量报告采用可下载文件形式，其中可能包含 NDJSON 数据。

NDJSON 全称 Newline Delimited JSON。

它通常以每一行保存一个独立 JSON 对象。

这种格式适合处理大量记录。

例如，企业报告可能包含不同日期、用户或统计维度的数据。

程序可以逐行读取，而不需要一次性把整个文件解析为单个巨大数组。

但实际报告结构仍应依据官方 Schema 处理。

尤其是新增的 totals_by_client 和 totals_by_model 字段，可能存在为空或者缺少某些统计数据的情况。

因此，解析程序应该允许字段缺失和空数组。

十六、如何制作企业用量分析表？

可以根据官方字段设计以下统计维度。

对于拥有多个业务部门的企业，还可以按组织和授权范围建立仪表盘。

但需要谨慎处理个人层级指标。

例如，用量较低不一定意味着员工工作效率较低。

某些开发岗位可能更加依赖传统工具。

也可能承担不适合 AI 自动化的工作。

因此，统计应优先服务于容量规划、费用管理和工具支持，而不是简单作为个人绩效排名。

十七、如何计算不同客户端的 Token 占比？

假设企业一天产生 100 万输入 Token。

其中通过 OpenCode 使用 Copilot 产生 40 万。

通过 Codex 使用 Copilot 产生 35 万。

通过 VS Code 产生 25 万。

那么对应输入 Token 占比分别为 40%、35% 和 25%。

但这只是说明统计方法的假设案例。

不能把上述数字当作真实 GitHub 企业用量。

此外，输入 Token 占比不是费用占比。

如果三个客户端使用不同模型，费用结构可能明显不同。

因此，想要真正分析成本，还需要获取相应模型价格和 Copilot 实际计费规则。

十八、为什么不能直接推导每位开发者的实际费用？

Copilot 的产品计费机制不一定与直接购买模型原厂 API 完全相同。

例如，产品可能采用订阅、请求额度或特定的使用规则。

而 totals_by_client 记录的是模型流量。

因此，即使知道某个客户端消耗了多少 Token，也不能直接将其乘以第三方模型官网单价，作为 GitHub 实际账单。

对于企业财务分析，最可靠的做法是分别记录使用量和实际费用。

Usage Metrics 帮助解释消费行为。

Billing 数据用于核对最终结算金额。

两者之间的差异应依据 GitHub 官方统计说明进行解释。

十九、GitHub 为什么区分 Agent App Activity？

GitHub 官方特别强调，新客户端统计与 Agent App Activity 不相同。

Agent App Activity 可能统计通过 GitHub 启动的 Agent 任务。

而 totals_by_client 统计通过 Copilot 发送的模型请求和 Token。

例如，一项 Agent 任务可能涉及多次模型调用。

因此，任务数与模型请求数并不是同一项指标。

这对企业理解 AI 编程效率十分重要。

如果只关注任务数，可能忽略单项任务的模型消费。

如果只关注 Token，又可能看不到实际完成的开发成果。

更合理的方式是将任务完成情况与成本指标结合。

二十、客户端身份是否完全可靠？

GitHub 明确指出，客户端根据请求中提供的集成 ID 进行分类。

因此，它属于 Best-Effort 分组。

如果某个客户端没有提供已识别的 ID，可能被归入 other。

某些客户端也可能提供不完整或错误的标识。

因此，统计报告适合观察整体趋势。

但不宜单凭客户端字段作为安全取证中的唯一身份依据。

如果企业需要判断某次敏感代码操作究竟由哪个工具执行，还需要结合 GitHub 审计日志、仓库记录和实际身份信息。

Usage Metrics 不应该替代正式安全审计。

二十一、此次更新会破坏旧代码吗？

GitHub 将此次变更明确描述为 Additive Change，即新增字段。

原有字段保持不变。

当没有相应使用数据时，totals_by_client 可以是空数组。

这意味着多数能够容忍新增 JSON 字段的客户端，不需要改变原有解析逻辑。

但如果企业使用严格的 Schema 校验，并拒绝未知字段，就可能需要更新处理程序。

对于 28 日报表，还要注意新增字段出现的位置。

因此，正式升级前建议准备一份真实报告样本，检查数据库导入和可视化逻辑是否能够处理。

二十二、企业如何建立完整的 AI 编程治理体系？

用量统计只是第一步。

一个成熟的 AI 编程管理体系还应该包括：

允许使用哪些模型。

哪些客户端可以接入企业账户。

如何管理用户权限。

哪些代码仓库允许 Agent 修改。

是否要求代码审查。

如何检查 API Key 泄露。

如何设置使用额度和成本告警。

如何评估实际任务完成质量。

例如，一家公司可以允许开发者使用 OpenCode 进行代码研究。

但生产仓库的提交仍需要 Pull Request 和审核。

同时，通过 Copilot Usage Metrics 观察模型用量。

这样可以同时兼顾开发效率、成本控制和安全。

二十三、哪些统计结论应该避免？

首先，不应把请求次数当作 Prompt 数量。

其次，不应把 Token 数量直接当作账单金额。

第三，不应把 client 字段当作强身份认证结果。

第四，不应将 Copilot 统计推广为所有 Claude Code 和 Codex 原厂账户用量。

第五，不应简单根据某个员工消耗多少 Token 判断工作表现。

第六，不应把已经处理完成的日报当作实时告警。

只有明确这些边界，企业才能真正利用数据改进管理，而不是制造新的误判。

二十四、FAQ：常见问题

GitHub Copilot 什么时候新增客户端用量统计？

2026 年 10 月 23 日。

新字段叫什么？

totals_by_client。

能统计 OpenCode、Claude Code 和 Codex 吗？

可以统计通过 GitHub Copilot 产生并正确归类的相应模型流量。

能看到独立 Anthropic API 的 Claude Code 用量吗？

不能仅依赖 GitHub Copilot Usage Metrics 获取。

request_count 是用户发送的 Prompt 次数吗？

不是，它统计成功的模型调用。

支持最近 28 天的数据吗？

支持相关 28 日报告，还提供单日报告。

必须是企业管理员才能查看吗？

需要符合 GitHub 规定的组织、企业或自定义统计权限。

报告 API 直接返回所有统计数据吗？

官方 REST API 通常返回具有时效性的报表下载链接。

新字段会导致旧接口失效吗？

GitHub 将此次更新描述为向后兼容的新增字段。

二十五、结语：AI 编程的成本管理正在走向统一可观测

GitHub Copilot Usage Metrics API 的更新，说明企业 AI 编程正在从单一编辑器体验，走向多客户端、多模型和多 Agent 协作。

在这样的环境中，企业不仅要知道购买了多少 Copilot 订阅。

还需要理解模型请求实际来自哪里，使用了哪些型号，以及这些工具是否真正帮助完成开发任务。

totals_by_client 为这种分析增加了重要数据维度。

但它并不自动提供完整财务成本、员工绩效或全部第三方 AI 服务的统计。

真正可靠的管理方式，需要将 Copilot Usage Metrics 与账单、任务验收、身份权限和代码审查结合起来。

对于拥有多种 AI 编程工具的团队，这将成为值得持续建设的运营能力。

官方参考资料

1. GitHub Changelog — Usage metrics API adds usage from tools like OpenCode https://github.blog/changelog/2026-10-23-usage-metrics-api-adds-usage-from-tools-like-opencode/

2. GitHub REST API — Copilot Usage Metrics https://docs.github.com/en/rest/copilot/copilot-usage-metrics

3. GitHub Copilot Usage Metrics 文档 https://docs.github.com/en/copilot

4. GitHub REST API 身份验证文档 https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api