Claude Code接入DeepSeek配置教程：settings.json三步跑通

不少开发者装好 Claude Code 满怀期待地启动，结果迎面就是报错——连不上、要登录、配置读不到。问题往往不在安装本身，而是卡在一个看似简单的文件：settings.json。

本文系统梳理 Claude Code 安装后的配置难题，提供模板化的解决方案，帮你三步跑通 DeepSeek、智谱、MiniMax 等国产大模型的接入。

Claude Code装好却跑不起来？问题出在settings.json

Claude Code 安装完成后，默认会尝试连接官方服务。但如果你想接入国产大模型（比如 DeepSeek V4、智谱、MiniMax），就需要通过 settings.json 告诉 Claude Code：别走默认服务，改为读取我们配置好的国产大模型接口。

与 GitHub Copilot 或 Cursor 等嵌入 IDE 的 AI 编程助手不同，Claude Code 是 Anthropic 推出的命令行原生工具，直接在终端中运行。它不依赖任何特定编辑器，而是通过命令行与整个项目代码库交互，具备读取文件、执行命令、修改代码等系统级能力。正因为它运行在终端层面而非编辑器插件层面，配置方式也更接近传统的命令行工具——通过独立的配置文件而非图形界面来管理连接参数。

这个文件的作用远不止普通的文本配置——它决定了 Claude Code 连接到哪个服务端、使用哪个 API Key、调用哪个模型。从技术原理上看，Claude Code 启动时会按照固定的优先级顺序扫描配置源：环境变量、用户级配置文件、项目级配置文件。settings.json 作为用户级配置文件，承担着 API 端点重定向的核心职责。当文件中指定了自定义的 apiBaseUrl 时，Claude Code 会将所有原本发往 Anthropic 官方 API（api.anthropic.com）的请求，转发到你指定的国产大模型网关地址。这本质上是一种 API 代理机制，利用了 OpenAI 兼容接口协议（OpenAI-compatible API）——该协议定义了统一的请求格式，如 /v1/chat/completions 端点、messages 数组结构、role/content 字段等，已经成为大模型行业的事实标准。路径、后缀、编码、符号，任何一个细节出错，Claude Code 就可能完全读不到配置，直接启动失败。

从大量用户反馈来看，绑大多数配置问题都集中在这个文件上。所以与其手把手教你从零写配置，不如直接提供经过验证的模板文件。

三步跑通：Claude Code接入DeepSeek等国产大模型

整个配置流程压缩到三步：

第一步：下载对应的settings.json模板

根据你要使用的模型，下载对应版本的 settings.json 模板。默认版本已配好 DeepSeek，想用智谱或 MiniMax 可以下载对应版本。

DeepSeek、智谱 GLM、MiniMax 等国产大模型之所以能被 Claude Code 调用，是因为它们的 API 接口都遵循了 OpenAI API 的通用规范。DeepSeek V4 是深度求索于 2025 年推出的旗舰模型，在代码生成和推理任务上表现突出；智谱 GLM 系列由清华技术团队打造，擅长中文理解和多轮对话；MiniMax 则在长上下文处理方面具有优势。选择哪个模型取决于你的具体使用场景和预算。

关键提醒：建议右键另存为下载文件，不要复制内容再粘贴到新文件中。 手动复制最容易引入隐藏字符和编码问题，这也是很多人 Claude Code 配置失败的根源。

第二步：填写你的API Key

打开下载好的模板文件，找到 API Key 字段，替换为你自己的密钥。这一步有一个极易踩坑的地方：JSON 文件里必须使用英文引号、英文冒号、英文逗号。 千万不要在中文输入法状态下编辑任何符号。

中文引号 “” 和英文引号 "" 肉眼看起来几乎一样，但程序完全不认中文符号。一个中文逗号就能让整个 JSON 解析失败。

第三步：放入.claude文件夹并重启Claude Code

将配置好的 settings.json 放入正确的目录：

C:\Users\你的用户名\.claude\settings.json

放好之后，在终端中按两次 Ctrl + C 退出当前进程，重新输入 claude 启动。如果一切配置正确，Claude Code 就能成功连接到 DeepSeek 等国产大模型了。

Claude Code配置失败？高频报错排查清单

如果跟着上面的步骤操作后仍然跑不起来，按以下顺序逐一排查。这些是社区反馈中出现频率最高的 Claude Code 报错问题：

排查一：文件名后缀是否正确

Windows 默认隐藏文件后缀名，这意味着你以为创建了 settings.json，实际文件名可能是 settings.json.txt。

解决方法： 打开文件资源管理器，点击「查看」→ 勾选「文件扩展名」，确认文件名确实是 settings.json 而不是带有双重后缀的版本。

排查二：settings.json目录路径是否放对

正确的路径是 C:\Users\你的用户名\.claude\。注意以下几点：

• 不是「下载」文件夹
• 不是桌面
• 不是项目目录
• .claude 是以点号开头的隐藏文件夹

如果该文件夹不存在，需要手动创建。在 Windows 中创建以点号开头的文件夹，可以在命令行中执行 mkdir .claude。

排查三：JSON符号是否被改坏

这是最隐蔽的问题。除了前面提到的中文符号外，手动新建文本文件写配置还可能遇到：

• BOM 头（Byte Order Mark）：BOM 是 Unicode 编码中用于标识文件编码方式的特殊字符（U+FEFF）。在 UTF-8 编码中，BOM 表现为文件开头的三个不可见字节：EF BB BF。Windows 自带的记事本（Notepad）在保存 UTF-8 文件时默认会插入 BOM 头，而大多数 JSON 解析器严格要求文件以 { 或 [ 开头，BOM 字符的存在会被解析器视为非法字符，直接抛出语法错误。这就是为什么用记事本编辑 settings.json 后经常出现「意外字符」报错的根本原因。推荐使用 VS Code、Notepad++ 等现代编辑器，它们默认以无 BOM 的 UTF-8 格式保存文件。
• 换行符差异：Windows 的 \r\n（CRLF）和 Unix/macOS 的 \n（LF）是两种不同的换行表示方式。CRLF 源自早期打字机时代的「回车+换行」操作，而现代类 Unix 系统只使用换行符。虽然大多数 JSON 解析器能兼容两种格式，但在极端情况下（特别是通过脚本处理配置文件时）可能引发问题。
• 多余的逗号：JSON 最后一个元素后面不能有逗号，这是新手常犯的语法错误。与 JavaScript 对象不同，JSON 规范（RFC 8259）对语法要求极为严格，不允许尾随逗号（trailing comma）。

这也是为什么强烈建议直接下载 settings.json 模板，而不是手写——模板文件已经规避了所有隐藏的编码和符号陷阱。

先跑通DeepSeek，再切换其他国产大模型

如果你刚开始接触 Claude Code 接入国产大模型，不要急着同时配置多个模型。先确保 DeepSeek 完全跑通，验证整个链路没有问题后，再尝试切换到智谱、MiniMax 等其他模型。

这里的「链路」指的是从 Claude Code 发出请求到收到模型响应的完整通路：Claude Code 客户端 → HTTPS 请求 → 模型 API 网关 → 模型推理服务 → 响应返回。任何一个环节出问题（网络、认证、模型名称、接口格式）都会导致调用失败。先用单一模型验证整条链路畅通，能帮你快速定位问题究竟出在本地配置还是远端服务。

切换方法也很简单：下载对应模型的 settings.json 模板文件，替换掉原来的文件，重启 Claude Code 即可。

Claude Code配置跑通之后学什么

配置跑通只是第一步。Claude Code 真正的价值在于它的实际编程能力：

• 读项目、改代码：让 Claude Code 理解你的代码库并进行修改。Claude Code 能够递归扫描项目目录结构，建立对整个代码库的上下文理解，然后根据自然语言指令精准定位需要修改的文件和代码段。
• 创建 SubAgent：构建专属的 AI 助手，处理特定领域的任务。SubAgent 是 Claude Code 中的高级功能，允许用户创建专门化的 AI 子代理。你可以将其理解为「AI 助手的助手」——主 Claude Code 实例可以将部分工作委派给预先配置好的 SubAgent，每个 SubAgent 拥有独立的系统提示词、工具权限和上下文范围。例如，你可以创建一个专门负责代码审查的 SubAgent、一个专门处理数据库操作的 SubAgent，以及一个专门编写测试用例的 SubAgent。这种分工模式借鉴了软件工程中的「关注点分离」原则，能显著提升复杂项目中 AI 辅助编程的效率和准确性。
• 完整项目实战：从零开始用 Claude Code 完成一个完整项目

建议按照「安装 → 配置 → 工作流 → SubAgent → 项目实战」的顺序循序渐进，不需要到处拼凑碎片化的教程。

配置问题看似琐碎，但它是所有后续操作的基础。把 settings.json 这一步走扎实了，后面的 Claude Code 学习曲线会平滑很多。

核心要点

• Claude Code安装后无法启动的核心原因是settings.json配置文件的路径、后缀、编码或符号出错
• 建议直接下载预制模板而非手写配置，可有效避免BOM隐藏字符、中文符号等常见问题
• 正确的配置路径为C:\Users\用户名.claude\settings.json，Windows隐藏后缀可能导致文件名实际为.json.txt
• JSON文件中必须使用英文引号、冒号和逗号，中文符号虽然肉眼难辨但程序完全无法识别
• 新手建议先跑通单个模型（推荐DeepSeek），验证链路正常后再尝试切换其他国产大模型