Claude Code 是 Anthropic 官方推出的终端编程智能体。简单说你可以在终端里通过自然语言让它读取项目文件、分析代码逻辑、执行命令、修改代码它不再只是一个聊天窗口而是真的会在你的项目目录里干活。安装完成后第一次让它改你手头的代码那种体验和普通问答完全不同。这篇教程我会把你从零带到完成第一次真实的代码修改从环境准备、安装登录、基本操作到配置和排错全部过一遍踩过的坑也会一并交代清楚。1. 先弄明白 Claude Code 能干什么1.1 它到底是不是普通的AI 聊天助手很多人会把 Claude Code 和网页版 Claude 混为一谈这是最大的误解。网页版你复制代码进去它给你一段结果你再手动粘回文件。Claude Code 则直接运行在项目的目录上下文里它能自己浏览你的文件结构、读取指定文件的内容、通过正则或语义定位问题点然后直接修改磁盘上的文件。你可以把它理解成一个带手脚的 AI 开发伙伴你不光能问它问题还能授权它真正动手改文件、跑命令、查报错。它和传统 IDE 里的补全插件也不一样。补全插件做的是你写一行它续一行Claude Code 做的是你给一个目标它自己决定改哪些文件、怎么改、改完怎么验证。比如我给它一个任务调整项目里订单模块的金额计算逻辑统一四舍五入到小数点后两位并补上对应单元测试它会自己找到相关文件、动手修改、给出 diff 说明甚至帮你把测试跑起来。这已经不是自动补全而是代理式开发。1.2 哪些场景最值得用哪些场景别硬用从实际使用来看下面这些场景 Claude Code 的表现是明显超出预期的历史项目的快速接手。进入一个陌生代码库你只需要让它梳理这个模块的调用链并说明核心逻辑它能很快产出一份相对靠谱的导读。常见需求改造。比如改函数签名、调整接口参数、批量替换写法、给老代码加日志这类需求描述清楚之后它完成度很高。报错排查。把编译错误、运行异常扔给它它会结合上下文去定位很多时候比复制错误信息去搜索引擎高效得多。批量重构。比如把一个公共方法从工具类里抽出来或者在多个文件里统一修改 API 调用方式。反过来有些场景我不建议硬用。比如代码量巨大但毫无结构的遗留系统Claude Code 也会在阅读范围上栽跟头再比如你对代码正确性有极强要求的生产核心模块AI 改完必须有代码评审兜底。嵌入式项目例如 STM32 的工程目录里那些庞大的 HAL 库和寄存器定义它读得过来但如果文件太多、编译体系复杂效率会下降需要你把范围缩小到当前要改的目录。1.3 适合哪类开发者只要你平时要跟命令行打交道基本都适合试试。前端、后端、脚本爱好者、运维、算法同学都能用上。纯小白也不用紧张安装流程只需要三步装 Node.js、装 Git、用 npm 装 Claude Code。真正需要你理解的部分在于两点一是模型是怎么被调用的二是文件修改权限怎么管。这两点我会在后面用专门的小节说明白。2. 安装前必须先备好的三样东西2.1 Node.jsnpm 能跑起来的前提Claude Code 本质是一个 npm 包因此系统里必须有 Node.js 18 或更高版本。很多人卡在这一步我先说最简单的安装方式。Windows 用户直接去 Node.js 官网下载 LTS 版本安装包一路点下一步即可。装完打开终端验证一下node -v npm -v能看到版本号就说明 Node.js 和 npm 都正常了。macOS 用户建议用 Homebrewbrew install nodeLinux 用户根据发行版选择Ubuntu/Debian 可以用 aptCentOS/RHEL 可以用 yum。不过我更推荐用 nvm 这类版本管理工具来装 Node.js它可以让你在不同 Node 版本之间自由切换也能尽量避免全局安装时的权限问题。比如装 Node 20nvm install 20 nvm use 20个人经验不要图省事装那种一键环境包很容易出现 PATH 混乱、npm 版本不一致后面排查问题反而更费时间。2.2 Git让 Claude 了解项目变更、生成 diffClaude Code 在真实项目里工作离不开 Git 的帮助。它需要 Git 来查看文件变更记录、生成统一的 diff、理解你当前分支的状态。所以 Git 必须提前装好。Windows 下载 Git for Windows 安装包装完在终端验证git --version。macOS 用brew install git。Linux 用sudo apt install git或sudo yum install git。装完记得配置你的用户名和邮箱Claude Code 帮你提交代码时也会用到这两个信息git config --global user.name Your Name git config --global user.email youexample.com2.3 一个顺手的终端环境Claude Code 是终端交互式工具终端环境直接影响体验。Windows 用户千万别用老旧的 cmd 窗口建议装 Windows Terminal配合 PowerShell 使用。Windows Terminal 对颜色渲染、Unicode 字符、鼠标交互的支持都好很多。如果你平时做 Linux 开发更推荐直接启用 WSLWindows Subsystem for Linux在 Ubuntu 环境里跑 Claude Code。WSL 的安装很简单wsl --install重启电脑之后系统会自动装好 Ubuntu后续的 Node.js、Git、Claude Code 都在 Linux 环境里操作很多 Windows 特有的路径问题、权限问题都不会遇到。3. 安装、登录、升级的全过程3.1 npm 全局安装 Claude Code环境备齐之后安装本身只有一条命令npm install -g anthropic-ai/claude-code执行完验证一下claude --version看到版本号说明安装成功。如果你所在网络环境访问 npm 官方源速度很慢可以把 npm 源切换为镜像源这是社区通用的合规加速方式npm config set registry https://registry.npmmirror.com之后再安装速度会明显提升。安装完成后如果提示claude: command not found大概率是 npm 全局 bin 目录不在 PATH 里。Windows 下 npm 通常会自动配置好macOS/Linux 下可以手动把全局 bin 目录加入 PATHexport PATH$(npm prefix -g)/bin:$PATH想永久生效就把它写到~/.bashrc或~/.zshrc里。3.2 登录认证的两种方式安装完成后在终端输入claude首次运行会进入登录流程有两种认证方式可供选择。第一种是 Claude 订阅账号登录。你会在终端看到一个链接浏览器打开后完成授权系统会给出一串授权码粘贴回终端即可。这种方式适合个人开发者订阅包含的额度内不需要额外支付 token 费用。第二种是 API Key 方式。前往 Anthropic Console 创建 API 密钥然后设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxxWindows PowerShell 下用$env:ANTHROPIC_API_KEYsk-ant-xxxx用 API Key 方式按 token 计费适合团队和自动化场景也更容易控制预算。设置完成后重新运行claude看到欢迎信息就是认证成功。3.3 报错organization has disabled claude subscription access很多公司会用 Claude Team 或 Enterprise 账号管理员工权限。如果你用的是组织账号管理员可以在后台关闭 Claude Code 的订阅访问权限这时登录会出现提示your organization has disabled claude subscription access for claude code这不是安装问题而是权限策略问题。解决办法有三个找管理员开启该权限换用个人订阅账号登录或者干脆改用 API Key 方式绕开组织订阅的限制。第三种方式在开发环境里最常见尤其适合有独立预算的团队。3.4 升级与卸载Claude Code 迭代速度很快升级命令同样简单npm update -g anthropic-ai/claude-code升级完重启会话即可。如果哪天不想用了npm uninstall -g anthropic-ai/claude-code另外提一句Claude Code 也有桌面版客户端本质上还是包了一层 CLI。如果你不熟悉命令行桌面版确实友好一些但实际还是建议先学会 CLI 方式因为后面接 VS Code、接远程服务器、接本地模型全是命令行思维。4. 第一次完成真实代码修改4.1 进入项目目录启动会话安装认证完成后在任意项目目录下运行cd my-project claude这就是第一个关键点Claude Code 的上下文基于你启动时所在的目录。它默认只访问当前项目范围想让它修改某个文件就先把终端切到那个项目里。不要在一个无关目录里启动然后让它去改别处的文件既容易权限混乱也不安全。启动后你就处于交互会话中可以直接用自然语言提需求。几个基本命令先记一下/help查看所有可用命令/clear清空当前对话上下文开始新话题/exit退出会话CtrlC取消正在进行的操作4.2 一个完整示例让 Claude 修改 Python 函数假设项目里有个data_clean.py内容大致是def process_data(rows): cleaned [] for row in rows: cleaned.append(row.strip()) return cleaned这个函数有两个问题空字符串没有被过滤原始大小写也没有统一。我想让 Claude 直接改掉。在会话里输入读取 data_clean.py找到 process_data 函数帮我修改跳过空值和空字符串把结果统一转成小写。Claude 会先读取文件定位函数然后给出它准备改动的 diff。部分情况下它会直接询问是否应用修改输入y确认。修改完成后我用编辑器打开文件查看内容可能是def process_data(rows): cleaned [] for row in rows: if row is None or not row.strip(): continue cleaned.append(row.strip().lower()) return cleaned符合预期。这就是第一次真实代码修改的完整闭环。注意中间有一个重要的细节Claude 在修改前会展示将要改的内容并且只有在获得允许后才会写文件这也是安全设计的关键。4.3 修改过程中的权限控制Claude Code 执行操作时会按权限模型区分动作类型。一类是读取操作比如读取文件、查看目录通常可以直接允许另一类是修改操作比如写文件、运行命令默认会弹窗询问。如果你已经信任当前环境可以用Always allow让某类操作不再询问反之对危险命令建议直接拒绝。这里有一个经验刚开始用的时候权限提示可以直接选择每次都确认先看清楚它想干什么。用上一两天之后再逐步放宽。不要因为嫌麻烦把所有权限都放开尤其是运行任意 shell 命令的权限。4.4 让 Claude 顺手把测试跑了修改完代码继续在同一个会话里追一句在项目里跑一下相关测试确认修改没有引入新问题。如果项目里有 pytest 配置它会尝试运行测试并读取结果。如果测试挂了它还能顺手修复。整个过程很连续改代码、跑测试、修问题不需要你来回切换工具。但这也有风险尤其是接入了大权限的情况下。我的建议是让 Claude 跑测试前用眼睛扫一遍它的命令内容再决定是否允许执行。5. 配置与场景进阶5.1 settings.json 里值得改的配置Claude Code 的配置文件采用 JSON 格式全局配置放在用户目录下~/.claude/settings.json项目级配置放在当前项目的.claude/settings.json优先级高于全局配置。一个常见的配置结构长这样{ model: claude-sonnet-4-5, systemPrompt: 你是一个熟悉 TypeScript 和 Node.js 的资深工程师回答要简洁直接。, permissions: { allow: [Read, Edit], ask: [Bash(*)], deny: [Bash(rm *), Bash(git push --force)] }, env: { HTTP_PROXY: http://127.0.0.1:port } }这里说明一下各字段的逻辑model用来固定 Claude 模型版本systemPrompt可以注入你自己的开发规范permissions里的allow/ask/deny控制动作策略env则用来注入环境变量。字段名称在不同版本可能略有差异使用前最好确认一下当前版本支持的写法原则是先小范围配置再推广。5.2 在 VS Code 里用包括远程服务器改代码Claude Code 本身不是 VS Code 插件但在 VS Code 里用起来非常顺手。打开项目文件夹调出集成终端直接输入claude就能启动。因为 Claude Code 修改的是磁盘上的真实文件VS Code 的资源管理器和编辑器会自动感知变化你甚至可以在侧边栏打开它刚改过的文件边看 diff 边继续对话。如果你要用它修改远程服务器上的代码常见姿势有两条。一是通过 VS Code 的 Remote-SSH 功能连上服务器在远程终端里安装 Node.js 和 Claude Code然后在远程项目目录里启动会话。这样 Claude 直接操作远程文件数据不经过本地中转。二是本地代码通过 SSH 映射或同步工具拉到本地改完再推上去但这种方式对实时调试不友好。从实际体验看第一种更直接推荐优先尝试。5.3 接入本地模型LM Studio / Ollama 的玩法与局限有人出于隐私、成本、离线开发的考虑想把 Claude Code 接上本地模型比如 LM Studio 或 Ollama 里跑的 Qwen3、Llama 3.1 等。核心思路是让 Claude Code 的请求走一个兼容层转发到本地模型的 API 上。常见做法是设置环境变量export ANTHROPIC_BASE_URLhttp://127.0.0.1:4000 export ANTHROPIC_API_KEYlocal其中ANTHROPIC_BASE_URL指向一个支持 Anthropic 请求协议的本地代理。很多本地推理引擎提供的是 OpenAI 兼容 API二者协议不同所以中间通常需要再接一层转换代理比如 LiteLLM 等工具充当桥接。配置完成后在 Claude Code 里选择目标模型就可以开始对话。这里必须说点实际的本地模型的效果目前和 Claude 差距仍然明显尤其是在长上下文、复杂重构、可靠生成 diff 这些场景。有人拿 Ollama 跑 Qwen3 让 agent 自动改代码最常见的现象是看到了但不改或者改到一半忘记原始目标。这不是配置问题而是模型本身能力还不够。我的建议是本地模型适合做代码解释、简单脚本编写、短文档生成复杂的多文件重构还是用原厂模型更稳。5.4 使用 CC Switch 接入 DeepSeek、Qwen、GLM 等第三方模型很多开发者希望用第三方 API 替代官方订阅降低运行成本。社区里常用的工具是 CC Switch它本质上是一个 Claude Code 配置切换器。安装后可以注册多个供应商每个供应商填好名称、Base URL、API Key、模型名然后在几个供应商之间一键切换。切换时工具会改写 Claude Code 的配置或环境变量下次启动会话就能生效。第三方 API 能不能直接接入关键看它是否提供 Anthropic 协议兼容端点。比如 DeepSeek 等部分服务商已经提供了 Anthropic 兼容的接入地址直接把 Base URL 填进去即可。如果某家服务只提供 OpenAI 兼容端点那还需要在前面加协议转换层链路会稍微复杂一点。使用第三方 API 时有三点提醒。第一关注数据安全不要把包含敏感业务逻辑的代码发送给不可信的服务商。第二确认计费方式按 token 计费的第三方服务在长会话下成本可能超过你的预期。第三当出现响应异常时先在切换工具里检查当前 Base URL 和 Key 是否匹配很多时候问题就出在切换后没重启会话。6. 常见问题速查与排错实录6.1 internetopenurl() failed 0x800 怎么处理这是 Windows 环境下比较典型的报错。完整信息类似claude code 使用 cli 执行此命令时发生意外错误: internetopenurl() failed. 0x800出现这个错误说明 Claude Code 在调用 Windows 系统网络接口时失败了。常见诱因有三个系统代理设置异常、防火墙拦截了进程联网、网络出口本身不稳定。按顺序排查第一步检查系统代理打开设置 - 网络和 Internet - 代理确认没有残留的无用代理地址。第二步把 Claude Code 的联网进程加入防火墙或安全软件白名单。第三步尝试在管理员终端里执行网络栈重置netsh winsock reset然后重启。如果问题只在部分网络环境出现可以检查是否需要为 npm 或 Node 配置合规的代理环境变量。还有一种绕开问题的方式把环境切到 WSL 再安装运行 Claude Code很多时候 Windows 原生网络栈的怪问题就不会再出现。6.2 其他高频错误一览表问题现象大概率原因解决办法claude: command not foundnpm 全局 bin 目录不在 PATH将$(npm prefix -g)/bin加入 PATHnpm install超时或网络错误默认 npm 源访问慢切换 npm 镜像源后重试本地模型配置后报 401API Key 为空或 base URL 不对设置任意非空 Key确认代理地址可访问上下文不够用会话过长使用/compact压缩上下文或换用更大上下文版本每次操作都反复询问权限权限策略过严在 settings.json 中合理配置 allow 列表远程服务器上无法启动 Claude Code服务器缺 Node.js 或路径错误在服务器上完整安装 Node.js 和 Claude Code第三方 API 接入后回复格式异常协议不兼容改用支持 Anthropic 协议的服务商或加转换层6.3 最后一点个人建议用过一段时间 Claude Code 之后我自己最大的体会是它确实能替代一部分琐碎开发工作但仍然需要你具备基本的代码判断力。工具越强大越要把最后一道审查关握在自己手里。建议所有重要改动都放在独立分支上进行让 Claude 改完之后认真看一遍 diff确认没有越权改动、没有凭空引入文件再提交合并。另外如果你要处理的是公司核心代码使用第三方模型接口前一定确认数据合规要求。平时可以在一个练习项目里多试几轮观察它在不同任务上的表现边界。它擅长什么、在什么场景会犯傻用不了半天你就能基本摸清。剩下的问题就不是怎么安装了而是怎么把它嵌入到你的日常工作流里让它成为真正提高效率的帮手而不是一个需要时刻盯着纠正的实习生。