Claude Code 非交互模式：用 claude -p 写脚本和自动化

这篇适合谁

适合已经在终端里用 Claude Code、想把它放进 shell 脚本、定时任务或 CI 流水线的人。读完你能跑通一次性的提示词，拿到程序可以解析的输出，提前给本次运行需要的工具授权，并接着上一次的对话继续做。

什么是非交互模式

直接运行 claude 会打开交互界面，等你一句一句输入。给任何 claude 命令加上 -p（或 --print），它就变成非交互模式：处理完提示词、打印结果，然后退出^[1]。官方说明里，Agent SDK 使用的是和 Claude Code 相同的工具、代理循环和上下文管理，有两种形式：给脚本和 CI/CD 用的 CLI，以及需要精细控制时使用的 Python 与 TypeScript 包^[1]。本文只讲 CLI。

最简单的一次运行是问一个关于代码库的问题，结果直接打印出来：

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

运行成功时退出码是 0，失败时是非零值，所以脚本可以根据退出码分支处理^[1]。两类错误要分开看：参数写错（比如用了不存在的参数），报错会在运行开始前输出到 stderr；运行过程中出的问题，比如没有登录认证，则以结果的形式打印在 stdout 上^[1]。

用 --bare 加快启动

普通的 -p 运行会加载交互会话里能加载的全部内容：hooks、skills、自定义命令、子代理、插件、MCP 服务器、自动记忆和 CLAUDE.md。加上 --bare 可以跳过这些自动发现，缩短启动时间^[1]。官方推荐脚本和 SDK 调用使用这个模式，并说明它将来会成为 -p 的默认行为^[1]。

代价是：需要的东西都要显式传进去。文档列出了对应的参数：额外的系统提示用 --append-system-prompt 或 --append-system-prompt-file，设置用 --settings，MCP 服务器用 --mcp-config，自定义代理用 --agents，插件用 --plugin-dir 或 --plugin-url^[1]。最容易踩的坑是 hooks：即使通过 --settings 传入，或者通过参数加载的插件里写了 hooks，bare 模式下也不会执行^[1]。

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

上面的例子同时预先允许了 Read 工具，这样调用不会停在权限确认上。bare 模式还会改变 Claude 看到的内容：Claude Code 平时会附加的系统提醒（例如可用 skills 的列表）不会提供给它，后台命令和后台子代理也不能用^[1]。

选 bare 模式的理由不只是快，也是安全。不加 --bare 时，即使是你从没信任过的目录，-p 运行也会执行项目 .claude/settings.json 里的 hooks，并连接 .mcp.json 里的 MCP 服务器；这种模式下没有信任对话框，也没有逐个服务器的审批提示^[1]。如果 CI 要跑来路不明的仓库，这一点要先检查。

bare 模式下的认证

bare 模式不读取 OAuth 凭据，也不读取系统钥匙串。调用 Anthropic API 时，要在环境变量里设置 ANTHROPIC_API_KEY，密钥在 Claude Console 里创建；或者在 --settings 的 JSON 里提供 apiKeyHelper^[1]。Amazon Bedrock、Google Cloud 和 Microsoft Foundry 仍按原来的方式读取各自的凭据^[1]。

给这次运行开放工具

默认情况下，需要审批的工具调用会停下来等人确认。--allowedTools 可以让 Claude 不经询问直接使用列出的工具；列出 Read 和 Edit，就允许读文件和改文件，但从网络路径读取仍需要确认^[1]。下面的命令允许运行测试、修改文件：

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

工具规则可以写得更窄。规则支持前缀匹配：Bash(git diff *) 覆盖所有以 git diff 开头的命令。* 前面的空格不能省，否则 Bash(git diff*) 也会匹配 git diff-index^[1]。文档里的提交示例只放行了 git diff、git log、git status 和 git commit，写脚本时这种收窄的列表是比较稳妥的默认值。

如果想为整个会话设一个基线，用 --permission-mode。auto 让分类器审查大部分操作，dontAsk 直接拒绝所有本需要询问的调用，acceptEdits 则让 Claude 不经询问就写文件^[1]。没有人值守的定时任务，可以再加上 --permission-prompts none：凡是会弹出询问的操作都会被拒绝，除非某个 PermissionRequest hook 放行，同时 Claude 会被告知不要重试。这个参数需要 Claude Code v2.1.259 或更高版本^[1]。

在脚本里读取输出

默认的 text 格式是纯文本。--output-format json 会返回结果，并附带会话 ID 和元数据；stream-json 则逐行输出 JSON 事件，适合实时展示^[1]。

JSON 结果里还包含 total_cost_usd 和按模型拆分的费用。官方把这两个数字称为客户端估算值，适合看趋势，不能当账单用^[1]。管道可以接任何命令行工具。下面的例子把构建日志传给 Claude，再把解释写进文件：

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

标准输入的上限是 10MB。内容更大时，先写进文件，再在提示词里给出文件路径^[1]。

如果需要固定的结构，在 JSON 运行里加上 --json-schema，结果会放进 structured_output 字段：

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

使用之前先检查 structured_output 是否存在。如果 Claude 拒绝了请求，或者运行结束时没有得到有效输出，这个字段就不会出现^[1]。Schema 无效时 claude 会报错退出。format 关键字可以写，但它只是注释，不会被强制校验^[1]。

接着上一次的对话

--continue 接续最近的一次对话。--resume 接一个会话 ID，续接指定的对话；它也接受某个会话 .jsonl 记录文件的路径^[1]。如果同时跑好几个对话，可以从 JSON 运行里取出会话 ID：

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

这两条命令可以在不同目录里执行，因为 Claude Code 会在本机的任何项目里按 ID 查找会话^[1]。

长时间运行的任务

一轮结束、标准输入关闭后，-p 运行可能还会等待它启动的后台工作：后台命令、后台子代理、工作流和 Monitor 监视。默认情况下，连续空闲等待 10 分钟后，它会停止仍在运行的工作，并丢弃部分结果。设置 CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS 可以修改这个上限，设为 0 则取消上限^[1]。

停止运行也要小心。发送 SIGTERM 会让 Claude Code 以退出码 143 结束，当前这一轮不会完成，也不会记录结果。要干净地结束这一轮，应先发送 SIGINT，或者在 Agent SDK 里调用 interrupt()^[1]。

常见问题

MCP 服务器最容易出意外。使用 --mcp-config 时，-p 会在第一轮开始前等待尚未连接的服务器，默认最多等 30 秒，由 MCP_TIMEOUT 控制。未通过校验的配置项会被跳过，但运行本身不会中断；system/init 事件里的 mcp_servers 和 mcp_server_errors 字段会列出它们，CI 任务可以据此在缺少服务器时直接失败^[1]。

插件也有对应的检查，看 plugins 和 plugin_errors 字段即可^[1]。需要终端交互的内置命令，例如 /login，在 -p 模式下不可用；但只要在提示词里写上 /skill-name，用户调用的 skills 和自定义命令仍然可以用^[1]。