1. 无交互场景下 Claude Code 的真实痛点很多人第一次接触 Claude Code都是在终端里敲claude进入交互式会话边聊边改代码。但只要你想把它塞进 CI 流水线、pre-commit hook 或者批量代码审查脚本交互式会话立刻就成了障碍它会等你输入、会保留上下文、会弹确认脚本根本没法稳定拿到结果。Claude Code headless mode无头模式就是为这种场景准备的。它通过-pprompt参数一次性传入任务执行完直接退出不进入交互界面再配合--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_URLhttps://taotoken.net/api如果你用的是 Codex 风格的auth.json字段名会不同但三件套的逻辑一致Base URL 指向https://taotoken.net/apiKey 填你创建的密钥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], stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, ) 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_PROXYCI 环境里这些变量可能被预置。用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要么在脚本里自己维护上下文拼接。这一点想清楚批量任务的稳定性会好很多。