从“帮我写一个函数”到“帮我完成一次重构、跑通测试、修复编译错误”AI 编程助手的形态正在从浏览器聊天窗口走向开发者的真实工作流。Claude Code 是这条线上被讨论最多的工具之一它不是一个简单的代码片段生成器而是一个直接运行在终端里的协作代理能读取项目文件、执行命令、运行测试也能根据报错信息反复修改代码直到任务满足验收条件。这篇文章会按保姆级的节奏把 Claude Code 的完整使用链路讲清楚从环境准备、安装认证、配置文件到接入 DeepSeek、Ollama 等第三方或本地模型最后用一个最小开发任务验证整条工作流。无论你是第一次接触 Claude Code还是已经安装但不知道如何系统使用只要熟悉终端基本操作都能按文章顺序把工具跑起来。先说明一点Claude Code 的版本迭代速度很快安装命令和部分配置在不同小版本间可能有差异。下文示例以 2026 年初常见安装方式和官方文档中的命令为准实际操作时要以claude --version的输出和官方文档为最终依据。1. 先说清楚 Claude Code 的角色边界它不是编辑器是一个终端协作代理1.1 网页版 AI 助手和 Claude Code 的使用差异很多人会把 Claude Code 和网页版 Claude 混淆。网页版的使用方式是“提问 - 回答 - 复制代码”你还需要手动创建文件再把代码粘贴进去。Claude Code 的默认工作模式完全不同它会被启动在某个项目目录下拥有读取文件、写入文件、执行命令的权限可以查看 Git 状态、运行测试然后基于真实反馈修改代码。举一个典型场景。普通 AI 助手经常在“修改一个函数但忘了另一个文件里的调用方”这件事上翻车。在 Claude Code 中它会自己执行grep搜索哪些文件调用了这个函数逐个检查调用点再统一修改。这就是“代理”和“聊天机器人”的核心差别它有上下文闭环不再依赖你手动复制粘贴代码。维度网页版 AI 助手Claude Code交互位置浏览器终端读取本地文件通常不行可以限定在授权目录内执行命令不能可以运行 bash 命令修改文件复制粘贴工具直接写入并给出 diff适合任务单段代码、概念解释多文件修改、重构、排错、测试1.2 一个代理工具适合做什么不适合做什么Claude Code 适合的任务类型很明确多文件重构修改接口签名同步调整实现和调用方。排错辅助根据报错定位日志、查看代码、提出修复方案并验证。测试维护生成测试用例、运行测试、修复失败用例。小需求开发在仓库里从零实现一个内部模块。工程代码讲解让工具阅读代码后解释某个业务模块的设计。不适合的场景同样要提前知道大型架构评审上下文窗口有限无法理解超大型代码库的全部边界。高并发生产变更需要人工演练、灰度、回滚不应直接交给工具执行。安全敏感操作例如删除数据库、修改线上配置必须加人工确认环节。理解边界是使用 Claude Code 的第一课。后面的权限配置文件本质上就是在围绕这个边界做控制。2. 安装前的环境检查和依赖准备版本不匹配会白折腾一圈2.1 必须先准备的三样东西Claude Code 本身是一个 Node.js 命令行工具安装前需要确认本机环境是否满足条件。最常见的方式是通过 npm 全局安装所以 Node.js 和 npm 是硬依赖。需要准备的依赖清单依赖作用建议要求Node.jsClaude Code 运行时18.0 或更高npm包管理器安装 Claude Code 用随 Node.js 安装Git仓库操作AI 查看 diff、提交变更时使用2.x 及以上Claude 账号认证和计费基础官方订阅或 API 密钥检查命令node -v npm -v git --version如果本机还没有 Node.js建议直接安装一个长期支持版本。JDK 17 并不是 Claude Code 的强制依赖但如果你打算用它写 Java 项目再单独准备 JDK 即可。不要在没有任何版本管理的情况下随便下载安装包这样后面排查版本问题时很难判断是哪个依赖出了问题。2.2 官方安装方式和“安装包”问题安装 Claude Code 的标准命令npm install -g anthropic-ai/claude-code在某些网络环境下npm 安装可能失败。这时先检查 npm 镜像配置npm config get registry如果镜像不是官方源可以临时换成官方源重试npm install -g anthropic-ai/claude-code --registryhttps://registry.npmjs.org/安装完成后验证版本claude --version这里需要特别提醒Claude Code 是官方发布的命令行工具官方推荐安装方式就是 npm。网上流传的“Claude Code 本地部署安装包”“一键安装包”多数是针对其他开源模型或辅助工具做的打包并不是 Claude Code 本体。如果你在非官方渠道看到打包好的二进制文件要先确认它的来源、数字签名和内容不要在生产环境直接安装来源不明的软件包。2.3 项目权限也是环境准备的一部分很多人安装完工具就急着使用却忽略了权限准备。Claude Code 默认只在授权目录内读写文件不会主动遍历磁盘内容。首次在某个目录启动 Claude Code 时工具会询问是否信任该目录。加入信任列表后它才能读取文件、执行命令。如果目录里存在.claude/settings.json工具会读取其中的权限规则如果不存在则使用默认权限。不要在系统根目录或用户主目录这样的宽泛位置启动 Claude Code。推荐进入具体项目目录再启动这样工具的工作边界清晰误操作文件的风险也小。3. 安装和首次登录用最小步骤跑通官方认证3.1 从零到第一次对话的最小闭环安装完成后在终端进入一个空目录mkdir claude-code-demo cd claude-code-demo claude首次运行会提示登录常见有两种方式使用 Claude 订阅账号登录适合个人开发者。使用 Anthropic API 密钥登录适合按量计费或脚本调用。在 Claude Code 界面输入/login可以打开认证流程。按提示在浏览器中完成授权再回到终端继续使用。认证成功后界面会显示当前上下文信息。然后输入第一句话不需要太复杂请告诉我你现在位于哪个目录并简单介绍这个目录里的内容。正常输出会显示当前目录路径并提示目录为空或只有初始化文件。这意味着读取链路、权限链路、输出链路全部正常。3.2 认证成功不等于配置完成还要确认模型认证只是第一步。很多新用户接下来会遇到困惑为什么同一个提示词在不同项目里表现不一样原因通常是配置里的模型名称不一致。查看当前配置claude config list如果输出里有一项model被设置成不存在的模型名称Claude Code 启动时会提示类似错误deepseek-v4-pro is not a model this version of claude code recognizes这类报错在社区中出现频率很高。原因主要有两个一是配置文件里的模型名写错了二是当前版本或服务商并不支持该模型名称。排查思路会放在第 7 节展开。3.3 常用斜杠命令还没开始写代码前先记住Claude Code 运行后输入/help可以查看全部可用命令。以下高频斜杠命令值得先记下来命令作用/status查看当前任务的自动提交记录和状态/compact压缩上下文长会话中减少 token 消耗/clear清空当前对话历史/cost查看当前会话消耗/config查看或打开配置文件位置退出时输入/exit或按CtrlC。再次进入同一个目录时Claude Code 会保留一定程度的会话恢复能力但跨目录调用或长期会话最好依赖/compact管理上下文不要指望自动恢复解决所有问题。4. 配置文件和常用参数改之前先弄懂每个参数影响什么4.1 配置文件层级和优先级Claude Code 的配置分为多个层级搞清楚优先级是排查“我的配置为什么不生效”的前提。配置层级路径生效范围项目级项目目录/.claude/settings.json只影响当前项目用户级~/.claude/settings.json影响当前系统的所有项目环境变量shell 中 export 设置临时覆盖影响当前进程优先级大致是项目级配置优先于用户级配置用户级配置优先于默认配置。遇到“配置没生效”时先确认你改的到底是不是当前项目正在读取的那份文件。创建项目级配置{ permissions: { allow: [ Bash(npm run *), Read(./src/**) ] }, model: claude-sonnet-4-5, env: { MY_CUSTOM_ENV: example } }4.2 高频参数含义和调整影响重点解释几个高频参数。model指定使用的模型。设置错误会出现模型识别失败表现形式就是启动时报错 “is not a model this version of claude code recognizes”。遇到这种情况先把配置清掉回到默认模型跑通再确认服务商到底支持哪个模型名称。permissions.allow允许工具在执行某些操作前不弹确认。写法要尽量窄例如Bash(npm run *)只匹配以npm run开头的命令。不要直接写Bash(*)否则 AI 可以执行任意命令等于把当前项目机器完全交给模型控制。permissions.deny显式禁止某些操作例如禁止读取生产环境密钥文件、禁止强制推送。env注入环境变量。注意不要把真实密钥长期写进项目配置文件因为项目文件会进入 Git存在密钥泄露风险。参数错误配置的表现差异很大用一张表格概括参数调大/加宽的影响调小/收紧的影响错误配置的表现model模型能力更强消耗更大更省 token模型名称不支持时报错permissions.allow减少打断自动化程度高确认频繁更安全允许过宽会执行危险命令maxTokens单次输出更长输出容易截断代码生成不完整env注入更多配置缺少自定义变量工具读不到所需变量4.3 配置文件该不该提交到 Git这里要分情况讨论。.claude/settings.json如果只包含权限规则和工具启停配置可以提交到仓库方便团队统一。如果里面包含真实 token、密钥、个人登录态就不能提交。推荐方式维护一份settings.sample.json作为配置模板真实配置放在本地并加入.gitignore。这是多成员项目最稳妥的做法。5. 接入其他模型和本地模型Claude Code 不只能连默认服务5.1 为什么会有“接入 DeepSeek、Ollama 本地部署”的需求Claude Code 默认调用的是 Anthropic 官方模型服务。但很多人希望在已有工作流里把模型推理部分切换到更便宜、更可控甚至运行在本地的大模型。“Claude Code 接入 DeepSeek”“Ollama 本地部署”这些搜索热点本质都是一件事复用 Claude Code 的终端工作流把模型改成其他服务商或本地模型。实现原理其实不复杂Claude Code 支持通过环境变量或配置指向一个兼容 Anthropic API 格式的服务端点。只要目标服务提供兼容接口就能让 Claude Code 通过该接口调用模型。注意Anthropic 官方模型能力与第三方模型并不完全对等。接入第三方或本地模型后Claude Code 的工具调用链路仍然能工作但模型本身的推理水平、指令遵循能力会直接影响最终效果。不要因为能接上模型就认为它能完整替代官方模型的表现。5.2 通过环境变量接入兼容服务通用做法是设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN把 Claude Code 的请求指向自定义端点。export ANTHROPIC_BASE_URLhttps://your-compatible-endpoint.example.com export ANTHROPIC_AUTH_TOKENyour-token export ANTHROPIC_MODELyour-model-name claude这里的ANTHROPIC_MODEL设置模型名称。如果端点不认识这个名称就会报出类似 “is not a model this version of claude code recognizes” 的错误。遇到这类报错先确认当前终端是否残留了自定义端点的环境变量。Windows PowerShell 下$env:ANTHROPIC_BASE_URL https://your-compatible-endpoint.example.com $env:ANTHROPIC_AUTH_TOKEN your-token $env:ANTHROPIC_MODEL your-model-name claude5.3 接入 Ollama 本地模型的示例如果本机安装了 Ollama并拉取了qwen2.5-coder:7b等模型可以尝试把 Claude Code 指向本地服务。先确认模型存在ollama list如果列表里已有模型说明本地推理服务可用。Ollama 默认 API 地址通常是http://localhost:11434但 Ollama 原生 API 与 Anthropic 消息格式并不完全一致直接设置ANTHROPIC_BASE_URL不一定能成功。通常需要额外安装一个支持 Anthropic 兼容格式的本地网关层再把ANTHROPIC_BASE_URL指向网关地址。具体安装步骤依赖网关工具版本落地前要阅读网关工具自己的 README确认环境变量名和请求格式不要照抄网上过期教程。接入成功后用一句话验证请用中文解释什么是函数柯里化并给出一个 TypeScript 示例。如果输出来自本地模型说明链路已经打通。但要注意本地小参数模型在复杂代码任务上准确度会明显偏低适合用来学习流程和验证配置不适合直接用于生产级代码审查。5.4 接入 DeepSeek 等在线第三方时要注意什么接入在线第三方服务时下面几点优先确认服务商是否提供 Anthropic 兼容接口还是需要自己搭网关转换。接口地址是否支持 HTTPS密钥是否只放在环境变量里。模型名称是否在服务商官方文档中列明不要自己猜测。调用速度、并发限制、计费方式是否适合你的使用场景。“Claude Code 接入 DeepSeek”在社区里讨论度很高但从技术原理看和接入任何兼容端点没有本质区别。具体的 API 地址、模型名称会随服务商更新变化实际配置前务必以服务商最新文档为准。6. 用一个小需求完整走一遍开发闭环从任务描述到测试通过6.1 一个适合第一次练习的多文件任务为了验证 Claude Code 的真实工作流这里设计一个简单但完整的任务在一个空 Node.js 项目中实现一个统计文本中单词出现频率的命令行工具。任务包含仓库初始化、模块设计、实现、测试、运行验证适合作为第一次完整使用 Claude Code 的练习。mkdir word-freq cd word-freq claude在对话中输入需求尽量把验收条件写清楚在这个目录下创建一个 Node.js 命令行工具。需求如下 1. 读取命令行传入的文件路径。 2. 统计文件中单词出现次数忽略大小写和标点。 3. 按出现次数降序输出相同次数按字母升序。 4. 使用 Node.js 内置模块完成不引入第三方依赖。 5. 提供 npm test 可运行的测试。提示词里的每一条都对应一个验收点。给 AI 明确验收条件比笼统地说“写个工具”要有效得多。6.2 AI 生成代码时你要观察什么Claude Code 会创建文件并运行命令。在关键节点它会停下来请求确认。例如创建package.json创建src/index.js运行node src/index.js验证输出创建test/index.test.js你应该关注文件是否都在当前项目目录内。包名、入口文件是否合理。测试是否覆盖了大小写、标点、空文件等边界。命令是否只影响当前项目目录。如果想确认工具对项目的理解可以追问请解释你刚才的目录结构和每个文件的作用。这能帮你判断它是否真的理解了需求。6.3 运行测试不是看“能启动”就够了假设 Claude Code 生成的文件结构是word-freq/ package.json src/index.js test/index.test.js在终端执行npm test预期看到测试全部通过。再用一条真实文本验证echo Hello world. Hello Claude Code. sample.txt node src/index.js sample.txt预期输出hello: 2 claude: 1 code: 1 world: 1如果输出和预期不一致把报错信息贴回 Claude Code 对话让它继续修复。这个“运行 - 报错 - 修复 - 重跑”的迭代闭环是 Claude Code 最有价值的地方。6.4 任务完成后的检查清单AI 辅助开发完成后建议按清单检查所有文件是否在当前项目目录内没有意外改动外部路径。代码是否引入了不必要的第三方依赖。测试是否覆盖了主要输入边界。是否查看了关键 diff而不是直接全盘接受。是否把敏感信息留在代码或配置里。Git 提交信息是否清晰可追溯。这份清单适合作为 AI 辅助开发的通用检查项不只是针对 Claude Code。7. 常见的 6 类报错和排查路径按现象倒推根因7.1 排查逻辑先从“输入是否正确”开始Claude Code 的报错形式很多但大部分根因集中在少数几层。遇到问题按下面顺序排查配置里是否设置了自定义模型端点或模型名称。当前 shell 环境变量是否残留旧值。依赖版本是否匹配。是否在授权目录内启动。网络和认证状态是否正常。日志中是否有具体的错误信息。7.2 常见报错速查表问题现象常见原因检查方式处理建议启动报错 “is not a model this version of claude code recognizes”配置或环境变量中的模型名称在当前版本/服务商中不存在执行claude config list和env | grep -i anthropic清空自定义 model或改为服务商文档列出的模型名安装命令提示 npm 权限不足全局目录无写权限npm prefix -g查看安装目录用 nvm 管理 Node避免直接改系统目录权限提示无法读取项目文件没有信任当前目录查看启动时是否出现信任确认确认目录确实需要授权后再允许访问执行命令时一直被拒绝permissions 配置不够宽查看.claude/settings.json的 allow 和 deny按需增删允许前缀不要放开 Bash(*)认证成功但会话无法恢复换目录或缓存被清理查看启动提示和会话保存路径重要上下文用/compact或写成任务文档接入本地模型后回复慢或乱答本地模型参数太小或网关格式转换错误查看本地服务日志和请求地址先跑通最简单的对话再逐步增加工具调用7.3 模型名报错专项排查在“Claude Code 接入 DeepSeek 或本地模型”的场景中最典型报错就是模型名不被识别。逐步排查# 1. 检查当前是否有自定义 base url 或模型名 env | grep -i ANTHROPIC # 2. 查看 Claude Code 当前配置 claude config list # 3. 临时清空自定义模型名回到默认如果确认没有自定义配置但模型名仍不被识别常见原因是本机缓存了过期配置或版本过旧。先重启终端再更新到最新版本npm update -g anthropic-ai/claude-code如果问题依旧备份自己的自定义配置后清除 Claude Code 的本地缓存目录再启动。7.4 日志和反馈是最后的证据很多用户遇到问题只贴一句报错很难定位。排查时可以让 Claude Code 提供完整的运行信息请把刚才运行测试的命令、完整输出和退出码贴出来。同时执行最小化还原清空自定义配置、使用默认模型、在最小目录中测试。这一步能过滤掉大量干扰因素。8. 放进生产环境前这几个工程习惯必须补齐