终于有人问到点子上。Claude Code这玩意儿刚出来那阵我还停留在“聊天框里问代码”的思路上真正把它当主力工具用起来是某天接手一个屎山老项目——六个微服务几百个配置文件光把项目结构理清楚就花了半天。后来我试着用 Claude Code 直接从终端里读代码、跑测试、改逻辑一个下午干完了原来两天的活。从那以后它成了我本地开发环境里离不开的东西。这篇就围绕 Claude Code 的常用指令和配置把我从零开始装环境、调配置、接入第三方模型、踩坑排错的经验一次性写清楚。内容适合这几类人刚听说这个工具想尝鲜的、装了但只会打开聊天框的、被官方模型限额折磨想换 DeepSeek 或 Ollama 的、以及在建团队协作规范想让 AI 编程助手更听话的。我会尽量把“为什么这么配”也讲明白而不只是扔一堆命令。1. 先聊聊为什么是 Claude Code1.1 一个点击率极高的使用场景先还原一下那个让我“路转粉”的场景。项目里有套老旧的支付回调逻辑排查问题时需要同时看三四个文件的调用链。以前在 IDE 里开一堆标签页来回跳转思路经常断。用 Claude Code 的时候我直接在终端里敲一句claude 帮我梳理 payment/callback 这条链路从入口到数据库写入列出每一步的关键代码位置和异常处理分支它自己会去读目录结构、打开相关文件、整理调用关系最后输出一份带文件行号的说明。中间我还能追问“第三个异常分支为什么吞了错误”它能接着上下文继续往代码里钻。这种体验比“复制粘贴代码进聊天框”要自然得多因为没有复制粘贴这一步它拿到的是完整的、未被截断的上下文。1.2 和 Cursor、Copilot 的定位差异很多人问我既然 Cursor 和 Copilot 都能聊天、都能补全还要终端工具干嘛。我的理解是Claude Code 更像一个“住在命令行里的结对程序员”它把操作单位从“当前文件”变成了“整个代码库”。Copilot 擅长的是局部补全光标附近的代码它给出后续行。Cursor 擅长的是跨文件的问答和改代码但操作入口还是编辑器。Claude Code 的优势在于不需要打开 IDE在 SSH 到服务器、处理大数据集、跑批处理脚本时也能用非交互模式可以直接挂进 CI 流程权限模型和配置体系更适合团队标准化。如果你日常工作就是打开 VSCode 写前端Cursor 体验可能更顺手。但如果你经常要处理多模块项目、要在远程环境里操作、想把 AI 助手变成自动化流水线的一环Claude Code 的“命令行原地干活”就是不可替代的。它不挑编辑器本质上只需要一个终端和 Node.js 环境。2. 环境准备Node.js版本、npm源和安装姿势2.1 为什么必须先搞定 Node.jsClaude Code 是 npm 分发的 CLI 工具本质上是跑在 Node.js 上的一套程序。所以环境准备的核心就是 Node.js。官方要求的版本底线是 18但我强烈建议直接上 20 LTS 或更高。原因很实际版本太低时CLI 初始化依赖和部分异步 I/O 会出现莫名其妙的兼容问题报错信息还不直观排查起来浪费时间。装 Node.js 我推荐用 nvm而不是去官网下载安装包。nvm 的好处是版本切换方便以后项目需要 16、18、20 自由切换不用重复操心路径冲突。Linux 或 macOS 下的装法如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置后 nvm install 20 nvm use 20 node -v npm -vWindows 用户直接用官方安装包选 LTS 即可或者用 winget 装。装完检查一下版本node -v npm -v这一步输出两行版本号环境就算成了。注意一个细节如果你机器上之前装过老版本 Node全局目录里残留的包可能和 Claude Code 冲突最省心的方式是 nvm 切一个干净的新版本再继续。2.2 npm 源和全局安装目录的坑终端里用 npm 下载全局包最头疼的就是网络慢、超时。这未必是网络本身的问题很多时候是默认源在大规模下载时的响应不稳定。我个人的习惯是先把 npm 源切到国内镜像下载速度能提升一个量级npm config set registry https://registry.npmmirror.com npm config get registry切换之后安装任何全局包都会快很多。如果是在公司内网环境npm 可能还配置了私有源注意别覆盖掉。另一个高频坑是权限报错。macOS 或 Linux 下用系统自带 Node 直接npm install -g经常遇到EACCES: permission denied。原因是全局安装目录/usr/local/lib/node_modules对当前用户没有写权限。别用sudo npm install -g硬刚那会把全局包的所有者改成 root后面升级、卸载全是权限问题。正确做法是走 nvm 管理 Nodenvm 安装的 Node 全局目录在用户目录下天然没有权限问题已经装了系统版 Node 的可以手动修改 npm 的 prefix 到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH这一步做完后面所有全局安装都会安静许多。2.3 顺便确认 git 环境Claude Code 对 git 的依赖很强。它默认会读取当前目录的 git 仓库状态、生成 diff、在改动文件时给你展示变更所以我建议把 git 也提前确认好git --version git config --global user.name your name git config --global user.email your email没有全局用户名和邮箱的话Claude Code 在生成提交信息或执行 git 操作时可能报错。这个不显眼但让人头疼提前设好省得后面折腾。3. 安装与登录从全局安装到VSCode联动3.1 安装命令与版本验证环境就绪后安装就是一条命令的事npm install -g anthropic-ai/claude-code装完先验证版本claude --version能输出版本号说明安装成功。这时候在任意项目目录下输入claude就会进入交互式 REPL类似进入一个会话。第一次运行如果是旧版本可能要求你授权终端处理权限按提示回车即可。如果版本号输出不出来大概率是 npm 全局 bin 目录没加到 PATH检查npm prefix -g对应的 bin 目录是否存在。3.2 登录方式订阅账号和 API Key 分别怎么弄Claude Code 支持两种身份体系。第一种是 Claude 订阅账号Pro/Max在浏览器里登录授权第二种是 Anthropic API 账号用 API Key 认证。订阅账号登录很简单运行claude后它会打印一个链接浏览器打开、登录、授权回到终端就自动完成了。好处是费用包含在订阅里不用额外准备 API Key缺点是有并发和额度限制热搜词里那句“your limits are temporarily boosted. your weekly claude code limit is 50%”就是这类限制的体现。API Key 方式适合按量付费、需要更高并发或要在 CI 里用的场景。设置ANTHROPIC_API_KEY环境变量即可export ANTHROPIC_API_KEYsk-ant-api03-...需要注意API 计费和订阅是两套体系如果你用第三方模型比如后文要写的 DeepSeek设置的通常是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY。这一点很多人搞混记一下官方 API Key 用ANTHROPIC_API_KEY第三方 Anthropic 兼容接口大多认ANTHROPIC_AUTH_TOKEN。3.3 VSCode 里怎么用插件还是终端社区里对“VSCode 配置 Claude Code”的搜索热度很高其实现在有 Anthropic 官方 VSCode 扩展也可以直接在 VSCode 的集成终端里跑claude两种方式并行不冲突。官方扩展装好之后侧边栏会多一个 Claude Code 面板可以在面板里输入指令也可以把当前编辑器选中的代码直接发给它。实际体验下来面板模式更适合“问问题、看解释”因为输出排版比终端好一些真要让它改代码、执行命令、跑测试我还是习惯在集成终端里跑纯 CLI。如果你不想装插件最省事的联动方案是VSCode 里按Ctrl ~打开集成终端直接运行claude。Claude Code 会自动感知当前工作区基于打开的文件夹作为项目根目录。这个连通的妙处在于它能看到你在编辑器里的改动生成的补丁也落在当前仓库里完成之后切回编辑器直接看 diff 即可。4. 指令拆解高频斜杠命令与自然语言指令4.1 用得最多的六个斜杠命令进入交互界面后所有斜杠开头的输入都会被当成指令而不是问题。我最常用的有六个命令作用使用场景/help列出全部可用命令忘了某个命令怎么写或版本更新后想看看新功能/clear清空当前对话上下文聊偏了、跑题了重新开个清晰的话题/compact压缩当前上下文再继续上下文快爆掉但还不想放弃当前任务/model查看或切换模型想临时切到大杯模型处理复杂重构/cost查看本次会话花费关心 token 消耗时非常实用/doctor诊断环境问题排查安装、权限、网络类异常/compact是续命神器。上下文过长后 Claude 会变笨表现为“记不住你说过的话”“改 A 文件忘了 B 文件”。此时/compact会把历史对话压缩成摘要保留关键信息丢掉冗余细节继续干活。代价是压缩后它可能会丢掉一些细节重要前置条件最好在压缩后手动重复一遍。/model在接入第三方模型后尤其好用。你可以在同一个会话里切模型不需要退出重进。比如日常小改动用 fast 模型大重构切到最强的模型成本控制很直观。4.2 退出、恢复与回滚别害怕试错Claude Code 的会话状态是可以延续的。退出交互界面用/exit下次在同一个项目目录下运行claude --continue它能把上次会话的上下文恢复出来。这个特性特别适合“今天没弄完明天接着搞”的场景上下文不用从头喂。还有/rewind顺着讨论方向回滚到你指定的某一步。比如跑偏了、改坏了/rewind可以回到之前的某个节点重新开始。它不改变文件系统里的代码只重新组织对话进程。真正改坏代码想还原还是要靠 git。在交互界面里执行 git 操作也很顺手。你直接说“帮我把所有改动提交提交信息写清楚一点”它会自动git diff、git add、git commit。如果只希望它读代码不允许写代码可以用--permission-mode或后续的权限配置来控制。4.3 非交互模式一条命令完成自动化除了交互式 REPLClaude Code 最被低估的是非交互模式claude -p 解释 src/main.go entry 函数的作用 claude -p 给 README.md 补一段安装说明 --output-format json-pprint模式下它执行完就退出不会进入对话循环。结合 shell 管道可以实现很多自动化思路。比如拿到 git 改动的文件列表逐个让 Claude 补充注释git diff --name-only | xargs -I {} claude -p 为 {} 文件中的主要函数补充中文注释不要改动业务逻辑把--output-format json加上输出就是结构化 JSON可以直接被脚本解析。我甚至见过同事把它挂在 CI 里让 Claude Code 自动生成 release notes效果意外地好。自然语言指令这部分记住一个原则把要求说具体。不要只说“优化这段代码”要说“把这段代码的重复逻辑提取成一个工具函数保持对外参数不变并补充单元测试”。Claude Code 的 Agent 能力越强对指令的语义理解越敏感你的需求边界越清晰它跑偏的概率越小。5. 配置进阶项目级CLAUDE.md与全局settings5.1 CLAUDE.md让 Agent 记住项目规矩Claude Code 有一个很重要的机制叫CLAUDE.md相当于项目的“出厂说明书”。在项目根目录运行/init它会扫描项目结构并自动生成一份基础说明。这份文件会被 Claude 在每次会话启动时自动加载因此所有指令的背景信息、编码规范、常用命令都会在上下文中。我的用法是手工在这份文件里维护三类内容项目背景这个仓库是做什么的技术栈是什么目录结构怎么组织的。常用命令如何跑测试、如何启动开发服务、如何构建。注意事项哪些目录不能乱改、代码风格要求、提交规范。举个例子文件里写# 项目说明 - 后端技术栈Spring Boot 3 MySQL - 启动命令./mvnw spring-boot:run - 测试命令./mvnw test ## 代码规范 - 所有 public 方法必须有 Javadoc - 禁止直接修改 mapper XML 中的公共 SQL改动需先与 DBA 确认 - 提交信息遵循 Conventional Commits有了这些我再启动 Claude Code 让它加功能时它给出的代码风格基本和项目现有代码一致不用每次反复强调。注意别把 CLAUDE.md 写得太长它占用的 tokens 很可观。建议控制在 80 行以内平时只放最核心的约定。全局级别的~/.claude/CLAUDE.md也存在适合放个人通用的规则比如“所有代码注释使用中文”“生成代码时优先考虑可读性”。项目级文件会覆盖或补充全局文件的内容。5.2 settings.json权限控制的主动出击Claude Code 的权限模型默认是“询问式”的也就是说它要执行bash命令或写文件时会先征求你的同意。正常使用没问题但一旦它频繁读取文件、反复执行 git 命令确认弹窗会多到让人烦躁。此时可以在配置文件里预设允许/禁止列表。配置目录默认在~/.claude/settings.json项目级配置放在.claude/settings.json后者会合并到前者之上。示例片段{ permissions: { allow: [ Bash(npm run *), Bash(git *), Read(**), Edit(**), WebFetch(domain:localhost) ], deny: [ Bash(rm -rf *), Bash(sudo *), Edit(config/prod/*) ] } }Read(**)允许读取项目内任意文件Edit(**)允许编辑任意文件生产环境配置目录手动排除掉等于给 Agent 划了安全边界。团队协作时这些配置可以提交进仓库保证所有成员跑 Claude Code 的行为一致。5.3 环境变量最容易被忽略的全局开关除了配置文件Claude Code 还认一批环境变量。最常用的是这几个ANTHROPIC_API_KEY官方 API Key。ANTHROPIC_AUTH_TOKEN第三方兼容接口的认证令牌。ANTHROPIC_BASE_URLAPI 网关地址接第三方模型时核心配置。ANTHROPIC_MODEL主模型名。ANTHROPIC_SMALL_FAST_MODEL快速小模型名通常用于标题生成、摘要等轻量任务。CLAUDE_CODE_CONFIG_DIR自定义配置目录。在 Windows PowerShell 里设置环境变量用$env:ANTHROPIC_BASE_URL...在 Linux/macOS 的 bash/zsh 里用 export。建议不要把这些变量写死在系统全局而是用direnv之类的工具按项目目录隔离避免不同项目的 API 配置互相污染。6. 接入第三方模型DeepSeek与Ollama实战6.1 为什么大家一门心思想接第三方模型官方 Claude 模型的体验当然最好但订阅型号有限额、API 费用偏高重度使用的人很快就碰到天花板。社区因此衍生出一堆“给 Claude Code 换模型”的方案最主流的就是接 DeepSeek 和本地 Ollama。接 DeepSeek 能大幅降低成本接 Ollama 能完全离线、数据不出机器。两种方案我都跑过下面分别说清楚。6.2 接入 DeepSeek改几个环境变量就行DeepSeek 官方提供了 Anthropic 兼容接口这意味着 Claude Code 不需要做任何代码层面的改动只要把 API 地址和令牌指过去即可。Linux/macOS 下export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的deepseek密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claudeWindows PowerShell 对应$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKENsk-你的deepseek密钥 $env:ANTHROPIC_MODELdeepseek-chat $env:ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude这样设置后进入交互界面Claude Code 面向第三方模型发起请求模型本身是 DeepSeek。日常代码理解、补全、简单重构都没问题。但有一条要提前有心理准备Claude Code 这类 Agent 工具依赖工具调用function calling第三方模型对工具调用的稳定性不如 Claude 原生模型复杂多步操作偶尔会出现“卡住”“答非所问”“返回空结果”的情况。实测下来 DeepSeek 做阅读、解释、生成测试这类任务非常稳但让它动辄改十几个文件的超长多步任务还是容易翻车。另外注意接 DeepSeek 时登录授权那套步骤可以完全跳过不需要 Claude 账号授权因为环境变量已经喂了身份信息。如果你在项目里混合使用官方模型和第三方模型强烈建议用 cc-switch 这类工具来做配置切换管理。6.3 Ollama 本地模型与 cc-switch 组合Ollama 是本地跑大模型的一把好手支持 Llama、Qwen、DeepSeek 开源版等。接 Ollama 最纠结的点在于Claude Code 的接口协议是 Anthropic 格式而 Ollama 暴露的是 OpenAI 风格接口两者默认不兼容不能像 DeepSeek 那样直接改 base URL 就完事。社区里常见做法是本机跑 Ollama先拉取一个模型比如ollama pull qwen2.5-coder:14b。通过一个兼容层把 Anthropic API 请求转成 OpenAI 请求发给 Ollama。用 cc-switch 管理不同供应商的配置一键切换官方、DeepSeek、Ollama。cc-switch 的使用逻辑是这样的它维护多套 Claude Code 配置base URL、token、模型名每个配置是一个 profile切换时把对应配置写入 Claude Code 的 settings 或环境变量然后重启 Claude Code 即生效。选择 provider 后相当于帮你把 6.2 那些变量批量搞定不用每次手敲 export。对普通用户我的建议是本地 Ollama 方案的体验上限取决于你本机显卡和显存。7B 模型跑代码解释够用但要让它承担复杂的重构任务效果和云端商用模型差距明显。适合的场景是离线环境、隐私敏感项目、或者只是想低成本体验一下 Agent 工作流。想真的提升编码效率DeepSeek 这种云端 API 是甜点区。7. 落地避坑限流、上下文爆炸与常见报错处理7.1 官方订阅的限额问题用的过程中官方订阅模型最常见的报错就是配额相关。热搜词里那句“your limits are temporarily boosted. your weekly claude code limit is 50% hi”我遇到过不止一次。本质是 Claude 订阅套餐对 Claude Code 的用量有周级别限制一旦接近上限系统会直接提示 limits 或降低响应优先级。这不一定是你操作错误而是套餐本身的限制。应对办法有三条路等额度重置短期应急就把非关键任务往后放。换 API Key 计费按量付费不存在周配额但费用更敏感。切第三方模型DeepSeek/Ollama用 6.2 和 6.3 的配置。我个人的选择是“默认 API 聊天问复杂问题用订阅”两套体系分开用各取所长。7.2 上下文长度和 /compact 的正确姿势另一个高频坑是“上下文爆炸”。Claude Code 单次会话能承载的上下文有限当它读了一堆大文件后你问它最简单的问题它也反应迟钝甚至答非所问。原因是上下文窗口被塞满了模型“看到”的信息太多且杂。处理思路是及时清理。觉得对话开始变笨时先/context看一眼当前上下文占用比例如果占比很高直接用/compact压缩。压缩完要主动把当前任务的关键目标再复述一遍以免摘要丢失细节。如果任务彻底切换了别犹豫直接/clear开新会话不要抱着旧对话舍不得放。开新会话的代价是它需要重新读文件但这比在拥堵上下文里挣扎高效得多。7.3 几个高频报错的排查链路最后集中写几个我踩过并验证有效的高频报错。报错一EACCES: permission denied。出现在 npm 全局安装阶段原因是全局目录无写权限。解决思路是切换到 nvm 管理的 Node或手动重设 npm prefix 到用户目录不要用 sudo 硬装。报错二ENOENT找不到模块或文件。多数是当前目录不是 git 仓库或者项目路径含中文/特殊字符导致解析异常。解决先进 git 项目目录再启动路径别带空格和中文。报错三网络类错误比如connect ETIMEDOUT。常见原因是终端无法访问 Anthropic 或第三方 API 的接口域名。排查顺序是先确认环境变量里的ANTHROPIC_BASE_URL是否指错了地址再确认网络连通性。如果是公司代理环境记得设置 NO_PROXY 把内网地址排除掉。报错四model not found或 404。这在使用第三方模型时尤其常见原因是ANTHROPIC_MODEL填写的模型名在当前 base URL 指向的服务上不存在。先查一下对应平台的模型列表把名字抄准确。比如 DeepSeek 的在线模型是deepseek-chat不是deepseek-coder后者已经下线了。报错五Windows 终端里中文乱码或指令显示异常。多半是代码页编码问题。在 PowerShell 里执行chcp 65001切到 UTF-8再启动 claude一般能解决。排错时优先跑一遍claude --doctor它会自动检查 Node 版本、配置路径、git 目录、权限等关键项并给出修复建议。这个命令放在最后用因为它输出的信息比较全面能少走很多弯路。最后再分享一点我个人的体会。Claude Code 用到现在我觉得比指令清单更重要的是把CLAUDE.md写好把项目上下文喂透。工具层面积累再多命令都不如让它一上来就懂这个项目“是什么规矩”。另外模型选择真不是越贵越好日常小改动用轻量模型反而快复杂任务再上大模型成本和体验可以兼得。这篇里的命令和配置都是我在真实项目里反复验证过的照着配一遍能少踩不少坑。
Claude Code实战：从安装配置到第三方模型接入全指南
终于有人问到点子上。Claude Code这玩意儿刚出来那阵我还停留在“聊天框里问代码”的思路上真正把它当主力工具用起来是某天接手一个屎山老项目——六个微服务几百个配置文件光把项目结构理清楚就花了半天。后来我试着用 Claude Code 直接从终端里读代码、跑测试、改逻辑一个下午干完了原来两天的活。从那以后它成了我本地开发环境里离不开的东西。这篇就围绕 Claude Code 的常用指令和配置把我从零开始装环境、调配置、接入第三方模型、踩坑排错的经验一次性写清楚。内容适合这几类人刚听说这个工具想尝鲜的、装了但只会打开聊天框的、被官方模型限额折磨想换 DeepSeek 或 Ollama 的、以及在建团队协作规范想让 AI 编程助手更听话的。我会尽量把“为什么这么配”也讲明白而不只是扔一堆命令。1. 先聊聊为什么是 Claude Code1.1 一个点击率极高的使用场景先还原一下那个让我“路转粉”的场景。项目里有套老旧的支付回调逻辑排查问题时需要同时看三四个文件的调用链。以前在 IDE 里开一堆标签页来回跳转思路经常断。用 Claude Code 的时候我直接在终端里敲一句claude 帮我梳理 payment/callback 这条链路从入口到数据库写入列出每一步的关键代码位置和异常处理分支它自己会去读目录结构、打开相关文件、整理调用关系最后输出一份带文件行号的说明。中间我还能追问“第三个异常分支为什么吞了错误”它能接着上下文继续往代码里钻。这种体验比“复制粘贴代码进聊天框”要自然得多因为没有复制粘贴这一步它拿到的是完整的、未被截断的上下文。1.2 和 Cursor、Copilot 的定位差异很多人问我既然 Cursor 和 Copilot 都能聊天、都能补全还要终端工具干嘛。我的理解是Claude Code 更像一个“住在命令行里的结对程序员”它把操作单位从“当前文件”变成了“整个代码库”。Copilot 擅长的是局部补全光标附近的代码它给出后续行。Cursor 擅长的是跨文件的问答和改代码但操作入口还是编辑器。Claude Code 的优势在于不需要打开 IDE在 SSH 到服务器、处理大数据集、跑批处理脚本时也能用非交互模式可以直接挂进 CI 流程权限模型和配置体系更适合团队标准化。如果你日常工作就是打开 VSCode 写前端Cursor 体验可能更顺手。但如果你经常要处理多模块项目、要在远程环境里操作、想把 AI 助手变成自动化流水线的一环Claude Code 的“命令行原地干活”就是不可替代的。它不挑编辑器本质上只需要一个终端和 Node.js 环境。2. 环境准备Node.js版本、npm源和安装姿势2.1 为什么必须先搞定 Node.jsClaude Code 是 npm 分发的 CLI 工具本质上是跑在 Node.js 上的一套程序。所以环境准备的核心就是 Node.js。官方要求的版本底线是 18但我强烈建议直接上 20 LTS 或更高。原因很实际版本太低时CLI 初始化依赖和部分异步 I/O 会出现莫名其妙的兼容问题报错信息还不直观排查起来浪费时间。装 Node.js 我推荐用 nvm而不是去官网下载安装包。nvm 的好处是版本切换方便以后项目需要 16、18、20 自由切换不用重复操心路径冲突。Linux 或 macOS 下的装法如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置后 nvm install 20 nvm use 20 node -v npm -vWindows 用户直接用官方安装包选 LTS 即可或者用 winget 装。装完检查一下版本node -v npm -v这一步输出两行版本号环境就算成了。注意一个细节如果你机器上之前装过老版本 Node全局目录里残留的包可能和 Claude Code 冲突最省心的方式是 nvm 切一个干净的新版本再继续。2.2 npm 源和全局安装目录的坑终端里用 npm 下载全局包最头疼的就是网络慢、超时。这未必是网络本身的问题很多时候是默认源在大规模下载时的响应不稳定。我个人的习惯是先把 npm 源切到国内镜像下载速度能提升一个量级npm config set registry https://registry.npmmirror.com npm config get registry切换之后安装任何全局包都会快很多。如果是在公司内网环境npm 可能还配置了私有源注意别覆盖掉。另一个高频坑是权限报错。macOS 或 Linux 下用系统自带 Node 直接npm install -g经常遇到EACCES: permission denied。原因是全局安装目录/usr/local/lib/node_modules对当前用户没有写权限。别用sudo npm install -g硬刚那会把全局包的所有者改成 root后面升级、卸载全是权限问题。正确做法是走 nvm 管理 Nodenvm 安装的 Node 全局目录在用户目录下天然没有权限问题已经装了系统版 Node 的可以手动修改 npm 的 prefix 到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加到 PATH这一步做完后面所有全局安装都会安静许多。2.3 顺便确认 git 环境Claude Code 对 git 的依赖很强。它默认会读取当前目录的 git 仓库状态、生成 diff、在改动文件时给你展示变更所以我建议把 git 也提前确认好git --version git config --global user.name your name git config --global user.email your email没有全局用户名和邮箱的话Claude Code 在生成提交信息或执行 git 操作时可能报错。这个不显眼但让人头疼提前设好省得后面折腾。3. 安装与登录从全局安装到VSCode联动3.1 安装命令与版本验证环境就绪后安装就是一条命令的事npm install -g anthropic-ai/claude-code装完先验证版本claude --version能输出版本号说明安装成功。这时候在任意项目目录下输入claude就会进入交互式 REPL类似进入一个会话。第一次运行如果是旧版本可能要求你授权终端处理权限按提示回车即可。如果版本号输出不出来大概率是 npm 全局 bin 目录没加到 PATH检查npm prefix -g对应的 bin 目录是否存在。3.2 登录方式订阅账号和 API Key 分别怎么弄Claude Code 支持两种身份体系。第一种是 Claude 订阅账号Pro/Max在浏览器里登录授权第二种是 Anthropic API 账号用 API Key 认证。订阅账号登录很简单运行claude后它会打印一个链接浏览器打开、登录、授权回到终端就自动完成了。好处是费用包含在订阅里不用额外准备 API Key缺点是有并发和额度限制热搜词里那句“your limits are temporarily boosted. your weekly claude code limit is 50%”就是这类限制的体现。API Key 方式适合按量付费、需要更高并发或要在 CI 里用的场景。设置ANTHROPIC_API_KEY环境变量即可export ANTHROPIC_API_KEYsk-ant-api03-...需要注意API 计费和订阅是两套体系如果你用第三方模型比如后文要写的 DeepSeek设置的通常是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY。这一点很多人搞混记一下官方 API Key 用ANTHROPIC_API_KEY第三方 Anthropic 兼容接口大多认ANTHROPIC_AUTH_TOKEN。3.3 VSCode 里怎么用插件还是终端社区里对“VSCode 配置 Claude Code”的搜索热度很高其实现在有 Anthropic 官方 VSCode 扩展也可以直接在 VSCode 的集成终端里跑claude两种方式并行不冲突。官方扩展装好之后侧边栏会多一个 Claude Code 面板可以在面板里输入指令也可以把当前编辑器选中的代码直接发给它。实际体验下来面板模式更适合“问问题、看解释”因为输出排版比终端好一些真要让它改代码、执行命令、跑测试我还是习惯在集成终端里跑纯 CLI。如果你不想装插件最省事的联动方案是VSCode 里按Ctrl ~打开集成终端直接运行claude。Claude Code 会自动感知当前工作区基于打开的文件夹作为项目根目录。这个连通的妙处在于它能看到你在编辑器里的改动生成的补丁也落在当前仓库里完成之后切回编辑器直接看 diff 即可。4. 指令拆解高频斜杠命令与自然语言指令4.1 用得最多的六个斜杠命令进入交互界面后所有斜杠开头的输入都会被当成指令而不是问题。我最常用的有六个命令作用使用场景/help列出全部可用命令忘了某个命令怎么写或版本更新后想看看新功能/clear清空当前对话上下文聊偏了、跑题了重新开个清晰的话题/compact压缩当前上下文再继续上下文快爆掉但还不想放弃当前任务/model查看或切换模型想临时切到大杯模型处理复杂重构/cost查看本次会话花费关心 token 消耗时非常实用/doctor诊断环境问题排查安装、权限、网络类异常/compact是续命神器。上下文过长后 Claude 会变笨表现为“记不住你说过的话”“改 A 文件忘了 B 文件”。此时/compact会把历史对话压缩成摘要保留关键信息丢掉冗余细节继续干活。代价是压缩后它可能会丢掉一些细节重要前置条件最好在压缩后手动重复一遍。/model在接入第三方模型后尤其好用。你可以在同一个会话里切模型不需要退出重进。比如日常小改动用 fast 模型大重构切到最强的模型成本控制很直观。4.2 退出、恢复与回滚别害怕试错Claude Code 的会话状态是可以延续的。退出交互界面用/exit下次在同一个项目目录下运行claude --continue它能把上次会话的上下文恢复出来。这个特性特别适合“今天没弄完明天接着搞”的场景上下文不用从头喂。还有/rewind顺着讨论方向回滚到你指定的某一步。比如跑偏了、改坏了/rewind可以回到之前的某个节点重新开始。它不改变文件系统里的代码只重新组织对话进程。真正改坏代码想还原还是要靠 git。在交互界面里执行 git 操作也很顺手。你直接说“帮我把所有改动提交提交信息写清楚一点”它会自动git diff、git add、git commit。如果只希望它读代码不允许写代码可以用--permission-mode或后续的权限配置来控制。4.3 非交互模式一条命令完成自动化除了交互式 REPLClaude Code 最被低估的是非交互模式claude -p 解释 src/main.go entry 函数的作用 claude -p 给 README.md 补一段安装说明 --output-format json-pprint模式下它执行完就退出不会进入对话循环。结合 shell 管道可以实现很多自动化思路。比如拿到 git 改动的文件列表逐个让 Claude 补充注释git diff --name-only | xargs -I {} claude -p 为 {} 文件中的主要函数补充中文注释不要改动业务逻辑把--output-format json加上输出就是结构化 JSON可以直接被脚本解析。我甚至见过同事把它挂在 CI 里让 Claude Code 自动生成 release notes效果意外地好。自然语言指令这部分记住一个原则把要求说具体。不要只说“优化这段代码”要说“把这段代码的重复逻辑提取成一个工具函数保持对外参数不变并补充单元测试”。Claude Code 的 Agent 能力越强对指令的语义理解越敏感你的需求边界越清晰它跑偏的概率越小。5. 配置进阶项目级CLAUDE.md与全局settings5.1 CLAUDE.md让 Agent 记住项目规矩Claude Code 有一个很重要的机制叫CLAUDE.md相当于项目的“出厂说明书”。在项目根目录运行/init它会扫描项目结构并自动生成一份基础说明。这份文件会被 Claude 在每次会话启动时自动加载因此所有指令的背景信息、编码规范、常用命令都会在上下文中。我的用法是手工在这份文件里维护三类内容项目背景这个仓库是做什么的技术栈是什么目录结构怎么组织的。常用命令如何跑测试、如何启动开发服务、如何构建。注意事项哪些目录不能乱改、代码风格要求、提交规范。举个例子文件里写# 项目说明 - 后端技术栈Spring Boot 3 MySQL - 启动命令./mvnw spring-boot:run - 测试命令./mvnw test ## 代码规范 - 所有 public 方法必须有 Javadoc - 禁止直接修改 mapper XML 中的公共 SQL改动需先与 DBA 确认 - 提交信息遵循 Conventional Commits有了这些我再启动 Claude Code 让它加功能时它给出的代码风格基本和项目现有代码一致不用每次反复强调。注意别把 CLAUDE.md 写得太长它占用的 tokens 很可观。建议控制在 80 行以内平时只放最核心的约定。全局级别的~/.claude/CLAUDE.md也存在适合放个人通用的规则比如“所有代码注释使用中文”“生成代码时优先考虑可读性”。项目级文件会覆盖或补充全局文件的内容。5.2 settings.json权限控制的主动出击Claude Code 的权限模型默认是“询问式”的也就是说它要执行bash命令或写文件时会先征求你的同意。正常使用没问题但一旦它频繁读取文件、反复执行 git 命令确认弹窗会多到让人烦躁。此时可以在配置文件里预设允许/禁止列表。配置目录默认在~/.claude/settings.json项目级配置放在.claude/settings.json后者会合并到前者之上。示例片段{ permissions: { allow: [ Bash(npm run *), Bash(git *), Read(**), Edit(**), WebFetch(domain:localhost) ], deny: [ Bash(rm -rf *), Bash(sudo *), Edit(config/prod/*) ] } }Read(**)允许读取项目内任意文件Edit(**)允许编辑任意文件生产环境配置目录手动排除掉等于给 Agent 划了安全边界。团队协作时这些配置可以提交进仓库保证所有成员跑 Claude Code 的行为一致。5.3 环境变量最容易被忽略的全局开关除了配置文件Claude Code 还认一批环境变量。最常用的是这几个ANTHROPIC_API_KEY官方 API Key。ANTHROPIC_AUTH_TOKEN第三方兼容接口的认证令牌。ANTHROPIC_BASE_URLAPI 网关地址接第三方模型时核心配置。ANTHROPIC_MODEL主模型名。ANTHROPIC_SMALL_FAST_MODEL快速小模型名通常用于标题生成、摘要等轻量任务。CLAUDE_CODE_CONFIG_DIR自定义配置目录。在 Windows PowerShell 里设置环境变量用$env:ANTHROPIC_BASE_URL...在 Linux/macOS 的 bash/zsh 里用 export。建议不要把这些变量写死在系统全局而是用direnv之类的工具按项目目录隔离避免不同项目的 API 配置互相污染。6. 接入第三方模型DeepSeek与Ollama实战6.1 为什么大家一门心思想接第三方模型官方 Claude 模型的体验当然最好但订阅型号有限额、API 费用偏高重度使用的人很快就碰到天花板。社区因此衍生出一堆“给 Claude Code 换模型”的方案最主流的就是接 DeepSeek 和本地 Ollama。接 DeepSeek 能大幅降低成本接 Ollama 能完全离线、数据不出机器。两种方案我都跑过下面分别说清楚。6.2 接入 DeepSeek改几个环境变量就行DeepSeek 官方提供了 Anthropic 兼容接口这意味着 Claude Code 不需要做任何代码层面的改动只要把 API 地址和令牌指过去即可。Linux/macOS 下export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的deepseek密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claudeWindows PowerShell 对应$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKENsk-你的deepseek密钥 $env:ANTHROPIC_MODELdeepseek-chat $env:ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude这样设置后进入交互界面Claude Code 面向第三方模型发起请求模型本身是 DeepSeek。日常代码理解、补全、简单重构都没问题。但有一条要提前有心理准备Claude Code 这类 Agent 工具依赖工具调用function calling第三方模型对工具调用的稳定性不如 Claude 原生模型复杂多步操作偶尔会出现“卡住”“答非所问”“返回空结果”的情况。实测下来 DeepSeek 做阅读、解释、生成测试这类任务非常稳但让它动辄改十几个文件的超长多步任务还是容易翻车。另外注意接 DeepSeek 时登录授权那套步骤可以完全跳过不需要 Claude 账号授权因为环境变量已经喂了身份信息。如果你在项目里混合使用官方模型和第三方模型强烈建议用 cc-switch 这类工具来做配置切换管理。6.3 Ollama 本地模型与 cc-switch 组合Ollama 是本地跑大模型的一把好手支持 Llama、Qwen、DeepSeek 开源版等。接 Ollama 最纠结的点在于Claude Code 的接口协议是 Anthropic 格式而 Ollama 暴露的是 OpenAI 风格接口两者默认不兼容不能像 DeepSeek 那样直接改 base URL 就完事。社区里常见做法是本机跑 Ollama先拉取一个模型比如ollama pull qwen2.5-coder:14b。通过一个兼容层把 Anthropic API 请求转成 OpenAI 请求发给 Ollama。用 cc-switch 管理不同供应商的配置一键切换官方、DeepSeek、Ollama。cc-switch 的使用逻辑是这样的它维护多套 Claude Code 配置base URL、token、模型名每个配置是一个 profile切换时把对应配置写入 Claude Code 的 settings 或环境变量然后重启 Claude Code 即生效。选择 provider 后相当于帮你把 6.2 那些变量批量搞定不用每次手敲 export。对普通用户我的建议是本地 Ollama 方案的体验上限取决于你本机显卡和显存。7B 模型跑代码解释够用但要让它承担复杂的重构任务效果和云端商用模型差距明显。适合的场景是离线环境、隐私敏感项目、或者只是想低成本体验一下 Agent 工作流。想真的提升编码效率DeepSeek 这种云端 API 是甜点区。7. 落地避坑限流、上下文爆炸与常见报错处理7.1 官方订阅的限额问题用的过程中官方订阅模型最常见的报错就是配额相关。热搜词里那句“your limits are temporarily boosted. your weekly claude code limit is 50% hi”我遇到过不止一次。本质是 Claude 订阅套餐对 Claude Code 的用量有周级别限制一旦接近上限系统会直接提示 limits 或降低响应优先级。这不一定是你操作错误而是套餐本身的限制。应对办法有三条路等额度重置短期应急就把非关键任务往后放。换 API Key 计费按量付费不存在周配额但费用更敏感。切第三方模型DeepSeek/Ollama用 6.2 和 6.3 的配置。我个人的选择是“默认 API 聊天问复杂问题用订阅”两套体系分开用各取所长。7.2 上下文长度和 /compact 的正确姿势另一个高频坑是“上下文爆炸”。Claude Code 单次会话能承载的上下文有限当它读了一堆大文件后你问它最简单的问题它也反应迟钝甚至答非所问。原因是上下文窗口被塞满了模型“看到”的信息太多且杂。处理思路是及时清理。觉得对话开始变笨时先/context看一眼当前上下文占用比例如果占比很高直接用/compact压缩。压缩完要主动把当前任务的关键目标再复述一遍以免摘要丢失细节。如果任务彻底切换了别犹豫直接/clear开新会话不要抱着旧对话舍不得放。开新会话的代价是它需要重新读文件但这比在拥堵上下文里挣扎高效得多。7.3 几个高频报错的排查链路最后集中写几个我踩过并验证有效的高频报错。报错一EACCES: permission denied。出现在 npm 全局安装阶段原因是全局目录无写权限。解决思路是切换到 nvm 管理的 Node或手动重设 npm prefix 到用户目录不要用 sudo 硬装。报错二ENOENT找不到模块或文件。多数是当前目录不是 git 仓库或者项目路径含中文/特殊字符导致解析异常。解决先进 git 项目目录再启动路径别带空格和中文。报错三网络类错误比如connect ETIMEDOUT。常见原因是终端无法访问 Anthropic 或第三方 API 的接口域名。排查顺序是先确认环境变量里的ANTHROPIC_BASE_URL是否指错了地址再确认网络连通性。如果是公司代理环境记得设置 NO_PROXY 把内网地址排除掉。报错四model not found或 404。这在使用第三方模型时尤其常见原因是ANTHROPIC_MODEL填写的模型名在当前 base URL 指向的服务上不存在。先查一下对应平台的模型列表把名字抄准确。比如 DeepSeek 的在线模型是deepseek-chat不是deepseek-coder后者已经下线了。报错五Windows 终端里中文乱码或指令显示异常。多半是代码页编码问题。在 PowerShell 里执行chcp 65001切到 UTF-8再启动 claude一般能解决。排错时优先跑一遍claude --doctor它会自动检查 Node 版本、配置路径、git 目录、权限等关键项并给出修复建议。这个命令放在最后用因为它输出的信息比较全面能少走很多弯路。最后再分享一点我个人的体会。Claude Code 用到现在我觉得比指令清单更重要的是把CLAUDE.md写好把项目上下文喂透。工具层面积累再多命令都不如让它一上来就懂这个项目“是什么规矩”。另外模型选择真不是越贵越好日常小改动用轻量模型反而快复杂任务再上大模型成本和体验可以兼得。这篇里的命令和配置都是我在真实项目里反复验证过的照着配一遍能少踩不少坑。
