降低Claude Code无头调用成本

你把 claude -p 接入脚本，运行起来一切正常，但用量数字却怎么都说不通：仅仅一行 prompt，成本竟然和完整的工作会话一样高。我们在定时运行 Claude Code 时就遇到了这个问题——在仓库根目录冷启动一次 claude -p，还没开始执行任何工作，就消耗了大约 150,000 个 token，因为 print 模式会加载交互式会话所加载的全部内容。

本文会介绍 -p 实际加载了什么、如何使用 --bare 解决成本问题，以及当 Claude Code 在无人值守环境中运行时，哪些权限和输出选项值得关注。

-p（完整形式：--print）会以非交互方式运行任意 claude 命令：输入一个 prompt，输出一个结果，然后进程退出。

claude -p "What does the auth module do?"

脚本层面的基础行为符合你的预期：

退出码：成功时为 0，失败时为非零，因此 CI 可以据此选择不同的处理分支。无效 flag 会在运行开始前报告到 stderr；运行过程中的失败（例如缺少身份认证）则会作为结果输出到 stdout。

支持读取 stdin：cat build-error.txt | claude -p 'explain the root cause' > out.txt 和其他 Unix 工具一样正常工作。管道输入的上限为 10MB（从 v2.1.128 开始）——超过限制后，你会收到清晰的错误，并得到非零退出码。因此，较大的输入应写入文件，再通过路径引用。

不兼容的 flag 会明确失败：同时使用 -p 与 --bg 或 --cloud 时，命令会拒绝执行，并在错误信息中指出冲突项。

下面是一个 package.json 脚本，它使用 Claude 检查 diff 中的拼写错误：

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

没人纳入预算的部分：-p 会加载你的整套配置

文档中的这句话解释了我们那笔 150k token 的账单：

如果不使用它，claude -p 会加载与交互式会话相同的上下文，包括工作目录或 ~/.claude 中配置的所有内容。

这意味着，每次脚本调用都会为以下内容的自动发现付出成本：

CLAUDE.md（加载链中的所有文件，而不仅仅是仓库里的那一个）

如果你的仓库里有一份很长的 CLAUDE.md、一个 skills 目录，以及几个 MCP servers——对于成熟的项目配置来说，这很正常——那么每次调用时，一个“快速的脚本问题”都会悄无声息地把所有这些内容作为上下文发送出去。我们实测每次冷调用约消耗 150k token，这不是 bug，而是 -p 忠实地复现了我们的交互式环境，即使这项任务根本不需要其中任何内容。

--bare：从零开始，只加回你需要的内容

--bare 会完全跳过这种自动发现——不加载 hooks、skills、plugins、MCP servers、auto memory 和 CLAUDE.md：

claude --bare -p "Summarize README.md" --allowedTools "Read"

有两个特性让它成为 CI 的合理默认选择：

1. 可复现性。队友 ~/.claude 中的 hook 或项目 .mcp.json 中的 MCP server 都不会运行，因为 bare 模式根本不会读取它们。在每台机器上执行相同的调用，都能得到相同的行为。

2. 显式凭据。Bare 模式绝不会读取 OAuth 凭据或系统 keychain。使用 Anthropic API 时，需要设置 ANTHROPIC_API_KEY（或通过 --settings 提供 apiKeyHelper）。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 仍会照常读取各自 provider 的凭据。这样就不会在不知情的情况下依赖最后登录的那个人。

在 bare 模式下，Claude 仍然拥有 Bash、文件读取和文件编辑工具。其他所有能力都需要通过 flag 显式启用：

文档指出，--bare 是脚本调用和 SDK 调用的推荐模式，并且会在未来版本中成为 -p 的默认模式。如果你的脚本依赖 -p 运行期间启用 CLAUDE.md 规则或 hooks，那么现在就应该留意这一点：默认值切换的那一天，这些脚本的行为也会随之改变。请逐个脚本做出判断——“需要我的规则”，还是“需要一个无干扰的干净环境”——然后显式写出对应的 flag。

面向脚本的结构化输出

--output-format 控制响应的格式：

claude -p "Summarize this project" --output-format json | jq -r '.result'

有三个细节值得了解：

json 中包含 total_cost_usd 和按 model 细分的成本信息。如果你在运行定时任务，请把它记录到日志中——这样你就能及时发现一次消耗 150k token 的冷启动，而不必等到查看 dashboard 时才知道。

--json-schema（与 --output-format json 一起使用）可以让响应遵循你提供的 JSON Schema；结构化部分会写入 structured_output 字段。

如果你正在基于输出构建进度 UI，stream-json 配合 --verbose --include-partial-messages，可以用 JSON Lines 的形式发出 token 级事件。

没人在场点击“允许”时的权限设置

Headless 运行无法响应权限提示，因此你需要提前批准：

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

你可以把 Bash 权限限定到特定的命令模式，而不是授予不受限制的访问权限：

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

如果要为整个会话设置权限基线，可以传入 permission mode，而不是逐一列出工具：

dontAsk 会拒绝所有未列入 permissions.allow 规则、且不属于内置只读命令集合的操作——这是适合严格受限 CI 的设置。

acceptEdits 允许 Claude 在不提示的情况下写入文件，并自动批准常见的文件系统命令（mkdir、touch、mv、cp）。其他 shell 命令和网络请求仍然需要 allow 规则——否则，一旦尝试执行，运行就会中止。

只有在 CI 中才会暴露的时序陷阱

以下问题经常会催生“本地正常，但在 CI 中卡住”的工单：

最终结果产生大约 5 秒后，后台 Bash 任务会被终止。如果 Claude 在一次 -p 运行期间启动了 dev server 或 watch build，那么在结果返回且 stdin 关闭大约五秒后，对应的 shell 就会被终止。（在 v2.1.163 之前，永不退出的后台进程会让 claude -p 调用一直无法结束——如果你曾遇到这种卡死，原因就在这里。）

后台 subagents 的行为则不同：它们的输出属于最终结果的一部分，因此 -p 会等待它们完成——从 v2.1.182 开始，默认最长等待十分钟。CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS 可以调整这个上限；设为 0 则表示无限期等待。

SIGTERM 可以被妥善处理：正在进行的 turn 会中止，所有正在运行的 Bash 命令的进程树都会被终止，SessionEnd hooks 仍会运行，退出码为 143。你的 supervisor 可以终止卡住的任务，而不会留下孤儿进程。

什么时候不该使用 -p

根据我们在生产环境中的使用经验，它有两个明确的边界：

迭代式工作。如果你看到回答后还会继续追问，那么保留着热上下文的交互式会话，会比一连串冷启动的 -p 调用更合适。（--continue 确实可以让脚本继续一次对话，但这种方式本质上是在逐个进程重建会话。）

任何需要结合项目判断标准的工作。--bare 之所以快，是因为它跳过了你的规则。定时执行的代码审查任务，或者编写面向用户文本的任务，很可能需要加载 CLAUDE.md——这意味着你应该有意识地支付上下文成本，而不是一味规避它。

对我们来说行之有效的模式是：机械性任务使用 --bare、显式的 --allowedTools 和 --output-format json；只有在规则确实值得消耗这些 token 的场景中，才使用完整上下文的 -p；同时在所有地方记录 total_cost_usd，这样一旦成本发生漂移，一周内就能发现，而不是等到一个季度后。

我在维护 Rulestack——一套面向 Claude Code、Cursor 和 Codex，经过测试的规则包、skills 与模板。

我每天都会在 Bluesky 上分享 AI coding agents 相关笔记：@ai-shop.bsky.social

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。