如果你最近在逛技术社区或者刷 GitHub应该已经被 Claude Code 刷屏了。有人拿它一口气跨二十个文件做重构有人还在跟第一个会话的启动报错搏斗。我一开始也以为这又是一个“AI 聊天套壳”真正上手之后才发现完全不是一回事——它不是陪你聊天的窗口而是直接住进你终端里的结对程序员。这篇文章不打算复读官方文档而是把从“Claude Code 是什么”到“安装部署”、“日常高频操作”、“接入 DeepSeek”、“扩展 Skills”再到各种连接失败、卸载重装踩坑的完整路线一次性写清楚。不管你是刚听说这个名字的小白还是已经在用但想换模型、加自定义技能的老手都能在这个实操清单里找到能直接抄作业的部分。我会尽量说人话该上命令上命令该放文件放文件顺便把那些官方文档里不会写的判断逻辑和坑位也一并交代。1. 先搞清楚 Claude Code 是什么它不是聊天窗口而是住在终端里的“结对程序员”1.1 与聊天式 AI 的本质区别很多人第一次打开 Claude Code 时都会犯同一个错把它当成 ChatGPT 或者网页版 Claude 的命令行版问一句答一句。实际用上十分钟你就会发现这东西的工作方式完全不同。它是一个以任务为中心的 agent也就是说你给它一个目标——比如“把项目里所有 console.log 统一替换成统一的 logger 调用”——它不只是给你写一段建议代码而是会自己去扫描文件、列出改动清单、挨个编辑、再尝试运行验证。我第一次感受到这种差异是在一个 React 项目里。项目里有十几个文件散落着调试日志手动改大概要半小时。我只是在会话里说了一句“把 console 调试输出全部改成 Logger.info并补齐上下文参数”它就开始自动列出它找到的文件逐一修改然后问我是否要运行测试来验证。那种感觉就像一个熟悉项目的老同事坐在旁边干活而不是一个只会出主意的嘴强王者。从根本上说Claude Code 的定位是命令行 AI 编程代理。它允许模型访问你的文件系统、执行终端命令、读取运行结果再根据结果决定下一步动作。这个“执行命令并读结果”的闭环是它和普通聊天 AI 之间最核心的分水岭。ChatGPT 给你的代码是静态的建议需要你手动复制、粘贴、运行、再报错给它听Claude Code 则是自己动手干完了还会告诉你结果。1.2 “note: claude code might not be available...” 到底是什么意思安装完成后第一次运行claude你可能会在欢迎语附近看到类似 “note: claude code might not be available in your country. check supported co...” 的提示。很多初学者看到这句话就慌了以为安装包坏了或者自己的环境有问题。先说结论这句话不是报错只是官方在告知你该服务有支持的地区范围。它是一个提示性质的信息不代表你的 CLI 安装失败也不代表当前环境一定不可用。真正决定是否可用的是你的账户状态、网络环境以及所在地区。遇到这种情况正确做法是去查官网的支持范围清单确认自己是否符合使用条件同时严格遵循当地法律法规与 Anthropic 的服务条款。不要在明知不符合条件的情况下去想方设法绕开限制这既不安全也不是一个合格开发者的做法。我个人对这类提示的态度是把它当成一个“体检提醒”而不是“死亡判决”。先继续把 API Key 配好再跑一次/status看真实的连接状态很多时候只是虚惊一场。2. 安装这一步就不简单Windows、Ubuntu、VSCode、桌面版一次说清2.1 npm 安装的最稳路径Claude Code 目前的主流安装方式是通过 npm 分发包名是anthropic-ai/claude-code。只要你的机器上有 Node.js 环境安装过程就是一条命令的事npm install -g anthropic-ai/claude-code不过我见过太多人卡在更前面的环节——Node.js 版本太老。Claude Code 对 Node 版本有一定要求如果版本过低安装时会出现各种奇怪的依赖报错。建议先确认一下node -v如果远低于要求先去 Node 官网或者在 Linux 上用 nvm 装一个新版再回来跑 npm 安装。装完以后用下面的命令验证是否成功claude --version只要能看到版本号说明核心程序已经跑起来了。如果显示claude: command not found多半是全球安装目录没在 PATH 里Windows 下常见于 npm 全局目录没加到系统环境变量Ubuntu 下则可能是用了 sudo 安装但当前用户无权限访问。这两种情况都不难解决把 npm 的 global bin 目录加进 PATH 即可。还需要说明的是npm 源如果下载缓慢或超时可以换成更快的 registry。这里我分享一个常规做法——检查并调整 npm 的 registry 配置npm config get registry如果确实很慢可以考虑使用 npm 官方源所在区域附近的可用端点或者在企业内网使用内部 npm 镜像仓库。这个话题展开讲可以写一篇长文这里只提醒一句检查连通性而不是反复重试同一个源。2.2 Windows 和 Ubuntu 安装的典型差异Windows 上最容易踩的坑不是安装本身而是 PowerShell 的执行策略。安装完 Claude Code 之后第一次在 PowerShell 里敲claude如果你看到类似“无法加载文件因为在此系统上禁止运行脚本”的提示那是 PowerShell 默认禁止执行 npm 生成的脚本。一个常见的做法是以管理员身份执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这是 Windows 上允许本地脚本运行的常规配置改完以后重新打开终端即可。要注意的是任何执行策略的调整都应当在理解其含义的前提下进行不要为了快而盲目关闭系统防护。Ubuntu 上的坑则更多集中在权限方面。如果你用sudo npm install -g装了包之后用普通用户运行claude可能会因为全局目录权限问题报 EACCES。解决思路有两个要么用sudo执行命令要么调整 npm 的全局目录权限。我更推荐后者因为日常使用不可能每次都加sudo。2.3 VSCode 配置和桌面版的选择VSCode 用户最舒服的用法不是装一堆插件而是直接在集成终端里跑claude。这样 AI 会话就在你的编辑器下方选中的代码可以直接粘贴进会话AI 的改动也能实时看到。你不需要任何额外扩展只需要一个干净的终端面板。我知道热词里有人在找“vscode配置claude code”和“claude code桌面版”所以这里多说两句。官方已经在推进带图形界面的桌面版核心引擎和 CLI 是一样的相当于给命令行套上了一个更友好的外壳。但我的个人体验是对于 VSCode 使用者来说集成终端方案已经足够顺滑桌面版更适合那些完全不习惯命令行的用户。至于国内下载桌面版的问题本质上取决于网络环境是否合规、能否正常访问官方分发渠道以及你的账号是否符合服务条款。遇到下载慢或者失败请先按常规网络连通性排查来处理不要试图通过任何不合规手段绕过限制。安装完之后Claude Code 会在你的用户目录下创建一个.claude配置目录。它会存放全局配置、Skills、历史会话数据等信息。知道这个目录在哪里非常重要后面讲备份和卸载时还会用到。Windows 一般在C:\Users\你的用户名\.claudemacOS 和 Linux 在~/.claude。3. 高频操作手册从进场到交代码的完整闭环3.1 启动、会话、恢复与清理安装完成后进入任何一个项目目录直接输入claude它会把当前目录作为工作区加载读取项目根目录下的CLAUDE.md如果有的话然后进入对话交互界面。如果上一个会话因为终端关闭而中断可以用claude --continue恢复最近的会话上下文这个功能在多任务并行时非常有用。会话过程中最常用的斜杠命令我整理成了一张表建议保存下来随时查阅命令作用使用场景/help查看内置帮助和可用命令不确定某个功能时先用它/clear清空当前会话上下文话题切换、上下文太乱/compact压缩当前会话上下文上下文快用完但不想丢信息/init生成项目级 CLAUDE.md第一次进入项目时/config打开配置文件调整权限、模型、环境变量/status查看账号、模型与连接状态排查连接问题很多新手分不清/clear和/compact的区别。/clear就是一刀切把当前上下文全部清空适合换一个完全无关的新任务/compact则更像“总结一下刚才聊了什么然后基于总结继续”适合处理同一个项目但上下文已经接近上限的情况。我的习惯是只要发现它开始“忘记”早期对话里的要求就先/compact而不是直接/clear因为后者会把任务背景也一并丢掉。3.2 让模型按你的节奏思考调整思考等级并配合 Workflows热词列表里有一条很有意思“claude code调整思考等级命令xhigh workflows”。这说明很多人在关注如何控制 Claude Code 的“思考深度”。简单来说思考等级决定模型在回答前愿意投入多少计算资源。等级越高推理越细致但响应越慢、消耗也越大等级低则速度快、成本低但复杂任务容易出错。不同版本的 Claude Code 对思考等级的参数写法会有差异有的版本会提供类似--thinking的参数后面可以接low、medium、high、xhigh这样的档位也有的版本是在/config里做默认设置。我的建议是先跑一下/help看看当前版本支持哪种写法然后按任务类型灵活选择简单 CRUD 代码用低档涉及多文件重构或者疑难 bug 用高档。不要一上来无脑拉满xhigh那样既慢又费钱。Workflows 则是把一系列固定动作固化成一条可重复执行的流程。比如你希望每次提交代码前让 AI 先跑一遍 lint、再检查单元测试、最后生成一个规范化的 commit message——这就可以做成一个 workflow。它的配置文件通常放在项目的.claude/workflows/目录下全局的放在~/.claude/workflows/目录下。为什么我要强调“思考等级 workflows”的组合因为实际项目中真正能提高效率的不是某一次对话而是把“标准动作”沉淀成流程。当思考等级和 workflow 配合起来你就是把自己的经验编码成了自动化流程这才是 Claude Code 这类工具最大的杠杆点。3.3 上下文管理1M 上下文与 Prompt Caching老版本的用户可能被“上下文窗口不够”折磨过。会话聊到一半模型开始遗忘最初的指令或者直接提示 context length exceeded。现在 Claude Code 已经支持更长的上下文选项热词里的“claude code 1m上下文”指的就是这类能力。不过我要泼一盆冷水上下文越长单次调用的成本和延迟越高而且模型并不总能充分利用超长上下文。日常开发中几百 KB 的窗口已经足够应对绝大多数项目真正的瓶颈往往不是窗口大小而是你有没有把关键信息写进CLAUDE.md。另外一个热词很值得聊claude code export enable_prompt_caching_1h1 这个配置有用吗。这是启用了 1 小时 Prompt Caching 的开关。缓存的作用是当你在同一个会话里反复调用模型时系统会把前面对话的固定前缀系统提示、项目背景、历史摘要缓存起来重复使用时不再重新计算从而降低费用并减少等待时间。实测下来这个配置在“长会话 多次请求”的场景下收益非常明显。我之前在一个大型重构会话里每次请求都要带上整个项目背景和前面的讨论摘要开启缓存后后续调用的速度和费用都有可感知的优化。但如果你是短会话、单次提问的轻度用户这个配置的作用就不明显——因为缓存还没来得及命中会话就结束了。所以答案不是简单的“有用”或“没用”而是“高重复性任务场景下非常有用”。4. 换引擎把 Claude Code 接到 DeepSeek 的完整配置流程4.1 为什么要做这件事很多人看到“Claude Code 接入 DeepSeek”时都会问一句为什么要换据我所知原因无非几类第一是预算因素DeepSeek 的调用成本通常比这个模型亲民第二是可用性因素某些环境下官方 API 的接入条件不满足而 DeepSeek 的开放平台更容易满足第三就是个人偏好有些任务简单直接不需要动用顶级模型。但这里有一个原则必须说在前头无论接入哪个模型服务商都要遵守 Claude Code 的条款、目标模型服务商的条款以及你所在地的法律法规。技术是无罪的但工具的使用必须合规。我在这里只是把配置方法和原理讲清楚具体能不能用、该不该用请结合你自己的实际情况判断。4.2 环境变量三板斧DeepSeek 提供了 Anthropic 兼容的 API 端点这才是能接入 Claude Code 的关键。Claude Code 本身不会在意后端是不是 Anthropic 官方它只是按照 Anthropic 的协议把请求发出去了。因此接入其他兼容服务商的思路就是重定向两个东西API 地址和身份令牌。具体配置三个环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 export ANTHROPIC_MODELdeepseek-chatANTHROPIC_BASE_URL把请求的目标地址从 Anthropic 官方指向 DeepSeek 的兼容端点ANTHROPIC_AUTH_TOKEN让 Claude Code 用你的 DeepSeek 身份去鉴权ANTHROPIC_MODEL指定实际使用的模型名。这里有个很容易搞混的点ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN在某些版本里等价某些版本里侧重不同。我自己在做演示时一般用ANTHROPIC_AUTH_TOKEN但如果你在/status里看到鉴权失败可以两个变量都检查一遍。地址和模型名方面不同版本之间可能会有变化建议始终以对应服务商的官方文档为准我记录的这些只是我在实践过程中使用的配置。配置完成后进入交互模式claude在会话里输入/status看看显示的模型名是不是你期望的。如果看到连接失败不要急着怀疑配置先检查ANTHROPIC_BASE_URL末尾的路径是否正确很多兼容端点对路径非常敏感。4.3 接入之后容易踩的坑我接入 DeepSeek 后踩过的第一个坑是模型名不对导致请求直接 404。Claude Code 默认会按 Anthropic 官方模型名发请求如果你没有显式设置ANTHROPIC_MODEL兼容端点收到一个认识不了的模型名就会报错。所以“换模型 改地址 改令牌”三件事必须一起做漏一个都会失败。第二个坑是上下文长度。不同模型的上下文窗口差异很大有的远达不到 Claude 原生长上下文的水准。我在迁移一个大型项目时试图把整个仓库详情直接塞进对话结果触发了长度限制。解决办法是回到现实对模型不熟悉的项目先把关键文件加入上下文而不是一股脑全塞进去。第三个坑是工具调用格式的兼容性。Claude Code 依赖模型按照特定格式返回工具调用指令而 DeepSeek 对 Anthropic 兼容协议的支持力度可能不像原生模型那么完整。实际使用中偶尔会遇到“模型给出建议但无法正确执行工具调用”的情况。遇到这种问题先把复杂任务拆小再观察具体哪一步不兼容而不是反复重试同一句话。关于热词里提到的 ccswitch这是一个社区里常见的快速切换配置的小工具方便在 DeepSeek 的不同模型之间切换。我自己的习惯是没有用这类工具而是直接把几个环境变量的导出写成 shell 函数存进~/.bashrc或~/.zshrc需要切换时一行命令搞定。这样所有行为都是可见、可控制的排查问题时也更简单。5. 给 Claude Code 加技能从零手装 GitHub 上的 Skills5.1 Skills 的目录结构与 SKILL.md 文件如果你希望 Claude Code 在某些场景下有更专业的表现或者掌握一些通用提示词之外的私有工作流就需要了解 Skills 机制。简单来说一个 Skill 就是一个目录里面放一个SKILL.md文件外加必要的脚本或参考资料。Claude Code 在合适的时机自动加载匹配的 Skill从而“切换”到对应的专家模式。Skills 放置的位置有两个全局目录~/.claude/skills/技能名/SKILL.md以及项目目录.claude/skills/技能名/SKILL.md。全局目录对所有项目生效适合放通用技能项目目录只在当前项目生效适合放团队定制流程。SKILL.md的格式要点是头部用 YAML frontmatter 写元信息然后正文写详细的执行说明。一个最小示例--- name: commit-scribe description: 根据 git diff 生成符合规范的 commit message --- 当你被要求生成 commit message 时先运行 git diff --staged 再根据 Conventional Commits 规范输出标题和正文。YAML 里的name是技能名description是最关键的部分——Claude Code 就是靠描述来判断“什么时候该激活这个技能”的。所以保存的 skill 描述要尽量具体说明触发条件和使用场景不要写得太笼统。5.2 手动安装 GitHub 上第三方 Skills 的步骤热词里有“claude code怎么手动装github上的skills”这个问题实际上很直白。GitHub 上有大量社区维护的 Skills 仓库手动安装流程大致是克隆对应仓库到本地git clone 仓库地址在仓库中找到包含SKILL.md的技能目录把整个技能目录复制到~/.claude/skills/或你当前项目的.claude/skills/重新启动一个 Claude Code 会话让技能被扫描加载在会话里用相关描述触发或等待 Claude Code 自动匹配举个例子假设你想安装一个“代码审查专家”技能。克隆仓库后你大概率会在仓库里看到code-review/SKILL.md这样的目录结构那么你就把code-review这个文件夹放进~/.claude/skills/重新启动会话即可。之后当它在项目里执行代码审查类任务时会自动读取 SKILL.md 里的规则。这里有一个非常重要的安全提醒第三方 Skills 可能包含脚本或命令尤其是那些声称“自动执行”的技能。装任何新技能之前先打开SKILL.md通读一遍看看它让模型执行的命令到底做什么。这不是不信任社区而是最基本的供应链安全意识。我自己在试用第三方技能时都会先在一个不敏感的测试项目里跑一遍确认没有危险行为才会在真实项目中使用。5.3 我实际在用的两个技能方向我个人目前最常用的两个技能完全可以自己手写不需要依赖第三方。第一个是代码审查规则把团队约定写进 SKILL.md包括命名规范、禁止全局变量、测试覆盖要求等。当 Claude Code 做代码审查时就按团队标准来而不是按模型自己的“习惯”来。第二个是数据库迁移检查让模型在改数据表之前确认是否有备份脚本、是否评估了存量数据的影响。这两个方向都是门槛不高但收益很大的场景。写任何 Skill 时记住一句话它就是一份“给 AI 看的岗位说明书”。你写描述越具体AI 越能在正确的时机调用你把步骤列得越清晰AI 执行越稳定。与其花时间到处找第三方技能不如先把自己团队最痛的流程写成一个 20 行的 SKILL.md。6. 踩坑合集连接失败、存储位置、卸载干净6.1 连接失败先排查环境而不是重装在论坛上看到最多的一个场景是这样的用npm install -g anthropic-ai/claude-code装好了敲claude后却看到欢迎语和一个unable to connect to an...的提示。很多人一看到“unable to connect”就开始重装事实上这是一个典型的“环境问题”重装没有任何作用。正确排查顺序如下首先确认版本正常claude --version。如果版本都出不来说明安装问题回到第二部分解决如果版本正常在会话里输入/status看鉴权和连接状态。重点检查环境变量有没有设置比如ANTHROPIC_BASE_URL或者ANTHROPIC_API_KEY然后再用 curl 之类工具测试到目标 API 的网络连通性。网络连通性问题通常是和官方服务之间的链路、账号所属区域、或者网络环境因素有关请务必结合合规条件来处理。这一整条链路查下来90% 的连接问题都能定位。剩下的 10% 才可能是登录态过期或者服务端问题这时可以考虑重启会话、检查版本更新或查阅官方的系统状态页面。6.2 存储位置、日志与备份使用一段时间后你会积累不少有价值的配置和会话数据。很多人从来没想过备份这些事情直到系统重装才追悔莫及。Claude Code 的主要数据存储位置包括全局配置文件~/.claude.json存放认证状态、全局设置全局配置目录~/.claude/存放 skills、workflows、部分缓存与日志项目配置目录.claude/存放项目级 CLAUDE.md、skills、workflows。换电脑或者重装系统前把~/.claude目录和项目里的.claude目录一起备份就够了。实际迁移时我甚至会把~/.claude里的 skills 目录直接打包到新环境的同一位置这样之前精心调的规则全部原样可用非常省事。6.3 从彻底卸载到干净重装很多人“卸载”Claude Code 的方式是只跑一条npm uninstall -g anthropic-ai/claude-code实际上并不彻底。如果你确认不再使用最稳妥的做法分三步npm uninstall -g anthropic-ai/claude-code然后备份需要保留的配置再清理用户目录里的残留数据rm -rf ~/.claude rm -f ~/.claude.jsonWindows 用户还要注意 npm 全局目录下可能有缓存残留建议一并清除 npm 缓存。如果你卸载后又重新安装遇到奇怪的 EEXIST 或 EACCES 错误多半是残留配置文件导致的。先清理再重装问题基本都能解决。还有一个容易误判的情况明明执行了卸载命令claude命令却仍然存在。这通常是因为你之前是通过npx anthropic-ai/claude-code方式使用的npx 缓存里的包还在。这时候不需要恐慌清理 npx 缓存中对应的包即可。最后再说几句私房话我实际用下来最深刻的体会是Claude Code 这类工具的能力上限很大程度上取决于你给它写的信息质量。很多人抱怨“AI 写代码不给力”其实是连一份像样的 CLAUDE.md 都没写过。不要把它当成一个通用的问答机器人而要把它当成一个能力很强但对你项目一无所知的实习生。你给它写的项目背景越充分你的指令越像“给同事布置任务”而不是“跟搜索引擎说话”它的表现就越惊人。另外一个非常实用的小技巧第一次进入大型项目时先花 15 分钟跑一遍/init让模型生成一份项目文档然后你自己动手补充项目里真正重要的潜规则——比如哪块代码是历史遗留不能大动哪个目录是自动生成的不要改。这些上下文信息比你在对话里反复强调一百遍都管用。工具会越来越强但能不能让它真正成为你的生产力关键还是取决于你怎么用它。