以编程方式运行 Claude Code

用 Agent SDK 从 CLI、Python 或 TypeScript 以编程方式运行 Claude Code。

Agent SDK 为你提供与驱动 Claude Code 相同的工具、智能体循环和上下文管理。它以 CLI 形式提供，适用于脚本和 CI/CD，也以 Python 和 TypeScript 软件包形式提供，适用于完整的编程控制。

要以非交互模式运行 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 文档。

基本用法

在任何 claude 命令中加上 -p（或 --print）标志，即可非交互式运行它。所有CLI 选项都适用于 -p，包括：

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

以下示例向 Claude 提出一个关于你代码库的问题，并打印回复：

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

用裸模式更快启动

添加 --bare 可以跳过对钩子、技能、插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现，从而缩短启动时间。如果不加它，claude -p 会加载与一个交互式会话相同的上下文，包括工作目录或 ~/.claude 中配置的任何内容。

裸模式适用于 CI 和脚本场景，你需要在每台机器上都得到相同的结果。团队成员 ~/.claude 中的一个钩子，或项目 .mcp.json 中的一个 MCP 服务器都不会运行，因为裸模式从不读取它们。只有你显式传入的标志才会生效。

以下示例以裸模式运行一次性的摘要任务，并预先批准 Read 工具，使该次调用无需权限提示即可完成：

claude --bare -p "Summarize this file" --allowedTools "Read"

在裸模式下，Claude 仍可以访问 Bash、文件读取和文件编辑工具。用标志传入你需要的任何上下文：

裸模式会跳过 OAuth 和密钥链读取。Anthropic 身份验证必须来自 ANTHROPIC_API_KEY，或传给 --settings 的 JSON 中的一个 apiKeyHelper。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 使用它们各自惯用的服务商凭据。

退出时的后台任务

如果 Claude 在一次 claude -p 运行期间启动了一个后台 Bash 任务（例如一个开发服务器或一次监视构建），该 shell 会在 Claude 返回最终结果、stdin 关闭之后约五秒被终止。这段宽限期让一个在结果返回后不久就完成的任务，仍能交付其输出。在 v2.1.163 之前，一个永不退出的后台进程会让 claude -p 调用无限期保持打开状态。

后台子智能体和工作流不受这五秒宽限期约束，因为它们的结果是最终输出的一部分，因此 claude -p 会等待它们完成。从 v2.1.182 开始，这个等待默认上限为十分钟，这样一个卡住的后台智能体就不会让该进程无限期保持打开。用 CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS 调整这个上限，或将其设为 0 以不限时等待。

示例

以下示例展示了常见的 CLI 模式。对于 CI 和其他脚本化调用，请加上 --bare，这样它们就不会获取本地恰好配置了什么。

将数据通过管道传给 Claude

非交互模式会读取 stdin，因此你可以像任何其他命令行工具一样，将数据通过管道传入，并将回复重定向出去。

以下示例将一份构建日志通过管道传给 Claude，并将解释写入一个文件：

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

带 --output-format json 时，响应负载中包含 total_cost_usd 以及按模型细分的成本，因此脚本化的调用方可以在不查阅用量仪表盘的情况下追踪每次调用的花费。

将 Claude 添加到构建脚本中

你可以把一次非交互式调用包装进一个脚本中，把 Claude 当作项目专属的 linter 或审查者使用。

以下这个 package.json 脚本将相对于 main 的 diff 通过管道传给 Claude，让它报告拼写错误。用管道传入这个 diff，意味着 Claude 不需要 Bash 权限来读取它，转义的双引号让这个脚本能移植到 Windows：

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

获得结构化输出

使用 --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 字段中。

以下示例提取函数名称，并以字符串数组的形式返回：

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

如果该值不是一份有效的 JSON Schema，claude 会以 Error: --json-schema is not a valid JSON Schema 退出，并附上校验器的诊断信息。Claude Code 接受使用 format 关键字的模式，例如 "format": "email"，但会把 format 当作一个标注，不会强制执行它。在 v2.1.205 之前，Claude Code 会静默忽略一份无效的模式并返回非结构化文本，并把任何包含 format 的模式都视为无效。

# 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 配合使用，即可在 Token 生成时接收它们。每一行都是一个表示某个事件的 JSON 对象：

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

以下示例用 jq 筛选文本增量，只显示流式文本。-r 标志输出原始字符串（不带引号），-j 在拼接时不加换行，让 Token 能连续流式显示：

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'

当一次 API 请求因可重试的错误而失败时，Claude Code 会在重试之前发出一个 system/api_retry 事件。你可以用它来展示重试进度，或实现自定义的退避逻辑。

system/init 事件会报告会话元数据，包括模型、工具、MCP 服务器和已加载的插件。除非设置了 CLAUDE_CODE_SYNC_PLUGIN_INSTALL（这种情况下 plugin_install 事件会先于它出现），否则它是该流中的第一个事件。

该事件还携带一个可选的 capabilities 字符串数组，列出了这个 Claude Code 版本实现的协议行为，例如 interrupt_receipt_v1。可以用它来检测特性，而不是比较版本字符串，忽略你不认识的值。该字段需要 Claude Code v2.1.205 或更高版本，更早的版本中不存在。关于能力列表，请参阅SDKSystemMessage。

使用插件字段，可以在某个插件未加载时让 CI 失败：

当设置了 CLAUDE_CODE_SYNC_PLUGIN_INSTALL 时，Claude Code 会在市场插件于第一轮之前安装期间发出 system/plugin_install 事件。可以用它们在你自己的界面中展示安装进度。

关于带回调和消息对象的编程式流式传输，请参阅 Agent SDK 文档中的实时流式输出。

自动批准工具

使用 --allowedTools，可让 Claude 无需提示即可使用某些工具。以下示例运行一个测试套件并修复失败项，允许 Claude 执行 Bash 命令并读写文件，无需请求权限：

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

要为整个会话设置一个基线，而不是逐一列出工具，可以传入一个权限模式。dontAsk 会拒绝任何不在你的 permissions.allow 规则或只读命令集中的操作，这对锁定的 CI 运行很有用。acceptEdits 让 Claude 可以无需提示即可写入文件，并自动批准常见的文件系统命令，例如 mkdir、touch、mv 和 cp。其他 shell 命令和网络请求仍需要一个 --allowedTools 条目或一条 permissions.allow 规则，否则一旦尝试就会中止运行：

claude -p "Apply the lint fixes" --permission-mode acceptEdits

创建一次提交

以下示例审查已暂存的更改，并创建一次带合适提交信息的提交：

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。

自定义系统提示词

使用 --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 继续最近的对话，或用带会话 ID 的 --resume 继续一个特定的对话。以下示例运行一次审查，然后发送后续提示词：

# 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"

请从同一个目录运行这两条命令：会话 ID 的查找范围限定于当前项目目录及其 git worktree。完整的范围规则请参阅恢复一个会话。

后续步骤

• Agent SDK 快速开始：用 Python 或 TypeScript 构建你的第一个智能体
• CLI 参考文档：所有 CLI 标志和选项
• GitHub Actions：在 GitHub 工作流中使用 Agent SDK
• GitLab CI/CD：在 GitLab 流水线中使用 Agent SDK