Claude Code SDK 完整指南

嗨，朋友你好，我是是诗康妈咪。致力于探索如何把AI应用于普通人生活的方方面面。

今天给大家继续分享claude code使用的方法——Claude Code SDK 完整指南。

1. 概述

Claude Code SDK 支持将 Claude Code 作为子进程运行，提供了一种构建 AI 驱动的编码助手和工具的方法，利用 Claude 的能力。

SDK 可用于命令行、TypeScript 和 Python 使用。

2. 身份验证

要使用 Claude Code SDK，我们建议创建一个专用的 API 密钥：

在

Anthropic Console 中创建一个 Anthropic API 密钥

然后，设置ANTHROPIC_API_KEY环境变量。我们建议安全地存储此密钥（例如，使用 Github

secret）

3. 基本 SDK 使用

Claude Code SDK 允许您在应用程序中以非交互模式使用 Claude Code。

3.1 命令行

以下是命令行 SDK 的一些基本示例：

# 运行单个提示并退出（打印模式）

$ claude -p "编写一个计算斐波那契数的函数"

# 使用管道提供标准输入

$ echo"解释这段代码"| claude -p

# 以 JSON 格式输出并包含元数据

$ claude -p "生成一个 hello world 函数" --output-format json

# 在到达时流式传输 JSON 输出

$ claude -p "构建一个 React 组件" --output-format stream-json

3.2 TypeScript

TypeScript SDK 包含在 NPM 上的主要@anthropic-ai/claude-code包中：

import{ query,typeSDKMessage}from"@anthropic-ai/claude-code";

const messages:SDKMessage[]=[];

forawait(const message ofquery({

prompt:"为 foo.py 写一首俳句",

abortController:newAbortController(),

options:{

  maxTurns:3,

},

})){

messages.push(message);

}

console.log(messages);

TypeScript SDK 接受命令行 SDK 支持的所有参数，以及：

3.3 Python

Python SDK 在 PyPI 上作为claude-code-sdk提供：

pip install claude-code-sdk

先决条件：

Python 3.10+

Node.js

Claude Code CLI：npm install -g @anthropic-ai/claude-code

基本使用：

import anyio

from claude_code_sdk import query, ClaudeCodeOptions, Message

asyncdefmain():

  messages:list[Message]=[]

asyncfor message in query(

      prompt="为 foo.py 写一首俳句",

      options=ClaudeCodeOptions(max_turns=3)

):

      messages.append(message)

print(messages)

anyio.run(main)

Python SDK 通过ClaudeCodeOptions类接受命令行 SDK 支持的所有参数：

from claude_code_sdk import query, ClaudeCodeOptions

from pathlib import Path

options = ClaudeCodeOptions(

  max_turns=3,

  system_prompt="你是一个有用的助手",

  cwd=Path("/path/to/project"),# 可以是字符串或 Path

  allowed_tools=["Read","Write","Bash"],

  permission_mode="acceptEdits"

)

asyncfor message in query(prompt="你好", options=options):

print(message)

4. 高级使用

下面的文档使用命令行 SDK 作为示例，但也可以与 TypeScript 和 Python SDK 一起使用。

4.1 多轮对话

对于多轮对话，您可以恢复对话或从最近的会话继续：

# 继续最近的对话

$ claude --continue

# 继续并提供新的提示

$ claude --continue "现在重构这个以获得更好的性能"

# 通过会话 ID 恢复特定对话

$ claude --resume 550e8400-e29b-41d4-a716-446655440000

# 在打印模式下恢复（非交互式）

$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "更新测试"

# 在打印模式下继续（非交互式）

$ claude -p --continue "添加错误处理"

4.2 自定义系统提示

您可以提供自定义系统提示来指导 Claude 的行为：

# 覆盖系统提示（仅适用于 --print）

$ claude -p "构建一个 REST API" --system-prompt "你是一个高级后端工程师。专注于安全性、性能和可维护性。"

# 具有特定要求的系统提示

$ claude -p "创建一个数据库架构" --system-prompt "你是一个数据库架构师。使用 PostgreSQL 最佳实践并包含适当的索引。"

您还可以将指令附加到默认系统提示：

# 附加系统提示（仅适用于 --print）

$ claude -p "构建一个 REST API" --append-system-prompt "编写代码后，请务必进行代码审查。"

4.3 MCP 配置

模型上下文协议（MCP）允许您使用来自外部服务器的附加工具和资源扩展 Claude Code。使用--mcp-config标志，您可以加载提供专门功能的 MCP 服务器，如数据库访问、API 集成或自定义工具。

创建一个包含您的 MCP 服务器的 JSON 配置文件：

{

"mcpServers":{

"filesystem":{

"command":"npx",

"args":[

"-y",

"@modelcontextprotocol/server-filesystem",

"/path/to/allowed/files"

]

},

"github":{

"command":"npx",

"args":["-y","@modelcontextprotocol/server-github"],

"env":{

"GITHUB_TOKEN":"your-github-token"

}

}

}

}

然后与 Claude Code 一起使用：

# 从配置加载 MCP 服务器

$ claude -p "列出项目中的所有文件" --mcp-config mcp-servers.json

# 重要：必须使用 --allowedTools 明确允许 MCP 工具

# MCP 工具遵循格式：mcp__$serverName__$toolName

$ claude -p "搜索 TODO 注释"\

--mcp-config mcp-servers.json \

--allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"

# 使用 MCP 工具在非交互模式下处理权限提示

$ claude -p "部署应用程序"\

--mcp-config mcp-servers.json \

--allowedTools "mcp__permissions__approve"\

--permission-prompt-tool mcp__permissions__approve

**注意：**使用 MCP 工具时，您必须使用--allowedTools标志明确允许它们。MCP 工具名称遵循模式mcp__<serverName>__<toolName>，其中：

serverName是您的 MCP 配置文件中的键

toolName是该服务器提供的特定工具

这种安全措施确保 MCP 工具仅在明确允许时使用。

如果您只指定服务器名称（即mcp__<serverName>），则该服务器的所有工具都将被允许。

不支持通配符模式（例如mcp__go*）。

4.4 自定义权限提示工具

可选地，使用--permission-prompt-tool传入一个 MCP 工具，我们将使用它来检查用户是否授予模型调用给定工具的权限。当模型调用工具时，会发生以下情况：

我们首先检查权限设置：所有 settings.json 文件，以及传递给 SDK 的--allowedTools和--disallowedTools；如果其中之一允许或拒绝工具调用，我们继续进行工具调用

否则，我们调用您在--permission-prompt-tool中提供的 MCP 工具

--permission-prompt-toolMCP 工具会传递工具名称和输入，并且必须返回一个带有结果的 JSON 字符串化载荷。载荷必须是以下之一：

// 工具调用被允许

{

"behavior":"allow",

"updatedInput":{...},// 更新的输入，或者只是返回原始输入

}

// 工具调用被拒绝

{

"behavior":"deny",

"message":"..."// 解释为什么权限被拒绝的人类可读字符串

}

例如，TypeScript MCP 权限提示工具实现可能如下所示：

const server =newMcpServer({

name:"测试权限提示 MCP 服务器",

version:"0.0.1",

});

server.tool(

"approval_prompt",

'模拟权限检查 - 如果输入包含 "allow"，则批准，否则拒绝',

{

  tool_name: z.string().describe("请求权限的工具"),

  input: z.object({}).passthrough().describe("工具的输入"),

},

async({ tool_name, input })=>{

return{

    content:[

{

        type:"text",

        text:JSON.stringify(

JSON.stringify(input).includes("allow")

?{

                behavior:"allow",

                updatedInput: input,

}

:{

                behavior:"deny",

                message:"被测试 approval_prompt 工具拒绝权限",

}

),

},

],

};

}

);

要使用此工具，添加您的 MCP 服务器（例如使用--mcp-config），然后像这样调用 SDK：

claude -p "..." \

--permission-prompt-tool mcp__test-server__approval_prompt \

--mcp-config my-config.json

使用说明：

使用updatedInput告诉模型权限提示改变了其输入；否则，将updatedInput设置为原始输入，如上面的示例所示。例如，如果工具向用户显示文件编辑差异并让他们手动编辑差异，权限提示工具应该返回该更新的编辑。

载荷必须是 JSON 字符串化的

5. 可用的 CLI 选项

SDK 利用 Claude Code 中可用的所有 CLI 选项。以下是 SDK 使用的关键选项：

6. 输出格式

SDK 支持多种输出格式：

6.1 文本输出（默认）

仅返回响应文本：

$ claude -p "解释文件 src/components/Header.tsx"

# 输出：这是一个 React 组件，显示...

6.2 JSON 输出

返回包括元数据的结构化数据：

$ claude -p "数据层是如何工作的？" --output-format json

响应格式：

{

"type":"result",

"subtype":"success",

"total_cost_usd":0.003,

"is_error":false,

"duration_ms":1234,

"duration_api_ms":800,

"num_turns":6,

"result":"响应文本在这里...",

"session_id":"abc123"

}

6.3 流式 JSON 输出

在接收到每条消息时流式传输：

$ claude -p "构建一个应用程序" --output-format stream-json

每个对话都以初始的init系统消息开始，然后是用户和助手消息列表，最后是带有统计信息的最终result系统消息。每条消息都作为单独的 JSON 对象发出。

7. 消息模式

从 JSON API 返回的消息根据严格的类型模式：

typeSDKMessage=

// 助手消息

|{

    type:"assistant";

    message:Message;// 来自 Anthropic SDK

    session_id:string;

}

// 用户消息

|{

    type:"user";

    message:MessageParam;// 来自 Anthropic SDK

    session_id:string;

}

// 作为最后一条消息发出

|{

    type:"result";

    subtype:"success";

    duration_ms: float;

    duration_api_ms: float;

    is_error:boolean;

    num_turns: int;

    result:string;

    session_id:string;

    total_cost_usd: float;

}

// 作为最后一条消息发出，当我们达到最大轮次时

|{

    type:"result";

    subtype:"error_max_turns"|"error_during_execution";

    duration_ms: float;

    duration_api_ms: float;

    is_error:boolean;

    num_turns: int;

    session_id:string;

    total_cost_usd: float;

}

// 在对话开始时作为第一条消息发出

|{

    type:"system";

    subtype:"init";

    apiKeySource:string;

    cwd:string;

    session_id:string;

    tools:string[];

    mcp_servers:{

      name:string;

      status:string;

}[];

    model:string;

    permissionMode:"default"|"acceptEdits"|"bypassPermissions"|"plan";

};

我们将很快以 JSONSchema 兼容格式发布这些类型。我们对主要的 Claude Code 包使用语义版本控制来传达此格式的重大更改。

8. 输入格式

SDK 支持多种输入格式：

8.1 文本输入（默认）

输入文本可以作为参数提供：

$ claude -p "解释这段代码"

或者输入文本可以通过 stdin 管道传输：

$ echo"解释这段代码"| claude -p

8.2 流式 JSON 输入

通过stdin提供的消息流，其中每条消息代表一个用户轮次。这允许对话的多个轮次而无需重新启动claude二进制文件，并允许在模型处理请求时向模型提供指导。

每条消息都是一个 JSON '用户消息' 对象，遵循与输出消息模式相同的格式。消息使用 jsonl 格式格式化，其中输入的每一行都是一个完整的 JSON 对象。流式 JSON 输入需要-p和--output-format stream-json。

目前这仅限于纯文本用户消息。

$ echo'{"type":"user","message":{"role":"user","content":[{"type":"text","text":"解释这段代码"}]}}'| claude -p --output-format=stream-json --input-format=stream-json --verbose

9. 示例

9.1 简单脚本集成

#!/bin/bash

# 运行 Claude 并检查退出代码的简单函数

run_claude(){

localprompt="$1"

localoutput_format="${2:-text}"

if claude -p "$prompt" --output-format "$output_format";then

echo"成功！"

else

echo"错误：Claude 失败，退出代码 $?">&2

return1

fi

}

# 使用示例

run_claude "编写一个读取 CSV 文件的 Python 函数"

run_claude "优化这个数据库查询""json"

9.2 使用 Claude 处理文件

# 通过 Claude 处理文件

$ cat mycode.py | claude -p "检查这段代码中的错误"

# 处理多个文件

$ forfilein *.js;do

echo"处理 $file..."

  claude -p "为这个文件添加 JSDoc 注释："<"$file">"${file}.documented"

done

# 在管道中使用 Claude

$ grep -l "TODO" *.py |whilereadfile;do

  claude -p "修复这个文件中的所有 TODO 项"<"$file"

done

9.3 会话管理

# 启动会话并捕获会话 ID

$ claude -p "初始化一个新项目" --output-format json | jq -r '.session_id'> session.txt

# 使用相同会话继续

$ claude -p --resume "$(cat session.txt)""添加单元测试"

10. 最佳实践

使用 JSON 输出格式进行响应的程序化解析：

# 使用 jq 解析 JSON 响应

result=$(claude -p "生成代码" --output-format json)

code=$(echo"$result"| jq -r '.result')

cost=$(echo"$result"| jq -r '.cost_usd')

优雅地处理错误- 检查退出代码和 stderr：

if! claude -p "$prompt"2>error.log;then

echo"发生错误：">&2

cat error.log >&2

exit1

fi

使用会话管理在多轮对话中维护上下文

考虑超时对于长时间运行的操作：

timeout300 claude -p "$complex_prompt"||echo"5 分钟后超时"

尊重速率限制在进行多个请求时通过在调用之间添加延迟

11. 实际应用

Claude Code SDK 能够与您的开发工作流程进行强大的集成。一个值得注意的例子是 Claude Code GitHub Actions，它使用 SDK 直接在您的 GitHub 工作流程中提供自动化代码审查、PR 创建和问题分类功能。

通过这些功能，您可以：

自动化代码审查流程

生成和优化代码

处理文档生成

实现智能代码分析

构建定制的 AI 编程助手

Claude Code SDK 为开发者提供了一个强大而灵活的工具，可以将 AI 能力无缝集成到现有的开发工作流程中。