最近我把 Claude Code 从安装到接入日常开发工作流完整跑了一遍过程中踩了不少坑也把整个链路摸顺了。Claude Code 是 Anthropic 推出的命令行 AI 编程助手直接跑在终端里能读你的项目目录、改文件、执行命令、跑测试和那种“只能聊天补代码”的 AI 工具完全是两种用法。这篇是系列文章的第一篇目标很明确从零开始安装、登录、跑通第一个任务再顺手把 VS Code、本地模型、MCP 这些高频需求配好。适合刚听说 Claude Code 还没动手的人也适合装到一半卡住、正犹豫要不要卸载的人。1. 安装前必读Claude Code能做什么两种计费模式怎么选1.1 一句话说清它是干什么的其实它就是一个跑在终端里的命令行工具。打开终端输入claude它就进入交互模式可以直接对话。但它和普通聊天工具不一样的是它天然有工作区上下文你在项目根目录启动它它会自动读取项目结构、git 状态、文件内容。你给它一个任务比如“这个接口超时了帮我排查一下”它可以自己去看代码、加日志、跑测试一步步把问题定位并修复。整个过程非常像你雇了一个远程实习生给了它权限它替你干活。很多第一次用的人会问这不就是 Copilot 吗不太一样。Copilot 更像“输入法”在你写代码时提供补全Claude Code 更像是“执行者”它接收的是一个更大的任务自己决定怎么读文件、怎么改、怎么验证。说直白点它是一个能在你的终端里长期工作的 agent而不是一个弹窗补全工具。1.2 计费模式订阅登录和 API到底用哪个安装前建议先想清楚用哪种账号两种方式区别挺大。第一种是 Claude 账号登录也就是 Pro/Max 订阅用户在终端里执行claude login用浏览器授权。这种方式额度按订阅套餐计算比如 Pro 套餐有每周限额高峰期会遇到类似“your limits are temporarily boosted. your weekly Claude Code limit is 50% high”的提示意思是本周额度显示已经用了一半高峰期可能需要等额度恢复再继续。第二种是 Anthropic API Key设置ANTHROPIC_API_KEY环境变量。这种方式按实际消耗 token 计费多退少补适合频繁使用、对响应速度有要求的人缺点是要预充值、盯着账单。这两种方式的选择直接影响后面的登录步骤和额度策略。如果只是偶尔用一下订阅登录更划算如果是重度使用API 按量计费更可控。我自己的习惯是日常探索和轻量任务用订阅额度跑自动化脚本、批量任务时切 API Key两边互不干扰。对比项Claude 订阅登录API Key 计费登录方式claude login浏览器授权设置ANTHROPIC_API_KEY环境变量计费模型订阅套餐内额度按 token 计费适合谁偶尔使用、轻量任务高频使用、可控预算典型限制每周限额、高峰期限流余额消耗快需要关注账单1.3 环境的硬性要求Claude Code 本质上是一个 Node.js 编写的命令行程序所以环境要求其实很宽松但有几个版本坑必须先确认。操作系统Windows 10/11、macOS、主流 Linux 发行版都可以。Node.js官方要求 18.0.0 以上实际体验下来建议用 20 LTS 或更高。版本太老不仅装不上装上也容易在登录时报莫名其妙的问题。npm跟着 Node 一起装的就行建议 6.14 以上实际上新一点的 npm 版本对依赖处理更稳健。终端Windows 下用 PowerShell 7 或 Windows Terminal 体验更好老版本 cmd 对渲染和中文支持都不太行。检查 Node 和 npm 版本node -v npm -v如果提示找不到 node先去装 Node 再继续如果 node 版本低于 18建议用 nvm 或直接装新版。这里特别提醒一句不要在同一台机器上试图绕过低版本的限制Claude Code 的依赖库对旧 Node 兼容性很差省这一步会在后面花十倍时间排查。2. 安装实操从命令行到跑通第一个任务2.1 两条官方安装路径第一个是 npm 全局安装一条命令npm install -g anthropic-ai/claude-code注意包名有作用域anthropic-ai/claude-code。网上有些教程写claude-code或anthropic-claude-code都可能是旧包或第三方包认准这个作用域名最稳。安装过程如果网络不稳定npm 容易卡在下载阶段可以先临时切到国内镜像源再装npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com第二个是官方原生安装器适合不想碰 npm 的人curl -fsSL https://claude.ai/install.sh | bashmacOS 和 Linux 上可以直接用这个脚本Windows 用户还是走 npm 更省事或者提前装好 WSL 后在 WSL 内安装。2.2 验证安装是否成功装完之后先检查版本claude --version如果能输出版本号说明命令已经进入 PATH。如果提示“claude 不是内部或外部命令”Windows或“command not found”macOS/Linux多数情况是 npm 全局安装目录没被加入 PATH。Windows 上先看 npm 全局根目录npm config get prefix把输出的目录加到系统环境变量 PATH 里再重开终端。macOS/Linux 上如果用的是 nvmnpm 全局包往往放在~/.nvm/versions/node/xxx/bin下确认这个路径在 PATH 里。新版本 Claude Code 还提供了一个自检命令可以顺手跑一下claude doctor这个命令会检查 Node 版本、登录状态、环境变量是否正常遇到问题它会直接告诉你哪里不对。第一次接触这个工具的人建议在登录前先跑一遍能省很多排查时间。2.3 登录认证两种账号两条路径安装完成后第一次运行claude会提示登录。订阅用户直接在终端里执行claude第一次启动会跳出一个链接浏览器打开后确认授权回到终端就能使用。这里有个常见问题浏览器打开了但终端一直转圈或者提示 403。多数原因是 Node 版本过旧或者终端网络状态不稳定可以先升级 Node 再试。如果反复失败把登录凭证缓存清掉再试rm -rf ~/.claude/.credentials.jsonAPI 用户走环境变量路线不需要交互式登录export ANTHROPIC_API_KEY你的APIKeyWindows PowerShell 下写成$env:ANTHROPIC_API_KEY 你的APIKey这种方式对脚本化、CICD 场景更友好因为不涉及浏览器授权。2.4 首次启动跑一个最简单的任务登录成功后进入项目目录直接运行claude看到提示符后先不要急着写复杂需求。建议先输入/status查看当前模型、账号类型和本轮上下文占用情况。然后可以这样问“先看一下这个项目的目录结构告诉我每个文件大致是干什么的。”Claude 会开始读项目给出结构梳理。这个过程可以直观感受到它和普通聊天的区别——它读的是真实文件不是猜。任务完成后输入/exit或直接 CtrlC 退出。这里特别提醒Claude Code 在第一次执行有副作用的操作时比如修改文件、执行命令会询问你是否允许并给出具体命令。比如它要执行git commit会列出完整命令等你确认。这个机制叫权限确认新手期建议保持默认的询问模式熟悉后再考虑放权。我见过不少人在第一次使用时直接选“一直允许”结果它把整个项目的文件格式化了一遍后悔都来不及。3. 进阶实用配置VS Code、本地模型与 MCP3.1 VS Code 集成不是插件胜似插件Claude Code 官方没有出传统意义的“插件”但 VS Code 集成方式反而更简单在 VS Code 里直接打开集成终端cd 到项目目录运行claude它就能看到当前项目文件。配合 VS Code 自身的文件树、diff 视图一边和 Claude 对话一边看它的改动体验非常顺。如果希望更深入的联动可以安装官方扩展“Claude Code for VS Code”或社区相关扩展原理上基本是在编辑器里嵌入一个 Claude Code 面板。无论哪种方式核心都是保持 Claude Code 在正确的工作目录运行。不要在 VS Code 的全局终端里启动然后指望它读某个特定项目——它是按当前目录来决定上下文的目录错了读到的内容就全是错的。3.2 用 Ollama 接入本地模型这个话题最近特别热因为很多人既想体验 Claude Code 这种 agent 工作流又不想每轮都消耗云端 token。理论上只要本地模型服务能兼容 Anthropic API 格式Claude Code 就能通过环境变量对接Ollama 是最常见的选择。第一步确保 Ollama 已经运行拉一个代码能力不错的模型ollama pull qwen2.5-coder:7b第二步设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:11434 export ANTHROPIC_MODELqwen2.5-coder:7b然后正常运行claude。注意一点本地模型不能完全替代官方模型尤其是工具调用能力和超长上下文理解上差距明显。我实测下来本地模型更适合做代码片段生成、解释、单元测试编写但让它自主重构多文件项目风险偏大。另外 Ollama 的接口默认不完全等于 Anthropic 格式实际使用往往需要一个小型适配层或者换成兼容 Anthropic API 的服务端社区里也有现成工具本质都是在协议层做转换。如果不想折腾也可以直接用 cc switch 这类第三方工具一键管理模型和供应商之间的切换。3.3 接入 DeepSeek 等兼容模型除了本地模型把 Claude Code 接到 DeepSeek 这种事也有人尝试。DeepSeek 官方提供了 Anthropic API 兼容端点配置起来非常顺export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeekAPIKey export ANTHROPIC_MODELdeepseek-chat设置完后运行claude如果模型识别正常就能开始对话。这里有个很典型的坑如果你写了一个当前版本的 Claude Code 不认识的模型名终端会直接报错“xxx is not a model this version of Claude Code recognizes”然后停止自动补全。解决办法就是保持ANTHROPIC_MODEL的值为该平台官方支持的模型名不要随便填别名。3.4 MCP让 Claude Code 能读数据库和文件MCP 全称 Model Context Protocol是 Anthropic 推动的开放协议作用简单说就是给 AI 加“外接设备”让它能读数据库、访问文件系统、调用外部服务。Claude Code 对 MCP 支持得不错通过claude mcp命令来管理。比如给 Claude Code 接一个 SQLite 数据库claude mcp add my-db -- npx -y modelcontextprotocol/server-sqlite ./test.db添加完后可以在 Claude Code 里输入/mcp查看已连接的 server确认状态是 connected。以后你在对话里说“查一下数据库里 orders 表的数据”它会通过 MCP 去读而不是靠猜。文件系统、PostgreSQL、GitHub 等都有官方或社区 server。需要说明的是MCP server 本质是给 AI 打开了一个可执行远程操作的通道生产环境里务必按最小权限原则配置别图省事把所有库都暴露给它。3.5 省 token 的几个实用技巧最后说一个大家最关心的问题怎么少烧 token。我实践下来最有效的有几条。第一限制输出长度设置环境变量export CLAUDE_CODE_MAX_OUTPUT_TOKENS4096数值越小单次回复越短token 消耗自然少。第二有意识地压缩上下文。完成一个阶段后让它先汇总要点再在汇总基础上继续不要连续几小时把大量源码日志直接灌进同一轮对话里。第三用命令切换模型。对话中输入/model可以切换模型简单任务切到便宜或轻量模型复杂重构再切回旗舰。第四让 Claude 先给方案再动手改代码。你可以明确说“先不要改文件只告诉我计划”这能省掉大量改完又回滚的无效 token 消耗。4. 和 Codex 相比Claude Code 的定位差异这段时间总有朋友问我“选 Codex 还是 Claude Code”这俩确实经常被放在一起比。Codex 是 OpenAI 推出的类似 agent 产品两者目标用户几乎重合但实际体验侧重点不一样。下面这张表是我自己用下来的感受整理不一定绝对权威但至少能帮你快速定位。4.1 两者到底差在哪一张表格看明白对比项Claude CodeCodex底层模型Claude 系列GPT 系列安装方式npm CLI、原生安装器npm 或 IDE 内使用计费模式订阅额度或 API 按量订阅套餐或 API 按量长任务处理多文件上下文强擅长重构对 OpenAI 生态集成更顺典型适用大仓库、多文件任务、精确读取ChatGPT 用户、快速生成、熟悉 GPT 模型从我自己的体验来说Claude Code 在“读懂大仓库”这件事上做得更细它读文件的方式更像一个真正在翻代码的人会自己确认依赖关系、搜索关键定义Codex 则和 OpenAI 的工具链贴合更紧日常快速问答、写一次性脚本时响应风格更直接。4.2 我的选型经验按任务类型切换选型建议很直接如果你已经重度使用 Claude 模型那 Claude Code 的上下文风格和模型能力是衔接最自然的如果你团队本来就在用 GPT 系列或者依赖 ChatGPT 的协作流程那 Codex 会更顺手。工具没有绝对好坏更多看你的项目类型和习惯。我自己的做法是两者都装按任务类型分别用读大仓库、做多文件重构时用 Claude Code日常快速问答、写脚本时用 Codex。终端里装两个 agent 并不冲突反而能互补。不要把选型当成站队工具最终是拿来干活的。5. 常见问题与排查技巧实录5.1 PowerShell 安装报错Windows 下最常见的报错有两类。一类是“无法加载文件……因为在此系统上禁止运行脚本”这不是 Claude Code 的问题是 PowerShell 执行策略限制。解决Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后再试。另一类是安装时卡住或报网络错误。这种先把 npm 缓存清掉再换镜像源安装基本都能解决npm cache clean --force npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com5.2 登录返回 403登录时打开浏览器授权后终端提示 403是问得最多的问题。依我的经验按下面顺序排查先看 Node 版本是否满足要求再看授权回调是否被本地安全软件或系统防火墙拦截最后清理凭证缓存重新登录。如果以上都试过还不行改用 API Key 方式不依赖浏览器授权稳定性高很多。5.3 终端乱码Windows 默认代码页是 GBKClaude Code 输出中文时容易乱码。切到 UTF-8 再启动chcp 65001另外建议把终端字体调成支持中文和符号的等宽字体部分疑似乱码其实是字体缺字形换个字体就好。macOS 和 Linux 上这类问题少很多基本不需要处理。5.4 对话历史到底存在哪、怎么恢复Claude Code 默认会保存对话历史和会话记录不需要手动开设置。历史文件一般存放在~/.claude/projects目录下按项目维度存成 JSONL 格式。想恢复某个历史会话启动后输入claude --resume回车后会出现历史会话列表选择就能继续。想直接接着上一次对话继续用claude --continue这个功能很实用特别是长任务做到一半关了终端下次还能接着聊上下文不会断。5.5 识别不了第三方模型如果你手动设置了本地模型或第三方模型却看到类似“xxx is not a model this version of Claude Code recognizes”的报错说明模型名写得不对或者当前版本的模型清单里没有这个模型。处理方式先去对应平台查询官方支持的模型名填完整准确的名称如果是本地 Ollama 模型确认ANTHROPIC_MODEL的值和ollama list里显示的名字完全一致。报这个错时通常不会自动补全因为工具根本不知道你指的是哪一个模型。另外提醒一句关于“桌面版”的说法Claude Code 官方目前的主体形态是 CLI 和编辑器集成并没有一个官方独立的“桌面版 App”。网上搜到的“Claude Code 桌面版”很多是第三方封装或同名工具安装前先确认来源尽量走官方渠道避免装到来路不明的包。最后说点我自己的使用体会。Claude Code 和传统 AI 补全工具最大的不同是它把“AI 写代码”从单点操作变成了完整的工作流它会读文件、执行命令、跑测试、根据结果反复调整。刚开始用的时候我习惯什么都让它直接改后来发现最好的方式是人定方向、它做执行让它先读代码给我结论我确认后再让它动手效率和确定性都高很多。这个系列后续我还会继续写具体场景的使用技巧包括怎么用好 Skills、怎么调 MCP、怎么在团队里统一配置。这一篇先把安装和基础配置搞定剩下的后面慢慢聊。