Claude Code 非交互模式：一条命令实现 grep 式高效查询
你是否也曾有过这样的体验？明明只是想问 Claude 一个简单的问题，它却直接启动全屏 TUI，加载项目、读取 CLAUDE.md、注入记忆……整套流程走下来，30 秒就没了。
实际上，Claude Code 还有一种更轻量的玩法：Headless 模式（非交互模式）。只需一条命令，结果直接输出，全程无需进入交互界面。
5 秒快速体验
打开终端，输入一行：
claude -p "用一句话解释什么是正则表达式"
然后？结果就会直接打印在终端里——这就是 Headless 模式的核心体验。没有全屏界面，没有弹窗确认，干净利落，就像 grep 或 curl 一样。
再来一条带实际用途的示例：
claude -p "统计当前目录下一共有多少个文件，只回复数字" --allowed-tools "Bash"
Claude 会自动帮你执行 ls | wc -l，结果直接输出到屏幕上。
终端里的两类程序对比
| 类型 | 特征 | 例子 |
|---|---|---|
| CLI 工具 | 执行 → 输出 → 结束 | ls、git、grep |
| TUI 程序 | 占全屏，有光标/面板交互 | vim、htop、Claude Code |
这便是 Headless 模式的本质——让 Claude Code 回归到第一类程序（CLI 工具）。有什么区别？区别很大：你可以轻松把它嵌入脚本中使用。
交互模式 vs Headless 模式详细对比
交互 claude | Headless claude -p | |
|---|---|---|
| 启动 | 进入全屏 TUI | 瞬间返回结果 |
| 对话 | 多轮来回 | 一问一答 |
| 权限 | 弹窗逐条确认 | 用 --allowed-tools 白名单 |
| 输出 | TUI 内渲染 | stdout 纯文本 |
| 适合 | 开发、调试、探索 | 脚本、定时任务、CI/CD |
-p 是 --print 的缩写，核心意思只有一个：计算完毕，打印结果，立即退出。简单来说，一个问题，一次回答，打完收工。
四个必知参数详解
--allowed-tools — 安全白名单机制
Headless 模式下没有弹窗让你确认工具调用，因此必须提前声明一个白名单：
claude -p "搜索今天 AI 新闻" --allowed-tools "WebSearch,WebFetch"
claude -p "审查代码" --allowed-tools "Read,Bash"
原则很简单：只授予任务所需的最小权限。
--model — 按需选择模型
claude -p "统计 .ts 文件数量" --model haiku --allowed-tools "Bash"
claude -p "审查全部代码变更" --model opus --allowed-tools "Read,Bash"
简单分类或搜索用 haiku，复杂分析与生成用 sonnet 或 opus。根据任务难度选模型，避免大材小用。
--max-turns — 控制对话轮次，防止过度执行
claude -p "搜新闻整理摘要" --allowed-tools "WebSearch" --max-turns 3
如果不加限制，Headless 模式可能会搜索 → 阅读 → 分析 → 再次搜索，多轮迭代。设置 --max-turns 1 适合单次查询，干净利落。
--continue — 延续上一次对话上下文
# 第一轮
claude -p "搜索 Claude Code Hooks 的 3 篇最佳实践" --allowed-tools "WebSearch"
# 第二轮，接着上一轮的上下文问
claude -p "把第三篇展开写 300 字摘要" --continue --allowed-tools "WebFetch"
--continue 会加载你最近一次会话的完整对话历史——不仅限于 Headless 模式，交互模式也算在内。
指定工作目录的方法
Claude Code 没有 --cwd 参数，但可以通过 cd && 模式来实现：
cd ~/my-project && claude -p "运行 npx tsc --noEmit" --allowed-tools "Bash"
在脚本中推荐使用子 shell，避免 cd 影响后续命令：
(cd ~/my-project && claude -p "运行 npx tsc --noEmit" --allowed-tools "Bash")
退出码 ≠ 任务结果
这里需要特别说明：claude -p 的退出码仅表示 Claude Code 进程本身是否正常退出，并不代表你交给它的任务是否成功。
0→ 进程正常退出- 非
0→ API 错误、网络超时、崩溃
举个例子：编译代码时发现 10 个错误，Claude 正常分析并报告“有 10 个错误”，退出码仍然是 0。判断任务结果需要解析输出内容——这是下一篇文章要讨论的话题。
跑通三条基础命令
# 1. 最简单的调用
claude -p "用一句话解释什么是 TypeScript" --model haiku
# 2. 让它读文件
claude -p "读取 package.json，统计有多少个依赖包" --allowed-tools "Read"
# 3. 管道喂数据
ls ~/your-project/src/ | claude -p "分析这个目录结构" --allowed-tools "Read" --model haiku
三条命令都能顺利跑通，你就已经掌握了 Headless 模式的基本用法。
下一篇预告：管道组合 + 结构化输出 —— 让 Claude 的输出能被脚本解析，与 grep、jq 等工具串联起来。
