Claude Code 的非交互模式：一条命令当 grep 用
系列第 1 篇 · 读完 5 分钟 · 跑通 3 条命令
有没有过这种感觉：只是想问 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 退回到第一类。有什么区别？——可以把它放进脚本里了。
交互模式 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 串联起来。
系列目录：共 4 篇，从零到把 Claude Code 嵌入自动化脚本。
