零基础上手 Claude Code：从安装到写出第一个本地脚本

如果你和我一样，属于那种“平时不搞专业开发，但是经常有些小脚本、小工具的念头，想让电脑帮自己干点活”的人，那你一定经历过这种场景：脑子里有个特别清晰的功能，打开编辑器盯着屏幕，却一个字都敲不出来，只能默默放弃。

2026年这几个月，我把 Claude Code 折腾得比较透。从一开始完全搞不懂它到底能在终端里干什么，到后来把它当成日常工作里的“外包程序员”，安装、配置、实操、排错，整条链路都踩过不少坑。这篇文章想以“零门槛”的方式，把我验证过的流程和踩过的坑原原本本分享出来。不管你有没有编程基础，只要电脑能上网、会打开终端，跟着步骤照做一遍，就能把 Claude Code 用起来。

它不是网页上的对话框，而是直接站在你的项目目录里、帮你读写文件、帮你执行命令的终端助手。它真正解决的，是“把脑子里那句话变成项目里的代码文件”这一整件事。

1. 安装前，先弄懂 Claude Code 是什么、要准备什么

1.1 一句话说清 Claude Code 是干什么的

Claude Code 是 Claude 官方推出的命令行编程助手，跑在你的本地终端里。它不是一个“聊天窗口”，而是一个能直接连接你当前文件夹的工具。你可以跟它说“帮我看看这个项目哪里有问题”，它真的会去读文件；你可以说“给我写一个脚本，做某某事情”，它会在你当前目录下把脚本文件创建出来；你还可以让它“跑一下这个命令”，它会在终端里帮你执行，然后把结果反馈回来。

所以它跟网页端最大的区别是：它跟你本地文件系统是打通的。这带来的价值是质变级的。就像一个“带着自己电脑进你办公室、能看你全部资料、还能顺便帮你做事的实习生”。你不需要把代码复制来复制去，只需要告诉它“做这件事”，剩下的读写文件、跑程序、修 bug 的循环，它自己就能完成。

1.2 你需要提前准备的 4 样东西

别被“命令行”三个字吓住。我整理了一份清单，你照着准备就行：

这里我重点说一下 Node.js。很多人装完 Claude Code 启动报错，十有八九是 Node 版本太老。Claude Code 对运行时版本有硬性要求，如果你电脑里是很久之前装的 Node 8 或者 Node 10，那基本就跑不起来。所以新手不要嫌麻烦，确定自己装的是最新的 LTS 版本，能省掉后面一大堆奇奇怪怪的问题。

另外，API 密钥这个东西，可能有人会觉得“后面再说”，但我强烈建议你提前准备。因为 Claude Code 支持两种鉴权方式，一种是浏览器登录授权，另一种是直接用 API 密钥。我实际用下来，API 密钥的方式更稳定、更可控，出错也更容易排查。官方平台的 API 密钥通常在账号设置里的 API Keys 区域创建，创建时注意把密钥完整复制保存，它只会显示一次。

2. 三分钟完成安装，Windows / macOS / Linux 都跑得起来

2.1 安装 Node.js 与 npm

安装 Node.js 没啥技术含量，去 Node 官网下载 LTS 版本的安装包，双击安装，一路 Next 就行。Windows 用户需要注意一点：安装向导里有两个勾选项，一个是“Automatically install the necessary tools”，新手可以勾上，它会顺便帮你装一些后续可能用到的开发工具；另一个是“Add to PATH”，这个必须保证是选中的，否则后面终端里敲node会提示“找不到命令”。

macOS 用户如果电脑里已经有 Homebrew，也可以直接终端执行brew install node。Linux 用户建议用官方源或者 nvm（Node Version Manager）安装，不建议直接用包管理器装老版本。

装完之后，打开一个全新的终端窗口，执行这两行命令确认环境：

node -v npm -v

正常情况下会输出两个版本号，比如v22.x.x和10.x.x。如果输出的是“command not found”，说明没安装成功或者 PATH 环境变量没生效，重新安装一遍，然后务必新开一个终端窗口再试。

2.2 安装 Claude Code 本体

打开终端，执行一行命令：

npm install -g @anthropic-ai/claude-code

-g参数的意思是全局安装，这样你以后在任何目录下都能直接调用claude命令。安装过程一般一两分钟，看到 “added xxx packages” 之类的输出就表示成功了。

Windows 用户如果这里报权限错误，建议以管理员身份重新打开终端再执行。macOS 和 Linux 用户如果报权限错误，通常需要在前面加sudo：

sudo npm install -g @anthropic-ai/claude-code

不过更推荐的方案是先用 nvm 管理 Node，这样不需要 sudo 就能全局安装，也避免了一些权限上的坑。

装完顺手验证一下：

claude --version

能看到版本号，说明本体已经安装好了。这里顺便说一句，Claude Code 如今也支持在官网直接下载桌面版 / 插件版，但我个人依然推荐纯命令行版本。原因是它最纯粹、最稳定，也方便脚本化和自动化集成，对新手来说，少一个图形界面反而更能理解“它到底在做什么”。

2.3 首次启动，该选的选对

在你准备好的项目空目录里，执行：

claude

第一次启动会有一个简短的交互引导。它会弹出一个问题，大致意思是“是否信任当前目录”，这个必须选 Yes。信任的含义是允许 Claude Code 在当前目录下读取文件和写入文件。如果你选了 No，它虽然能启动，但没法读写文件，那基本就等于不能用了。

如果已经配置好环境变量里的 API 密钥（下面第 3 章会说），它会直接跳过登录流程进入工作状态；如果没有，它会提示你登录 Claude 账号或者输入 API 密钥。按提示操作就行。

启动成功之后，你会看到一个以>开头的输入行，这就说明 Claude Code 已经开始等待你的指令了。有基础的同学可以输入/help看看帮助信息，想清空对话就输入/clear，不用记任何东西，这会儿看不懂也没关系，直接进入第 3 章开始配置。

3. 不想每次登录？直接配置 API 密钥与默认模型

3.1 两种鉴权方式，到底怎么选

我在前面提过，Claude Code 支持两种不同的鉴权方式，实际体验差异还挺大。

第一种是账号登录授权。好处是不需要额外申请密钥，坏处是它依赖浏览器 OAuth 流程，在某些网络环境下容易卡在“等待登录确认”这一步，而且这种授权方式跟个人账号的免费额度绑定，对高频使用来说不太友好。

第二种是 API 密钥方式。去官方平台创建密钥，然后通过环境变量让 Claude Code 自动读取。这种方式配置一次之后就非常安静，启动直接进工作界面，不会弹出浏览器、不用频繁刷新 token，请求和计费也都在 API 控制台可以看到。

我的建议很直接：只要你是想要长期用、重度用，就选第二种。新手也别嫌麻烦，配置过程就是第 3.2 小节这几行命令的事。

3.2 用环境变量配置 API 密钥

macOS / Linux 用户：

打开终端，用你习惯的编辑器编辑 shell 配置文件。如果你用的是 zsh（现在 macOS 默认），执行：

nano ~/.zshrc

在文件末尾加一行：

export ANTHROPIC_API_KEY="sk-ant-your-api-key"

保存退出（nano 的快捷键是 Ctrl+O 回车保存，Ctrl+X 退出），然后让配置立刻生效：

source ~/.zshrc

Windows 用户（PowerShell）：

在 PowerShell 里执行下面这条，注意只对当前窗口有效：

$env:ANTHROPIC_API_KEY="sk-ant-your-api-key"

如果想永久生效，打开“系统属性 - 环境变量”，在“用户变量”里新建一个变量，变量名填ANTHROPIC_API_KEY，变量值填密钥，确定保存。之后新开的终端窗口都会自动带上这个变量。

验证一下是否配置成功：

echo $ANTHROPIC_API_KEY

macOS/Linux 能输出密钥内容，Windows 在 PowerShell 里执行echo $env:ANTHROPIC_API_KEY，能看到内容就对了。

3.3 把默认模型和输出风格也设置好

密钥配好之后，Claude Code 会用默认模型给你干活。官方在迭代过程中一直在调整默认值，通常就是当前能力最均衡的那个。如果你想手动指定，可以设置CLAUDE_CODE_MODEL环境变量，比如：

export CLAUDE_CODE_MODEL="claude-sonnet-4-5"

具体型号名字以官方文档为准，我这里不写死，毕竟这玩意儿更新频率很快。需要说明的是：不同模型在代码生成能力、速度、价格上差别挺大的。如果只是写写脚本、整理文件，选性价比高的版本就足够了；如果是做复杂项目，可以考虑升级更强的模型。

另外，Claude Code 还支持结构化输出。如果你有自动化需求，希望它输出 JSON 而不是自然语言，可以在设置里开启 JSON 输出模式。这个对新手可能还用不上，但是知道有这个选项就行，以后写自动化脚本的时候会回来找它的。

配置完了之后，重新开一个终端，进入项目目录，执行claude，看到欢迎界面就说明整套环境已经准备好了。

4. 第一次实操：无脑让 Claude Code 帮你产出一个待办事项脚本

4.1 初始化项目目录并启动

我用一个真实的例子来带你走完整条流程。假设你想在电脑上做一个“待办事项管理”的小工具，它需要能添加任务、完成任务、列出任务，并且把任务数据保存到本地文件里。

先创建一个项目目录：

mkdir todo-demo cd todo-demo

然后执行：

claude

4.2 一句需求，直接拿到完整可运行的代码

进入 Claude Code 交互界面之后，直接把需求用大白话说出来：

请帮我创建一个 Python 待办事项管理脚本。功能包括：添加任务、完成任务、列出所有任务。数据保存到本地 JSON 文件。交互方式用命令行菜单。

它不会马上动手，而是会问我几个补充问题，比如“任务是否需要截止日期”“要不要支持优先级”。我说“不需要太复杂，基础功能就行”。然后它就开始工作了。

我观察了一下它的执行流程：先规划要创建的文件结构，然后新建了一个todo.py，又考虑数据存储，自动设计了data/tasks.json的路径。最关键的是，它写完之后告诉我“文件已创建”，而不是在终端里吐一大段代码让我自己复制。我跑到项目目录里一看，todo.py就躺在那里。

这种“生成结果直接落地成文件”的体验，跟网页版完全不一样。网页版你复制代码、新建文件、粘贴、保存，每一步都是人工操作，出了错还得自己排查；Claude Code 把这一串动作全自动压缩了。

4.3 让它自己跑一遍测试，再帮你修 bug

我跟它说：

现在运行一下这个脚本，看看有没有问题。

它直接帮我在终端里执行了python todo.py。第一次运行就看到了菜单界面，但对我来说有个问题：中文显示出现了乱码。我还没开口，它自己就发现了，并主动说“这可能是编码问题，我建议在脚本里显式指定 UTF-8 编码”，然后问我“是否应用这个修复”。

我说“应用”，它直接修改了文件。我再次让它运行，中文显示正常了。整个过程下来，我没有复制过哪怕一行代码，没有打开过编辑器，只是像跟一个同事沟通需求一样，它就把脚本交付了。

这一步对新手来说很有意义：你不需要懂编码问题背后的原理，也不需要知道怎么修改 Python 文件，只需要描述现象，剩下的排查和修复交给 Claude Code 自己解决。这就是“自然语言编程”最直接的样子。

这里要补充一句：它写出来的代码细节不一定是最优架构，但对个人工具项目来说完全够用。当作“外包交付”，它能做到 80 分；你把需求提得更清楚，它就能无限逼近 95 分。

5. 用了一个月之后，我总结出的 5 个高效技巧

5.1 用claude -c做一次性零交互任务

有时候你根本不想进入交互界面，只想让 Claude Code 干一件具体的事，然后退出。比如“统计这个项目里一共有多少行代码”“看一下这个配置文件里有哪些参数”。这时可以直接用：

claude -c "统计当前目录所有 Python 文件的总行数"

加-c参数之后，它不会进入交互模式，而是直接执行完任务把结果输出到终端然后退出。这特别适合写脚本做自动化，或者日常快速查询。比我手动翻文件效率高太多了。

5.2 在项目根目录放一个 CLAUDE.md，收益超乎想象

这绝对是我用了一个月之后觉得最值的技巧。CLAUDE.md是项目的“说明文档”，每次启动 Claude Code 时，它都会自动读取这个文件，把它当作项目的背景知识。

我的做法是，在每个项目目录里放一个CLAUDE.md，写清楚：

• 这个项目是干嘛的
• 技术栈用的什么语言、什么框架
• 目录结构大概是怎样的
• 代码风格偏好（比如用 tabs 还是 spaces）
• 一些约定俗成的规则（比如“不要在data/目录下删文件”）

这样一来，不管过了多久重新打开这个项目，Claude Code 都能快速“回忆起”上下文，不需要我每次重新复述需求背景。这个文件既是给 Claude Code 看的说明书，也是给未来自己看的项目笔记，一举两得。一个空目录配一个 CLAUDE.md，10 分钟就能搞定，回报率极高。

比如我那个 todo 项目里的CLAUDE.md就写了三行：

# 项目说明 - 这是一个本地待办事项管理工具，使用 Python 标准库实现。 - 数据以 JSON 格式存储在 data/tasks.json。 - 不要修改 data 目录下的任何文件。

第二次再启动，我跟它说“加一个统计已完成任务数量的功能”，它完全没有多问项目背景，直接就改好了。

5.3 让它执行脚本，而不是只给你代码

很多第一次用 Claude Code 的人，还停留在“让它给代码，然后自己跑”的旧习惯里。其实它的权限远不止于此。

你可以在需求里直接写：

运行python todo.py，然后告诉我它正常工作。

它会在本地执行该命令并返回输出结果。如果命令执行失败，它看到错误信息之后会主动分析原因、提出修复方案。这个能力大幅缩短了“写代码 - 跑代码 - 改问题”的循环时间。

尤其是当你频繁修改脚本、需要反复运行验证的时候，直接指挥它“运行一下试试”，比自己切到终端敲命令高效得多。这会慢慢改变你的工作流：你不再需要记住一串命令，只需要告诉它“我要什么结果”。

5.4 及时用 /clear 清理上下文，省 token 还提速

Claude Code 的计费方式按 token 来，token 指的是模型处理的文本数量。你每轮对话发送的内容，加上它回复的内容，都会进入上下文窗口。对话越长，上下文越重，两个直接后果就出现了：第一，每轮请求都在变慢；第二，费用在蹭蹭涨。

我的习惯是每完成一个小任务之后，执行/clear清空对话历史。别担心它“失忆”，必要的信息可以放在 CLAUDE.md 里，它会自动读取。对话保持清爽，响应速度快得多，钱包也没那么痛。

5.5 活用 /info 让 Claude Code 快速理解陌生项目

如果你接手一个别人的项目，或者很久没碰自己的旧项目，不要上来就让它改代码。先输入：

/info

它会显示当前目录的关键信息，包括文件结构、项目类型、可能的技术栈等。然后再让 Claude Code “读取项目 README 或者关键文件，用自己的话概括这个项目是干嘛的”。等它理解清楚了，再开始提需求。这个顺序能避免它“盲人摸象”式地乱改代码。

6. 安装到首次使用最容易踩的 6 个坑（附带排查方法）

6.1 版本过低或 npm 全局安装报错

Node 版本太老是最常见的问题，症状是在启动 claude 时提示requires Node.js >= 18之类的报错。解决办法就是去官网装新版，然后用node -v确认。

npm 全局安装报权限错误也很常见，尤其是 macOS 和 Linux 用户。解决思路有两个：要么命令前加sudo，要么用 nvm 安装 Node 并切换到用户目录，从根上避开权限问题。我强烈推荐后者，因为sudo npm install -g容易造成权限混乱，以后装其他包也会遇到类似问题。

6.2 API 密钥鉴权失败

这个问题出现的概率不小，而且错误提示往往都指向“unauthorized”或“invalid api key”。排查思路按顺序来：

1. 确认密钥完整，没有多余空格。粘贴进来的密钥经常带着换行符，可以在环境变量值里手动检查。
2. 确认终端是配置环境变量之后新开的。很多新手配完环境变量不重开终端，直接运行，发现没生效。
3. 确认密钥格式正确。Claude 的 API 密钥一般以sk-ant-开头，如果发现你的密钥长得不太一样，很可能是复制错了。
4. 确认环境变量名是否写对，ANTHROPIC_API_KEY一个字母都不能错。

6.3 启动后找不到项目文件

很多人在某个目录里执行claude，然后发现 Claude Code 看到的文件列表跟实际的对不上。这一般不是 Claude Code 的问题，而是你启动时所在的目录不对。在终端执行pwd（Windows 执行cd）看看当前路径是什么，确保它和你预期的项目路径一致。

另外要提醒一点：Claude Code 只能访问你“信任”的目录。首次启动时弹出的信任确认如果选了 No，后续它不会主动去读文件。重新启动并且在提示时选 Yes，就能解决。

6.4 对话越长越慢、花费越来越贵

这个问题其实不算 bug，算“特性”。根因就是我上面说的 token 累积。每轮对话，历史信息都会被一起发送给模型处理，所以越到后面越慢，费用也越高。

解决方案非常朴素：一个任务一个会话，做完就/clear。如果是连续多步骤的大任务，尽量把中间结果写到文件里（比如“把当前的修改记录写到 notes.md 里”），而不是靠对话上下文硬记，省流效果立竿见影。

6.5 生成的中文注释或输出乱码

如果让 Claude Code 生成了中文字符串或者中文注释，在某些 Windows 终端下运行出现乱码，这通常是文件编码问题。Python 还好，在文件开头加上# -*- coding: utf-8 -*-就能解决大部分问题；Node.js 脚本一般默认 UTF-8，问题不大。如果是终端本身显示设置的问题，可以在终端设置里把编码切到 UTF-8，或者用 Windows Terminal 替代老版控制台。

6.6 执行命令时提示权限不足

Claude Code 默认不会擅自执行高风险命令，一些涉及系统级修改的操作会触发确认机制。如果它提示“command not permitted”，你可以明确授权它“可以执行必要的命令”，或者让它给出具体命令，你手动复制到终端执行。这不是故障，而是安全机制。始终保持“看一眼再放行”的习惯，能让你的电脑保持在安全状态。

我把上面几个问题和排查方向整理成一张表，方便你对照：

我自己第一次上手的时候，光是在“信任目录”这一步就卡了十几分钟，因为没搞清楚它到底在问什么。现在回头看看，真的一点都不复杂。按照这篇文章的顺序走一遍，从安装到跑通第一个项目，新手也就是半小时的量。

最后再分享一个小经验：永远从小需求开始。我最初折腾 Claude Code 的时候，上来就让它开发一个完整的上传工具，结果需求太大，它生成了一堆我根本看不懂的文件，反而不知道怎么收场。后来我换了个策略，只让它“写一个脚本，把当前文件夹里的文件按类型整理到对应子文件夹”。需求小、目标清晰，它一次就完成了，那种成就感是实打实的。等跑通这个小流程之后，再慢慢给它加任务量，你就会发现，它真的能成为你桌面上的一个“话痨工程师”。