最近几个月我基本都泡在终端里写代码AI 编程辅助工具换了不少最后长期留在工作流里的反而是刚上手时觉得“有点别扭”的 Claude Code。它跟网页版聊天、IDE 补全插件都不太一样没有图形按钮也不靠侧边栏对话而是直接把一个能读代码、改文件、跑命令的智能体塞进了命令行。这篇文章是使用笔记的第一篇先把最基础的配置和上手路径讲透包括怎么安装、怎么登录、怎么理解它的权限体系、CLAUDE.md 到底该写什么以及我头一个月踩过的坑。适合刚接触 Claude Code、想把它正式接入项目工作流的人。写完之后你会发现它之所以让人“回不去”核心并不是模型多聪明而是这套终端交互设计确实切中了日常开发的真实痛点。1. 安装与初始环境准备先说安装。Claude Code 本身是一个基于 Node.js 的命令行应用不是那种下载下来就能跑的单文件二进制。所以第一步不是急着敲npm install而是先确认你的机器上有没有可用的 Node.js 环境。1.1 为什么先装 Node.js 环境很多第一次接触 Claude Code 的人上来就卡在安装环节原因大概率不是命令敲错而是 Node 版本不对。它要求 Node.js 18 以上我实际用下来更建议直接上 20 或更高版本因为新旧版本的交互输出在某些细节上会有差异。如果你机器上还跑着老项目的 Node 12、14千万别直接升级全局版本那样容易把别的项目搞挂。我最推荐的方式是用版本管理工具装 Node比如 nvm。装好之后把默认版本切到 20nvm install 20 nvm alias default 20 node -v这里顺便说一句为什么要用版本管理Claude Code 这种工具更新频率极高几乎每周都有版本变化偶尔还会要求运行时升级。如果 Node 环境是单点安装的升级成本很高用 nvm 管理后切版本只是两行命令的事。实测下来这种“随时能换运行环境”的灵活度在排查兼容性问题时能省大量时间。1.2 安装方式与验证环境就绪后直接用 npm 全局安装官方发布的包npm install -g anthropic-ai/claude-code官方也提供了原生安装脚本但我个人更推荐 npm 方式好处是升级方便npm update -g一下就行。安装完成先验证claude --version如果这里能正常输出版本号说明安装链路没问题。如果你用的是 pnpm 或 yarn也可以装但要注意全局 bin 路径是否已经加入PATH。我见过很多“明明装了却提示 command not found”的情况一半是因为全局 bin 目录没有暴露在终端里。提示如果你有 Node 环境但 npm 安装时报 EACCES 权限错误别急着加 sudo。先检查是不是用了系统级 Node更稳妥的解法是切到 nvm 管理的用户级 Node再重新执行安装。1.3 终端选择与启动姿势Claude Code 是一个交互式命令行工具对终端渲染有一定要求。建议使用支持 ANSI 颜色和 Unicode 字符的现代终端比如 Windows Terminal、iTerm2 或 VS Code 内置终端。老旧的系统自带终端不是说不能用而是输出里的颜色、进度条、交互选项会变得很难看甚至出现布局错乱影响判断。启动时有个很多人忽略的小习惯先cd到项目目录再执行claude。因为它启动后会读取当前工作目录作为“项目上下文”如果你在 home 目录启动它看到的是整个用户目录的文件这对权限提示的频繁程度和上下文质量都有负面影响。我习惯建一个专门的工作目录或者直接进入项目根目录再启动。2. 登录认证与两种使用模式装好之后第一件事是登录。Claude Code 不是装完就能用的它需要和 Claude 的服务端建立身份关联。这一步卡住了很多人因为涉及订阅账号和 API 计费的区别。2.1 两种身份认证方式怎么选Claude Code 支持两类认证方式一类是使用 Claude 的订阅制账号直接登录另一类是使用 API 的密钥来认证。对大多数个人开发者来说如果已经有 Claude 订阅直接用它登录最省事。首次运行claude时工具会输出一个授权链接引导完成浏览器授权流程。这个流程本质上是一个 OAuth 登录终端会等待回调确认。如果你走 API 计费路线就需要先设置环境变量export ANTHROPIC_API_KEY你的密钥为了不用每次打开终端都重新 export可以写进 shell 配置文件echo export ANTHROPIC_API_KEY你的密钥 ~/.zshrc source ~/.zshrc这里容易混的点是如果环境变量和订阅登录同时存在工具会优先读取 API Key而不是你登录的订阅账号。结果就是你明明付了订阅费但它依然按 API 调用扣费。我一开始就把两边都配置了月底查账单才发现费用翻倍。后来习惯是日常用订阅账号登录不设置ANTHROPIC_API_KEY环境变量只有在跑自动化脚本时才单独注入密钥。2.2 登录与退出的正确姿势在交互界面里可以用斜杠命令管理登录状态/login触发登录流程/logout退出当前身份如果终端环境不支持浏览器跳转也可以手动复制终端里打印的授权链接去浏览器完成。注意授权码有时效性超时了需要重新执行命令获取新的链接。另外登录状态不是永久的偶尔会遇到会话过期表现就是工具开始频繁报鉴权错误这时候不用重装重新/login一次就行。2.3 计费意识与成本控制Claude Code 按实际使用的模型 token 计费尤其是几类不同档位的模型单位成本差很多。这不算什么秘密但很多人会忽略交互式对话和自动化批处理之间的成本差异。建议养成一个习惯在会话里随时用/cost查看当前会话的累计消耗。我通常是在一个大的重构任务结束后查一次对成本做到心里有数。后面我会专门写一篇成本控制笔记这里先记住一个原则就好——把 Claude Code 当成一个有价值的工程工具来用而不是无限免费的聊天窗口。2.4 权限体系是保护机制不是摆设Claude Code 启动后会扫描当前项目文件但它并不会直接乱改。第一次尝试读取敏感文件或写入文件时终端会弹出权限确认你需要在“允许本次”“总是允许”“拒绝”之间做选择。这个机制看起来很啰嗦但它是保护项目不被误操作的核心防线。我见过有开发者为了少点几次确认直接对项目设置了“总是允许”结果 Claude 在一次重构中误删了一个配置文件整个代码库跑不起来。权限弹窗不是刻意制造麻烦而是给你一个“机器执行前人类最后确认”的节点。个人建议刚开始使用时一律选择“允许本次”等熟悉了它的行为模式再针对少数可信目录设置持久化允许规则。3. 终端交互基础模式切换与文件引用Claude Code 真正让人上手的门槛是不太像传统聊天工具。它没有一个“发送”按钮也没有冒泡式的对话记录整个交互发生在终端里的输入框和回话区之间。理解它的操作语法比理解模型能力更重要。3.1 核心概念这不是聊天框很多新人会把 Claude Code 当成终端里的 ChatGPT不断向它提问等着回复。但它更强的地方在于“直接动手”。你输入需求后它会自主决定读取哪个文件、运行什么命令、修改哪段代码然后汇报结果。如果你的需求只是“帮我讲讲这段代码”它会走只读分析。要是你输入“把这个函数拆成两个模块并更新所有调用点”它就会进入读写执行流程。这个从“聊天”到“代理执行”的转变是使用体验上最大的分水岭。3.2 模式切换正常模式与只读计划模式Claude Code 内置了两个交互模式用Shift Tab在输入区切换。屏幕底部的输入框会显示当前模式标识plan 模式只做分析、给出修改计划不真正改动代码或执行有副作用的命令。默认的正常模式可以读写文件、执行命令是完整代理模式。我在实际使用中的习惯是任何涉及批量改动的大需求先切到 plan 模式让它出方案我审完方案后再切回正常模式让它执行。这套打法能有效防止“它理解错需求然后直接改出一堆烂摊子”的尴尬场景。花五分钟审计划能省下半小时返工。3.3 文件引用与上下文投喂Claude Code 最大的优势之一是可以直接引用项目里的文件而不必把代码片段复制粘贴进对话框。输入后跟上文件名工具会弹出文件路径补全用 Tab 或方向键选择。更实用的技巧是同时引用多个文件用空格分隔src/utils/helper.ts src/api/client.ts 帮我检查这两个文件里有没有类型定义不一致的问题如果你要描述视觉问题也可以把截图直接拖进终端它会作为图片输入解析。这个能力在调 UI 细节时非常好用比打一堆文字描述“按钮偏了 2 像素”高效得多。3.4 一次会话该放多少任务终端交互的上下文窗口是有限的尽管 Claude Code 的会话上下文要比网页版长不少但它依然是稀缺资源。我踩过的坑就是在一个会话里同时塞“重构登录逻辑”“更新文档”“修复历史遗留 bug”三个任务结果做到第二个任务时上下文已经膨胀模型开始行为怪异、重复输出、甚至虚构不存在的文件。后来我给自己定的规矩一个会话只围绕一个明确任务展开。哪怕这个任务涉及十几个文件也比三个无关任务塞一个会话里效果更好。这个体验上的差异来自上下文空间的利用率完全不同。4. 常用命令速查与上下文管理Claude Code 的操作高度依赖斜杠命令。基础篇不追求把所有命令都背下来但有几个命令属于“不知道就不好用”的级别。4.1 基础命令速查表命令作用我的使用频率/help查看所有命令说明低/status查看当前会话的上下文占用中/init生成项目级 CLAUDE.md高/clear清空当前会话上下文开启新会话高/compact压缩当前上下文保留关键信息继续对话中/cost查看当前会话的 token 开销中/memory查看和编辑跨会话的长期记忆低/model切换模型版本中/config打开配置文件目录中/help里的完整命令列表很长但真正高频使用的基本就是上面这张表。建议把命令表截图或抄在笔记里需要时一眼能找到而不是每次都去翻帮助文档。4.2 clear 和 compact 的差异很多人分不清/clear和/compact的区别其实它们解决的问题完全不同。/clear是彻底清空会话模型会忘掉之前所有讨论内容相当于从零开始。代价是你之前跟它对齐的上下文、让它看过的东西全部丢失如果是一个复杂的重构任务清空后往往要从头解释需求。/compact是压缩它会保留对话的核心信息把冗余内容折叠成一段精炼摘要然后在这个摘要之上继续新的对话。如果任务还没有结束但你觉得它开始“犯迷糊”了用/compact比/clear更合适。它就像是给模型做了一次“中场复习”把前面聊过的重要结论重新喂给它。4.3 会话恢复与多任务管理Claude Code 支持断点续聊。如果你中途关闭了终端或者电脑重启可以用下面的命令恢复claude --continue也可以先claude进入交互界面再在输入框里执行/resume它会列出历史会话列表选择要加载的那一个。这个机制对长任务特别有效。我之前处理过一个持续两天的数据迁移任务每天结束时用/clear关掉第二天用/resume找回昨天的上下文直接接着干。需要注意历史会话会占用磁盘空间建议定期清理。你可以在.claude目录下看到会话历史文件删除过期的会话记录不会影响工具本体运行。5. 配置体系解密settings.json 与 CLAUDE.mdClaude Code 的配置体系是它和普通脚本工具最大的不同。不只是“可配置”而是有一套明确的分层结构理解这套结构后你才能真正让它适应自己的项目而不是每次启动都从零教一遍。5.1 settings.json 和 CLAUDE.md 的根本区别这两个东西经常被混为一谈但职责完全不同settings.json是给 Claude Code 这个工具本身看的运行配置像是工具的“控制面板”决定权限规则、默认模型、hooks 等。CLAUDE.md是给 Claude 模型看的项目说明像是“新同事入职手册”告诉模型这个项目是什么、有哪些约定、怎么跑构建命令。简单类比前者是 IDE 的配置后者是项目的 README。IDE 配置影响工具行为README 影响模型对项目的理解。两者配合使用才能既保证执行安全又保证理解准确。5.2 settings.json 的层级与优先级配置文件有三层从低到高是用户级~/.claude/settings.json项目级.claude/settings.json本地个人级.claude/settings.local.json优先级高的配置会覆盖低的这种设计是让“通用偏好”和“项目特殊要求”能够共存。比如在用户级配置里统一关闭某些低价值权限提示在项目级配置里设置针对本项目的 allow 规则。我常用的一个示例配置{ permissions: { allow: [ Read, Glob, Bash(npm run lint), Edit ], deny: [ Bash(rm -rf *) ] }, model: sonnet, env: { MY_CUSTOM_ENV: value } }注意deny里的危险命令规则这是一个保护手段。你可以在项目级别明确禁止某些危险的 shell 操作这样即使某次对话里模型提出要执行rm -rf之类的危险命令也会被直接拦截。5.3 CLAUDE.md 到底该怎么写这个文件的价值容易被低估。很多人要么不写要么让工具自动生成一份然后就不管了。实际使用下来一份好的 CLAUDE.md 能显著提升 Claude Code 在项目里的表现。我常用的结构是项目一句话简介和技术栈说明。目录结构速览标注哪些目录是关键代码、哪些是生成文件。常用命令启动、测试、构建、lint。编码约定命名风格、是否使用类型、测试要求。需要特别注意的事项例如某个目录不能删除、某个模块依赖外部服务。举例一个典型项目的 CLAUDE.md 开头可能是这样# 项目名 这是一个基于 React TypeScript 的中后台前端项目构建工具使用 ViteUI 组件库使用自研组件包。 ## 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test ## 重要约定 - 所有新增业务代码必须提供类型定义。 - 不要在 src/api 目录之外直接发起请求。 - 生成的图表组件统一放在 src/components/charts 下不要散落到业务目录里。写 CLAUDE.md 的另一个原则是“重质不重量”。我见过有人把整个 README 和数十页设计文档全部塞进去结果模型反而抓不住重点。控制在一两百行以内用最精简的语言描述最不可违背的约定就够了。如果你第一次接触不确定怎么写可以直接在项目目录里执行/init让工具生成一份初始版然后你再手工修改补充。我会把它当成起点真正的价值来自后续你对项目的梳理而不是 AI 的自动生成。5.4 MCP 扩展机制Claude Code 还支持 MCP 协议可以用来连接外部工具和服务比如数据库、浏览器调试、部署平台等。基础篇只需要知道这个机制存在它相当于给 Claude Code 增加了“新的手和眼”让它不再只局限于操作文件系统。至于怎么配置具体的 MCP 服务、怎么选择可靠的工具源我会在后续的进阶笔记里详细展开。6. 常见问题排查实录这部分是我用一个多月以来实际遇到的典型问题整理每个问题的排查思路都来自现场踩坑希望能帮你绕开。6.1 安装失败或命令找不到现象执行claude提示 command not found。排查顺序确认安装是否成功npm list -g anthropic-ai/claude-code确认全局 bin 路径npm bin -g检查该路径是否在PATH环境变量里常见原因就是全局安装目录没有被终端识别。用 nvm 管理 Node 的用户尤其会遇到因为 nvm 每次切换版本全局 bin 路径都会跟着变。解决方式是把 nvm 的默认版本固定好并让PATH解析到对应目录。6.2 鉴权报错与身份冲突现象能启动但每次请求都报 401、403 或者提示身份无效。排查顺序运行/status看当前身份。检查是否设置了ANTHROPIC_API_KEY环境变量如果设置了它会覆盖订阅登录。退出登录重试/logout然后/login。这个问题的根源通常不是密钥写错了而是环境变量和登录状态同时存在导致工具优先走了不正确的认证路径。建议在 shell 配置文件里不要设置全局的 API Key只在临时执行自动化脚本时按需注入。6.3 上下文过长导致行为异常现象会话进行到中后期Claude 开始答非所问、重复输出甚至无视你的指令。原因上下文窗口被无关内容占满有效注意力被稀释。解决/compact压缩上下文。如果压缩后还是混乱就用/clear开新会话但把关键结论先复制出来在下一次会话开头粘贴给它。会话不是越久越好适当的切割是让工具保持高效运转的关键。6.4 权限被拦截或误拒绝现象Claude 明明需要修改某个文件但操作直接失败或者总是得不到执行权限。排查方向查看.claude/settings.json里的permissions.deny规则有可能你之前不小心把某个操作永久拒绝了。这时候编辑配置把对应规则删掉或加入 allow 白名单即可。6.5 网络请求失败与服务不可用现象工具报网络错误或服务端错误。原因短时间请求过多触发了限流或服务端临时波动。解决停止操作等待一段时间再试。不要在限流状态下反复重试这样只会在限流解除后继续堆积请求。如果长时间不可用可以留意一下版本更新公告有些故障与本地版本过旧有关。6.6 项目文件过多导致响应迟缓现象大项目里 Claude Code 的行动变得缓慢经常跑去读无关文件。原因没有显式告诉工具忽略哪些目录。解决在项目目录的.claude/settings.json中配置文件读取的忽略规则尤其要排除node_modules、dist、build等生成目录。这不仅提升响应速度还能减少上下文污染让它聚焦在真正重要的源码上。7. 个人使用心得与工作流建议最后这部分不写什么总结了就分享几个我沉淀下来的工作流习惯也是我实际使用中觉得收益最大的地方。7.1 新项目默认先跑 /init我现在的习惯是任何新接手的项目第一件事就是在项目根目录启动 Claude Code然后执行/init。它会生成一份项目级 CLAUDE.md随后我再根据项目的实际情况手工补充那些“只有人类才知道”的背景信息比如某个模块的历史包袱、某个命令不能随便跑、某个目录是自动生成的不能改。这个动作只用几分钟但后续每次会话都能少解释很多背景。7.2 改代码前先要解释现状拿到一个需求之后我不会直接让它开改。我会先问一句“先介绍一下这个功能涉及的核心文件和当前实现逻辑再告诉我你打算怎么改。”如果它的描述和我的理解对不上说明需求本身还需要更精确地定义或者我对代码库的记忆已经过时了。先对齐、再动手是我用下来效果最好的一套节奏。7.3 定期检查成本而不是回避成本有一些开发者不太愿意面对 token 成本这个话题。我的实际感受是如果不看成本并不会消失反而会在月底带来惊吓。Claude Code 提供了/cost这个非常直观的命令我建议每天收工时跑一下看看今天的消耗量级。这能帮你培养对 token 成本的直觉尤其是当你开始写自动化脚本批量调用时这种成本直觉会非常有用。7.4 后续笔记的规划这篇基础笔记先到这里。后续我会接着写 Claude Code 的几个进阶主题主要是 hooks 自动化事件、自定义 slash 命令、MCP 服务接入以及如何用它做自动化测试和代码审查流程。如果你已经用上了 Claude Code欢迎把你在配置阶段踩到的特殊问题记录下来很多“坑”其实都是配置层面的小细节整理出来就是最有价值的实战材料。