Claude Agent SDK 与 CLI 对比完全指南

烁烁闪闪烁烁2026-02-11 8:58

Claude Agent SDK 与 CLI 对比完全指南

目录

  1. 概述
  2. 系统提示对比
  3. 核心区别详解
  4. 输出一致性分析
  5. 实战配置方案
  6. 使用场景推荐
  7. 常见问题解答

概述

什么是 Claude Agent SDK 和 Claude CLI？

Claude CLI (Claude Code) 是 Anthropic 官方提供的命令行交互工具，专为开发者设计，提供了丰富的开发辅助功能。

Claude Agent SDK 是用于构建自定义 AI 代理的编程接口，允许开发者将 Claude 集成到自己的应用程序中。

Claude直连平台 🔗Weelinking Opus4.6 效率十倍提升。 第一时间体验 Opus4.6

核心差异一览

特性 Claude CLI Agent SDK (默认) Agent SDK (预设模式)
系统提示 模块化架构（~269+ 基础token） 最小化 模块化（匹配CLI）
内置工具 18+ 个工具 仅提供的工具 18+ 个工具
自动加载 CLAUDE.md ✅ 是 ❌ 否 ❌ 需配置
编码规范 ✅ 包含 ❌ 无 ✅ 包含
安全规则 ✅ 完整 ⚠️ 基础 ✅ 完整
输出确定性 ❌ 无保证 ❌ 无保证 ❌ 无保证
使用场景 交互式开发 程序集成 匹配CLI行为

系统提示对比

Claude CLI 的系统提示架构

Claude CLI 采用模块化系统提示架构，由 110+ 个系统提示字符串组成，基础提示约 269 个 token，根据激活的功能条件加载额外内容。

系统提示组件详解
组件 说明 加载方式 Token 影响
基础系统提示 核心指令和行为规范 始终加载 ~269 tokens
工具指令 18+ 个内置工具说明 始终加载 中等
编码指南 代码风格、格式、安全实践 始终加载 中等
安全规则 拒绝规则、注入防御、危害预防 始终加载 中等
响应风格 语气、详细程度、emoji使用 始终加载 较小
环境上下文 工作目录、git状态、平台信息 始终加载 较小
项目上下文 CLAUDE.md 内容、设置、钩子配置 条件加载 可变
子代理提示 计划模式、探索代理、任务代理 条件加载 较大
安全审查 扩展安全指令 条件加载 ~2,610 tokens

关键特性：

  • ✅ 模块化架构，根据需求灵活组合
  • ✅ 基础提示精简，总量根据激活功能而变化
  • ✅ 包含广泛的安全和注入防御层
  • ✅ 自动加载工作目录中的 CLAUDE.md 文件
  • ✅ 交互模式下保持会话持久上下文

Agent SDK 的系统提示架构

默认模式（最小化）

SDK 默认使用最小化系统提示，仅包含：

组件 说明 Token 影响
基本工具指令 仅显式提供的工具 最小
基础安全 最小安全指令 最小

特点：

  • ❌ 默认无编码指南或风格偏好
  • ❌ 默认无项目上下文
  • ❌ 无详细工具描述
  • ✅ 需要显式配置以匹配 CLI 行为
预设模式（claude_code）

可以通过配置启用与 CLI 相同的系统提示：

typescript 复制代码 
import { query } from "@anthropic-ai/agent-sdk";

const response = await query({
  prompt: "您的问题",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code"  // 使用 CLI 预设
    }
  }
});

使用预设后，系统提示结构与 CLI 相同，但仍需配置 settingSources 来加载 CLAUDE.md。

核心区别详解

1. 发送的内容差异

通过 Claude CLI 发送

当你向 Claude CLI 发送消息时：

复制代码 
系统提示: [模块化, ~269+ 基础 tokens]
├── 基础系统提示 (~269 tokens)
├── 工具指令 (Write, Read, Edit, Bash, Grep, Glob 等)
├── Git 安全协议
├── 代码引用指南
├── 专业客观性指令
├── 安全和注入防御规则
├── 环境上下文 (操作系统、目录、日期)
├── CLAUDE.md 内容 (如果存在) [条件加载]
├── MCP 工具描述 (如果配置) [条件加载]
├── 计划/探索模式提示 [条件加载]
└── 会话/对话上下文

用户消息: "挪威的首都是什么？"
通过 Agent SDK (默认) 发送
复制代码 
系统提示: [最小化]
├── 基本工具指令 (如果提供了工具)
└── 基本操作上下文

用户消息: "挪威的首都是什么？"

Claude直连平台 🔗Weelinking Opus4.6 效率十倍提升。 第一时间体验 Opus4.6

通过 Agent SDK (claude_code 预设) 发送
typescript 复制代码 
const response = await query({
  prompt: "挪威的首都是什么？",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code"
    },
    settingSources: ["project"]  // 加载项目上下文
  }
});
复制代码 
系统提示: [模块化, 匹配 CLI]
├── 完整 Claude Code 系统提示
├── 工具指令
├── 编码指南
└── 安全规则

// 注意: 仍需配置 settingSources 来加载 CLAUDE.md

2. 自定义方式对比

Claude CLI 自定义
方法 命令 效果
追加到提示 claude -p "..." --append-system-prompt "..." 添加指令，保留默认设置
替换提示 claude -p "..." --system-prompt "..." 完全替换系统提示
项目上下文 CLAUDE.md 文件 自动加载，持久化
输出样式 /output-style [名称] 应用预定义响应样式

示例：

bash 复制代码 
# 追加自定义指令
claude -p "修复这个bug" --append-system-prompt "使用详细的注释解释每个步骤"

# 完全替换系统提示
claude -p "生成报告" --system-prompt "你是一个技术写作专家"
Agent SDK 自定义
方法 配置 效果
自定义提示 systemPrompt: "..." 完全替换（会丢失工具）
预设 + 追加 systemPrompt: { type: "preset", preset: "claude_code", append: "..." } 保留 CLI 功能 + 自定义指令
CLAUDE.md 加载 settingSources: ["project"] 加载项目级指令
输出样式 settingSources: ["user"] 或 settingSources: ["project"] 加载保存的输出样式

示例：

typescript 复制代码 
// 方式1: 自定义提示（会丢失工具功能）
const response1 = await query({
  prompt: "生成报告",
  options: {
    systemPrompt: "你是一个技术写作专家"
  }
});

// 方式2: 预设 + 追加（推荐）
const response2 = await query({
  prompt: "修复这个bug",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "使用详细的注释解释每个步骤"
    },
    settingSources: ["project", "user"]
  }
});

输出一致性分析

⚠️ 重要发现：无确定性保证

Claude Messages API 不提供 seed 参数来保证可重现性。 这是一个根本性的架构限制。

阻止完全一致输出的因素

因素 说明 可控？
系统提示差异 CLI 与 SDK 默认设置不同 ✅ 可以（通过配置）
浮点运算 并行硬件的微小差异 ❌ 不可控
MoE 路由 混合专家架构的路由变化 ❌ 不可控
批处理/调度 云基础设施差异 ❌ 不可控
数值精度 推理引擎变化 ❌ 不可控
模型快照 版本更新/变更 ❌ 不可控

Temperature 和采样

即使设置 temperature=0.0（贪婪解码）：

实现最大一致性的方法

要在 SDK 和 CLI 之间获得尽可能接近的相同输出：

SDK 配置示例
typescript 复制代码 
import Anthropic from "@anthropic-ai/sdk";
import { query } from "@anthropic-ai/agent-sdk";

// 使用 Messages API
const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  temperature: 0,  // 贪婪解码
  system: "匹配 CLI 的系统提示内容",
  messages: [
    { role: "user", content: "挪威的首都是什么？" }
  ]
});

// 使用 Agent SDK query 函数
for await (const message of query({
  prompt: "挪威的首都是什么？",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code"
    },
    temperature: 0,
    model: "claude-sonnet-4-20250514",
    settingSources: ["project"]  // 像 CLI 一样加载项目上下文
  }
})) {
  // 处理响应
}
CLI 配置示例
bash 复制代码 
# 匹配 SDK 配置
claude -p "挪威的首都是什么？" \
  --model claude-sonnet-4-20250514 \
  --temperature 0

⚠️ 仍不保证一致

即使配置完全匹配：

  • 输出可能在不同运行之间有所不同
  • 输出可能在 SDK 和 CLI 之间有所不同
  • 不存在 seed 参数来强制可重现性

实战配置方案

场景 1: 在 SDK 中完全复现 CLI 行为

需求： 在自己的应用中获得与 CLI 相同的体验。

配置方案：

typescript 复制代码 
import { query } from "@anthropic-ai/agent-sdk";

for await (const message of query({
  prompt: "帮我重构这段代码",
  options: {
    // 使用 claude_code 预设
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "特别注意代码的可读性和性能优化"
    },

    // 加载项目和用户设置
    settingSources: ["project", "user"],

    // 使用推荐模型
    model: "claude-sonnet-4-20250514",

    // 贪婪解码（最大一致性）
    temperature: 0,

    // 其他 CLI 默认设置
    max_tokens: 4096
  }
})) {
  console.log(message);
}

场景 2: 轻量级 SDK 集成（最小 token 使用）

需求： 在应用中嵌入 Claude，但不需要完整的开发工具功能。

配置方案：

typescript 复制代码 
import { query } from "@anthropic-ai/agent-sdk";

for await (const message of query({
  prompt: "总结这篇文章的要点",
  options: {
    // 使用自定义系统提示（轻量级）
    systemPrompt: "你是一个专业的内容总结助手，善于提取关键信息",

    // 不加载额外设置
    settingSources: [],

    // 使用快速模型
    model: "claude-haiku-4-5-20251001",

    // 允许一些创造性
    temperature: 0.3
  }
})) {
  console.log(message);
}

场景 3: CLI 中添加自定义指令

需求： 使用 CLI 的完整功能，但添加项目特定的指令。

方式 1: 使用 CLAUDE.md（推荐）

在项目根目录创建 .claude/CLAUDE.md 或 CLAUDE.md：

markdown 复制代码 
# 项目指南

## 编码规范
- 使用 TypeScript strict 模式
- 所有函数必须有 JSDoc 注释
- 优先使用函数式编程风格

## 测试要求
- 每个功能必须有单元测试
- 测试覆盖率不低于 80%

## 提交规范
- 使用 Conventional Commits 格式
- 提交前必须运行 lint 和 test

方式 2: 使用命令行参数

bash 复制代码 
# 追加指令
claude -p "添加用户认证功能" \
  --append-system-prompt "遵循 OWASP 安全最佳实践，使用 JWT 进行身份验证"

# 完全自定义
claude -p "生成 API 文档" \
  --system-prompt "你是一个 API 文档专家，生成符合 OpenAPI 3.0 规范的文档"

场景 4: 批量处理任务（SDK）

需求： 自动化处理大量代码审查或文档生成任务。

配置方案：

typescript 复制代码 
import { query } from "@anthropic-ai/agent-sdk";

async function batchReview(files: string[]) {
  const results = [];

  for (const file of files) {
    const fileContent = await readFile(file);

    for await (const message of query({
      prompt: `审查以下代码并提供改进建议：\n\n${fileContent}`,
      options: {
        systemPrompt: {
          type: "preset",
          preset: "claude_code",
          append: `
            专注于以下方面：
            1. 代码质量和可维护性
            2. 性能问题
            3. 安全漏洞
            4. 最佳实践遵循情况
          `
        },
        model: "claude-sonnet-4-20250514",
        temperature: 0,
        // 缓存系统提示以提高性能
        settingSources: ["project"]
      }
    })) {
      results.push({ file, review: message });
    }
  }

  return results;
}

Claude直连平台 🔗Weelinking Opus4.6 效率十倍提升。 第一时间体验 Opus4.6

使用场景推荐

何时使用 Claude CLI

场景 原因
交互式开发 完整工具套件，项目上下文自动加载
快速原型 无需配置，开箱即用
学习和实验 内置帮助和示例
一次性任务 快速设置，即时上下文
团队协作 通过 CLAUDE.md 共享项目知识

典型使用：

bash 复制代码 
# 快速开始开发
cd my-project
claude

# 一次性任务
claude -p "生成这个API的测试用例"

# 使用项目配置
claude  # 自动加载 .claude/CLAUDE.md

何时使用 Agent SDK

场景 原因
程序化集成 细粒度控制，嵌入到应用中
一致的 API 响应 更多系统提示控制
批量处理 更适合自动化管道
自定义工作流 构建定制的 AI 工作流
生产环境 可预测的行为，错误处理

典型使用：

typescript 复制代码 
// 嵌入到 Web 应用
app.post('/api/code-review', async (req, res) => {
  for await (const message of query({
    prompt: req.body.code,
    options: {
      systemPrompt: { type: "preset", preset: "claude_code" }
    }
  })) {
    res.write(message);
  }
  res.end();
});

// 自动化管道
async function automatedPipeline() {
  // 步骤 1: 生成代码
  // 步骤 2: 审查代码
  // 步骤 3: 生成文档
  // 步骤 4: 创建测试
}

混合使用策略

推荐工作流：

复制代码 
1. 开发阶段     → Claude CLI (终端)
2. 测试验证     → Claude CLI (交互式调试)
3. 自动化集成   → Agent SDK (程序化)
4. 生产部署     → Agent SDK (稳定 API)

常见问题解答

Q1: 为什么 SDK 和 CLI 给出的答案不完全一样？

A: 主要有三个原因：

  1. 系统提示不同 - CLI 默认有丰富的系统提示，SDK 默认最小化
  2. 上下文不同 - CLI 自动加载 CLAUDE.md 和项目上下文
  3. 非确定性 - Claude API 没有 seed 参数，即使配置相同也可能有细微差异

解决方案： 使用 claude_code 预设 + settingSources: ["project"]

Q2: 如何让 SDK 行为与 CLI 完全一致？

A: 使用以下配置：

typescript 复制代码 
const options = {
  systemPrompt: {
    type: "preset",
    preset: "claude_code"
  },
  settingSources: ["project", "user"],
  model: "claude-sonnet-4-20250514",
  temperature: 0
};

注意： 即使这样也不能保证 100% 一致，因为存在基础设施层面的非确定性。

Q3: 系统提示会消耗多少 token？

A: Token 消耗情况：

配置 基础 Token 额外内容
SDK（最小） 极少 仅基本工具指令
SDK（claude_code 预设） ~269+ 根据激活功能变化
CLI（默认） ~269+ + 项目上下文 + MCP 工具
CLI（启用 MCP） ~269+ + 大量 MCP 工具描述

建议：

  • 如果上下文预算紧张，使用最小化系统提示
  • 如果需要完整功能，接受额外的 token 消耗

Q4: 可以完全禁用系统提示吗？

A: 不推荐，但技术上可以：

typescript 复制代码 
// ⚠️ 不推荐：会丢失所有工具功能
const response = await query({
  prompt: "你的问题",
  options: {
    systemPrompt: ""  // 空系统提示
  }
});

后果：

  • ❌ 失去所有内置工具（Read、Write、Edit 等）
  • ❌ 失去编码规范和安全规则
  • ❌ Claude 行为可能不可预测

Q5: CLAUDE.md 和系统提示有什么区别？

A:

特性 CLAUDE.md 系统提示
用途 项目特定指令 全局行为规范
加载 CLI 自动，SDK 需配置 始终存在
版本控制 通常提交到 git 不提交
团队共享 ✅ 是 ❌ 否
优先级 高（可覆盖部分系统提示） 低

最佳实践：

  • 系统提示：通用行为（如语气、安全规则）
  • CLAUDE.md：项目特定规则（如编码规范、架构决策）

Q6: 如何查看完整的系统提示内容？

A:

CLI 方式：

bash 复制代码 
# 启用调试模式
claude --debug

# 查看系统提示组件
# 系统提示会在调试输出中显示

SDK 方式：

typescript 复制代码 
import { query } from "@anthropic-ai/agent-sdk";

// 启用详细日志
process.env.DEBUG = "anthropic:*";

for await (const message of query({
  prompt: "测试",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
})) {
  // 系统提示会在日志中输出
}

Q7: temperature=0 真的能保证确定性吗？

A: ❌ 不能保证

虽然 temperature=0 使用贪婪解码（总是选择最可能的 token），但由于以下因素仍可能产生不同输出：

  • 浮点运算的微小差异
  • 并行计算的执行顺序
  • 模型快照的更新
  • 基础设施的变化

建议：

  • 不要依赖位级别的可重现性
  • 使用结构化输出和验证逻辑
  • 对关键任务考虑使用多次生成 + 一致性检查

Q8: 如何在保持功能的同时减少 token 消耗？

A: 策略组合：

typescript 复制代码 
// 1. 使用更快的模型处理子任务
const haiku_options = {
  model: "claude-haiku-4-5-20251001",  // 更快、更便宜
  systemPrompt: "简化的系统提示"
};

// 2. 仅在需要时启用完整功能
const full_options = {
  systemPrompt: {
    type: "preset",
    preset: "claude_code"
  },
  settingSources: ["project"]  // 仅在需要项目上下文时加载
};

// 3. 使用提示缓存
// Claude 会自动缓存系统提示，减少重复消耗

总结

核心要点

  1. 系统提示不同 - CLI 使用模块化架构（~269+ 基础 token），SDK 默认最小化
  2. 无确定性保证 - 即使配置相同，输出也可能不同
  3. 可配置匹配 - SDK 可以通过 claude_code 预设匹配 CLI 行为
  4. 场景选择 - CLI 适合交互开发，SDK 适合程序集成

选择建议

如果你需要... 使用
交互式开发和调试 Claude CLI
嵌入到应用程序 Agent SDK
批量自动化处理 Agent SDK
快速原型和实验 Claude CLI
生产环境集成 Agent SDK (claude_code 预设)
团队协作和知识共享 Claude CLI + CLAUDE.md

最佳实践

  1. 不依赖完全确定性 - 构建能容忍输出变化的应用
  2. 使用结构化输出 - 通过 JSON schema 验证
  3. 在 SDK 中匹配 CLI - 使用 claude_code 预设 + settingSources
  4. 合理使用 token - 根据任务复杂度选择系统提示级别
  5. 善用 CLAUDE.md - 团队共享项目特定知识

相关资源

相关推荐
安科士andxe4 小时前
深入解析｜安科士1.25G CWDM SFP光模块核心技术，破解中长距离传输痛点
服务器·网络·5g
mCell6 小时前
如何零成本搭建个人站点
前端·程序员·github
九.九7 小时前
ops-transformer：AI 处理器上的高性能 Transformer 算子库
人工智能·深度学习·transformer
春日见7 小时前
拉取与合并：如何让个人分支既包含你昨天的修改，也包含 develop 最新更新
大数据·人工智能·深度学习·elasticsearch·搜索引擎
小高不会迪斯科7 小时前
CMU 15445学习心得(二) 内存管理及数据移动--数据库系统如何玩转内存
数据库·oracle
恋猫de小郭7 小时前
AI 在提高你工作效率的同时，也一直在增加你的疲惫和焦虑
前端·人工智能·ai编程
YJlio7 小时前
1.7 通过 Sysinternals Live 在线运行工具：不下载也能用的“云端工具箱”
c语言·网络·python·数码相机·ios·django·iphone
deephub7 小时前
Agent Lightning：微软开源的框架无关 Agent 训练方案，LangChain/AutoGen 都能用
人工智能·microsoft·langchain·大语言模型·agent·强化学习
e***8907 小时前
MySQL 8.0版本JDBC驱动Jar包
数据库·mysql·jar
l1t7 小时前
在wsl的python 3.14.3容器中使用databend包
开发语言·数据库·python·databend
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05Linux下V2Ray安装配置指南06openclaw使用nginx反代部署过程 与disconnected (1008): pairing required解决07AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南08【Linux操作系统12】Git版本控制与GDB调试：从入门到实践09Vue-skills的中文文档10OpenClaw Chrome扩展使用教程 - 浏览器中继控制