Claude Code 核心机制与 DeepSeek 接入实战

说实话我第一次看到 Claude Code 团队把自家写 CLAUDE.md 的套路、Skills 的目录结构、甚至 Workflows 里的思考等级配置都摊开在官方文档里讲的时候第一反应就是标题那句讲究啊这都往外说。这些通常被视为“工程内功”的东西很多团队巴不得藏深一点结果 Anthropic 的人不仅没藏着反倒把推荐做法的示例、目录约定、配置参数全部公开了。Claude Code 是什么简单说它是一个跑在终端里的 AI 编程助手。你可以把它理解成一个能把“读代码、改代码、跑命令、搜文件”这些脏活一肩挑的 Agent。它和 IDE 插件的思路不一样终端交互天然适合在服务器、容器、嵌入式工程这些环境里用也可以嵌入 VSCode、桌面对话流里。这篇文章不管你是刚听说这个名字、正在纠结安装还是已经装好但想让模型切换成 DeepSeek、想手搓 Skills 和 Workflows都可以直接照着下面的步骤走。我会把安装、配置、目录存放、第三方模型接入、常见报错这些实际踩过的点全部写出来省得你再去翻一堆零散文档。1. Claude Code 到底是什么手艺1.1 一个跑在终端里的 AI 编程搭子很多人第一次接触 Claude Code 会觉得这不就是把 ChatGPT 塞进终端吗其实差别还挺大的。它不是一个单纯的聊天窗口而是被设计成可以替你把活干完的执行体。你给它一个目标比如把这个模块的重构做完、查一下这个内存泄漏在哪它会自己去读代码、定位问题、写补丁、甚至跑测试来验证。平时大家用 IDE 插件核心是人在写AI 补全。Claude Code 反过来是AI 在写人做审阅。它会把每个动作拆成一个个工具调用比如Read、Edit、Bash、Grep而这些调用都会在终端里实时展示出来。这种透明感是它最讲究的地方你随时可以打断、纠正也更容易信任它做出来的改动。适合用它的场景也很有指向性。单人维护的仓库、需要快速熟悉陌生代码库、批量做跨文件重构、处理重复的脚手架工作——这些场景里它的效率优势非常明显。反过来如果你只是偶尔写几行脚本那可能用不上这么重的工具Web 界面随便聊两句反而更快。1.2 团队讲究在哪儿官方文档和公开实践的“含金量”Claude Code 团队最让我意外的是他们在文档里花了大量篇幅讲怎么使用而不是怎么显得厉害。比如 CLAUDE.md 到底该写什么Skills 要怎么组织Workflows 怎么设计思考深度怎么控制这些在很多团队里都属于口口相传的暗知识但官方直接给出最佳实践和可复用的框架。这种往外说的策略看着是吃亏其实特别聪明。工具本身的差异会越来越小但用户能不能把工具用好直接决定了忠诚度。你把底层机制讲透彻了用户就会用得越顺手越顺手就越离不开。而且社区学了这些方法也会反过来做更多高质量的 skill 和 workflow整个生态就被喂起来了。对于普通用户来说这件事最大的好处是我们不需要再从零摸索如何驯服一个 AI Agent。照着官方公开的套路抄作业大概率不会偏。接下来我会把几个核心机制挨个拆开讲先说安装再说配置最后讲实战和排坑。2. 安装与初始化十分钟跑起来2.1 三种安装路径CLI、桌面版和 VSCode 插件安装 Claude Code 有两条主流路径一个是命令行版一个是桌面版另外 VSCode 插件属于锦上添花。命令行版是核心底层就是 npm 包anthropic-ai/claude-code。前提是机器上有 Node.js建议版本 18 以上太低跑不起来。可以用node -v确认。然后直接执行npm install -g anthropic-ai/claude-code装完跑claude --version能输出版本号就说明成功了。如果你觉得 npm 源速度很慢可以先把 registry 指向国内镜像源比如npm config set registry https://registry.npmmirror.com再把装包命令执行一遍速度会快很多。这个操作只影响 npm 下载源不影响 Claude Code 后续连接到模型服务。桌面版和 VSCode 插件则适合不喜欢纯终端交互的人。桌面版官方是提供安装包的Windows 用户下载后一路下一步就能装好。VSCode 插件直接在扩展市场搜索 Claude Code 安装它会复用同一个登录态和配置目录。我个人的建议是日常用 CLI复杂排错时打开桌面版看可视化文件树两边互补。2.2 API 密钥与首次启动安装只是第一步真正启动还需要一个模型入口。如果你用的是 Anthropic 官方 API需要先准备一个 API Key然后设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxWindows PowerShell 里写法不同$env:ANTHROPIC_API_KEYsk-ant-xxxx设置完之后在项目根目录输入claude工具会先扫描目录然后提示你确认权限范围。第一次启动它会问你是否允许 Claude Code 读取和修改这个目录的文件建议先允许不然它只能看不能动用处大打折扣。如果你不想用官方 API而是想接 DeepSeek 这类第三方模型这步也要顺带把 base_url 改了。具体方式我在第四节单独讲因为这步有个经常踩的坑光改 base_url 不够模型名和鉴权方式也要一起改否则启动会报 401 或者找不到模型。2.3 卸载要留神有些朋友装完觉得不对味想卸载其实很简单npm uninstall -g anthropic-ai/claude-code但只跑这一条是卸不干净的。它会在用户目录下留一个.claude文件夹里面存着配置文件、历史会话、Skills、Workflows甚至登录态。如果确定不用了想清干净可以把这个目录删掉。Linux 和 macOS 上路径是~/.claudeWindows 上是C:\Users\你的用户名\.claude。删除前留个心眼如果里面有你辛辛苦苦写的 CLAUDE.md 和自定义 Skills先备份到别处。别问我怎么知道的我删过一次所有自定义技能灰飞烟灭。3. 核心机制CLAUDE.md、Skills 与 Workflows3.1 CLAUDE.md 是给 Agent 的“项目说明书”这是 Claude Code 团队公开的第一个大讲究每个项目根目录都应该有一个CLAUDE.md。这个文件会被 Agent 在每次启动时加载相当于它的长期记忆和项目说明书。和 README.md 不一样README 是写给人看的往往藏着大量上下文假设CLAUDE.md 是写给 AI 看的要极其直白。我平时写 CLAUDE.md 会尽量包含这几类内容项目是干什么的用了什么技术栈代码目录怎么组织哪个目录是入口常用的构建、测试、部署命令是什么编码风格约束比如不要用any、注释用中文还是英文哪些目录或文件不要乱动比如生成代码、锁文件举个例子一个简单的 CLAUDE.md 长这样# 项目说明 这是一个基于 FastAPI 的订单服务数据库使用 PostgreSQL。 # 命令 - 启动服务: uvicorn app.main:app --reload - 跑测试: pytest tests/ -q # 注意 - 所有数据库迁移文件集中在 migrations/ 目录 - 不要手工修改生成的 protobuf 文件别小看这几行它能让 AI 的行为从瞎猜变成有的放矢。和它聊天时模型会基于这个文件来做一切判断你不必每次都把项目背景重复一遍。很多初学者抱怨 Agent 回答跑偏其实根因往往是项目说明书没写好。3.2 Skills把 AI 的专业技能收进文件夹如果说 CLAUDE.md 是项目的长期记忆Skills 就是 AI 的专业工具箱。Claude Code 的 Skills 机制其实是官方公开的一种规范把一段带标题、描述、用法说明的指令放到一个固定目录里当模型觉得当前任务和某个 skill 匹配时就会自动加载这段内容来辅助工作。SKILL 的标准位置有两个项目级放在.claude/skills/技能名/SKILL.md用户级放在~/.claude/skills/技能名/SKILL.md。SKILL.md 的文件头是 YAML 格式的 frontmatter包含name和description正文就是具体的操作说明和示例。很多人问怎么手动安装 GitHub 上的 Skills其实完全不需要靠什么花哨工具文件复制就行。步骤我整理成如下git clone你想装的技能仓库到临时目录比如/tmp/my-skill找到仓库里的SKILL.md确认它是不是放在skills/技能名/SKILL.md这种层级里如果目录结构符合规范直接把整个技能名文件夹复制到项目的.claude/skills/下如果想让所有项目都能用这个技能就复制到~/.claude/skills/下重启 Claude Code 会话输入/skills查看技能是否被识别我遇到过最典型的失败原因是把仓库整个复制到.claude/根部导致SKILL.md不在预期路径下加载器报警。记住它找的是.claude/skills/技能名/SKILL.md这个层级一个都不能错。3.3 Workflows 与思考等级xhigh 该用在哪Workflows 是 Claude Code 为了应对复杂任务推出的一种模板机制。实操中如果你总是让 AI 干先调研、再设计、后编码、最后测试这类多阶段任务每次都手工描述流程太累而且容易遗漏。Workflow 可以把这套流程固化下来放在.claude/workflows/目录里用 YAML 描述步骤和注意事项。这个功能里有个被社区反复拿来讨论的就是思考等级配置有时候会听到xhigh这个词。简单理解思考等级决定了模型在该步骤上愿意花多少推理时间。high或者xhigh适合架构评审、疑难 bug 排查、代码审计这类需要深度推理的任务普通的增删改查就没必要拉高反而会明显增加响应时间和 token 消耗。所以我的建议是不要在全局把所有步骤都开成 xhigh而是只在你真正会觉得模型想得不够深的步骤上开高。比如一个 workflow 里有重构核心模块和跑测试两步我只会把重构核心模块的思考等级设为高跑测试保持默认。团队把这些配置公开就是希望用户按场景控制成本而不是一味追求更长的思考过程。4. 接入 DeepSeek把模型换着用4.1 为什么要折腾第三方模型Claude Code 默认连接的是 Anthropic 官方 API但这个工具并不强制绑定单一模型厂商。很多人出于成本考虑或者想换一种模型风格会选择把后端换成 DeepSeek。热词里出现频率很高的Claude Code 接入 DeepSeek就是这么来的。DeepSeek 提供开放平台 API本身是兼容多种调用格式的其中也提供了 Anthropic 兼容的接口地址这点很方便意味着你不需要在 Claude Code 和 DeepSeek 之间搭一个转换层只需要改几个环境变量就能把前端保留成 Claude Code、后端换成 DeepSeek。等于你用一个顺手的外壳接上了另一个模型的大脑。当然这种切换是有取舍的。DeepSeek 的成本确实低很多但在某些代码生成任务的细节遵循度上和官方模型还是存在差异。我的建议是日常开发和简单重构用 DeepSeek重要模块设计、跨文件大规模重构时切回官方模型。这就是为什么很多社区工具都强调切换能力而不是让你一条路走到黑。4.2 环境变量法接入 DeepSeek先说最简单的方法直接改环境变量。以 DeepSeek 为例需要设置三个内容API 地址、API Key、模型名。在 bash 或 zsh 里执行export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEY你DeepSeek的APIKey export ANTHROPIC_MODELdeepseek-chat第一条把 Claude Code 的 API 请求指向 DeepSeek 的 Anthropic 兼容端点第二条换成 DeepSeek 的密钥第三条告诉工具用哪个模型。如果想用 DeepSeek 的推理模型可以把deepseek-chat换成deepseek-reasoner。然后正常输入claude启动它就会通过 DeepSeek 接口做问答。第一次验证可以直接问11等于几不要废话能快速返回就说明通了。需要提醒的是每次新开终端都需要重新 export否则这些变量会失效。如果你嫌麻烦可以把这三行写进~/.bashrc或~/.zshrc里每次登录自动加载。也可以写进项目的.claude/settings.json用env字段固化这样团队成员拉下来项目就自动生效。4.3 用 ccswitch 做双模型切换环境变量法虽然简单但两个模型来回切的时候很痛苦每次都要重新 export。社区里针对这个问题出了不少工具ccswitch 就是其中之一。它的思路很简单在本地维护几套 模型预设切换时只需要执行一条命令它会把对应配置写回 Claude Code 的 settings 或 shell 环境。ccswitch 的典型用法是这样的先配置好两个预设一个走 DeepSeek 的deepseek-chat一个走官方 Anthropic 模型然后命令行执行ccswitch从菜单里选一个回车后就切换完毕。它会自动处理ANTHROPIC_BASE_URL和ANTHROPIC_MODEL这些变量的变更。我在使用时踩过一个坑ccswitch 改写的是本地全局 settings如果你同时开了多个终端窗口后一个终端的切换可能会覆盖前一个终端的配置。所以短时间切换模型时最好只保留一个活跃会话或者切完就重启终端。另外不同版本的工具参数格式略有差异安装后先ccswitch --help确认一下再动手。4.4 1M 上下文的使用心法热词里还有一个很显眼的1M 上下文。如果入口支持百万级上下文意味着它能一次性读完非常庞大的代码库。听起来很爽但我建议别真的把整个仓库全塞进去。上下文窗口越大首字响应越慢费用也越高。我处理大型工程时会先让它扫描目录结构、读入口文件再按模块逐步深入。这样既保留了对全局的理解又不会让无用的代码把宝贵的 token 全占了。长会话进行到一半如果明显感觉到速度变慢就说明历史记录里堆了太多内容这时候果断/clear清空对话另开一个会话接续效果远好过硬撑。5. 实战场景VSCode、STM32 与桌面端5.1 VSCode 里配置 Claude Code靠命令行吃遍天也是会腻的所以官方做了 VSCode 插件。安装之后在侧边栏或者命令面板输入 Claude Code 就能打开会话面板。它的好处是可以直接在编辑区域看到 AI 的 diff 建议点击应用比终端里的事件流直观很多。配置上VSCode 插件和 CLI 共用同一个.claude目录也就是说你在 CLI 里装的 Skills、Workflows在插件里同样可用。如果你之前用环境变量接入了 DeepSeek插件不一定能读到终端的环境变量需要检查一下插件设置里有没有env配置项。我一般会在项目根目录的.vscode/settings.json里显式指定好模型参数避免插件每次都走官方默认配置。另外有个操作习惯问题很多人在 VSCode 里直接让 AI 改生成器生成的代码。如果你用的是 CUBEMX 这类图形化配置工具生成的固件工程建议在 CLAUDE.md 里写明不要修改生成代码只改用户代码区否则一次顺手改动就能让下次重新生成时冲突得头疼。5.2 嵌入式项目STM32里怎么用STM32 相关热词看着和前端、后端开发距离很远但 Claude Code 在嵌入式场景里反而挺能打。拿实际项目举例它可以帮你读芯片参考手册里某段寄存器的描述生成对应的初始化代码也可以分析一个老的 Makefile 工程找出链接脚本里出错的符号定义。实操时我建议先做一步把整个工程的核心信息浓缩进 CLAUDE.md。比如芯片型号、HAL 库还是 LL 库、编译工具链命令、烧录方式。AI 对这些内容越清楚给出的代码越贴合实际不会给你生成一堆基于错误的库版本的函数。但有个红线要注意不要让 AI 直接去改CubeMX生成的.ioc文件和自动生成的初始化代码。.ioc是图形化工具的配置文件AI 很难保证在保留所有外设状态的前提下做修改一旦格式错了整个工程可能打不开。正确的姿势是让它写业务层的逻辑然后自己重新生成或手动核对初始化代码。5.3 桌面版与 CLI 的文件共享官方桌面版越来越多人讨论它比终端友好的地方在于有可视化的文件浏览、会话历史列表和设置面板。如果你已经用了一段时间 CLI桌面版装好后会发现自己的 Skills、Workflows、历史记录全都在因为它和 CLI 读写的是同一个用户目录。这里有个容易犯迷糊的点桌面版的设置里可能看不到 CLI 里用环境变量配的参数。比如你之前用 ccswitch 切到了 DeepSeek桌面版启动时会不会受影响从我自己的实测看桌面版会读取同一个 settings 文件所以配置是共享的但切换后必须完全退出并重启桌面版才能让新的模型配置生效。别在桌面版开着的时候切模型不然你会收到一堆莫名其妙的超时错误。6. 常见问题与排查技巧6.1 一张表看清高频报错实战中报错不可怕可怕的是不清楚错误在说什么。我把自己遇到过的高频问题整理成了一张速查表方便你直接对照。报错或现象常见原因解决思路unable to connect to anthropicAPI 地址配置错误或网络无法访问官方 API检查ANTHROPIC_BASE_URL是否写了第三方地址先清空再试确认本机可以访问api.anthropic.comclaude: command not foundnpm 全局目录没有加入 PATH重新安装或把 npm 的 bin 目录加到 PATH401 unauthorizedAPI Key 无效或用了第三方 key 却没改 base_url确认 key 所属服务商与 base_url 对应model not found模型名写错或当前 API 服务商没有这个模型列出支持模型列表比如 DeepSeek 用deepseek-chat/skills里看不到自定义技能SKILL.md 目录层级不对确认路径是.claude/skills/技能名/SKILL.md响应一次比一次慢上下文窗口堆入了太多历史/clear开新会话或者长任务分阶段处理这里要特别注意的是unable to connect并不一定是网络问题也可能是因为你之前给ANTHROPIC_BASE_URL设置过一个失效的第三方地址长时间没改动。遇到这类报错第一件事不是怀疑网络而是先检查设置里有没有残留的 base_url。6.2 跳过每次确认的正确姿势Claude Code 出于安全考虑每次修改文件都会弹一次确认这在批量重构时特别烦人。很多热词都在问怎么避开每次确认的动作其实官方有对应的权限模式。最简单的做法是启动时加上--permission-mode acceptEdits它会自动接受所有文件编辑类操作但对 Bash 命令执行依然会询问。如果想连命令确认也省掉可以用--dangerously-skip-permissions但我个人非常不建议在正式项目里这么玩尤其当 AI 在帮你执行 git 操作或者删除文件的时候。如果你只是想在脚本或 CI 里跑一次性任务更推荐用非交互模式claude -p 检查 todos 并输出重构方案这种模式执行完就退出不会陷入交互确认循环适合批处理链路。权限收得越紧事故概率越低这个习惯值得养成。6.3 配置文件到底存在哪很多问题最后都能追溯到配置文件找不到。Claude Code 的配置分全局和项目两层。全局配置在~/.claude/下里面有settings.json、CLAUDE.md、skills/、workflows/项目配置在项目根目录的.claude/下同样有settings.json和CLAUDE.md。这两层的关系是项目层优先。也就是说如果全局 CLAUDE.md 说用 CMake但项目层 CLAUDE.md 说用 MakefileAgent 会听项目层的。这个设计很合理避免全局规则污染不同项目。Windows 机器上全局路径在用户目录下和 Linux 一样都是隐藏文件夹资源管理器里看不到的话用路径直接访问即可。如果要在多台电脑之间同步 Skills 和工作流只需要同步~/.claude/里的skills/、workflows/和settings.json历史会话文件没必要同步否则文件会越来越大。我个人实际操作中越来越觉得Claude Code 团队这种讲究着往外说的做法其实藏着一种最聪明的产品观把工具的底牌交给用户用户就能玩出超出官方预期的花样最后反哺生态。你现在看完这些配置、切换和排错方法最好别攒着不用先拿一个小项目建好 CLAUDE.md再装一个你需要的 Skill切一次 DeepSeek 跑通全流程。只有亲手走一遍才会真正理解为什么这套东西值得被这么多人讨论。