1. 无交互场景下 Claude Code 的真实痛点
很多人第一次接触 Claude Code，都是在终端里敲claude进入交互式会话，边聊边改代码。但只要你想把它塞进 CI 流水线、pre-commit hook 或者批量代码审查脚本，交互式会话立刻就成了障碍：它会等你输入、会保留上下文、会弹确认，脚本根本没法稳定拿到结果。
Claude Code headless mode（无头模式）就是为这种场景准备的。它通过-p（prompt）参数一次性传入任务，执行完直接退出，不进入交互界面；再配合--output-format控制输出结构，你就能在 shell 脚本、Python 脚本里像调用普通命令行工具一样调用它。适合谁？适合已经在用 Claude Code 做日常开发、现在想把能力延伸到自动化的工程师，尤其是需要批量审查、issue 分类、提交前检查的团队。
我试过把这套组合接到一个几十个文件的小仓库上做批量审查，最大的感受是：难点不在-p本身，而在输出格式和退出码的稳定性。默认的文本输出人看着舒服，脚本解析起来很痛苦；stream-json虽然结构化，但如果没加对参数，你会拿到一堆事件对象却不知道哪条才是最终答案。这篇文章就围绕-p与output-format的参数组合，把无头模式在 CI、批量审查里的落地方式讲清楚，并演示把 endpoint 切到 TaoToken 后跑通一次完整调用。
先明确一个关键点：headless mode 不会在会话之间保持状态。每次调用都是独立的一次性会话，你必须每次都把完整 prompt 传进去。这既是限制也是优点——脚本里没有隐藏状态，行为可预测，适合放进流水线。
2. TaoToken 前置准备：Base URL、Key 与 Model ID
在把 Claude Code 的无头调用接进脚本之前，需要先准备好三件套：Base URL、API Key、Model ID。这三样缺一不可，而且必须和 Claude Code 的配置字段对应上，否则你会遇到 401 或者模型找不到的报错。
TaoToken 的 API 入口是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 Base URL 使用。API Key 需要到控制台的 API Keys 页面创建，创建后复制保存，它只会完整显示一次。Model ID 则根据你要调用的模型填写，比如 Claude 系列对应的模型标识。
这里要强调一个容易踩的坑：Claude Code 读取配置时，环境变量和 settings 文件的优先级不同。如果你在 shell 里 export 了ANTHROPIC_BASE_URL，又在~/.claude/settings.json里写了不同的值，实际生效的可能是环境变量。脚本环境里尤其要注意，CI runner 往往会预置一些环境变量，先确认没有冲突再往下走。
配置的三种常见方式，你可以按场景选：
| 方式 | 适用场景 | 持久性 |
|---|---|---|
| 环境变量 export | 临时测试、CI 单次任务 | 当前 shell 会话 |
~/.claude/settings.json | 本机长期使用 | 持久 |
项目内.claude/settings.json | 团队共享、仓库级配置 | 随仓库 |
对于无头模式跑在 CI 里的情况，我建议用环境变量注入 Key（从 CI 的 secret 里读），用项目内 settings 固定 Base URL 和 Model ID。这样 Key 不会写进仓库，配置又能被团队复用。
如果你还没创建 Key，可以先去控制台生成一个；接入细节和字段说明在接入文档里有完整对照。这两步做完，再进入下一节的配置片段。
3. 可复制的 settings 配置与 output-format 参数组合
这一节是核心。先给出可直接复制的配置片段，再讲-p和--output-format怎么组合。
项目内.claude/settings.json示例，路径就是仓库根目录下的.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929" }, "permissions": { "allow": [ "Read", "Grep", "Glob" ] } }注意ANTHROPIC_API_KEY我没有写进这个文件，而是留给环境变量注入，避免密钥进仓库。在 CI 里这样设置：
export ANTHROPIC_API_KEY="你的Key" export ANTHROPIC_BASE_URL="https://taotoken.net/api"如果你用的是 Codex 风格的auth.json，字段名会不同，但三件套的逻辑一致：Base URL 指向https://taotoken.net/api，Key 填你创建的密钥，Model ID 填对应模型。Cline MCP 或 CC Switch 这类工具也是同样的三件套映射，只是配置文件位置和字段名有差异，认准 Base URL、Key、Model ID 三个值不要填错。
接下来是-p与--output-format的组合。-p后面跟 prompt 字符串，启用无头模式；--output-format可选text、json、stream-json。三者的区别：
# 纯文本，人看方便，脚本难解析 claude -p "分析这个项目的代码质量" --output-format text # 单个 JSON 对象，适合一次性拿结果 claude -p "分析这个项目的代码质量" --output-format json # 流式 JSON，每个事件一行，适合实时处理和长任务 claude -p "分析这个项目的代码质量" --output-format stream-json --verbosestream-json必须配合--verbose才能拿到完整的事件流，否则输出会不完整。这是官方文档里提到但很容易漏掉的一点。流式输出的每一行是一个 JSON 对象，包含事件类型、内容块等信息，最终结果在result类型的事件里。
在 CI 脚本里，我通常这样组织：
#!/usr/bin/env bash set -euo pipefail RESULT=$(claude -p "审查本次改动的代码，指出潜在问题" \ --output-format json \ --max-turns 5) echo "$RESULT" | jq -r '.result'--max-turns限制最大轮次，防止无头模式在复杂任务上无限循环。这个参数在批量审查里很重要，能控制单次调用的成本和时间。
4. 验证请求：跑通一次 headless 调用并解析 stream-json
配置就绪后，先做一次最小验证，确认 endpoint 切到 TaoToken 后能正常返回，输出格式和退出码符合预期。
第一步，确认环境变量生效：
echo $ANTHROPIC_BASE_URL # 应输出 https://taotoken.net/api第二步，跑一次最简单的 headless 调用：
claude -p "用一句话说明什么是无头模式" --output-format json预期你会拿到一个 JSON 对象，里面有result字段包含模型回答。如果这里报 401，说明 Key 没生效；如果报模型找不到，说明 Model ID 填错了。
第三步，验证 stream-json 输出并写解析脚本。下面这个 Python 脚本逐行读取流式输出，提取最终结果：
import json import subprocess proc = subprocess.Popen( ["claude", "-p", "分析当前目录的代码结构", "--output-format", "stream-json", "--verbose"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, ) final_result = None for line in proc.stdout: line = line.strip() if not line: continue try: event = json.loads(line) except json.JSONDecodeError: continue if event.get("type") == "result": final_result = event.get("result") proc.wait() print("退出码:", proc.returncode) print("最终结果:", final_result)运行后你应该看到退出码为 0，最终结果是模型对代码结构的分析。如果退出码非 0，检查 stderr 里的报错信息。
第四步，验证退出码语义。在 CI 里，退出码决定流水线是否继续。Claude Code 在正常完成时返回 0，遇到错误返回非 0。你可以在脚本里这样判断：
if claude -p "检查是否有语法错误" --output-format json > /tmp/out.json; then echo "检查通过" else echo "检查失败，退出码 $?" cat /tmp/out.json fi实测下来，把 endpoint 切到 TaoToken 后，这套调用链是通的，stream-json的事件结构稳定，result事件里能拿到完整回答。批量审查时，我会把每个文件的审查结果收集起来，最后统一输出报告。
5. 本篇常见错排查：401、local proxy failed 与 reading choices
无头模式跑不起来，报错往往集中在几个固定位置。这一节按真实报错逐个排查。
401 Unauthorized：最常见。原因通常是 Key 没注入、Key 过期、或者 Base URL 和 Key 不匹配。排查顺序：先echo $ANTHROPIC_API_KEY确认非空，再确认ANTHROPIC_BASE_URL是https://taotoken.net/api，最后到控制台确认 Key 状态。注意不要有多余空格或换行，从控制台复制时容易带上。
local proxy failed / connection refused：这类报错说明请求根本没发出去，或者被本地某个配置拦截了。检查是否有残留的代理环境变量，比如HTTP_PROXY、HTTPS_PROXY，CI 环境里这些变量可能被预置。用env | grep -i proxy看一眼，有的话 unset 掉再试。另外确认网络能正常访问https://taotoken.net/api。
reading choices / 解析不到 result 字段：这个报错通常出现在你按 OpenAI 风格的响应结构去解析，但实际拿到的是 Claude 风格的结构。stream-json的事件里，最终答案在type为result的对象的result字段，不是choices[0].message.content。如果你混用了不同工具的解析代码，就会在这里卡住。对照第 4 节的解析脚本改一下字段路径即可。
OAuth 相关报错：如果你之前用 OAuth 方式登录过 Claude Code，配置里可能残留了 OAuth 凭据，和 API Key 方式冲突。检查~/.claude/下的凭据文件，必要时清理掉，改用 API Key 方式。CC Switch 这类工具切换配置时也容易留下旧凭据，切换后确认当前生效的是哪一套。
输出为空但退出码为 0：检查是否漏了--verbose。stream-json不加--verbose时，部分事件不会输出，你可能只拿到开头几条就结束了。加上--verbose再跑一次。
批量审查时超时：无头模式默认没有超时限制，长任务可能挂住。在脚本外层加timeout命令，比如timeout 120 claude -p ...，超时后强制退出并记录。
排查时养成一个习惯：先把--output-format换成text，看模型有没有正常回答。如果 text 能出结果，说明连接和鉴权没问题，问题在 JSON 解析；如果 text 也出不来，问题在配置或网络。这个二分法能省很多时间。
6. 把无头调用接进 CI 与批量审查的落地建议
配置和排障都通了之后，最后聊聊怎么真正用起来。
CI 场景下，我建议把 Claude Code 的无头调用封装成一个独立的脚本文件，比如scripts/review.sh，在流水线里调用它。脚本里固定--output-format json，用jq提取result字段，再根据内容决定是否阻断流水线。注意把 API Key 放在 CI 的 secret 里，不要硬编码。
批量代码审查场景，可以遍历改动文件列表，对每个文件单独调用一次，或者把多个文件拼成一个 prompt 一次性审查。前者粒度细、成本高，后者成本低但可能遗漏细节。我的做法是：改动文件少于 10 个时逐个审查，超过就分批，每批 5 个文件。
pre-commit hook 里用无头模式要谨慎，因为它会增加提交耗时。建议只对暂存区的改动做轻量检查，比如拼写和明显错误，把深度审查留给 CI。
如果你需要长期跑这类自动化任务，Coding Plan 在用量和稳定性上更适合持续集成场景；只是临时验证模型输出，用模型对话页面手动试几次更快。接入字段和配置细节随时可以查接入文档，Key 的管理在 API Keys 页面。
最后提醒一句：无头模式每次调用都是独立会话，不要把需要上下文连续的任务拆成多次调用，那样模型看不到之前的对话。要么一次性把上下文写进 prompt，要么在脚本里自己维护上下文拼接。这一点想清楚，批量任务的稳定性会好很多。
