提升 GitHub Agentic Workflows 中的 token 效率

GitHub Agentic Workflows 就像一队街道清扫工，清理 repo 里的各种小问题。这些团队显著改善了 repo 的卫生状况和质量，但和所有 agentic work 一样，成本正成为开发者越来越关心的问题。由于像 agentic workflows 这样的 CI jobs 会自动调度和触发，成本可能在不易察觉的地方累积起来。好在，让 automations 更高效，比让交互式桌面会话更高效要容易。开发者会话期间完成的工作可能很难预测，但 agentic workflows 的工作完全由 YAML 指定，并且每次执行都会重复。因为我们在自己的 GitHub repositories 中维护并使用 GitHub Agentic Workflows，所以我们和用户一样关心 token 效率。这就是为什么在 2026 年 4 月，我们开始系统性地优化许多日常依赖的 workflows 的 token 使用量。本文介绍了我们做了哪些 instrumentation、应用了哪些优化，以及初步结果。

记录 token 使用量

我们在 repos 中依赖数百个 agentic workflows 来做维护和 CI。所有 workflows 都作为 GitHub Actions 运行，并受真实 API rate limits 约束。我们是一边飞一边造飞机，同时还在消耗航空燃料。在优化 token 消耗之前，我们需要知道 token 是如何被消耗的。

我们面临的第一个挑战是，每个 agent framework（Claude CLI、Copilot CLI、Codex CLI）输出的日志格式都不同，而且历史运行的 usage data 可能不完整。好在 agentic-workflows 的 security architecture 使用 API proxy 来防止 agents 直接访问 authentication credentials。这个 proxy 让我们能够以单一的标准化格式捕获所有运行中的 token 使用情况，而不受 agent framework 影响。

现在，每个 workflow 都会输出一个 token-usage.jsonl artifact，其中每条 API call 一条记录，包含 input tokens、output tokens、cache-read tokens、cache-write tokens、model、provider 和 timestamps。将这些数据与 workflow 的其他日志结合起来，就能得到 token 通常如何被消耗的历史视图，并帮助我们优化未来运行。

用 workflows 优化 workflows

拿到 token data 后，我们构建了两个每日运行的 optimization workflows。Daily Token Usage Auditor 会读取近期 workflow runs 的 token usage artifacts，按 workflow 聚合消耗，并发布结构化报告。它的任务是标记近期使用量显著增加的 workflow，展示成本最高的 workflows，并记录异常运行（例如，一个通常 4 次 LLM turns 就能完成的 workflow 却用了 18 次）。

当 Auditor 标记某个 workflow 时，Daily Token Optimizer 会查看该 workflow 的 source 和近期日志，创建一个 GitHub issue，描述具体低效之处，并提出特定优化建议。Optimizer 发现了许多我们本来会错过的低效问题。当然，Auditor 和 Optimizer 本身也是 agentic workflows，它们的 token 使用量也会出现在每日报告中，从而形成一个小的良性循环。

移除未使用的 MCP tools

根据最初的 Auditor 和 Optimizer 结果，最常见的低效问题是未使用的 MCP tool registrations。由于 LLM APIs 是 stateless 的，agent runtimes 通常会在每次请求中包含 MCP tool function names 和 JSON schemas。实践中，这意味着完整的 tool 集合可能成为每次调用 context 的一部分。对于一个有 40 个 tools 的 GitHub MCP server，这可能会在每个 turn 增加 10–15 KB 的 schema。如果 agent 只使用两个 tools，那么剩下 38 个就是每次请求都会附带的纯开销。

Workflow authors 自然会从完整 tool-set 开始，因为这是阻力最小的路径，agent 可以自己判断需要哪些 tools。但随着时间推移，大多数 workflows 只会依赖一组狭窄且稳定的 tools。Optimizer 会通过交叉比对 tool manifests 和实际 tool calls 来识别这种模式，并建议从配置中裁剪未使用的 tools。

在我们的 smoke-test workflows 中，从 MCP configuration 中移除未使用的 tools，使每次调用的 context size 减少了 8–12 KB，在行为不变的情况下，每次运行节省了数千个 tokens。

用 GitHub CLI 替换 GitHub MCP

移除未使用的 MCP tools 是一个相对简单的收益点。更大的结构性机会，是将用于数据获取操作的 GitHub MCP calls 替换为 GitHub CLI calls，例如获取 pull request diffs、file contents 和 review comments。

这一变化不仅减少了未使用 tools 的开销，因为一次 MCP tool call 除了数据获取之外，还是一个 reasoning step。agent 必须决定调用该 tool，构造参数，并将其输出作为 context 接收。这是一次完整的 LLM API round-trip call，会消耗 tool-use JSON schema、argument block 和 response 的 tokens。相比之下，调用 gh pr diff 是一次确定性的 HTTP request，访问 GitHub 的 REST API，不涉及 LLM。

我们使用了两种策略进行迁移：

Pre-agentic data downloads。对于 agent 总是会需要的数据，例如 pull request diff 或 changed files 列表，我们在 workflow 中添加 setup steps，在 agent 启动前运行 gh commands，并将结果写入 workspace files。agent 读取这些 files，而不是发起 MCP calls。这消除了 tool-call 开销，并允许 agent 利用其在 bash scripting 上的大量训练，高效处理数据。

In-agent CLI proxy substitution。在 agent 需要在运行时决定获取什么数据的情况下，无法预先下载。这时我们依赖一个轻量级透明 HTTP proxy，将 CLI traffic 路由到 GitHub 的 API servers，同时不向 agent 暴露 authentication token。agent 运行 gh pr view –json 并获得 structured data，就像用户在 terminal 中操作一样。这降低了 token 使用量，同时不破坏我们对 agent 的 zero-secrets security 要求。

这些技术结合起来，将大部分 GitHub data-fetching 移出了 LLM reasoning loop。

衡量效率提升并不容易

开始优化 workflows 后，我们遇到了一个更细微的问题：你如何知道某个改动确实提高了效率，而不是让 workflow 做了更少（也许更差）的工作？

这里有三个混淆因素。

并非所有 tokens 都相同。在 Claude Haiku 和 Claude Sonnet 上运行同一个 workflow，会产生类似的 token counts，但成本差异很大。Haiku 每个 token 的成本大约比 Sonnet 低 4×，因此一个切换模型的 workflow 在 raw token count 上看起来没有变化，但实际上代表了显著的成本下降。为了解决这个问题，我们使用 Effective Tokens（ET）指标，对每种 token type 应用 model multipliers：

ET = m × (1.0 × I + 0.1 × C + 4.0 × O)

其中 m 是 model cost multiplier（Haiku = 0.25×，Sonnet = 1.0×，Opus = 5.0×），I 是 newly-processed input tokens，C 是 cache-read tokens，O 是 output tokens。Output tokens 权重为 4×，因为在所有主要 providers 中，它们都是最昂贵的 token type。Cache-read tokens 只赋予 0.1× 权重，因为它们来自 cache，成本只是新 input 的一小部分。这个公式可以跨 model tiers 归一化消耗，因此 10% 的 ET 降低意味着真正的 10% 成本降低，而不取决于使用的是哪个 model。

Workload 是一个 live repository。据我们所知，目前没有可用于优化 token 使用量的 agentic-workflow benchmark。当我们开始查看 workflows 的 token 使用情况时，发现一次运行可能处理一个五行修复，下一次运行则处理一个 200 行的 pull request。第一次运行自然会使用更少 tokens，但差异并不是效率突然变化导致的。Raw token counts 可能会把 workload variation 和 efficiency fluctuation 混淆。我们尝试通过同时跟踪 LLM API call counts 和 token counts 来归一化这一点；如果 LLM turns-per-run 保持稳定，而 tokens-per-call 下降，就说明效率确实提升。如果两者同时下降，则可能意味着做的工作变少了。

质量是否发生变化？理解 output quality 是最困难的因素。使用更轻量 model、运行约束更强的 workflow，可能会产生较低质量的输出。我们查看 process-level signals，例如每次 LLM call 的 output tokens、每次运行的 turn counts，以及 tool-call completion rates，以近似衡量质量。对于我们优化后的 Smoke Copilot workflow，在优化期间，即使 token 消耗下降，这三个指标都保持稳定。优化前后，该 workflow 每次运行大约都在 5 个 LLM turns 内完成。当然，这些是 process signals，而不是 outcome signals。我们无法直接观察质量是提升、下降还是保持稳定，因为没有 ground-truth “correctness”。衡量 tokens-per-unit-of-correct-work 还需要额外的 instrumentation 和思考。

初步结果

在 gh-aw 和 gh-aw-firewall repos 中，将 auditor 和 optimizer 部署到十几个 production workflows 后，我们下载了每个 workflow 在优化前后的 token-usage artifacts，并为每次运行计算 ET。12 个 workflows 中有 9 个接收了 optimizer 推荐的改动。我们只纳入在优化前后两个时期都至少有 8 次运行的 workflows。它们是：Auto-Triage Issues、Daily Compiler Quality、Community Attribution、Security Guard 和 Smoke Claude。

Auto-Triage Issues 在 109 次修复后运行中显示出清晰、持续的 62% 降低。Daily Compiler Quality 在 12 次修复后运行中提升 19%，Daily Community Attribution 在 8 次修复后运行中提升 37%。在 gh-aw-firewall repo 中，Security Guard 会审计每个 pull request 是否包含 security-sensitive changes；Smoke Claude 是一个 integration test，用于测试 firewall 的 Claude CLI path。它们拥有最多的修复后运行次数，分别显示出 43% 和 59% 的提升。

运行频率和单次运行节省同样重要。Auto-Triage Issues 会在每个新 issue 上触发（平均每天 6.8 次运行，最高 15 次），而 Daily Compiler Quality 最多每天运行一次。62% 的节省乘以每天 6.8 次运行，会很快累积：在观察期内，假设沿用优化前速率，Auto-Triage 的优化总计节省了大约 7.8 M ET。Security Guard 和 Smoke Claude 的运行频率甚至更高。在确定优先优化哪些 workflows 时，运行频率和单次运行消耗同样重要。

需要注意的是，并非 agent 推荐的每个优化都会转化为可测量的 ET 节省，尤其是在 live repository 上的短观察窗口中，workload 每天都会变化。例如，Contribution Check workflow 的 ET 增加了 5%，我们将在下文更详细讨论。

结论

基于这些结果，我们强调三种模式。

许多 agent turns 都是确定性数据收集。Auto-Triage Issues 在 gh-aw 中显示出最强且持续的提升（62 次修复后运行中 −44%），因为优化消除了结构性低效：许多 agent turns 都花在不需要 inference 的读取上，例如获取 issue metadata 和扫描 labels。将这些读取移到 agent 启动前的 pre-agentic CLI steps 中，就能把它们完全移出 LLM reasoning loop。相同模式也推动了 gh-aw-firewall 中 Security Guard 的 −60% 降低：现在有一个 relevance gate，会对未触及 security-sensitive files 的 pull requests 完全跳过 LLM。最便宜的 LLM call，就是你不发起的那一次。

Contribution Check 展示了一个混淆因素：82–83% 的 input tokens 是 cache reads（data-gathering），但平均 ET 增加了 5%。这是 workload shift 导致的，而不是优化失败：在优化前时期，41% 的运行处理的是小型 pull requests（ET 300K）。优化后时期恰好遇到一波开发活动，workflow 处理的小型 pull requests 占 9%，大型 pull requests 占 65%。由于 agent 在审查更大的 diffs，output tokens 增加了 14%，而 output tokens 在 ET 公式中的权重是 4×。优化很可能提高了 per-turn efficiency，但 workload 变重掩盖了聚合数字中的收益。

携带未使用的 tools 成本很高。在被排除的 gh-aw workflows 中，Glossary Maintainer 是一个有启发性的案例。一次运行中，一个 tool——search_repositories——被调用了 342 次，占所有 tool calls 的 58%，尽管对于一个只扫描本地 file changes 的 workflow 来说，它完全不必要。optimizer 的建议是将其从 toolset 中移除。在 gh-aw-firewall 中，Smoke Claude 的 −79% 降低，部分来自激进的 MCP tool pruning，以及切换到 Haiku model tier。Daily Community Attribution workflow 则说明了这种方法的局限：它配置了 8 个 GitHub MCP tools，但整次运行中对任何一个都没有发起调用；然而移除它们并没有降低 ET。Tool manifests 只占该 workflow 整体 context 的很小一部分。

一个配置错误的规则可能导致失控循环。同样在被排除的 workflows 中，Daily Syntax Error Quality 在优化前是项目中 ET 最高的 workflow。根因是一行配置错误：workflow 将 test files 复制到 /tmp/，然后调用 gh aw compile *，但 sandbox 的 bash allowlist 只允许 relative-path glob patterns。每次 compile attempt 都被阻止。由于无法使用它需要的 tool，agent 陷入了一个 64-turn fallback loop，手动读取 source code 来重建 compiler 本应告诉它的内容。对允许的 bash patterns 做一次修复就消除了这个循环。我们没有足够的 baseline runs 来精确量化提升，但问题很清楚，修复也很明确。

下一步是什么？

我们用于优化 workflows 的工具，包括 API-level observability、automated auditing workflows、MCP tool pruning 和 CLI substitution，目前都已在 GitHub Agentic Workflows framework 中可用。另一个即将到来的优化，是将 monolithic agents 重构为由更小、更便宜模型驱动的 subagents teams。

下一步是从 workflow-level optimization 走向 system-level optimization。一次 workflow run 并不真的是一个扁平的 API calls 序列。它是一连串 episodes：一些短阶段的工作，例如 gathering context、reading artifacts、failure 后 retry，或者 synthesis final answer。一旦能清晰看到这些 episodes，就能提出更好的问题。哪个 episode 实际导致了一次昂贵运行？哪些 episodes 大多是重复工作、受阻工作或失败工作？哪些应该完全停止 agentic 化，变成 deterministic pre-steps？

同样的逻辑也适用于 portfolio level。Repositories 并不是孤立运行一个 workflow。它们运行的是一组 agentic automations，这些 automations 往往由相同事件触发，检查相同的 diffs 和 logs，并产生相邻的判断。这意味着成本不仅是单个 workflow 的属性，也是整个 portfolio 中重叠部分的属性。我们接下来想做的是 portfolio-level 分析：哪些 workflows 在重复读取，哪些 workflows 应该合并，以及哪些 shared intermediate artifacts 应该被 cache，而不是每次运行都重新发现。

这些开放问题确实很难。衡量 goodput 仍然需要 outcome instrumentation，而这在 agentic CI workflows 上尚未大规模存在；理解 episode 和 portfolio efficiency 也需要比大多数系统今天收集的更丰富的 lineage data。但这是重要的方向。Proxy-level observability 和 optimizer workflows 已经改变了我们开发和部署新 agentic automations 的方式。我们从第一天起就添加 token monitoring，而不是之后再补上；并且越来越多地从整个 automation fleet 的可避免工作角度思考，而不是只孤立地关注昂贵运行。

如果你在 CI 中运行 agentic workflows，并想知道自己是否花了不必要的钱，第一步和我们一样：添加 API proxy，开启 logging，让数据告诉你该看哪里。如果你想添加本文提到的 workflows，只需使用 gh-aw CLI 将它们放入你的 repo：gh extensions install github/gh-aw gh aw add githubnext/agentic-ops/copilot-token-audit githubnext/agentic-ops/copilot-token-optimizer

将它们与你现有的 CI 一起运行，可以立即获得 usage 可见性，并帮助你持续优化 workflows。

我们很想了解其他人如何处理这个问题。欢迎在 community discussion 中分享你的想法，或加入 GitHub Next Discord 的 #agentic-workflows channel。

探索 GitHub Agentic Workflows repo >

文章 Improving token efficiency in GitHub Agentic Workflows 最早发布于 The GitHub Blog。