我最早注意到这个工具是因为换了一台新电脑重新配环境时折腾到凌晨实在不想再手动敲一遍初始化脚本。当时看到 GitHub 趋势榜上挂着Claude Code CLI这个关键词本以为是又一个需要折腾半天才能跑通的终端玩具没想到装上之后它真的改变了我的日常编码习惯。今天这篇教程我打算从一个普通开发者的视角把这套终端里的 AI 编程助手从头到尾讲清楚包括安装、配置、核心命令、实际干活流程以及我在头一周踩过的那些坑。这篇快速入门适合谁看如果你用过命令行工具但没接触过 AI 编程助手或者你已经用过一些图形界面里的 AI 插件却想知道为什么有人在终端里也能爽快地让它改代码那这篇内容正好。我会用我自己的真实操作记录来讲尽量做到每一步都能照着做而不是只讲概念。1. 先搞清楚这个 CLI 到底解决什么问题1.1 从图形界面回到终端的逻辑过去几年AI 编程助手基本都是图形化的打开一个 IDE装个插件选中代码右键唤起对话框。这种方式确实直观但它有个结构性缺陷——AI 和你的代码库之间是割裂的。它能看到你选中的那几行代码却看不到整个项目的结构、依赖关系、配置文件、测试用例。于是你经常需要手动把多个文件的内容复制粘贴进对话框或者反复描述第X个文件的函数在哪里效率很快就掉下来了。CLI 版本的思路完全不同。它直接跑在你的项目根目录里天然拥有当前工作目录的读写权限。它不仅能看到你当前打开的文件还能自己去浏览整个目录树找到相关引用执行测试命令甚至在你确认后修改多个文件。这种以项目为上下文的交互模式才是它最核心的价值。我打个比方图形界面里的 AI 像是一个只能隔着玻璃看代码的顾问你把代码举到玻璃前它才能看到而 CLI 里的 AI 像是直接坐在你的工位上文件、终端、测试环境都在它手边你只需要传达意图它自己会去翻资料、动手改。1.2 它擅长做什么、不擅长做什么Claude Code CLI 的核心场景我梳理了一下大致有四类读代码、解释代码拿到一个陌生项目直接让它解释一下这个模块的调用链远比自己在文件间跳转来得快。写新功能给它一个清晰的需求描述它可以自动创建文件、补全逻辑、写出配套的测试。重构与修 Bug你描述异常现象或目标结构它会先分析现状再给出改动方案确认后批量修改。执行重复性工程操作批量重命名、统一错误处理、补充注释、生成文档这些枯燥活儿它干得尤其好。但它不是万能的。我试下来复杂业务逻辑的架构设计它仍然做不到——你不能扔给它一句帮我做一个电商系统然后就等它输出所有业务代码。它更像一个动手能力极强的执行者你把方向想清楚告诉它每一步怎么落地它能高效完成而且比你自己慢慢敲要快得多。1.3 快速判断你适不适合入坑如果你是以下几种情况这个工具值得花一个晚上试试日常大量使用 Git、终端、服务器习惯了命令行工作流。接手过自己不熟悉的老项目经常需要快速读懂代码。写前端页面或脚本时讨厌反复在写代码—切窗口—粘贴—复制回来之间循环。需要做大量机械性编码任务比如重复的 CUD 操作、增删字段、写单元测试。反之如果你完全没用过终端连cd和ls都还没形成肌肉记忆建议先花两周熟悉基础命令行再上手。这个工具虽然号称自然语言编程但它默认你是能看懂终端的操作员不是被照顾的小白用户。2. 安装与第一轮配置2.1 硬性依赖Node.js 版本检查Claude Code CLI 基于 Node.js 运行安装前请先确认你的环境。终端执行node -v我建议 Node.js 版本不低于 18.0。如果你用的还是 16 或更老后面大概率会遇到运行时报错那时候再回头升级也行但不如一开始就准备好。如果你机器上还没有 Node.js直接用包管理器装一个 LTS 版本即可这里不展开。确认版本没问题后安装本体就一条命令npm install -g anthropic-ai/claude-code等等这里我得说一下。这串包的名称按我记忆里的写法是anthropic-ai/claude-code但生态变化很快不同时间点的安装命令可能略有差异。如果你执行这一条报错包不存在先不要慌去 npm 官网搜claude-code或anthropic-ai/claude-code以搜索到的真实包名和官方 readme 里的安装命令为准。我不能在教程里给你编造一个确定的包名因为那会误导你。实际上我自己的装机步骤通常是# 1. 确认 node 版本 node -v # 2. 安装命令行工具 npm install -g anthropic-ai/claude-code # 3. 验证安装 claude --version安装完成后终端敲claude --version能输出版本号说明第一步成了。2.2 API Key 配置绕过登录这一步这个工具本身是围绕调用云端大模型能力设计的所以你需要一个可用的密钥。具体来说安装完成后首次运行它大概率会让你完成某种身份认证或登录流程。我想强调的是无论你使用的是哪种认证方式本质上都是把你的本地环境与一个具备模型调用权限的账号关联起来。你需要准备好某个支持 Claude 模型能力的 API 密钥或者一个已登录状态的账号。确保你的网络能正常访问目标服务。如果官方 CLI 出现在你所在地区不可用的情况比如网络不通那就主动放弃千万不要尝试任何绕过网络限制的方案这类操作既不稳定也不安全没必要为一个编码工具冒险。我配置好的环境变量大概是这样的# 在你的 shell 配置里加上 export ANTHROPIC_API_KEY你的密钥也有通过claude交互式命令/login或首次启动向导完成绑定的看你实际版本支持哪种。配置完成后我建议先跑一个最简单的对话来验证连通性claude进入 REPL 交互界面后输入你好如果它能正常回复说明连接没问题。2.3 在你自己的项目里初始化很多教程喜欢讲全局配置但我更推荐项目级使用。进入一个具体的代码仓库然后启动cd ~/projects/my-todo-app claude此时工具会扫描当前目录并生成一个会话相关的配置文件通常是一个隐藏目录比如.claude里面存放会话历史与项目上下文。这一步很重要它会让你确认这个工具被允许读取和写入哪些目录以及是否允许自动执行命令。如果你面对的是生产环境的敏感仓库建议更谨慎地选择允许的权限范围。首次运行时它会问你是否信任当前目录。我见过不止一个朋友在这步直接回车选了允许一切权限结果它在一个不想被碰的目录里自作主张改了一堆文件。这个坑我会在第 6 节详细讲。3. 核心概念与常用命令速览3.1 会话机制从一次性对话到连续上下文Claude Code CLI 里的一个关键概念是会话Session。每一次你启动claude开始对话到关闭它算一个会话。会话内它会记得之前聊过的内容以及它对项目结构的理解。我强烈建议按任务分会话一个会话只干一件事完成就退出下次开新会话。为什么因为会话上下文有长度上限如果在一个会话里拖得极长它能记住的项目细节会被逐渐稀释最后可能忘掉前面的关键约束。你可以用claude --continue来继续上一个会话。比如昨晚让它改了一半的功能今天想接着聊就用这条命令。如果只有一个历史会话它会直接恢复如果有多条它会列出历史会话供你选择。用claude --resume也可以达到类似效果但两者的细微差别在旧版本中体现为--continue更偏向接着干当前活--resume更偏向选择任意会话恢复。实际用下来差别不大你选一个习惯就行了。3.2 斜杠命令不只是聊聊天进入交互界面后你能看到所有内置命令的列表直接在输入框里打/就会弹出提示。我筛出几个最高频的命令作用我用它做什么/init初始化项目上下文生成一个项目记忆文件新项目第一次启动后教它记住项目约定/clear清空当前会话上下文当前任务做完了、下一件事不想让它惦记旧内容/help显示命令帮助忘了某个命令的具体用法时/compact压缩当前会话上下文会话长了以后防止它失忆/status查看本次会话的文件改动、命令执行记录复盘它到底动了哪些文件其中/init是我最想重点说的。一条具体的命令解释如下在项目根目录进入claude后输入/init它会把当前项目的代码结构、技术栈、常用命令等信息整理成一个类似CLAUDE.md的说明文件后续每一次会话它都能自动读取这个文件作为背景知识。这个机制非常有用相当于给 AI 写了一份项目入职手册。3.3 权限系统与控制策略与写代码类工具通常要处理掉信任边界一样这个 CLI 也有完善的权限控制。它执行命令和修改文件前都会先询问你。常用选项如下Yes, and dont ask again for this directory # 信任这个目录之后不再问 Yes, once # 仅单次允许 No, and dont ask again # 拒绝并记住这个决定我个人的策略是在个人练习项目的目录里放权多一些在涉及公司业务或生产数据的项目目录里保守一些逐次确认每一项改动。你要观察它在每次请求中出示的具体命令是什么再决定要不要允许——比如删除整个目录的命令无论如何都应该先看清楚。3.4 非交互式调用的基础入门除了在终端里一个对话框聊天这个工具还支持直接以参数形式传递问题。简单讲就是不需要启动交互界面直接执行claude 给 utils/format.ts 里的 formatDate 函数补充完整的 JSDoc 注释这种模式的好处是方便脚本化。你可以写一个 shell 脚本批量地对多个代码文件发起结构化修改请求。不过注意非交互模式下如果缺少某些必要参数它可能仍会在某些环节停下来或直接读取配置文件的权限设置。这个玩法更适合进阶用户入门阶段先用好交互模式就够了。4. 实操从零搭一个 TODO 管理小工具讲了这么多概念不如直接看一次完整对话记录。我用一个真实的练习项目来做演示——一个极简的 TODO 命令行工具。4.1 项目目标与初始描述项目结构如下这里演示的就是一个小仓库my-todo-app/ ├── package.json ├── index.js └── README.md我的第一个需求是写一个能在终端里添加、列出、标记完成、删除 TODO 的小程序数据保存在本地 JSON 文件里。在claude交互界面里我输入了我想用 Node.js 写一个命令行 TODO 管理工具。要求 1. 数据存到本地 todos.json 文件 2. 支持 add、list、done、delete 四个子命令 3. 命令行参数交互尽量简洁 4. 输出要带颜色可读性好 请直接创建/修改相关文件。4.2 观察它如何自我规划按下回车后Claude Code CLI 的第一反应不是直接写代码而是输出一段计划。大意是检查目录下现有文件内容确定用什么数据结构存储决定是否需要引入第三方依赖比如颜色输出库规划好四个命令的入口逻辑直接创建或修改文件接下来它会读取我的package.json、index.js然后开始动手。整个过程我是实时看到的它先读文件再向我确认是否允许创建todos.json是否允许修改 的package.json是否允许安装依赖。我一路选了允许大约两三分钟后一个能跑的版本就产生了。截图中的实际终端输出大概是这样的还原片段$ claude 我想用 Node.js 写一个命令行 TODO 管理工具... ✓ 已读取 package.json当前无依赖 ✓ 已创建 todos.json 数据结构定义 ✓ 已重写 index.js包含四个子命令的实现 - 建议安装 tinycolor2 来增强终端输出颜色 是否需要运行 npm install tinycolor2 ? (Yes/No)它甚至会主动备注依赖安装的必要性。这里小技巧是如果你不想引入太多依赖直接对它说不要安装任何第三方包全部用 Node.js 内置能力实现它就会乖乖地只写原生代码。4.3 验证功能与迭代修改工具写完后我直接在另一个终端里测试node index.js add 学习命令行 AI 工具 node index.js list node index.js done 1第一个版本执行基本正确但输出格式有点朴素。我回到claude会话里追加需求列表输出时已完成的 todo 前面加 ✅未完成的前面加 已完成条目文字变灰并加删除线。需要说明一下这里我用了 Emoji实际终端里的支持情况和当前运行的 shell 环境有关。如果你的终端不支持 Emoji 显示可以要求换成文本标记[x]和[ ]。这个修改在几秒钟内完成效果立即可见。这个输入需求—确认 — 再输入新需求的循环就是日常用这个工具最舒服的模式。你完全可以用自然语言不断追加修改不需要再自己人肉逐字改文件。4.4 让它做事之前先让它说说思路我后来让工具给 README.md 补文档它补得倒很快但一开始的用词偏AI 味严重啰嗦而且喜欢加免责声明。我加了一句README 用中文简洁禁用任何模板化表达它生成的质量立刻好很多。所以在实际干活时多花 30 秒把约束条件说清楚远比事后反复纠正要高效。下面是一个我常用的提示模板请修改或创建哪些文件。 具体需求是什么。 哪些地方不允许改动哪些依赖不允许引入。 输出风格上有什么偏好比如注释语言、代码风格、README 风格。 先给我方案确认后再动手。最后一句尤其好用。默认情况下它会边想边做你如果加一句先想后做它普遍会先给你列出改动计划而不是直接动手这会让你对即将发生的变化更有掌控感。5. 高频使用的小技巧与配置参数5.1 通过系统提示词让它更懂你的习惯除了项目级的CLAUDE.md还可以在全局配置里放一套自己的通用行为守则。比如我给自己设了三条硬性规则所有新写的代码必须包含注释注释用中文。所有函数不得超过 60 行超了就要拆。改写现有代码时先 diff不覆写。这个工具的全局配置交互入口不同版本不太一样。但通常你可以找到类似编辑系统提示词或设置用户偏好的入口。如果找不到也可以考虑使用 Bash 方式手工编辑配置文件具体路径可以在/help里查看各命令的帮助信息。5.2 上下文压缩会话变长了怎么办当你和它在同一个会话里聊了很多轮以后会发现它开始前言不搭后语——忘掉最初的约束或者重复提出已经讨论过的问题。这是上下文窗口快要装满的信号。此时输入/compact它会尝试压缩当前对话历史把关键信息保留下来。压缩完以后它通常还会给你一个摘要说明它记住了哪些要点。我记得第一次用这个功能时惊了一下它把之前所有的沟通浓缩成 20 行左右的项目简述后面继续对话时依然能准确执行需求体验相当好。如果你发现/compact之后还是不好使那就老老实实重启一个新会话但把重要背景写进项目说明文件里再从那里继续。5.3 让它读文件而不是你手动贴常见的一个低效用法是用户把一大段代码反面粘贴进对话框然后问这段代码哪里有问题。在 CLI 工具里正确的做法是直接用自然语言指向文件路径请检查 src/api/index.ts 和 src/api/user.ts找出接口调用里可能存在的并发安全问题并给出修复建议。它会自己去读文件、追踪 import、看上下文然后给你结论。这不仅省去复制的麻烦而且它能看到完整的调用链结论的准确性明显更高。我自己用下来最大的改变就是再也不在对话框里贴代码了。5.4 一次性使用不启动交互界面也能干活前面提到过claude 需求这种一次性调用方式。这里补充一个更实用的场景把它和git联动。我自己的习惯是commit 之前不再自己写 message而是让工具根据暂存区的改动生成git diff --stat git diff claude 根据本次改动内容帮我看 diff 并生成一份符合规范的中文 git 提交信息这个工作流如果你觉得好用甚至可以写进脚本里。核心乐趣在于终端里的 AI 助手可以成为 shell 工作流的一个环节而不仅仅是一个聊天窗口。6. 我踩过的坑与排查建议6.1 权限放得太宽项目被帮忙重构了第一次在某个目录里运行时我图省事直接选了完全信任该目录。结果有一次我让它优化一下代码结构它把所有文件全部重命名并按新目录结构移到了新位置。功能没坏但 review 成本极高——这个教训是即使在自己主导的项目里也要克制放权的冲动。改成单次确认模式之后每次执行前都给我看命令安心多了。解决建议把权限模式调整为逐次确认。尤其在面对自己不熟悉的目录或生产环境时宁可多点几下确认也不要事后花几个小时找它改了啥。6.2 命令找不到 / 版本不一致如果你执行claude --version时提示 command not found大概率是 npm 全局 bin 路径没有在你的 PATH 里。排查方式npm config get prefix这个命令输出的是全局安装目录把该目录下的bin路径添加进你的 shell 配置文件。比如上面的 prefix 是/usr/local那就加export PATH/usr/local/bin:$PATH另外升级之后行为发生变化多半是版本升级带来的命令或参数变化。我的建议是如果某个功能突然失效先跑/help看看当前版本的命令列表再想想是不是把旧教程里的--continue记成了新版本不存在的命令。6.3 中文显示乱码 / shell 编码问题终端里显示的中文乱码通常是当前 shell 环境编码问题。先检查环境变量echo $LANG正常情况下应该可以看到类似en_US.UTF-8或zh_CN.UTF-8这样的值。如果$LANG为空或不是 UTF-8在 shell 配置里补一行export LANGen_US.UTF-8 export LC_ALLen_US.UTF-8改完后重启 shell 再试。这种问题不是工具本身的 bug而是你本机环境的经典坑换个机器往往就没有了。6.4 会话丢失 / 历史找不回来有几次我电脑重启后再执行claude --continue它显示没有找到可继续的会话。看你平时怎么使用——说白了如果你在运行claude时使用了sudo权限会话文件会分别记录在 root 用户目录和普通用户目录下互相之间是隔离的。解决方案不要轻易用 sudo 跑这个工具。正常情况下claude根本不需要管理员权限。这样会话历史才能稳定地保存在你当前用户的家目录里。6.5 API 连接不稳定或超时如果你配置好了密钥但每次对话响应特别慢或者直接报超时先别怀疑工具本身。确认你的网络可以正常访问对应的模型服务如果你处于特殊的公司网络或网关环境下可能需要向网络管理员咨询。这里我不推荐也不支持任何绕过网络限制的方案——直接说结论如果你的网络条件导致服务不可用最稳妥的做法是停止使用而不是寻找不正规的通道。补充一点如果只是偶发超时不妨检查本地是否有过度消耗资源的进程。CLI 工具需要网络请求终端性能或本地资源占满时响应也会受拖累。6.6 输出内容泛泛而谈 / 不贴合项目这是最常见的假性故障明明给了具体项目它却总是答得很空。多数情况下是你没有给它足够具体的上下文。往下推我会这样补救不要猜测请先阅读项目根目录下所有 README、配置文件、源码目录结构 然后基于本项目实际情况回答我刚才的问题。这样它就会去真正读项目而不是凭一般经验堆砌。如果仍然不行看看项目的CLAUDE.md是否已经生成了。没有就先/init给它建立记忆。6.7 安全与平台合规问题的个人建议这个工具的核心价值是让 AI 直接操作你的代码随之而来的安全边界不要在非授权环境里分享你的密钥。不要把公司敏感代码随意送入外部模型服务除非你确认数据政策允许。在一个新项目里先让它做只读操作读文件、列目录、解释代码确认它理解正确后再放权改动。如果你用它的场景是在不熟悉的环境中处理敏感代码务必对能访问云端的 AI保持敬畏。有经验的朋友会直接在敏感项目里完全不启用这个工具或者只在自己完全可控的模拟项目里练习。这个选择本身就是一个工程师成熟与否的分界线。从能跑到用得顺要跨过的三道坎从装好到真正用顺我大概花了一周时间。这个过程里最明显的三道坎第一道坎是忘记它是一个终端命令——总想把它当聊天窗口对话没有指向性。之后我开始明确指定文件路径、列出需求边界、要求它先给方案输出质量才有了质的提升。第二道坎是权限恐惧——总怕它乱改所以每次操作都要盯住每一行。后来学会区分环境和目录练习项目放心放权核心库保持一致一切改动都能通过版本控制回滚心态就放松了。第三道坎是习惯用自然语言描述技术细节——刚开始写需求时老是担心自己说得不够程序员加了一堆技术术语。后来发现它其实擅长把模糊需求拆解成具体方案你反而应该用更接近人话的方式来描述问题让它去补全技术细节。这篇入门教程里我没讲任何晦涩的内部实现原理只挑了我实际操作中最高频使用的东西。如果你照着这些步骤走下来恭喜你你已经在开发者群体里领先了很大一截——至少当别人还在图形界面里手动选择代码—上下文的时候你已经能在终端里用一个自然语言项目上下文的方式让 AI 直接帮你动手写代码了。我个人目前的使用习惯是把这工具当作结对编程搭子而非无人驾驶司机。它负责执行、补全和重复劳动我负责审查、纠偏和方向定义——这会是我推荐的踏实用法。后续如果有时间我再写写它和其他脚本化工具结合、以及多项目并行会话管理的高级玩法。