如果你最近在 B 站刷到过 Claude Code 相关的视频大概率会和我一样遇到同一个问题视频里演示的都是“开箱即用”的顺畅流程但自己照着敲命令时总会在安装、登录、模型配置上卡住。尤其是你想把 DeepSeek 接到 Claude Code 里用的时候评论区最常见的回答就是“要加一个网关”至于网关怎么搭、环境变量怎么配、报错怎么查很少有人系统讲清楚。这篇文章会从零开始把 Claude Code 的安装、DeepSeek 接入、Skill 自定义到完整项目实战全部串起来。内容偏“保姆级”新手可以一步一步跟着做有经验的同学可以直接跳到第四章看模型接入部分。全文不涉及任何非官方渠道也不会引导你使用违规操作只围绕合法、合规、可落地的开发流程展开。1. 从零认识 Claude Code、DeepSeek 与 Skill1.1 Claude Code 到底是什么Claude Code 是 Anthropic 推出的一款终端原生 AI 编程代理工具。你可以在命令行中启动它让它读取项目文件、修改代码、执行终端命令、运行测试甚至帮你完成 Git 提交。与普通聊天式 AI 不同Claude Code 是一个真正的 Agent智能体。它不只是“给你一段代码让你自己复制”而是会主动拆解任务、读取相关文件、生成修改计划然后逐一执行。这种工作方式非常适合代码重构、单元测试补齐、旧项目逻辑梳理、批量文件修改等场景。举个例子你可以在项目根目录输入一行提示词让 Claude Code “找出所有没有异常处理的文件读取操作并修复”它会先扫描项目列出候选文件再逐个修改最后把改动汇总成 diff 给你确认。这比手动翻文件高效得多。1.2 为什么选择 DeepSeekDeepSeek 是国内团队开发的大语言模型API 使用 OpenAI 兼容协议中文理解能力强成本相对传统的海外模型 API 更低并且对国内开发者来说访问更稳定。因此很多中文开发者希望把 DeepSeek 作为 Claude Code 的底层模型来使用。但这里有一个关键限制Claude Code 原生请求的是 Anthropic 的 Messages API而 DeepSeek 官方提供的是 OpenAI Chat Completions 格式。两者不是同一个协议所以你不能直接把 DeepSeek 的 API Key 填进 Claude Code 就完事。要实现“Claude Code 外壳 DeepSeek 模型”的组合需要一个中转层把两种协议互相转换。这个中转层可以是开源自部署的网关服务也可以是企业内部已有的 AI 网关。1.3 Skill 让 AI 编程更进一步Claude Code 中的 Skill技能是一种可复用的能力包。你可以把某个标准操作流程写成一份 SKILL.md 文件让 Claude Code 在遇到对应场景时自动加载并执行。例如“代码审查 Skill”可以定义当用户提到“review”时按固定维度检查安全性、可读性、性能、测试覆盖并在指定目录下输出 markdown 审查报告。Skill 带来的最大价值是“流程统一”。团队里所有人使用同一套 SkillAI 的行为就会保持一致不会因为每个人 prompt 写法的差异而输出完全不同的结果。这也是很多团队把 Claude Code 从个人工具升级为团队工具的第一步。2. 环境准备与版本说明2.1 需要准备的工具在开始安装之前先确认本机是否具备以下基础环境。工具用途是否必须Node.js 18运行 Claude Code 安装脚本必须npm安装 anthropic-ai/claude-code必须Git配合 Claude Code 查看 diff、提交代码建议VS Code可选使用 Claude Code 编辑器集成可选DeepSeek API Key作为备用模型接入 Claude Code建议终端执行命令Windows 推荐 PowerShell 或 Git Bash必须需要注意Claude Code 仍然处于快速迭代状态功能、参数和默认行为可能随版本调整。本文以写作时的通用 beta 版本为例安装前建议先查看官方更新日志遇到差异时以你实际安装的版本为准。2.2 检查 Node.js 与 npm打开终端输入以下两条命令确认 Node.js 和 npm 已正确安装。node -v npm -v如果提示命令不存在需要先安装 Node.js。安装完成后node 和 npm 通常会一起生效。国内网络环境下npm 官方源下载速度可能不稳定推荐先切换到国内镜像源这一步不会影响后续任何功能。npm config set registry https://registry.npmmirror.com设置完成后可以再执行一次npm config get registry验证是否生效。镜像源不是必须的但能显著提高依赖包下载成功率。2.3 获取 DeepSeek API KeyDeepSeek 的 API Key 需要前往 DeepSeek 开放平台注册并创建。整个流程非常简单注册并登录 DeepSeek 开放平台。进入 API Keys 管理页面。点击创建 API Key复制保存。按平台要求完成账户充值API 调用按 token 计费。拿到 Key 后先自己存好不要粘贴到公开仓库、聊天记录或代码注释里。后面章节会演示如何安全地把它写入环境变量。3. Claude Code 安装与登录3.1 使用 npm 安装 Claude CodeClaude Code 的官方 npm 包名是anthropic-ai/claude-code。全局安装命令如下。npm install -g anthropic-ai/claude-code安装完成后检查版本。claude --version如果你看到类似x.y.z的版本号说明安装成功。如果安装过程报错常见原因是 npm 全局目录没有写入权限。macOS / Linux 环境下可以先尝试sudo npm install -g anthropic-ai/claude-codeWindows 环境下可以尝试用管理员身份重新打开 PowerShell 再执行。还有一类问题是 PATH 中没有包含 npm 全局目录导致claude命令无法识别。此时可以先运行npm config get prefix然后把输出的路径加入系统 PATH 环境变量重新打开终端即可。3.2 登录与 API Key 认证安装完成后直接在项目目录运行claude即可启动。首次启动时Claude Code 会引导你完成认证。目前主要有两种认证方式。第一种是登录 Claude 账号适合已经订阅了 Claude 会员服务的用户。进入交互界面后选择对应登录方式并按提示完成浏览器授权即可。第二种是使用 Anthropic API Key适合按 token 计费、或者希望通过网关接入其他模型的用户。你可以在当前 shell 中设置环境变量export ANTHROPIC_API_KEYsk-ant-你的API_KeyWindows PowerShell 下写法略有不同$env:ANTHROPIC_API_KEYsk-ant-你的API_Key需要注意API Key 会保存在当前会话中关闭终端后失效。如果希望长期生效可以写入 shell 配置文件但一定不要提交到 Git 仓库。3.3 验证 Claude Code 可用启动 Claude Code 后可以用/status命令查看当前登录状态、模型信息和上下文用量。如果一切正常输入一个简单问题试试你好请用一句话介绍当前项目目录。如果 Claude Code 正常回复说明安装和认证已经完成。Claude Code 是一个非常强大的 Agent它会在你授权下执行命令、修改文件。日常使用时我建议你对所有改动保持可见状态尽量在 Git 仓库内使用这样可以随时查看 diff。3.4 VSCode 与桌面版说明如果你习惯在 VS Code 中写代码可以在扩展市场搜索 Claude Code 官方扩展。安装后编辑器内可以通过快捷键或命令面板唤起 Claude Code 终端会话直接在编辑器侧边查看 AI 生成的内容。此外 Claude Code 还推出了桌面版应用提供了更图形化的操作界面。由于桌面版仍处于快速迭代阶段请务必从官方渠道获取安装包避免下载到来源不明的第三方修改版本。本文后续的演示将以命令行版本为主这样最通用也最容易排查问题。4. 将 DeepSeek 接入 Claude Code4.1 为什么不能直接切换模型Claude Code 默认通过 Anthropic 的 Messages API 与模型通信请求路径一般是/v1/messages。而 DeepSeek 提供的 API 是 OpenAI 兼容格式请求路径是/chat/completions。直接设置 DeepSeek 的 Key 会导致协议不匹配Claude Code 无法正常调用。因此接入 DeepSeek 的正确思路是在 Claude Code 和 DeepSeek API 之间增加一个“协议转换层”也就是常说的兼容网关。网关接收 Claude Code 发出的 Anthropic 格式请求将其转换为 DeepSeek 可以理解的 OpenAI 格式再把结果返回给 Claude Code。4.2 方案一基于开源网关自建转发层目前社区中已经有不少支持模型路由的开源项目比较典型的是 LiteLLM。这类网关通常支持配置多种模型供应商并对外提供一个统一的 Anthropic 兼容端点。部署好网关后在网关的模型映射表中把某个模型名指向 DeepSeek例如模型映射名: deepseek-chat 目标服务: https://api.deepseek.com然后在本地 shell 中设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_API_KEYsk-你的DeepSeek_API_Key启动 Claude Code 时指定模型名claude --model deepseek-chat以上localhost:4000只是示例实际端口和模型名以你部署的网关文档为准。使用网关时ANTHROPIC_API_KEY不一定要求是真实的 Anthropic Key因为网关会重写认证信息并将请求转发给 DeepSeek具体机制由网关实现决定。需要强调的是不同网关的安装方式、配置字段差异很大而且迭代速度很快我无法在这里给出一个“永远正确”的部署命令。建议以对应项目的官方 README 为准先跑通一个最简单的模型代理再逐步增加模型路由规则。4.3 方案二使用团队已有的兼容网关如果你所在的公司或团队已经搭建了统一的 AI 网关通常会由管理员提供一个base_url、一个api_key和一组可用模型名。这种情况下你不需要自己部署任何服务只需要把网关信息填入 Claude Code 的环境变量即可。这也是一种更工程化的方式网关层统一处理认证、计费、流量控制业务侧不需要关心底层用的是 DeepSeek 还是其他模型。唯一要确认的是网关是否提供了 Anthropic 兼容的/v1/messages端点因为 Claude Code 只认这个协议。4.4 先用 Python 快速验证 DeepSeek API在把 DeepSeek 接入 Claude Code 之前我建议先用 Python 直接调用一次 DeepSeek API确认 Key 有效、网络通畅、模型名正确。这样可以缩小排查范围避免后面出了问题分不清是网关配置问题还是 Key 问题。先安装 OpenAI Python SDKDeepSeek 官方支持通过它来调用。pip install openai然后新建一个test_deepseek.py文件。from openai import OpenAI client OpenAI( api_keysk-你的DeepSeek_API_Key, base_urlhttps://api.deepseek.com ) response client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个代码助手。}, {role: user, content: 请用 Python 写一个快速排序函数。}, ] ) print(response.choices[0].message.content)运行脚本python test_deepseek.py如果正常输出代码说明 DeepSeek Key 可用。模型名目前常见的是deepseek-chat和deepseek-reasoner具体名称以官网文档为准。这一步很有价值。通过独立验证你可以确认 DeepSeek API 本身没有问题剩下的问题大概率出在 Claude Code 与网关之间的配置上。5. Skill 机制与自定义技能实战5.1 Agent Skill 的核心概念Claude Code 的 Skill 机制本质上是把“固定的操作流程”和“可变的输入”分离。一个 Skill 通常存放在项目的.claude/skills目录下每个 Skill 是一个独立文件夹文件夹内必须有SKILL.md文件。SKILL.md的头部是 YAML frontmatter包含name和description字段。description尤其重要Claude Code 会根据它的内容判断什么时候自动调用这个 Skill。所以描述要写得具体包含触发关键词和适用场景。5.2 创建第一个代码审查 Skill下面我们创建一个“代码审查”Skill。项目结构如下。项目根目录/ └── .claude/ └── skills/ └── code-review/ └── SKILL.md创建.claude/skills/code-review/SKILL.md内容如下。--- name: code-review description: 审查 Python 或 JavaScript 代码输出结构化审查报告。当用户说“review”“审查代码”“检查代码质量”“帮我看下这段代码”时使用。 --- # Code Review Skill ## 触发条件 - 用户要求审查指定文件或目录 - 用户要求检查最近一次 Git 改动 - 用户要求分析代码中的安全风险、性能问题或可读性问题 ## 执行步骤 1. 确定审查范围单个文件、目录或 Git diff。 2. 按以下维度检查代码 - 正确性边界条件、空值处理、异常路径 - 安全性SQL 注入、敏感信息、文件权限 - 性能循环复杂度、IO 开销、重复计算 - 可维护性命名、函数长度、注释质量 - 测试关键分支是否有测试覆盖 3. 生成审查报告保存到 docs/review-YYYYMMDD.md。 4. 报告按“严重 / 建议 / 可选”三个等级排列每条给出文件路径、行号和建议。 ## 注意事项 - 如果用户只要求“快速看一下”可以只输出要点不生成报告文件。 - 审查结果要具体不要说“代码可以优化”这种空话必须说明哪里可以优化、为什么。创建之后在 Claude Code 会话中输入review 一下 src 目录下的代码Claude Code 会读取这个 Skill并按照SKILL.md中定义的流程执行。你不需要每次重新写一遍审查要求。5.3 用斜杠命令补充常用操作除了 SkillClaude Code 还支持自定义斜杠命令。斜杠命令适合封装那些需要用户主动触发、且不需要复杂上下文判断的任务。在.claude/commands目录下创建命令文件项目根目录/ └── .claude/ └── commands/ └── review.mdreview.md内容如下。--- description: 审查最近一次提交的代码变更 --- 请审查最近一次 git commit 涉及的代码变更重点分析可能导致 bug 或安全问题的修改并输出具体改进建议。保存后在 Claude Code 中直接输入/review就会执行“审查最近一次提交”的任务。斜杠命令适合高频、固定场景比如“生成 commit message”“清理未使用依赖”“补全 README”。Skill 和斜杠命令的区别在于Skill 更多是“按场景自动触发”斜杠命令则是“用户手动触发”。实际使用中两者可以搭配使用。6. 从需求到代码的完整实战6.1 定义需求为了演示完整流程我们做一个简单的 Python 待办事项命令行工具英文叫 TODO CLI。需求如下支持add添加任务支持list列出未完成任务支持done标记任务完成支持delete删除任务数据保存到本地 JSON 文件为关键函数编写单元测试这个需求足够小适合跑通“Claude Code 自动生成代码 自动测试 Skill 审查”的完整链路。6.2 用 Claude Code 生成项目新建一个项目目录并进入。mkdir todo-cli cd todo-cli git init在项目根目录启动 Claude Code。claude然后在会话中输入以下提示词。请帮我创建一个 Python 待办事项命令行工具 1. 支持 add、list、done、delete 四个子命令 2. 数据保存在 todos.json 文件中 3. 使用 argparse 解析命令行参数 4. 为 add、done、delete 编写单元测试 5. 代码风格清晰函数要有 docstring。Claude Code 会先给出执行计划然后开始创建文件。你需要观察它准备修改哪些文件并在它执行命令前确认授权。真实生成的文件名和代码可能因模型版本、上下文不同而有所差异。下面是一份整理后的可运行结果你可以直接复制保存。todo.py文件内容import argparse import json import os from datetime import datetime DATA_FILE os.path.join(os.path.dirname(os.path.abspath(__file__)), todos.json) def load_todos(): if not os.path.exists(DATA_FILE): return [] with open(DATA_FILE, r, encodingutf-8) as f: return json.load(f) def save_todos(todos): with open(DATA_FILE, w, encodingutf-8) as f: json.dump(todos, f, ensure_asciiFalse, indent2) def add_task(text): todos load_todos() task_id max([t[id] for t in todos], default0) 1 todos.append({ id: task_id, text: text, done: False, created_at: datetime.now().isoformat(timespecseconds), }) save_todos(todos) print(f已添加任务 {task_id}: {text}) def list_tasks(show_allFalse): todos load_todos() if not todos: print(暂无任务) return for t in todos: if not show_all and t[done]: continue status [x] if t[done] else [ ] print(f{status} {t[id]}: {t[text]}) def done_task(task_id): todos load_todos() for t in todos: if t[id] task_id: t[done] True save_todos(todos) print(f任务 {task_id} 已完成) return print(f未找到任务 {task_id}) def delete_task(task_id): todos load_todos() new_todos [t for t in todos if t[id] ! task_id] if len(new_todos) len(todos): print(f未找到任务 {task_id}) return save_todos(new_todos) print(f任务 {task_id} 已删除) def main(): parser argparse.ArgumentParser(description简单的待办事项命令行工具) subparsers parser.add_subparsers(destcommand, requiredTrue) add_parser subparsers.add_parser(add, help添加任务) add_parser.add_argument(text, help任务内容) subparsers.add_parser(list, help列出待办任务) done_parser subparsers.add_parser(done, help完成任务) done_parser.add_argument(task_id, typeint, help任务 ID) delete_parser subparsers.add_parser(delete, help删除任务) delete_parser.add_argument(task_id, typeint, help任务 ID) args parser.parse_args() if args.command add: add_task(args.text) elif args.command list: list_tasks() elif args.command done: done_task(args.task_id) elif args.command delete: delete_task(args.task_id) if __name__ __main__: main()test_todo.py文件内容import os import tempfile import unittest import todo class TestTodo(unittest.TestCase): def setUp(self): self.temp_dir tempfile.TemporaryDirectory() self.data_file os.path.join(self.temp_dir.name, todos.json) todo.DATA_FILE self.data_file def tearDown(self): self.temp_dir.cleanup() def test_add_and_list(self): todo.add_task(写文章) todos todo.load_todos() self.assertEqual(len(todos), 1) self.assertEqual(todos[0][text], 写文章) self.assertFalse(todos[0][done]) def test_done_task(self): todo.add_task(准备示例) todo.done_task(1) todos todo.load_todos() self.assertTrue(todos[0][done]) def test_delete_task(self): todo.add_task(临时任务) todo.delete_task(1) self.assertEqual(todo.load_todos(), []) if __name__ __main__: unittest.main()需要说明的是上面的代码有意识地使用固定文件路径便于测试时通过修改todo.DATA_FILE来隔离数据。如果你希望代码更工程化可以把DATA_FILE设计成可注入参数。6.3 运行与验证先添加两个任务测试功能python todo.py add 学习 Claude Code python todo.py add 学习 DeepSeek API查看任务列表python todo.py list预期输出[ ] 1: 学习 Claude Code [ ] 2: 学习 DeepSeek API标记第一个任务完成python todo.py done 1 python todo.py list预期输出[ ] 2: 学习 DeepSeek API最后运行单元测试python -m unittest test_todo -v如果三个测试全部通过说明功能符合预期。6.4 让代码审查 Skill 参与进来项目已经可以运行但我们需要检查代码质量。在 Claude Code 会话中输入review 当前项目的 todo.py如果你的.claude/skills/code-review/SKILL.md已经创建Claude Code 会自动加载对应的审查 Skill按照既定格式输出审查报告。审查结果可能包括这些建议add_task函数中任务 ID 直接取最大值加一删除任务后可能出现 ID 复用建议改为自增计数器或使用 UUID。list_tasks没有实现--all参数的解析。当DATA_FILE目录不存在时save_todos会报错建议写入前自动创建父目录。测试用例覆盖了主流程但没有测试“任务不存在时执行 done/delete”的边界行为。这些建议是不是合理需要你结合项目目标来判断。Claude Code 给出的代码建议不一定全都要采纳但它能帮你在提交之前发现很多容易忽略的边界问题。7. 常见问题与排查思路7.1 高频问题速查表问题现象常见原因解决思路npm 安装失败网络不稳定或源码下载慢切换 npmmirror 镜像源后重试claude 命令无法识别npm 全局目录不在 PATH 中执行npm config get prefix并加入 PATH安装时权限不足npm 全局目录无写入权限macOS/Linux 使用 sudoWindows 使用管理员终端启动后一直无法登录认证域名不可达或网络策略限制检查网络策略改为使用 API Key 认证请求返回 401API Key 无效或环境变量拼写错误重新生成 Key检查变量名和空格返回 model not found网关模型映射名不对查看网关支持的模型列表核对--model参数DeepSeek 请求超时网络延迟或服务限流使用test_deepseek.py独立测试确认服务可用中文输出乱码终端编码不是 UTF-8Windows 终端切换到 UTF-8 编码7.2 典型排查示例401 Unauthorized如果 Claude Code 返回401 Unauthorized先不要急着怀疑 Key 失效。按以下顺序排查echo $ANTHROPIC_API_KEY确认变量是否为空、是否包含多余空格、前缀是否完整。如果使用了.env文件确认是否正确加载。如果使用网关确认网关侧是否启用了独立 Key 校验。大多数 401 问题都出在环境变量没有正确传递或者复制 Key 时少了几个字符。7.3 典型排查示例model not found如果你接入网关后看到model not found或Unknown model说明 Claude Code 发送的模型名不在网关授权列表里。排查方法查看网关的模型列表确认可用模型名。检查启动命令中的--model是否与网关模型名完全一致。如果网关要求模型名写成provider/model的格式例如deepseek/deepseek-chat请按网关约定调整。不要自己猜测模型名不同网关的命名规则差别很大。8. 最佳实践与工程建议8.1 API Key 与敏感信息管理API Key 是最高优先级的敏感信息。无论你是使用 Anthropic 官方 Key还是 DeepSeek API Key都应该遵守以下原则不要写入 Git 仓库。不要写死在代码文件里。不要截图发到公开群聊。推荐做法是在项目根目录创建.env文件并在.gitignore中加入.env。启动 Claude Code 之前用export命令或工具加载环境变量。团队环境下可以使用密钥管理服务统一分配和轮换。8.2 项目级记忆 CLAUDE.mdClaude Code 会自动读取项目根目录下的CLAUDE.md文件把它作为项目级上下文。这个文件非常适合沉淀团队约定。示例内容# CLAUDE.md ## 项目规范 - 使用 Python 3.10 - 代码风格遵循 PEP 8 - 所有函数必须有 docstring - 不要修改 data/ 目录下的原始数据 ## 常用命令 - 运行测试python -m unittest discover -v - 启动服务python app.py有了CLAUDE.md每次启动 Claude Code 时它都能快速了解项目背景和规范减少重复说明。8.3 成本、安全与协作建议成本方面使用 DeepSeek 这类价格相对较低的模型可以明显降低日常 AI 编程开销。但在团队环境里我建议通过网关做统一的配额和限额避免某个任务异常产生大量 token 消耗。同时可以在 Claude Code 中通过/status查看当前会话的 token 使用情况。安全方面Claude Code 有执行命令的能力这既是优势也是风险。首次使用或面对不熟悉的项目时不要让 Claude Code 直接跳过所有确认环节。生产环境的修改、删除操作必须经过 review 和授权。不要尝试使用任何破解版、修改版工具也不要使用试图绕过模型安全机制的提示词这不仅不稳定还违反服务提供方的使用条款。协作方面.claude/skills和CLAUDE.md这类配置应该纳入版本管理。这样团队新成员克隆仓库后就能获得相同的 AI 协作规范。注意把.env、日志文件和数据文件排除在版本管理之外。9. 总结与下一步学习建议这篇文章介绍了 Claude Code 的安装、DeepSeek 的接入思路、Skill 的编写方法并完成了一个 TODO CLI 的实战项目。你现在应该掌握了以下关键点Claude Code 是一个终端原生的 AI 编程代理适合代码生成、重构、审查类任务。DeepSeek 需要依赖兼容网关才能接入 Claude Code核心是解决 Anthropic 和 OpenAI 协议之间的转换。Skill 和斜杠命令是沉淀团队流程的重要手段应该从小的场景开始逐步扩展。API Key、CLAUDE.md、审查报告等工程规范决定了工具能否长期稳定使用。如果你打算在团队里推行这套工作流我的建议是不要一上来就写很多复杂的 Skill。先从一个代码审查 Skill 开始跑通之后再补充测试生成、提交信息生成、CI 检查等场景。每增加一个 Skill都是一次流程固化但也需要持续维护否则它会慢慢失效。下一步可以深入研究 Claude Code 官方文档中关于 model 配置、hooks、权限控制的章节或者对比一下 DeepSeek 官方文档中不同模型参数的区别。AI 编程工具迭代非常快保持阅读官方更新日志比到处找过时教程更有效。如果这篇文章对你有帮助可以收藏备用。实际使用中遇到其他问题也欢迎按文中的排查思路先定位再提问这样解决问题的效率会高很多。