Claude Code SDK
了解如何使用 Claude Code SDK 以编程方式将 Claude Code 集成到您的应用程序中。
Claude Code SDK 支持将 Claude Code 作为子进程运行,提供了一种构建 AI 驱动的编码助手和工具的方法,利用 Claude 的能力。
SDK 可用于命令行、TypeScript 和 Python 使用。
身份验证
要使用 Claude Code SDK,我们建议创建一个专用的 API 密钥:
- 在 Anthropic Console 中创建一个 Anthropic API 密钥
- 然后,设置
ANTHROPIC_API_KEY
环境变量。我们建议安全地存储此密钥(例如,使用 Github secret)
基本 SDK 使用
Claude Code SDK 允许您在应用程序中以非交互模式使用 Claude Code。
命令行
以下是命令行 SDK 的一些基本示例:
TypeScript
TypeScript SDK 包含在 NPM 上的主要 @anthropic-ai/claude-code
包中:
TypeScript SDK 接受命令行 SDK 支持的所有参数,以及:
参数 | 描述 | 默认值 |
---|---|---|
abortController | 中止控制器 | new AbortController() |
cwd | 当前工作目录 | process.cwd() |
executable | 要使用的 JavaScript 运行时 | 在 Node.js 中运行时为 node ,在 Bun 中运行时为 bun |
executableArgs | 传递给可执行文件的参数 | [] |
pathToClaudeCodeExecutable | Claude Code 可执行文件的路径 | 与 @anthropic-ai/claude-code 一起提供的可执行文件 |
Python
Python SDK 在 PyPI 上作为 claude-code-sdk
提供:
先决条件:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
基本使用:
Python SDK 通过 ClaudeCodeOptions
类接受命令行 SDK 支持的所有参数:
高级使用
下面的文档使用命令行 SDK 作为示例,但也可以与 TypeScript 和 Python SDK 一起使用。
多轮对话
对于多轮对话,您可以恢复对话或从最近的会话继续:
自定义系统提示
您可以提供自定义系统提示来指导 Claude 的行为:
您还可以将指令附加到默认系统提示:
MCP 配置
模型上下文协议(MCP)允许您使用来自外部服务器的附加工具和资源扩展 Claude Code。使用 --mcp-config
标志,您可以加载提供专门功能的 MCP 服务器,如数据库访问、API 集成或自定义工具。
创建一个包含您的 MCP 服务器的 JSON 配置文件:
然后与 Claude Code 一起使用:
使用 MCP 工具时,您必须使用 --allowedTools
标志明确允许它们。MCP 工具名称遵循模式 mcp__<serverName>__<toolName>
,其中:
serverName
是您的 MCP 配置文件中的键toolName
是该服务器提供的特定工具
这种安全措施确保 MCP 工具仅在明确允许时使用。
如果您只指定服务器名称(即 mcp__<serverName>
),则该服务器的所有工具都将被允许。
不支持通配符模式(例如 mcp__go*
)。
自定义权限提示工具
可选地,使用 --permission-prompt-tool
传入一个 MCP 工具,我们将使用它来检查用户是否授予模型调用给定工具的权限。当模型调用工具时,会发生以下情况:
- 我们首先检查权限设置:所有 settings.json 文件,以及传递给 SDK 的
--allowedTools
和--disallowedTools
;如果其中之一允许或拒绝工具调用,我们继续进行工具调用 - 否则,我们调用您在
--permission-prompt-tool
中提供的 MCP 工具
--permission-prompt-tool
MCP 工具会传递工具名称和输入,并且必须返回一个带有结果的 JSON 字符串化载荷。载荷必须是以下之一:
例如,TypeScript MCP 权限提示工具实现可能如下所示:
要使用此工具,添加您的 MCP 服务器(例如使用 --mcp-config
),然后像这样调用 SDK:
使用说明:
- 使用
updatedInput
告诉模型权限提示改变了其输入;否则,将updatedInput
设置为原始输入,如上面的示例所示。例如,如果工具向用户显示文件编辑差异并让他们手动编辑差异,权限提示工具应该返回该更新的编辑。 - 载荷必须是 JSON 字符串化的
可用的 CLI 选项
SDK 利用 Claude Code 中可用的所有 CLI 选项。以下是 SDK 使用的关键选项:
标志 | 描述 | 示例 |
---|---|---|
--print , -p | 在非交互模式下运行 | claude -p "query" |
--output-format | 指定输出格式(text 、json 、stream-json ) | claude -p --output-format json |
--resume , -r | 通过会话 ID 恢复对话 | claude --resume abc123 |
--continue , -c | 继续最近的对话 | claude --continue |
--verbose | 启用详细日志记录 | claude --verbose |
--max-turns | 在非交互模式下限制代理轮次 | claude --max-turns 3 |
--system-prompt | 覆盖系统提示(仅适用于 --print ) | claude --system-prompt "Custom instruction" |
--append-system-prompt | 附加到系统提示(仅适用于 --print ) | claude --append-system-prompt "Custom instruction" |
--allowedTools | 允许的工具的空格分隔列表,或 允许的工具的逗号分隔列表字符串 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 拒绝的工具的空格分隔列表,或 拒绝的工具的逗号分隔列表字符串 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | 从 JSON 文件加载 MCP 服务器 | claude --mcp-config servers.json |
--permission-prompt-tool | 用于处理权限提示的 MCP 工具(仅适用于 --print ) | claude --permission-prompt-tool mcp__auth__prompt |
有关 CLI 选项和功能的完整列表,请参阅 CLI 参考 文档。
输出格式
SDK 支持多种输出格式:
文本输出(默认)
仅返回响应文本:
JSON 输出
返回包括元数据的结构化数据:
响应格式:
流式 JSON 输出
在接收到每条消息时流式传输:
每个对话都以初始的 init
系统消息开始,然后是用户和助手消息列表,最后是带有统计信息的最终 result
系统消息。每条消息都作为单独的 JSON 对象发出。
消息模式
从 JSON API 返回的消息根据以下模式严格类型化:
我们将很快以 JSONSchema 兼容格式发布这些类型。我们对主要的 Claude Code 包使用语义版本控制来传达此格式的重大更改。
Message
和 MessageParam
类型在 Anthropic SDK 中可用。例如,请参阅 Anthropic TypeScript 和 Python SDK。
输入格式
SDK 支持多种输入格式:
文本输入(默认)
输入文本可以作为参数提供:
或者输入文本可以通过 stdin 管道传输:
流式 JSON 输入
通过 stdin
提供的消息流,其中每条消息代表一个用户轮次。这允许对话的多个轮次而无需重新启动 claude
二进制文件,并允许在模型处理请求时向模型提供指导。
每条消息都是一个 JSON ‘用户消息’ 对象,遵循与输出消息模式相同的格式。消息使用 jsonl 格式格式化,其中输入的每一行都是一个完整的 JSON 对象。流式 JSON 输入需要 -p
和 --output-format stream-json
。
目前这仅限于纯文本用户消息。
示例
简单脚本集成
使用 Claude 处理文件
会话管理
最佳实践
-
使用 JSON 输出格式 进行响应的程序化解析:
-
优雅地处理错误 - 检查退出代码和 stderr:
-
使用会话管理 在多轮对话中维护上下文
-
考虑超时 对于长时间运行的操作:
-
尊重速率限制 在进行多个请求时通过在调用之间添加延迟
实际应用
Claude Code SDK 能够与您的开发工作流程进行强大的集成。一个值得注意的例子是 Claude Code GitHub Actions,它使用 SDK 直接在您的 GitHub 工作流程中提供自动化代码审查、PR 创建和问题分类功能。
相关资源
- CLI 使用和控制 - 完整的 CLI 文档
- GitHub Actions 集成 - 使用 Claude 自动化您的 GitHub 工作流程
- 常见工作流程 - 常见用例的分步指南