Claude Code 是 Anthropic 推出的终端 AI 编程代理最近在开发社区里的讨论热度一直很高。它解决的核心问题并不是“帮你生成一段代码”而是让你在真实项目目录里用自然语言驱动一个能读文件、改代码、跑命令、看结果的代理把“理解需求—修改代码—运行验证—迭代”的编码循环压缩在同一个终端会话里。很多人连续搜索“Claude Code 安装”“Claude Code 下载”“VS Code 配置 Claude Code”“Claude Code 和 Codex 有什么区别”本质上都是在问同一件事这个工具能不能进入我日常的开发流程以及我该怎么把它配置好、用好。下面按从入门到进阶的 8 个阶段展开。每一阶段都包含可操作的内容第一轮先把概念讲清楚第二轮解决环境安装第三轮跑通第一次对话第四轮接入 VS Code 和常见切换工具第五轮讲解核心配置第六轮进入 MCP、Skills 和本地模型第七轮做一次和 Codex 的选型对比第八轮集中处理乱码、会话保存、token 控制和生产环境排错。学完之后你能独立搭出一套 Claude Code 的最小可用环境也能在遇到报错时按链路一步步查下去。1. Claude Code 是什么它不是又一个聊天窗口而是终端里的编程代理1.1 编程代理和普通聊天工具的本质区别前端开发、后端开发、运维脚本几乎每个开发者都用过大模型聊天工具。普通聊天工具的工作方式是你把代码复制进去它给你返回一段修改建议你再手动贴回编辑器。这个流程的问题在于上下文断裂模型看不到完整项目不知道这个函数在哪里被调用不知道测试怎么跑也不知道改完以后有没有破坏其他功能。Claude Code 的工作方式不同。它运行在项目的根目录里可以读取目录结构、查看文件内容、搜索关键词、运行 shell 命令、修改文件甚至执行测试。也就是说它不是一个“问答窗口”而是一个能操作当前代码库的代理agent。你给它一个任务比如“找到登录接口里 token 过期没有处理的逻辑补上统一异常处理”它会先自己寻找相关文件理解调用关系然后修改代码并告诉你它改了什么、为什么这样改。这个差异决定了使用方式也不同。使用聊天工具时你的主要成本是“把上下文搬运给模型”使用 Claude Code 时你的主要成本是“把任务边界和约束描述清楚”。模型已经能自己看代码你只需要告诉它目标、约束和验收标准。1.2 Claude Code 的典型工作链路Claude Code 在终端里启动后会建立一条循环链路读取当前目录的上下文包括项目文件、.gitignore、CLAUDE.md记忆文件。根据你的自然语言指令决定下一步使用哪个工具读取文件、编辑文件、运行命令、搜索代码。每执行一步都会把结果带回对话上下文继续判断下一步。遇到需要授权的高风险操作比如执行会影响环境的命令、修改大量文件它会向你请求确认。循环直到任务完成或者你主动打断。这条链路就是“agentic loop”。与一次性问答相比它的优势在于多步推理和自验证。比如让 Claude Code“写一个脚本统计日志里 ERROR 出现次数并输出到文件”它不只会写代码还会实际运行脚本、查看输出、调整参数直到结果合理。1.3 它适合做什么不适合做什么适合的场景包括旧项目重构、补测试用例、修复定位明确的 bug、理解陌生代码库、批量修改重复逻辑、写一次性脚本、生成迁移 SQL 或数据字典。随着 MCPModel Context Protocol的引入它还可以读取本地数据库、连接外部服务成为开发环境里的“数据巡检员”。不适合的场景是完全无人值守地让它改生产代码把它当作代码审查的唯一手段或者在没有版本控制的项目里直接让它大面积改动。工具本身有能力做很多事但工程上的把控仍然需要人来负责。注意Claude Code 是帮助你更高效地完成编码任务的工具不是自动程序员。它产生的代码同样需要 review、测试和版本管理尤其是生产环境改动。2. 安装前置条件与三种安装方式2.1 安装前的环境检查清单安装前先检查环境很多失败都出在 Node 版本、系统编码或权限上。检查项要求常见问题Node.js建议 18 及以上版本过低时 npx/npm 无法解析依赖npm随 Node 安装网络源问题会导致安装超时操作系统macOS、Linux、WindowsWindows 推荐配合 Windows Terminal终端编码UTF-8中文乱码大多与代码页有关磁盘空间数百 MB 级别依赖安装需要临时空间在终端执行以下命令确认环境node -v npm -v如果node和npm都正常输出版本号就可以继续。如果提示找不到命令说明 Node 环境没有安装或没有加入 PATH需要先解决这个问题。2.2 通过 npm 全局安装npm 是目前最常见的安装方式包名是anthropic-ai/claude-codenpm install -g anthropic-ai/claude-code安装完成后验证版本claude --version如果输出版本号说明安装成功。这里要注意全局安装需要 npm 的全局目录有写权限。使用系统自带 Node 时某些环境下会报EACCES权限错误推荐先用nvm或fnm管理 Node而不是直接改用 sudo 安装。2.3 通过官方原生安装脚本安装官方也提供原生安装脚本适合不想依赖 npm 的环境。常见做法是在终端执行官方文档提供的安装脚本。脚本安装和 npm 安装二选一即可不要混用否则可能出现两个可执行文件互相覆盖的情况。示例命令形如curl -fsSL https://claude.ai/install.sh | bash这里需要说明两点。第一任何curl | bash方式都建议先下载脚本、阅读内容再执行第二安装脚本的地址和更新频率以 Anthropic 官方文档为准不同版本可能不同。如果你更看重可审计性npm 安装更容易固定版本。2.4 Windows PowerShell 安装报错的处理Windows 上最常见的报错有两类。一类是 PowerShell 执行策略限制安装或运行脚本时提示“禁止运行脚本”。解决办法是把当前用户的执行策略调整为允许本地脚本签名Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser另一类是安装后claude命令找不到。原因通常是 npm 全局 bin 目录没有加入 PATH。执行npm config get prefix查看全局目录然后把对应的 bin 路径加入系统 PATH重开终端再验证。注意不要一遇到权限错误就直接用管理员权限全局安装。先确认是不是 Node 安装方式导致的问题使用版本管理器通常更干净。3. 第一次运行登录、权限确认和最小对话闭环3.1 账号授权和 API Key 两种认证方式在项目目录里输入claude第一次启动时它会引导你完成认证。认证方式通常有两大类。一类是使用 Claude 账号订阅登录。这种方式适合个人开发者登录后按订阅套餐的限额使用。配额信息会以“每周限额”“用量已使用 xx%”等方式显示在会话里。另一类是使用 Anthropic API Key。设置环境变量export ANTHROPIC_API_KEY你的 API Key claude使用 API Key 时费用按 token 消耗统计不受订阅配额限制但需要你自行关注成本。如果是在公司环境或通过兼容网关使用第三方模型认证方式会根据网关要求设置为自定义 Base URL 和 Token这在第 6 部分展开。3.2 在项目目录中启动推荐在真实项目根目录启动这样 Claude Code 能正确读取项目结构、Git 状态和配置文件。cd my-project claude启动后它会显示交互式界面等待你输入指令。如果你只是想快速跑一个一次性任务可以直接在后面跟 promptclaude 列出当前项目的目录结构并说明每个模块的职责这种方式适合脚本化调用。不同版本对一次性模式、输出格式的参数略有差异使用前可以执行claude --help查看当前版本的参数列表。3.3 最小闭环让 Claude Code 完成一个小任务为了验证安装和认证是否正确推荐先找一个临时目录做最小闭环测试。假设目录里有一个简单的 CSV 文件你输入写一个 Python 脚本读取 data.csv统计每一列的非空值数量并把结果打印出来。运行一次确认输出正确。Claude Code 会依次做这几件事查看目录找到data.csv。编写 Python 脚本。请求权限运行脚本。运行后查看输出如果格式有问题会自行调整。这个闭环验证了五个关键点模型能读取文件、能创建文件、能运行命令、能读取运行结果、能根据结果迭代。任何一个环节不通都能在后续配置中定位。注意不要只验证“它能启动”。一个能启动但读不了文件、跑不了命令的环境在实际项目里基本不可用。最小闭环一定要包含“运行命令并读取输出”这一环。4. 把 Claude Code 接入日常开发环境4.1 在 VS Code 中集成 Claude Code很多人的日常开发在 VS Code 里完成直接在终端里切换会打断思路。社区里常见的做法是安装官方提供的 VS Code 扩展扩展名称通常是“Claude Code for VS Code”在扩展市场搜索 Claude Code 即可找到发布方以扩展页面的信息为准。安装扩展后一般有两种使用入口在 VS Code 的终端面板里直接运行claude扩展会识别终端输出并增强文件跳转和 diff 展示。使用扩展面板中提供的命令入口例如“在终端中打开 Claude Code”或类似功能。具体命令名称以当前插件版本为准。集成 VS Code 的主要价值在于Claude Code 修改文件后你能在编辑器里直接看到 diff能快速打开它涉及的文件review 效率比纯终端高很多。4.2 使用 cc-switch 在多个模型供应商之间切换cc-switch 是社区开发者制作的一个工具用于切换 Claude Code 的配置环境尤其是在不同模型供应商之间切换。比如你有时使用官方 Claude API有时想切换到 DeepSeek 或其他兼容接口手工改环境变量比较麻烦用 cc-switch 可以保存多套配置点一下就能切换。使用方式一般是先配置多个供应商的 Base URL、API Key、模型名然后在 cc-switch 的界面里选择当前生效的配置再重新启动 Claude Code。注意这是一个社区工具不是 Anthropic 官方产品下载和使用前要检查来源并且理解它本质上是帮你改写 Claude Code 的配置文件和环境变量。4.3 桌面版和纯 CLI 的选择Claude Code 也提供了桌面形态的应用入口和安装方式以官方发布为准。对于多数开发场景CLI 仍然是核心它轻量、可脚本化、能嵌入编辑器终端。桌面版更适合喜欢图形界面的用户或者需要可视化查看会话记录的场景。无论使用哪种形态底层都是同一个代理引擎配置文件也基本通用。实际项目中建议把 CLI 作为主力桌面版作为补充避免两套环境配置不一致。5. 核心配置详解CLAUDE.md、常用命令与参数、配额机制5.1 CLAUDE.md项目的长期记忆文件Claude Code 每次启动时会把当前目录下的CLAUDE.md加载进上下文把它当作项目的“长期记忆”。全局记忆放在用户目录下的~/.claude/CLAUDE.md项目级记忆放在项目根目录或.claude目录下。CLAUDE.md里可以写这些内容项目简介和模块划分。常用构建、测试、启动命令。代码风格约定和命名规范。禁止改动的目录或文件。部署和发布流程的关键信息。示例# 项目约定 ## 技术栈 - 后端Python 3.11, FastAPI - 数据库PostgreSQL 15 ## 常用命令 - 启动开发服务uvicorn app.main:app --reload - 运行测试pytest tests/ -v - 代码检查ruff check . ## 约定 - 新接口必须写 OpenAPI 描述。 - 数据库迁移使用 Alembic不要手动改表结构。 - 不要修改 migrations/versions 下已发布的迁移文件。CLAUDE.md 的价值是减少重复解释。只要把这些约定写进去后续每个会话都不需要你重新说一遍项目背景模型也会更倾向于遵守这些规则。5.2 常用命令和参数速查不同版本的功能有差异以claude --help输出为准。下面列出常见用法命令作用claude在当前目录启动交互式会话claude 任务描述一次性执行任务claude -c继续最近一次会话claude -r从会话列表中选择恢复claude --model 模型名指定模型claude --output-format json控制输出格式claude --output 文件路径把输出写入文件claude mcp --help查看 MCP 相关命令claude --version查看版本交互界面里也有斜杠命令例如/clear清空当前上下文、/compact压缩上下文、/cost查看本会话费用、/export导出会话记录、/status查看当前环境信息。具体列表在会话里输入/即可显示。5.3 API Key、会话恢复与配额限制使用 API Key 时环境变量ANTHROPIC_API_KEY优先于账号登录。配置格式是export ANTHROPIC_API_KEY你的 API Key export ANTHROPIC_MODELsonnet订阅模式下用户可能会看到类似“your limits are temporarily boosted, your weekly Claude Code limit is 50%”的提示。这条提示不是报错而是说明你的本周配额已使用到 50%并且当前额度被临时提升过。遇到这种情况的处理方式是继续使用时留意剩余额度如果任务量很大考虑改用 API Key 计费或者把任务拆到下周。--continue和--resume是会话管理的重要能力。开发任务常常是跨天的当天没做完的任务第二天用claude -c继续不需要重新描述上下文。6. 进阶玩法MCP、Skills 与本地模型接入6.1 MCP 是什么为什么 Claude Code 需要它MCP 全称 Model Context Protocol是模型上下文协议。它做的事情是把“模型能用哪些外部工具、能访问哪些外部数据”标准化。没有 MCP 之前每接入一种新数据源都要单独开发集成模型要理解不同工具的私有个性化接口有了 MCP 之后模型只要按协议连接一个 MCP server就能通过统一方式调用工具。在 Claude Code 场景里MCP 最典型的应用是读取数据库。模型本身不能直接连数据库但通过 MCP server它可以把“查询某个表结构”“执行某条只读 SQL”变成可控的工具调用。这非常适合做数据巡检、生成数据字典、排查数据质量问题。6.2 用 MCP 读取数据库配置示例假设你要连接一个 SQLite 数据库可以添加一个 SQLite 的 MCP server。命令式添加的语法大致如下claude mcp add --transport stdio sqlite -- npx -y modelcontextprotocol/server-sqlite --db-path ./data.db也可以使用项目级配置文件.mcp.json把它提交进 Git让团队共享{ mcpServers: { sqlite: { command: npx, args: [ -y, modelcontextprotocol/server-sqlite, --db-path, ./data.db ], env: {} } } }配置完成后在会话里输入类似“查看当前数据库有哪些表并读取 users 表的字段结构”的指令Claude Code 会通过 MCP server 执行查询并返回结果。这里需要注意几点数据库 MCP 的权限模型由 server 决定有的 server 允许执行任意 SQL有的只支持只读查询。生产环境接入数据库前一定要确认 MCP server 是否限制写操作并保证数据库账号是最小权限而不是 DBA 账号。6.3 接入 Ollama、DeepSeek 等第三方模型的路径Claude Code 默认使用 Anthropic 的模型和接口但社区里有不少方案让它接入本地模型或第三方模型。这条路的本质是Claude Code 作为一个客户端通过环境变量指向其他兼容接口而不是官方 Claude API。本地模型使用 Ollama 的常见配置思路如下。先安装并启动 Ollama拉取一个支持工具调用的模型ollama pull llama3.1 ollama serve然后设置环境变量让 Claude Code 指向 Ollama 提供的兼容接口export ANTHROPIC_BASE_URLhttp://localhost:11434/v1 export ANTHROPIC_AUTH_TOKENollama export ANTHROPIC_MODELllama3.1 claude接入 DeepSeek 的思路类似只是 Base URL、Token 和模型名要换成 DeepSeek 服务商提供的信息。不同服务商的兼容程度差异很大有些只兼容聊天补全不支持复杂的工具调用导致 Claude Code 的“修改文件后运行验证”链路不稳定。落地前要做一次最小闭环测试重点验证工具调用是否正常。6.4 Skills官方文档与自定义技能Skills 是 Claude Code 的一组机制让模型在特定任务场景下加载预设的知识和操作流程。一个 skill 通常放在项目的.claude/skills/某个技能名/目录下目录里的SKILL.md文件包含该技能的描述、触发条件和操作步骤。官方文档会说明 SKILL.md 的格式一般是 YAML frontmatter 加 Markdown 正文。frontmatter 里写技能名称和描述正文里写详细执行步骤、代码模板和注意事项。你可以把一个项目的上线检查流程封装成一个 skill之后凡是涉及上线检查的任务模型都会自动加载这套流程。社区里已经有不少公开的 skill 示例比如生成 PPT、整理会议记录、批量处理文件等。使用第三方 skill 前要检查它是否会执行外部命令、读写哪些目录避免引入不必要的行为。自己写 skill 时尽量把步骤写具体少写空泛描述这样模型才能真正按流程执行。6.5 关于“model not recognized”类问题的本质使用第三方模型经常会遇到类似“GLM-5.2 is not a model this version of Claude Code recognizes, so auto-complete...”的提示。它的意思是当前 Claude Code 版本的模型列表中不包含这个名字模型补全和某些功能无法正常工作。原因通常是两个。一是 Claude Code 版本太旧不认识新发布的模型名二是你的ANTHROPIC_MODEL环境变量或配置里写了一个不在当前版本识别范围内的模型名。处理方式是先升级 Claude Code再检查当前生效的模型名配置。如果通过网关接入第三方模型网关可能负责把外部模型映射成 Anthropic 兼容模型这种情况下要以网关文档给出的模型名为准。7. Claude Code 与 Codex 的选型对比7.1 两者的定位差异Codex 是 OpenAI 推出的编码代理工具同样强调在真实代码环境里执行多步任务。两者在“终端代理”“读取文件”“运行命令”这些基础能力上非常像真正的差异在生态和使用成本上。Claude Code 的特点是与 Claude 模型深度绑定使用 Anthropic 的实验性能力较早MCP 支持也比较成熟。Codex 的特点是深度融入 OpenAI 生态和 ChatGPT 套餐、OpenAI 的云服务联动更方便。两者都不是“免费的代码补全插件”而是完整的代理式工具使用时都要消耗模型配额或 API 费用。7.2 关键维度对比对比维度Claude CodeCodex开发者AnthropicOpenAI入口形态终端 CLI 为主有桌面版和 VS Code 扩展CLI、VS Code 扩展及云环境底层模型Claude 系列OpenAI Codex 系列模型协议支持原生支持 MCP生态成熟支持 MCP但默认工作流略有差异本地/第三方模型可通过环境变量接入兼容接口支持情况和限制以官方文档为准配额方式订阅配额或 API 按量计费ChatGPT 套餐或 API 按量计费典型场景本地项目重构、多步调试、MCP 数据查询云端开发、与 OpenAI 生态联动表中的信息会随版本更新而变化选型前要以两边官方文档为准。这个表的价值是帮你快速建立判断框架而不是给出永久结论。7.3 选型建议选型可以从三个问题入手。第一你常用的模型生态是哪家。如果你已经在使用 Claude 订阅并且认可 Claude 在长上下文和代码理解上的表现Claude Code 的学习成本最低。如果你已经在使用 ChatGPT 套餐Codex 的联动更顺。第二你的主要使用场景在本地还是云端。Claude Code 的典型用法是在本地仓库里跑适合重视代码不出本机的团队。Codex 与云端 IDE 的结合更强适合云端开发工作流。第三你是否需要接 MCP。Claude Code 对 MCP 的支持出现得早社区示例也多。如果你有“让 AI 读取数据库、查询内部系统”这类需求可以先从 Claude Code 开始验证。不建议同时深度混用两套工具。它们都会产生上下文消耗和学习成本先选一个主流场景跑一个月再根据真实体验决定是否切换。8. 常见问题排查与工程化最佳实践8.1 终端乱码问题怎么排查现象在 Windows PowerShell 或旧版终端里Claude Code 输出的中文变成乱码或者你输入的中文变成乱码。排查顺序检查终端代码页。执行chcp查看当前代码页如果不是 65001UTF-8切换后再启动chcp 65001检查 PowerShell 的输出编码。在会话前设置$OutputEncoding [Console]::OutputEncoding [System.Text.Encoding]::UTF8推荐直接改用 Windows Terminal它对 UTF-8 的支持比传统控制台好很多。如果只有特定脚本输出乱码检查脚本自身是否声明了 UTF-8 编码以及 Python 等运行时是否设置了PYTHONIOENCODINGutf-8。乱码问题通常是环境编码不是 Claude Code 本身的问题。先改终端再改运行时的编码配置。8.2 保存对话历史和跨天恢复会话对话历史不是“聊天记录”那么简单它决定了你能不能跨天继续一个复杂任务。交互式会话中可以使用/export导出当前会话记录。一次性任务的输出可以用--output写入文件claude --output-format json --output result.json 分析项目里所有 TODO 并生成清单跨天恢复会话使用claude --resume查看历史会话列表并选择恢复或者用claude -c继续最近一次会话。这里有一条工程建议重要任务做完一个阶段后先让会话状态保持清晰再开始下一个阶段不要一个会话里塞太多不相关的任务否则上下文膨胀后模型容易忽略早期约定。8.3 省 token 的实用技巧token 消耗是使用 Claude Code 的主要成本省 token 的本质是减少无效上下文。第一把项目约定写进CLAUDE.md避免每个会话都重新解释一遍背景。第二在任务描述里直接给出文件路径、函数名和期望行为不要让模型靠猜。第三上下文变得很长时使用/compact压缩而不是继续堆叠。第四简单任务使用更轻量的模型复杂重构再用能力更强的模型。第五不要让 Claude Code 一次性读取整个大文件可以用 grep、定位符号等方式先缩小范围。第六尽量在干净的会话里做单一任务避免一个会话里堆积大量历史。这套做法同时能提高输出质量因为上下文越聚焦模型越不容易“忘事”。8.4 常见报错与处理速查报错提示常见原因检查方式处理建议GLM-5.2 is not a model this version recognizesClaude Code 版本过旧或模型名配置错误执行claude --version检查ANTHROPIC_MODEL升级 Claude Code修正模型名查看网关文档your weekly Claude Code limit is 50%订阅配额使用阈值提示查看/cost和/status继续使用但留意额度任务量大时改用 API 计费your organization has disabled claude subscription access组织策略禁止订阅登录和团队管理员确认策略咨询管理员开启或使用组织授权的 API KeyPowerShell 禁止运行脚本执行策略限制执行Get-ExecutionPolicy设置当前用户为 RemoteSignedEACCES 权限错误Node 全局目录无写权限执行npm config get prefix使用 nvm/fnm 管理 Node避免 sudo 安装乱码终端代码页或编码不匹配执行chcp检查终端类型切到 UTF-8 和 Windows Terminal排查原则是先查环境再查配置最后查版本。不要一报错就怀疑模型多数问题出在 Node 环境、PATH、代理设置、终端编码和配额策略上。8.5 生产环境使用检查清单在真实项目里使用 Claude Code 前建议过一遍这个清单代码已提交当前工作区是干净的或者至少能通过 Git 还原。明确告诉 Claude Code 哪些目录不能动例如vendor、dist、migrations已发布目录。高风险操作不开“完全跳过权限确认”模式。虽然存在类似--dangerously-skip-permissions的参数但它适合自动化场景不适合直接用在生产仓库上。每次改动都要 review diff不要直接信任输出。可以要求 Claude Code 在修改后自述改动理由和影响范围。数据库类 MCP 使用只读账号禁止给代理配置写权限。不要把 API Key、密码写进CLAUDE.md或 prompt密钥走环境变量或密钥管理服务。固定 Claude Code 版本读每个版本的 release notes新版本可能调整默认行为。关注/cost和配额消耗出现异常增长时及时停会话排查。这个清单的核心思路是让代理足够自由地工作但工作空间始终可控、可恢复、可审计。到这里你已经走完了从概念、安装、首次运行到 VS Code 集成、MCP、本地模型、Codex 对比和排错的完整链路。最重要的一条经验是Claude Code 能不能发挥价值不取决于它会多少功能而取决于你会不会给它清晰的边界和可验证的任务。接下来可以先拿一个非核心的旧项目做实验把CLAUDE.md、最小闭环、会话恢复这套流程跑熟再逐步扩展到日常开发。等你熟悉了它的工作风格再研究自定义 skills 和 MCP 服务那时候你的核心工作就不再是“应付报错”而是设计一套适合自己团队的 AI 编码工作流。