最近这两周我一直在折腾 Claude Code本来只是抱着“终端里也能聊代码”的心态试了试结果一用就停不下来了。尤其是把自定义模型参数、项目级配置、甚至自建的 API 网关都串起来之后整个体验跟网页版完全不在一个层级。今天不写功能列表就把我从安装到配置、再拿它实际跑任务踩过的坑和顺手沉淀下来的心得一次性讲清楚。如果你平时主要用 VSCode 写代码或者经常在服务器、SSH 环境里做开发又不想在浏览器和编辑器之间来回切换那这篇内容可以直接照着抄。当然如果你是第一次接触 Claude Code我也尽量把前置概念补完整保证你能从零开始复现整套流程。1. 项目概述Claude Code 到底是个什么工具Claude Code 是 Anthropic 官方的命令行 AI 助手它不像普通聊天框那样只给你返回一段建议而是可以真正活在终端里直接读写你的项目文件、执行命令、跑测试、提交代码。说直白点它把“AI 编程助手”从网页对话框里搬到了你日常写代码的环境里而且是以 Agent 的形态工作。1.1 它能做哪些事我实际使用下来最常让它干的事情有这几类项目代码问答把整个仓库喂给它直接问“这个模块的入口在哪里”“当前有哪些 TODO”它能结合上下文给出准确回答。批量代码修改比如跨文件重命名、接口替换、重构某个公共函数它可以直接改文件不需要我逐个打开。自动生成单元测试给它一个函数或类它能生成可运行的测试并且跑给你看。执行命令与脚本它可以在终端里执行 shell 命令比如安装依赖、跑构建、运行测试然后把结果反馈给你。辅助提交代码它能够帮你整理变更内容、生成规范的 commit message甚至直接执行 git 操作。这几种能力组合起来Claude Code 就不再是“聊天机器人”更像是一个坐在你旁边、随叫随到的终端副驾。1.2 为什么值得折腾它我见过不少人觉得“网页版 Claude 已经够用了”但一旦你开始处理真实项目就会发现网页版最大的瓶颈是它看不到你的代码。每次都要手动复制粘贴效率太低而且上下文经常超出限制。Claude Code 的价值在于它默认就是跑在你的本地项目目录里能通过内置的 Read、Write、Glob、Grep 等工具去自主探索代码库。你只需要给它一个目标它会自己决定看哪些文件、改哪些文件、跑哪些命令。配合自定义模型配置还可以根据任务难度动态切换模型成本、速度、效果都能自己掌控。适合折腾的人主要有三类经常写脚本和工具类项目的开发者、需要批量重构的老项目维护者以及想在 CI 或远程开发环境里使用 AI 助手的人。如果你只是偶尔写几行代码那直接网页版也行但如果你是高频开发者值得花时间把手上的工作流迁移过来。2. 安装与认证全流程先说安装这里最容易踩坑的部分不是装不上而是装完之后不知道怎么登录和初始化项目目录。我建议严格按下面的顺序走能省不少事。2.1 安装前的环境检查Claude Code 官方依赖 Node.js虽然它也有原生安装脚本但核心运行时依然是 Node。所以第一步先确认你的机器上有 Node.js而且版本不能太老。官方要求 Node 18 以上我自己是 20 版本运行起来很稳定。如果你机器上版本过低安装时会直接报错甚至装完也无法启动。建议先跑一句node -v npm -v如果输出的版本号低于 18先去 Node 官网装一个新版。安装完成之后建议顺手把 npm 镜像源配好不然国内网络环境下下载依赖可能会很慢。注意这里我说的是 npm 镜像源而不是任何非官方网络代理任何绕过限制的手段都不在讨论范围内。2.2 三种安装方式怎么选Claude Code 安装方式主要有三种我分别试过简单说下差异。第一种是 npm 全局安装适合大多数开发机npm install -g anthropic-ai/claude-code安装后直接运行claude就能启动。这种方式的优点是升级方便一条命令搞定。缺点是对 Node 版本有要求如果系统自带 Node 版本太老需要你自己维护 Node 环境。第二种是官方原生安装脚本适合不想依赖 Node 全局环境的场景curl -fsSL https://claude.ai/install.sh | bash脚本会把 Claude Code 装在用户目录下并自动配置好环境变量。这种方式对已有 Node 环境的冲突更小而且升级也比较方便。第三种是 VSCode 扩展安装适合主要用 VSCode 写代码的人。直接在 VSCode 扩展市场搜索“Claude Code”找到 Anthropic 官方发布的扩展点击安装即可。扩展本质上是把命令行的 Claude Code 包装成了编辑器内可交互的界面所以核心还是需要命令行环境可用。我个人建议如果是快速试用直接用 npm 全局安装如果你需要长期稳定使用并且不想被 Node 版本折腾可以用原生安装脚本如果你日常工作流都在 VSCode 里建议第二种安装方式配合 VSCode 扩展一起用。2.3 登录认证与项目初始化安装完成之后在终端输入claude首次启动会要求你登录 Anthropic 账号。正常情况下会跳转浏览器完成授权然后回到终端就可以开始对话了。有几个细节值得注意登录状态会保存在本地配置文件中后续不需要重复登录。如果机器上配置了ANTHROPIC_API_KEY环境变量Claude Code 会优先使用 API Key 认证不会走 OAuth 登录流程。对于服务器场景这两种方式都可以但 API Key 更适合无人值守环境。如果你是在某个已有项目目录里启动claude它会自动把当前目录作为工作根目录。首次使用建议先运行claude并随便问一句“当前目录结构如何”让它确认能正常读取文件。初始化完成后项目根目录下会生成一个.claude文件夹里面可以放置项目级配置文件。后面讲自定义模型的时候这个文件夹里的 settings.json 是核心。3. 自定义模型配置把默认模型换成自己需要的Claude Code 默认使用的模型通常是 Anthropic 官方的旗舰模型但实际开发中不一定总是需要最强模型也不是所有人都希望把请求直接打到官方接口。这个章节讲的就是如何把模型“自定义”成自己想要的样子。3.1 理解模型选择Opus、Sonnet、HaikuClaude 系列目前常见的几个模型定位分别是Opus 系列性能天花板适合复杂推理、架构设计、大范围重构但响应慢、成本最高。Sonnet 系列均衡型速度与质量兼顾大多数编码任务用它最合适。Haiku 系列轻量快速适合简单问答、格式化、生成模板成本最低。Claude Code 允许你在不退出对话的情况下切换模型。最简单的方式是在对话中输入/model会弹出可选模型列表直接选择即可。也可以在启动时指定claude --model claude-sonnet-4-5这里的模型 ID 只是一个示例具体以你账号可用的模型列表为准。官方文档里会给出当前最新的模型 ID建议每次配置前先看一眼。用/model切换是临时的一旦对话结束下次启动还会回到默认模型。要长期固定某个模型需要靠环境变量或配置文件。3.2 通过环境变量固定模型在 shell 配置文件里加上export ANTHROPIC_MODELclaude-sonnet-4-5这样每次启动 Claude Code 都会默认使用你指定的模型。这个配置对 VSCode 扩展里的集成终端同样生效因为扩展会继承你的 shell 环境变量。如果你同时在多个项目里使用不同的模型环境变量就没那么灵活了。更推荐的做法是项目级配置文件。3.3 用 settings.json 管理项目级模型在项目根目录的.claude/settings.json里可以定义该项目专属的配置。举个例子{ model: claude-sonnet-4-5, permissions: { allow: [ Read, Glob, Grep, Write ], deny: [ Bash(npm run lint) ] } }配置文件的优先级从高到低依次是命令行参数 环境变量 项目.claude/settings.json 用户目录~/.claude/settings.json。也就是说你在对话中临时用/model切换的模型只在当前会话有效不会覆盖持久化配置。这里我还要提一个细节permissions是很多人忽略的功能。Claude Code 会在执行写文件、跑命令等敏感操作前请求授权通过配置文件里的 allow/deny 规则可以自动化一部分操作减少交互确认。比如我自己的常用项目里允许它自由读写文件但明确禁止执行某些危险命令。3.4 通过 ANTHROPIC_BASE_URL 接入自定义 API 端点“自定义模型”除了切换 Claude 官方不同型号之外还有一个高级玩法通过环境变量把自己的 Claude Code 请求指向一个兼容 Anthropic API 的自建网关。做法是在 shell 环境里添加export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKENyour-token这个场景适合以下团队公司内部希望统一审计所有 AI 请求不想让每个开发者的 Key 直接暴露。需要通过内部网关做模型路由比如把简单任务分流到 Haiku把复杂任务交给 Opus。需要在某个隔离环境里离线开发统一走内部代理服务。要注意的是你的网关必须兼容 Anthropic 的 API 协议否则 Claude Code 无法解析响应。我自己测试下来最常见的坑是网关返回的字段结构和官方不完全一致导致 Claude Code 报“format invalid”错误。如果你没有这种基础设施不建议贸然配置。这个话题点到为止重点是你得理解 Claude Code 并不是只能连官方接口它把自定义能力开放给了用户。至于要不要用、怎么用取决于你的网络环境和团队规范别硬来。4. 实操体验用 Claude Code 完成一个真实任务说了这么多配置下面给你看一个完整的实战记录。我用一个小项目来演示包括代码优化、生成测试、运行测试和提交 commit这基本覆盖了日常开发里最常见的几个使用场景。4.1 准备一个测试项目我在本地新建了一个文件夹claude-demo里面放了一个 Fibonacci 的递归实现# fib.py def fib(n): if n 1: return n return fib(n - 1) fib(n - 2) if __name__ __main__: print(fib(30))同时初始化了 gitgit init然后启动 Claude Codeclaude4.2 对话过程与 Claude Code 的执行逻辑我的第一句话是请分析当前目录结构重点看看 fib.py然后把它改成高性能版本补充单元测试并把测试跑通。Claude Code 接收到指令后先是用了 Glob 和 Read 工具查看了当前目录里的文件接着直接调用了 Read 读取了 fib.py 的内容。很快它给出了修改方案将递归算法改为带缓存的记忆化递归或者直接用循环迭代增加test_fib.py包含几个典型边界值修改完成后自动运行 pytest。我在终端里看到它请求执行命令的授权提示因为要运行 pytest我允许了。随后它创建了新的fib.py和test_fib.py并执行了测试。最终输出显示 5 个测试全部通过。这中间有个小插曲它最开始想用functools.lru_cache但考虑到演示项目的简单性我让它改用循环迭代实现这样不引入额外依赖代码也更直观。它重新改写并再次运行测试效率很高。修改后的fib.py大致是def fib(n): if n 0: raise ValueError(n must be non-negative) if n 1: return n a, b 0, 1 for _ in range(2, n 1): a, b b, a b return b测试文件里覆盖了fib(0)、fib(1)、fib(10)、fib(20)和负数参数抛异常的情况。4.3 把 AI 纳入 Git 工作流测试通过之后我又让它帮我提交代码。我直接说请帮我为当前改动生成 commit message并执行 git commit。Claude Code 运行了git diff分析了变更内容然后自动执行了git add -A和git commit -m Optimize fib implementation and add tests。整个过程不需要我手写 commit message。接着我让它回顾一下整个仓库的文件状态确认没有残留临时文件。它运行了git status和目录扫描确认干净后才结束任务。这一套流程走下来我的感受是它在处理“小范围、目标明确”的任务时非常可靠但你必须给它足够明确的边界比如“只看这个文件”“只允许运行 pytest”否则它可能会做出超出预期的操作。4.4 常用提速技巧经过一段时间的使用有几个让体验更顺畅的小技巧用/memory让 Claude 记住项目偏好比如“测试框架使用 pytest”“禁止修改 src/ 目录之外的文件”它会存储在本地配置中后续对话自动生效。在 prompt 里主动声明约束条件比如“只修改 fib.py其他文件不要动”这样能减少权限确认次数。临时切换模型跑不同任务简单问题用 Haiku复杂重构切 Opus避免每次都等大模型慢吞吞思考。如果你是先用网页版 Claude 整理了方案再想让 Claude Code 实际执行可以把方案直接贴给它效率更高。5. 与 VSCode 的深度集成目录式开发环境里终端是主战场。但很多人还是在 VSCode 里写代码所以在编辑器里集成 Claude Code 也能显著提升效率。这里我重点讲 VSCode 配置的注意点。5.1 安装官方扩展在 VSCode 扩展市场搜索“Claude Code for VSCode”安装量最高的那个是 Anthropic 官方发布的。安装后左侧边栏会多出一个 Claude Code 图标点击可以打开对话面板。如果你已经通过命令行完成了登录认证扩展会直接复用同一份账号状态一般不需要重复授权。如果扩展一直提示未登录可以用命令行跑一次claude确认正常后再回到 VSCode 里刷新。扩展的核心功能有两个一是在编辑器里直接打开 Claude Code 面板可以选中代码发过去二是在 VSCode 内置终端里调用claude命令把终端复用到当前项目。我一般更习惯第二种因为面板模式有时候对终端输出支持不够直观。5.2 配置编辑器级模型VSCode 扩展本身也支持自定义模型。最简单的做法是在 VSCode 的settings.json里添加{ claudeCode.model: claude-sonnet-4-5 }这个设置最终会覆盖到扩展启动的 Claude Code 会话。不过要注意扩展里的设置优先级通常低于环境变量如果你在 shell 里已经设置了ANTHROPIC_MODEL可能还需要在 VSCode 的终端环境里同步配置。我踩过的一个小坑是通过 GUI 启动的 VSCode 不一定继承 shell 里设置的ANTHROPIC_MODEL变量导致面板里用的模型和终端里不一致。解决办法是不要在 VSCode 里手动设置模型而是统一在~/.claude/settings.json里配置这样所有入口都读取同一份配置。5.3 远程开发与容器场景VSCode 的 Remote-SSH 和 Dev Containers 场景下Claude Code 也能正常工作。核心要点是远程机器上需要先安装 Claude Code 并完成认证。如果你使用 API Key 认证把ANTHROPIC_API_KEY环境变量配置到远程环境里。项目目录必须放在远程机器上Claude Code 才会在这个工作区内读写文件。我在一个 Ubuntu 服务器上试过安装命令和本地完全一样只是登录授权需要在远程终端里完成。远程开发时配合ANTHROPIC_BASE_URL指向内部网关可以让所有加入服务器的开发者统一走同一套模型路由管理和审计都方便很多。6. 常见问题与排查技巧实录最后这部分是纯踩坑记录。我遇到过的问题不少挑几个典型的写出来给后来人省点时间。6.1 安装时报 Node 版本过低这是最常遇到的安装失败原因。报错信息一般是Engine not compatible或者Unsupported engine。排查方法很简单node -v如果版本低于 18用 Node 版本管理工具比如 nvm切换到新版。切换完成后记得重新打开终端确认 npm 全局路径正常。6.2 登录认证失败或 OAuth 流程中断首次运行claude时终端会输出一个网址要求你打开浏览器授权。如果点击后没有跳转成功或者终端一直等待先检查是不是浏览器没有正确打开。可以手动复制终端里的完整链接到浏览器中访问登录后回到终端按回车。如果公司网络环境限制较多授权页面打不开我更推荐直接用 API Key 方式。在终端里先设置export ANTHROPIC_API_KEYyour-api-key再运行claude即可跳过 OAuth 登录。注意 API Key 要妥善保管不要提交到 git 仓库里。6.3 启动时提示可用性相关错误如果你在启动时看到类似“Claude Code might not be available in your country”或者“check supported countries”之类的提示说明当前账号或网络环境不在官方支持范围内。遇到这种情况我建议先确认官方文档中的支持地区清单使用官方支持的账号或环境继续不要尝试任何非官方手段去改变区域判断。这类限制违反服务条款而且容易引发账号安全问题。如果你是通过自建 API 网关绕过官方接口限制的思路也请先确认这样做是否合规我个人的经验是尽可能在官方支持范围内使用这样才能长期稳定。6.4 模型调用时报错或返回为空这类问题的原因多半是模型 ID 写错了或者你的 API Key 没有该模型的访问权限。Claude Code 里查询当前可用模型最简单的方法是claude --help看看帮助信息里有没有列出模型相关选项或者打开官方模型列表确认 ID。另外有些团队用网关时网关后端只开放了部分模型也会导致调用失败。遇到这个情况先直接用官方接口跑一个最小请求确认 Key 和模型 ID 没问题后再排查网关配置。6.5 上下文超长与性能变慢如果你让 Claude Code 读取了整个仓库下的大量文件它可能会因为上下文过长而反应变慢甚至提示超出上下文限制。解决办法是不要直接说“看下整个项目”而是给出明确路径或文件名比如“看 src/utils/string.ts”。如果你确实需要全局分析先构建一个仓库索引再让 Claude 基于索引分析效果会好很多。另外复杂任务下如果等待时间过长可以临时用/model切换成 Haiku 模型去处理轻量步骤最后再用 Opus 做最终修改能明显降低等待时间。6.6 权限确认过于频繁Claude Code 出于安全考虑每次要运行 Bash 命令或写文件时都会请求授权。如果你的信任度足够可以在.claude/settings.json里配置 allow 规则允许它自动执行常见命令这样就不用每次都点确认。但我不建议把 Bash 全部放开尤其是网络请求、删除文件这类高风险操作建议保留手动确认。我自己的实践是只放行 Read、Write、Glob、Grep 和 pytest/git 这类安全命令其他一律手动确认安全性和效率都兼顾。上面这些内容基本覆盖了我这段时间折腾 Claude Code 和自定义模型的主要路径。从安装到配置从命令行到 VSCode 集成从真实任务到问题排查每一步都有对应的场景和解决方案。如果你也准备把它纳入日常工作流我建议先从一个小项目开始跑通整个闭环之后再逐渐把更复杂的任务交给它。最后再分享一个小技巧Claude Code 的配置文件是可以版本管理的我会把.claude/settings.json提交到项目仓库里团队里每个人都用同一套模型和权限配置省去了大量互相沟通的成本。不过要注意配置文件里不要写入任何密钥信息API Key 一律通过环境变量或密钥管理服务注入这一点非常重要。