以编程方式运行 Claude Code

Agent SDK 为您提供了支持 Claude Code 的相同工具、agent 循环和上下文管理。它可作为 CLI 用于脚本和 CI/CD，或作为 Python 和 TypeScript 包用于完整的编程控制。

CLI 之前称为”headless mode”。-p 标志和所有 CLI 选项的工作方式相同。

要从 CLI 以编程方式运行 Claude Code，请使用 -p 传递您的提示和任何 CLI 选项：

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

本页介绍通过 CLI (claude -p) 使用 Agent SDK。对于具有结构化输出、工具批准回调和本机消息对象的 Python 和 TypeScript SDK 包，请参阅完整 Agent SDK 文档。

基本用法

将 -p（或 --print）标志添加到任何 claude 命令以非交互方式运行它。所有 CLI 选项都适用于 -p，包括：

--continue 用于继续对话
--allowedTools 用于自动批准工具
--output-format 用于结构化输出

此示例询问 Claude 关于您的代码库的问题并打印响应：

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

示例

这些示例突出了常见的 CLI 模式。

获取结构化输出

使用 --output-format 控制响应的返回方式：

text（默认）：纯文本输出
json：包含结果、会话 ID 和元数据的结构化 JSON
stream-json：用于实时流式传输的换行符分隔的 JSON

此示例以 JSON 格式返回项目摘要以及会话元数据，文本结果在 result 字段中：

claude -p "Summarize this project" --output-format json

要获得符合特定架构的输出，请使用 --output-format json 与 --json-schema 和 JSON Schema 定义。响应包括关于请求的元数据（会话 ID、使用情况等），结构化输出在 structured_output 字段中。此示例从 auth.py 中提取函数名称并将其作为字符串数组返回：

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"]}'

使用 jq 之类的工具来解析响应并提取特定字段：

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

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

流式传输响应

使用 --output-format stream-json 与 --verbose 和 --include-partial-messages 在生成令牌时接收它们。每一行都是代表一个事件的 JSON 对象：

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

以下示例使用 jq 过滤文本增量并仅显示流式文本。-r 标志输出原始字符串（无引号），-j 不带换行符连接，以便令牌连续流式传输：

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

有关具有回调和消息对象的编程流式传输，请参阅 Agent SDK 文档中的实时流式传输响应。

自动批准工具

使用 --allowedTools 让 Claude 使用某些工具而无需提示。此示例运行测试套件并修复失败，允许 Claude 执行 Bash 命令和读取/编辑文件而无需请求权限：

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

创建提交

此示例审查暂存的更改并创建具有适当消息的提交：

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

--allowedTools 标志使用权限规则语法。尾部的 * 启用前缀匹配，因此 Bash(git diff *) 允许任何以 git diff 开头的命令。空格在 * 之前很重要：没有它，Bash(git diff*) 也会匹配 git diff-index。

用户调用的 skills 如 /commit 和内置命令仅在交互模式中可用。在 -p 模式中，改为描述您想要完成的任务。

自定义系统提示

使用 --append-system-prompt 添加指令同时保持 Claude Code 的默认行为。此示例将 PR diff 传递给 Claude 并指示它审查安全漏洞：

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

有关更多选项（包括 --system-prompt 以完全替换默认提示），请参阅系统提示标志。

继续对话

使用 --continue 继续最近的对话，或使用 --resume 与会话 ID 继续特定对话。此示例运行审查，然后发送后续提示：

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

如果您运行多个对话，请捕获会话 ID 以恢复特定对话：

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

后续步骤

Agent SDK 快速入门

使用 Python 或 TypeScript 构建您的第一个 agent

CLI 参考

探索所有 CLI 标志和选项

GitHub Actions

在 GitHub 工作流中使用 Agent SDK

GitLab CI/CD

在 GitLab 管道中使用 Agent SDK

入门指南

核心概念

平台和集成

使用 Claude 构建

部署

管理

配置

参考

资源

更新日志

基本用法

示例

获取结构化输出

流式传输响应

自动批准工具

创建提交

自定义系统提示

继续对话

后续步骤

Agent SDK 快速入门

CLI 参考

GitHub Actions

GitLab CI/CD

​基本用法

​示例

​获取结构化输出

​流式传输响应

​自动批准工具

​创建提交

​自定义系统提示

​继续对话

​后续步骤

Agent SDK 快速入门

CLI 参考

GitHub Actions

GitLab CI/CD

基本用法

示例

获取结构化输出

流式传输响应

自动批准工具

创建提交

自定义系统提示

继续对话

后续步骤