如果你最近逛技术社区肯定见过一个词频繁刷屏claude code。无论你是写业务代码的、折腾 AI 工具的、还是想用自然语言批量处理文件的人这个工具几乎成了终端里的 AI 程序员代名词。它不需要你开 IDE不需要复制粘贴代码到网页对话框而是在你项目的根目录里直接和你对话读代码、改文件、跑命令、调 bug一条龙干完。今天这篇不完全使用指南我基于自己的实际体验把从安装到配置、从接第三方模型到写自定义技能的全过程拆开讲一遍尽量让你看完就能上手。先说清楚这篇指南的定位它不是官方文档的翻译而是一个普通开发者踩过一堆坑之后的实操记录。我会从最简单的安装说起接着讲怎么让它真正干活再深入讲怎么接入 DeepSeek 这类模型、怎么用 Skills 定制自己的流程最后整理一份高频报错的排查清单。无论你是 Windows、Ubuntu 还是 macOS 用户都能在里边找到对应的操作路径。1. 这个工具到底解决了什么问题1.1 终端里的自动编程代理是什么意思要理解 claude code 的价值先得把它和常见的 AI 编程工具区别开。之前很多人用的 Copilot、CodeWhisperer核心是补全你在编辑器里写代码它帮你续写下一行。后来有了 Cursor可以框选代码然后说帮我把这个函数改成异步它给你改。但 claude code 的工作方式完全不同——它是一个跑在终端里的 Agent代理能理解整个项目的结构能读多个文件能主动执行命令然后基于命令的输出去做下一步判断。我举个具体例子。假设你现在有个老项目想把所有接口的错误处理从console.log改成统一的日志上报。如果人工改你得先找出所有接口文件逐个改还要小心漏掉。如果用 claude code你只需要在终端里说一句把 src/api 目录下所有接口的错误处理改成调用 utils/logger 里的 reportError并且把原来 console.log 的内容作为 message 参数传进去。它会自己去翻文件、修改代码、跑测试验证如果遇到不确定的地方还会停下来问你。这种理解上下文到动手执行再到自动验证的闭环才是它真正的核心能力。1.2 它能做的不只是写代码虽然名字叫 code但它实际能干的事远不止写代码。我身边有人用它整理 CSV 数据有人让它批量重命名文件有人让它分析日志里的异常还有人直接把它当项目文档生成器用。原因在于 claude code 终端环境下有文件读写和执行命令的权限只要是在这个项目目录内能做的事它都能尝试。比如我见过一个最离谱的用法有人拿 claude code 给自己做了一个PPT 大纲生成器输入一个主题它自动生成章节结构、拟好每页的标题和要点然后输出成 Markdown 文件再配合其他工具转成 PPT。虽然每一步做得不算深入但胜在一条龙省掉了大量重复劳动。所以不要把它只当成程序员的专属工具它更像一个长在终端里的全能助手只要有命令行操作基础就能用。1.3 适合哪些人用先说结论写代码的人最受益但不是只有程序员能用。如果你是程序员claude code 能帮你做三类事最顺手第一类是理解陌生项目刚接手一个仓库时让它梳理目录结构、核心模块关系、关键接口调用链比人肉翻代码快一个量级第二类是写枯燥的样板代码比如写单元测试、补注释、生成类型定义这些活儿它做得又快又整齐第三类是排查 bug把报错信息直接丢给它让它沿着调用栈往上查通常它能给出比搜索引擎更贴合你项目的答案。如果你不是程序员但工作中经常碰命令行——比如运维、数据分析、自动化脚本编写——claude code 依然值得一用。你可以让它写一个批量处理文件的 Python 脚本然后你在终端里运行报错了把错误发回去让它改来回几轮之后一个能用的工具就出来了。本质上它把一个助手的思考能力和终端的执行能力合并了你只需要会表达需求就行。2. 从零开始安装环境的三个前置条件2.1 Node.js 版本不是越新越好但有底线安装 claude code 之前先检查你有没有装 Node.js因为它的 CLI 版本是用 npm 分发的。官方要求 Node.js 18 及以上版本低于 18 用不了。我用的是 20 的 LTS 版本跑了很久都没出问题。这里要提醒一句虽然 Node 20 是合理选择但如果你机器上装的是 Node 18也别急着升级很多老项目对 Node 版本有要求升级可能连带引出一堆兼容性问题。只要版本号大于等于 18就先凑合用遇到再升级。怎么检查版本打开终端输入node -v如果能输出版本号就说明已经装了。如果提示找不到命令需要先去 Node.js 官网下载安装包或者用包管理器安装。macOS 用户如果装了 Homebrew一条brew install node就能搞定Ubuntu 用户建议用 nvm 装避免 sudo 权限的坑Windows 用户直接下载安装包最省事。2.2 登录账号和订阅那些事装完 CLI 之后第一次运行claude会提示你登录。它支持用 Claude 账号登录登录之后才能和 Anthropic 的模型对话。这里有个新手最容易迷惑的点claude code 本身是免费的但你实际调用 Claude 模型要么有 Claude 的订阅Pro 或 Max要么有 API 额度并要消耗 token 费用。如果不想折腾订阅完全可以用我后面第 4 章讲的方案在配置文件里把模型换成 DeepSeek、智谱或者其他兼容模型。这也是国内大量用户在用 claude code 的方式——把它当成一个前端壳后端接不同的模型 API既绕开了订阅成本又能体验这套 Agent 流程。这个思路我会在配置部分详细介绍先记住一点登录不是死路模型可以换。2.3 三条安装路线CLI、桌面版、VSCode 插件claude code 官方提供了三种使用形态我建议你按自己的使用习惯选CLI 版本npm install -g anthropic-ai/claude-code全局安装然后在任意项目目录里运行claude就能启动。优点是轻量、灵活在任何终端里都能用缺点是全命令行操作对不熟悉终端的人门槛略高。桌面版官方后来推出了 Claude Code Desktop桌面应用提供图形界面支持直接打开文件夹、在聊天框里发指令还能看到运行日志和文件变更记录。对不太习惯纯命令行的人友好很多我认识的很多非程序员用户都是从桌面版入门的。VSCode 插件在 VSCode 扩展市场搜 Claude Code装好之后可以绑定当前打开的项目在编辑器面板里直接对话查看代码变更也更直观。因为日常开发就在 VSCode 里插件可以省掉切换终端的麻烦。三条路线共用同一套配置和登录状态也就是说你可以在 VSCode 插件里接入好模型再去桌面版打开同一个项目配置是互通的。它们之间的详细对比我建议刚上手的人先装 CLI 版本因为命令行版本最容易理解这个工具到底在干嘛如果实在无从下手就装桌面版图形界面上手成本最低。3. 核心操作五分钟让 claude code 开始干活3.1 在你的项目里启动第一次对话安装完成并登录后找一个你自己的项目文件夹在终端里进入这个目录然后输入claude如果项目较大它可能会先问你要不要跳过某些目录比如node_modules、.git、dist这类无关紧要的地方。我建议你允许它自动生成一个虚拟文件系统索引方便它后续快速查找文件但如果项目动辄几十万文件建议手动排除掉依赖目录否则每次初始化都会卡半天。启动后你会看到一个交互式输入框。这时候就可以直接提需求了。我第一个建议的需求是简单介绍一下这个项目的功能和整体结构。它会搜索文件、阅读关键配置然后给你一个结构清晰的梳理。这个操作看似简单实际上是测试它有没有正确读取项目的关键一步。如果连这个都答不好多半是模型配置或文件权限有问题趁早排查。3.2 掌握斜杠命令效率提升一个档次claude code 的交互界面里以/开头输命令可以快速完成很多操作。我把自己常用的整理成一张表命令作用使用心得/help查看所有命令列表不确定怎么操作时先敲这个/clear清空当前会话上下文换了任务方向时用避免旧上下文干扰新判断/compact压缩历史对话保留核心信息对话太长、模型开始健忘时使用/cost查看本次会话消耗的 token 和费用接 API 后养成定期看的习惯避免月底账单吓人/model切换底层模型多模型切换时用CC Switch 也依赖这个机制/status查看当前会话状态、权限和模式排查问题时先看状态日常使用中最容易忽略的是/clear。很多人和 AI 对话时会遇到一种情况前面聊了 20 轮后面让它做什么它都答非所问。这不是模型变笨了而是上下文窗口被无关内容塞满优先级被冲淡。这时候不要继续硬聊直接/clear开新会话把必要的背景重新说一遍效果会好很多。3.3 用 CLAUDE.md 给项目设定操作规范每启动一个项目的 claude code它都会自动读取项目根目录下的CLAUDE.md文件如果存在的话。这个文件用 Markdown 格式写内容相当于你给 AI 的项目交接文档让它了解这个项目的特殊约定和偏好。我自己所有的项目都会维护这个文件至少写三块内容一是项目简介说明这是一个什么系统、技术栈是什么二是代码规范比如接口返回格式统一为 { code, message, data }类型定义放 src/types 下三是禁忌事项比如不要修改迁移文件公共组件改动前先问确认。举个实际例子一个前端项目里写# 项目约定 - 组件使用 TypeScript React函数组件写法 - 样式使用 Tailwind禁止引入其他 CSS 文件 - API 请求统一走 src/api/index.ts 封装 - 新增功能必须同步补充 README 文档 - 不要修改 src/entry.tsx 的挂载逻辑这样你每次启动 claude code它不需要你重复交代这些背景直接按照规则执行。这比在对话里每次说明要可靠得多。还有一个小技巧CLAUDE.md支持引用其他文件比如在文件里写docs/architecture.md它会自动把这个文件内容也作为上下文。如果你的项目文档较多强烈建议用这种方式组织避免 CLAUDE.md 自身膨胀得不可维护。4. 进阶玩法接入 DeepSeek 等第三方模型4.1 为什么要换模型以及换模型的思路官方 claude code 默认用的是 Anthropic 的 Claude 模型效果确实好但对于个人开发者来说订阅费用和网络门槛是绕不开的问题。我认识的所有国内开发者几乎都在琢磨同一个问题能不能让 claude code 接上别的模型答案是可以而且比想象中简单。由于 claude code 的架构支持通过环境变量指定模型接口我们可以让它走 OpenAI 兼容协议接上 DeepSeek、智谱 GLM 这些服务。这样一来你依然用 claude code 的操作界面和 Agent 工作流但底层的模型换成了成本低得多的国产方案。当然要提前说清楚换模型之后体验不会和官方模型完全一致。不同的模型在指令跟随、代码理解、长上下文处理上各有差异。DeepSeek 在代码方面表现不错日常写业务代码完全能打智谱的 GLM 系列胜在稳定如果你很在意效果也可以再对比一下其他兼容模型。我的建议是别指望 100% 平替而是把它当作一个体验 Agent 编程流程的低成本入口如果以后预算允许再切回官方模型也不迟。4.2 修改 settings.json核心配置项一次讲清接入第三方模型的核心是配置文件。claude code 的配置路径在不同系统上略有差异但逻辑一样WindowsC:\Users\你的用户名\.claude\settings.jsonmacOS / Linux~/.claude/settings.json如果这个文件不存在自己新建一个就行。在 JSON 文件里你需要设置env字段写入模型接口的地址和密钥。以接入 DeepSeek 为例网上流传最广的一份配置长这样{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的DeepSeek密钥, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat } }这里有一个非常关键的坑ANTHROPIC_BASE_URL必须以/anthropic结尾因为 DeepSeek 提供了专门的 Anthropic 兼容接口路径写错或者漏掉会直接报连接错误。ANTHROPIC_AUTH_TOKEN填你在 DeepSeek 开放平台申请的 API Key不用加 Bearer 前缀。ANTHROPIC_MODEL指定主模型ANTHROPIC_SMALL_FAST_MODEL指定快速小模型用于一些消息摘要等轻量任务通常填同一个就行。改完保存文件重启终端里的 claude code然后直接发一句你好介绍一下你自己如果它能正常回答说明模型接通了。有些版本的 claude code 还会有模型更新提示忽略即可不影响使用。4.3 多模型切换怎么办试试 CC Switch如果你不止接一个模型比如既接了 DeepSeek 又接了智谱不想每次都手动改配置文件可以用一个开源小工具CC Switchcc-switch。它本质上是一个图形化的配置管理器让你在多个模型配置之间一键切换不用碰命令行。CC Switch 的使用逻辑很简单先在软件里添加多个供应商配置每个配置填上名称、API 地址、密钥、模型名然后保存。之后想用哪个模型点一下对应的配置它会自动改写 claude code 的 settings.json然后你重启 claude code 就能生效。等于把容易写错的 JSON 配置变成了点按钮。我在多项目场景下特别喜欢这个工具。比如 A 项目用 DeepSeek 控制成本B 项目用官方 Claude 追求效果来回切换也就几秒钟的事。但要注意切换模型后一定要重启 claude code 再继续否则会话还保持着旧模型的连接。另外CC Switch 本身不负责登录它只是管配置所以 Claude 账号登录和模型切换是两码事别搞混。4.4 兼容性问题的排查思路接入第三方模型时最容易踩的坑是版本不匹配。网上大量出现类似报错某个模型名在 claude code 里不被识别比如 deepseek-v4-pro is not a model this version of claude code recognizes。这类问题的根因不是模型供应商的问题而是 claude code 的中继层对模型名做了校验新出的模型不在它内置的模型列表里。碰到这种报错怎么处理我的排查顺序供你参考第一步确认ANTHROPIC_MODEL填的是不是官方支持的模型名比如 DeepSeek 在 Anthropic 兼容接口里一般用deepseek-chat别用带版本号后缀的别名第二步检查ANTHROPIC_BASE_URL有没有写错不带/anthropic的地址可能在对话时没有模型名校验但实际请求会失败第三步升级 claude code 到最新版因为新版会同步更新模型支持列表。整体来说配置层面 90% 的问题都能用这三步定位。5. 让 claude code 学会你的私有流程Skills 玩法5.1 Skills 到底是什么和 CLAUDE.md 有什么区别当基础配置稳定后就该聊聊让 claude code 真正好用的东西Skills技能。理解 Skills 有个最简单的类比CLAUDE.md 约定的是你在这个项目里做事要遵守什么规矩Skills 则是你能一招调用的一套完整工作流程。规矩是静态的流程是动态的。具体来说Skill 是一组文件放在某个目录下。它告诉 claude code当你需要使用这个技能时应该按以下步骤操作可以调用我提供的脚本或模板。这样一来你的很多重复性工作就可以沉淀成固定流程让 AI 一键执行。5.2 一个完整的 Skill 长什么样Skills 的存放位置有一定讲究。官方规范是在项目根目录建一个.claude/skills文件夹下面每一个子文件夹就是一个 Skill。每个 Skill 文件夹里至少有一个SKILL.md文件用来描述这个技能是干什么的、什么时候用、怎么做。如果有配套的资源还可以放脚本文件、模板文件等。举个例子如果你想给 claude code 加一个生成提交信息的技能目录结构可以是这样.claude/skills/generate-commit/ ├── SKILL.md └── scripts/ └── suggest_commit.pySKILL.md的内容大致长这样--- name: generate-commit description: 根据当前的 git diff 生成符合规范的 commit message --- ## 使用场景 在用户说生成 commit message或提交代码时使用。 ## 执行步骤 1. 运行 git diff --stat 查看变更范围 2. 运行 git diff 查看具体变更内容 3. 根据变更类型用 conventional commits 规范生成 commit message 4. 将生成结果展示给用户由用户确认后执行 git commit注意description字段写得越清楚越好因为 claude code 会扫描所有 Skills 的描述来决定何时调用某个技能。如果描述模糊很可能需要你手动提醒它用一下那个技能。5.3 实操案例做一个检查需求的清单型 SkillSkills 不只是代码工具。我最常用的一个 Skill 是PR 自检。每次写完代码要提 Pull Request 前我会用自然语言说帮我做一个提交前的检查它会按照 SKILL.md 里的流程逐项检查是否有调试日志、是否有未使用的变量、是否有注释掉的死代码、测试文件是否更新、文档是否同步。这个流程以前完全靠人肉执行现在变成了一次对话。写这个 Skill 的 SKILL.md 也很简单就是列一个 checklist--- name: pr-checklist description: 在用户准备提交 pull request 前按照项目规范逐项检查代码质量 --- 1. 运行 git diff HEAD 获取当前全部改动的内容 2. 检查是否有 console.log/debugger 等调试残留 3. 检查是否有 TODO 标识未被处理 4. 检查新增文件是否有对应的单元测试 5. 检查是否更新了 README 或 API 文档 6. 汇总检查结果逐条列出问题和修改建议这个 Skill 我每天都在用。它的价值不在于逻辑有多复杂而在于它把标准操作流程固化了。很多团队辛辛苦苦制定代码规范但人总有忘的时候Skill 不会忘。5.4 在哪声明 Skills以及多项目共享的技巧Skills 默认只对当前项目生效因为它是放在.claude/skills下的。如果你想所有项目都能用某个 Skill可以把 Skill 放在全局目录里比如在用户主目录下的~/.claude/skills。这样每次启动 claude code它都能识别到这些全局技能不用在每个项目里重复复制。另外我习惯在每个项目的CLAUDE.md里写一句类似如果需要生成 commit message使用 generate-commit 技能提交 PR 前使用 pr-checklist 技能的话。这样等于给 AI 一个更明确的触发条件它能更快地判断何时该调技能而不是等你手动指出。如果项目里多个技能容易混淆这个做法尤其有效。6. 踩坑实录我从报错里攒下来的排查清单6.1 一启动就报 529 错误怎么处理我用 claude code 过程中遇到最多的错误就是 529。这个错误码很直白地告诉你服务器过载当前请求量太大模型服务端暂时处理不过来。对新用户来说529 特别容易出现在刚配置好模型的第一次对话时很多人以为是配置出了问题急得不得了其实不是。处理方式很简单等几秒到几分钟再试。如果频繁出现可能和当前接的模型服务商在某个时段的负载有关可以换个时段再用或者切换备用的模型。如果是官方 Claude 服务频繁 529基本就是官方全局负载高的表现大家都会遇到别慌。这个错误我以前会直接归因于我配置错了白白折腾半天后来才发现很多时候就是服务端的临时问题。6.2 模型名不识别、配置不生效问题出在哪另一个高频报错是模型名无法识别。网上有很多截图典型文案类似 xxx is not a model this version of claude code recognizes。这个报错我前面提过模型列表校验的问题这里再补充两个排查点。第一检查模型名的大小写和连字符。DeepSeek 的官方模型名往往就是deepseek-chat这种格式如果你从某篇文章复制了带版本号的名字比如deepseek-v4-pro大概率会撞上模型列表校验的坑。第二配置文件保存后必须重启 claude code环境变量的读取发生在启动时光保存不重启不生效。如果你是在 VSCode 插件里改的配置重启插件或重开窗口也算重启。还会遇到一种隐蔽情况配置文件里有多个env块后写的覆盖了先写的导致你以为改了却没生效。这种时候把 JSON 格式化一下再看或者干脆删掉多余的环境变量块。6.3 输出乱码编码问题的根源和解决在 Windows 上使用 claude code 时中文输出乱码是常见问题。根源基本都出在终端编码上。Windows 默认的 GBK 编码和 claude code 默认输出的 UTF-8 之间没对齐中文就变成了一堆问号或者乱码。解决办法有两种一种是在启动前先执行chcp 65001把当前终端代码页切到 UTF-8另一种是在系统设置里把使用 Unicode UTF-8 提供全球语言支持的选项打开这个选项在 Windows 的区域设置里勾选后重启系统基本能根除乱码问题。VSCode 的终端则通常默认 UTF-8乱码概率低很多。Linux 和 macOS 用户遇到乱码的概率很小如果出现了检查终端 locale 设置即可。6.4 卸载不干净重装老是报错很多人在初次配置失败后选择把 claude code 卸载重装。但如果你只执行npm uninstall -g anthropic-ai/claude-code会发现重新安装后旧配置还在有时甚至启动报错。因为这些命令只删了全局 npm 包没有清理用户目录下的.claude文件夹。如果你确实想干净卸载我建议按这个顺序来第一步执行 npm 卸载命令第二步删除用户主目录下的.claude目录注意提前备份settings.json和CLAUDE.md避免重要配置丢失第三步如果使用过桌面版在系统设置里卸载桌面应用并清掉对应的 AppData 或 Library 目录里的缓存。这样清理完之后重新安装基本就是一个全新的状态不会再被旧配置干扰。我见过不少配不上、卸不掉、反复折腾的情况最后都是因为.claude目录没有清掉。6.5 电脑风扇狂转、还发出各种声音提示如果你用 claude code 时发现电脑风扇突然全速运转或者运行过程中有提示音这两种情况都正常到不值得慌张。风扇狂转一般发生在它执行大量文件读取或运行测试时特别是大型项目CPU 或磁盘 I/O 飙升是合理现象。但如果你在空闲状态下风扇依然飙高那大概率是某个会话还挂着后台任务可以通过/status看看有没有正在执行的命令或者直接重启 claude code。至于声音提示claude code 在某些操作完成或出错时会触发系统提示音这个可以在设置里关掉。如果你不喜欢叮叮咚咚的提示在设置里开启静音模式或者直接关闭终端声音。如果你在远程服务器上使用声音提示通常不生效那不是 bug是服务器没接音频设备。6.6 在 Windows 上装成快捷方式还有个实用小习惯最后分享一个 Windows 用户的便利性技巧。因为 claude code 是命令行工具每次都要打开终端、输入claude对没有快捷方式就难受的人来说有点繁琐。你可以创建一个桌面快捷方式目标设为cmd /k claude双击就能直接进入 claude code 界面省去输入命令的步骤。如果你有固定的工作目录可以把启动目录也改成项目文件夹这样打开就是项目环境。我个人的习惯是在系统 PATH 里配了claude然后用 Windows Terminal 固定一个 profile启动即进入工作目录并自动运行claude体验几乎等同于打开一个桌面应用。7. 一些实际操作中沉淀下来的建议用 claude code 大半年我最深的体会是这个工具的上限不在模型而在你怎么用它。把 CLAUDE.md 写好、把常见流程固化成语义清晰的 Skills、在遇到报错时按系统性思路排查——这几件事做好之后它的稳定性和效率会连跳几个台阶。反过来如果只是随便装好然后裸用遇到报错就认为是工具不行那你大概率会错过这个其实很好用的东西。最后提一个小技巧如果你刚开始接触 claude code不需要一上来就追求多模型切换、自定义 Skills 这些进阶操作。先在真实项目里连续用一周至少完成两到三件小任务比如帮我写一个接口层的单元测试帮我梳理这个模块的依赖关系把这个函数的类型声明补全。等你对它的工作方式产生了手感再回头研究配置和技能你会发现一切都顺理成章。工具就是这么个工具重点是你要真的拿它去干一件具体的事。