2026 年 6 月改名后 claude-code-sdk 报导入错误：原因与修复

你刚升级完，构建就崩了，报 ModuleNotFoundError: No module named 'claude_code_sdk'，或者 TypeScript 抛出 @anthropic-ai/claude-code 没有导出成员 query。这不是你哪里做错了，是包搬家了。

让人迷惑的地方在于：npm install @anthropic-ai/claude-code 照样能装成功。只不过它现在装的是另一个东西。你记忆里那个名字指向的是 CLI 工具；SDK 早就收拾东西走了。

2026 年 6 月，Anthropic 把 Claude Code SDK 改名成了 Claude Agent SDK。TypeScript 包变成 @anthropic-ai/claude-agent-sdk，Python 包变成 claude-agent-sdk。旧名字没有全部干净地 404 掉，这正是错误信息让人摸不着头脑的原因。这是一次精确的修复，不是推倒重来。下面讲清楚什么坏了、为什么坏，以及两种语言各自的改前/改后对照。

30 秒修复：改前 → 改后

这次改名涉及包名、导入路径，以及（Python 里的）一个类名。把你的旧行映射到新行，大部分代码就能继续跑。

写本文时的当前版本：@anthropic-ai/claude-agent-sdk 在 0.3.x，PyPI 上的 claude-agent-sdk 在 0.2.x。被冻结的旧包停在 claude-code-sdk 0.0.25（Python），@anthropic-ai/claude-code 现在是 CLI，版本 2.1.x。想深究为什么，本文后面会逐个错误字符串走一遍。

为什么导入崩了（CLI 与 SDK 的命名冲突）

短答：SDK 从 @anthropic-ai/claude-code 搬走了，但那个包名作为 CLI 工具保留了下来，于是安装能成功、导入却失败。这种错位是这次迁移里最大的困惑来源，所以值得把现在「谁拥有哪个名字」说清楚。

2026 年 6 月之前，@anthropic-ai/claude-code 同时发布两样东西：claude CLI 二进制，以及编程用的 SDK（query、tool、createSdkMcpServer）。改名之后，这两份职责分家了：

所以 npm install @anthropic-ai/claude-code 不会失败，它装的是 CLI。然后你的 import { query } from "@anthropic-ai/claude-code" 会失败，因为这个包不再导出 SDK 符号。错误信息指向导入语句，但真正的问题在你装错了包。

改名本身反映的是范围变化。这个 SDK 起初是个写代码的助手，后来长成了一个搭建 agent 的通用框架（客服机器人、代码评审 agent、金融助手），所以「Agent SDK」比「Code SDK」更贴切。如果你刚开始围绕它搭 agent，我们的 Python AI agent 开发指南讲了搭在这个 SDK 之上的循环和工具接线模式。

错误信息 → 修复对照表

下面每条错误字符串都对应同一个根因：你指向了一个旧名字。找到你那条确切信息，照着修。

TypeScript / JavaScript 的修复

卸掉旧包，装上新包，改写导入字符串。符号名（query、tool、createSdkMcpServer）没变，所以大多数文件里导入是唯一要改的地方。

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

然后更新每一处导入：

// Before
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// After
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

如果你在 package.json 里 pin 了依赖，那个键也要更新。留着旧条目，就会落得两个包都装着、编辑器还会从错误的那个里解析出 query：

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.3.0"
  }
}

有一个值得 grep 一下的坑：如果你的脚本里还用到 CLI（claude 命令），那就为它留着 @anthropic-ai/claude-code，但绝不要从它里面导入 SDK 符号。把 CLI 和 SDK 当成两个职责分明的独立依赖。

Python 的修复

卸掉 claude-code-sdk，装上 claude-agent-sdk，然后改导入模块和 options 类名。构造函数参数完全一致，所以 model、permission_mode 这些都原样保留。

pip uninstall claude-code-sdk
pip install claude-agent-sdk

改写导入和类名：

# Before
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# After
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

第一个错误背后还藏着第二个：claude-agent-sdk 需要 Python 3.10 或更新版本。如果你用 3.9 建了 venv，pip 要么拒绝安装、要么什么都没装，于是你即便「装过了」也会撞上 ModuleNotFoundError: No module named 'claude_agent_sdk'。查一下导入实际跑在哪个解释器下：

python -c "import sys; print(sys.version)"
python -c "import claude_agent_sdk; print(claude_agent_sdk.__file__)"

如果第一条打印的是 3.9.x，用 3.10+ 重建 venv。如果第二条报错、但 pip show claude-agent-sdk 又能列出它，那说明你装进了和运行脚本不同的环境里。这是 SDK issue tracker 上「装了却找不到」这类报告里最常见的原因。

没人读的破坏性改动：默认系统提示

v0.1.0 及之后，默认系统提示没了，所以即便导入都编译通过，你的 agent 行为也会变。这是唯一一处「修好了构建却悄悄改了行为」的改动，所以它往往在迁移看起来已经搞定一周后才咬你一口。

旧版 SDK 会自动注入 Claude Code 面向 CLI 的系统提示。从 v0.1.0 起，SDK 发的是一份极简默认。要恢复旧行为，开启那个 preset：

import { query } from "@anthropic-ai/claude-agent-sdk";

// Restore the old Claude Code behavior:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

# Restore the old Claude Code behavior:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

或者传一个普通字符串（TS 里 systemPrompt: "You are a helpful coding assistant"，Python 里 system_prompt="..."）自己定义。对于上线部署的 agent，这反而是更好的默认值，因为你通常不希望 CLI 味的指令渗进一个客服机器人里。如果你的 agent 倚重工具定义，提示的变化可能改变工具如何被选用；我们的函数调用与工具使用指南讲了系统提示和工具 schema 是怎么互动的。

指南里还有一处细节：settingSources 在 v0.1.0 一度默认成「什么都不加载」，后来又改回来了。现在省略它会加载用户、项目和本地文件系统设置，跟 CLI 一致。要跑一次隔离运行，就传 settingSources: []（TS）或 setting_sources=[]（Python），这在 CI 和多租户部署里很要紧。Python SDK 0.1.59 及更早把空列表当成省略该选项来处理，所以靠它之前先升级。

这个修复救不了你的情况（以及该怎么办）

当你的错误是模块缺失、导出缺失或类被改名时，套这次改名修复。当症状是下面这些时，直接跳到别的修复：

• 你还在 Python 3.9 上，没法升级。 改名跟你无关，SDK 根本装不上。要么升级解释器，要么 pin 住旧的 claude-code-sdk 0.0.25，并接受它不再有任何修复。
• 认证或网络错误（401、ECONNRESET、超时）。 这些是运行时问题，不是导入问题。包名是对的，去看凭证、base URL 和重试逻辑。我们关于安全运行 Claude Code的笔记讲了几个权限和配置上的坑。
• 迁移后成本飙升。 改名是免费的，你的 token 用量可不是。如果账单突然涨了，看Claude Code token 优化。

退出规则：如果 python -c "import claude_agent_sdk" 跑通了、你的 TS 导入在编辑器里也能解析，迁移就算完成了。再往后的一切都是正常的运行时问题，不是改名留下的尾巴。

通过 ofox 让 Agent SDK 接多个模型

Agent SDK 走的是 Anthropic 风格的 endpoint，你也可以让同一套 agent 循环跑在一个 OpenAI 兼容的网关上。ofox 暴露一个 OpenAI 兼容的 base URL https://api.ofox.ai/v1，一把 key 接 100+ 个模型，包括 Claude、GPT 和 Gemini。如果你自己写工具使用循环（或者用 OpenAI 风格的客户端跑它），把 base_url 指向 ofox，你就能只改一个字符串就换模型，不用重新折腾 SDK 接线：

from openai import OpenAI

client = OpenAI(api_key="OFOX_API_KEY", base_url="https://api.ofox.ai/v1")
resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.8",   # swap this string to change models
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

这就是本文唯一的行动召唤。想要 Anthropic 原生的 agent 框架时，Claude Agent SDK 是对的工具；想在多家厂商之间 A/B 又不想重写客户端代码时，OpenAI 兼容网关是对的工具。

替代方案与相关工具

如果 Agent SDK 不合适，下面是几个实在的选项，ofox 排在前面：

• ofox API 网关（https://api.ofox.ai/v1）：OpenAI 兼容、多模型、一把 key。适合你想要厂商可移植性，并在同一套循环里把 Claude 和 GPT、Gemini 摆在一起测的时候。
• 直接用 Claude Agent SDK（@anthropic-ai/claude-agent-sdk / claude-agent-sdk）：原生框架，适合你想要 Anthropic 内置的 agent 功能、MCP 支持以及 claude_code preset 的时候。
• Claude Code CLI（@anthropic-ai/claude-code，v2.1.x）：终端工具，不是库。用它做交互式和脚本化的命令行活儿，不要拿它往应用代码里 import query。

FAQ

claude-code-sdk 是不是已经废弃了？ 是的。Python 的 claude-code-sdk（冻结在 0.0.25）和原本住在 @anthropic-ai/claude-code 里的 TypeScript SDK 都不再是 SDK 了。请改用 claude-agent-sdk 和 @anthropic-ai/claude-agent-sdk。

ClaudeCodeOptions 被什么取代了？ ClaudeAgentOptions，从 claude_agent_sdk 导入。构造函数参数一样，名字换了。

为什么 npm install @anthropic-ai/claude-code 能装上，导入却失败？ 因为那个包现在是 CLI 工具（v2.1.x），不是 SDK。SDK 符号搬到了 @anthropic-ai/claude-agent-sdk。

怎么修 ModuleNotFoundError: No module named ‘claude_code_sdk’？ pip uninstall claude-code-sdk、pip install claude-agent-sdk，然后从 claude_agent_sdk 导入。确认你用的是 Python 3.10+。

是 API 变了还是只改了包名？ 主要是名字。唯一的行为破坏是 v0.1.0+ 默认不再加载 Claude Code 的系统提示；用 preset 手动开启。

迁移后需要改 model ID 吗？ 不需要。改名不影响 model 字符串。

升到 v0.1.0+ 后，为什么我的 agent 行为不一样了？ 默认系统提示被移除了。传 claude_code preset 或自定义的 systemPrompt 恢复之前的行为。

@anthropic-ai/claude-code 和 @anthropic-ai/claude-agent-sdk 是同一个东西吗？ 不是，是两个不同的包。一个是 CLI，另一个是 SDK。

本次更新核对过的信息源

• Anthropic，《Migrate to Claude Agent SDK》官方指南：https://code.claude.com/docs/en/agent-sdk/migration-guide （2026-06-24 核对）
• npm @anthropic-ai/claude-agent-sdk（核对时 0.3.x）：https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk （2026-06-24 核对）
• npm @anthropic-ai/claude-code（CLI，核对时 2.1.x）（2026-06-24 核对）
• PyPI claude-agent-sdk（核对时 0.2.x）：https://pypi.org/project/claude-agent-sdk/ （2026-06-24 核对）
• PyPI claude-code-sdk（冻结在 0.0.25）（2026-06-24 核对）
• anthropics/claude-agent-sdk-python 仓库及关于 Python 3.10 要求的 issue 报告（2026-06-24 核对）
• ofox 模型目录与 API base URL：https://ofox.ai/llms-full.txt （2026-06-24 核对）

如果你的构建在改名后崩了，修复几乎总是一行：指向新包名。除此之外只有两处要改——类改名和那个消失的默认系统提示，而这两处一旦知道它们存在，各花一分钟就搞定。