<!-- title: Claude Code零基础上手：装通配好并造首个待办CLI -->

## 概述

本教程面向**从未用过 Claude Code、甚至刚接触命令行**的零基础读者。读完它，你将完成三件事：在自己的电脑上把 Claude Code 装好并登录成功；把模型、权限、项目记忆文件这些「新手最容易踩坑」的配置一次调对；最后用它从零造出一个**真正能跑的命令行待办管理器（todo CLI）**——带增删查改、带文件持久化。全程大约需要 45 分钟，每一步都给出可复制的命令、预期结果和常见报错解法。

## 前置条件

- 一台 macOS、Linux 或 Windows 电脑（Windows 用户强烈建议先用 WSL2，体验更顺）
- 一个能联网的终端窗口：macOS 用「终端」App，Linux 用自带的 Terminal，Windows 用「Windows Terminal + WSL」
- 一个 Anthropic 账号（用 Google 或邮箱在 claude.ai 注册即可，免费额度也能跑通本教程）
- 不需要预先装 Node.js——2026 年 Claude Code 已经有原生安装器，连 Node 都能跳过

> 小提示：如果你完全没用过命令行，不要慌。下面每个命令都会解释「它做了什么」。

## 第一步：选择适合你的安装方式

Claude Code 在 2026 年主要有三条安装路径，按「省事程度」排序如下。

### 方式 A：原生安装器（最推荐，免 Node）

在 macOS / Linux / WSL 终端里粘贴这一行：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

它会下载一个独立可执行文件并放进系统路径，**全程不需要 Node.js**。Windows 用户在 PowerShell 里用官方提供的对应安装脚本即可。装完验证：

```bash
claude --version
```

预期输出类似 `claude 2.1.x`。看到版本号就说明装好了。

### 方式 B：npm 全局安装（已有 Node 生态的人）

如果你电脑上已经有 Node.js（`node -v` 能输出版本，建议 18 以上），直接：

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

### 方式 C：系统包管理器

- macOS：`brew install --cask claude-code`
- Windows：`winget install Anthropic.ClaudeCode`

| 方式 | 适合谁 | 是否需要 Node | 速度 |
|------|--------|---------------|------|
| 原生安装器 | 几乎所有人 | 否 | 最快 |
| npm | Node 开发者 | 是 | 快 |
| 包管理器 | Mac/Win 常用者 | 否 | 快 |

**常见问题**

- *`command not found: claude`*：安装器把可执行文件放进了 `~/.local/bin` 或 `~/.claude/local`，但该目录不在你的 `PATH` 里。按报错提示把对应路径加入 shell 配置（zsh 改 `~/.zshrc`，bash 改 `~/.bashrc`），加一行 `export PATH="$HOME/.local/bin:$PATH"`，然后 `source` 一下即可。
- *公司网络装不上*：换 npm 方式往往更稳，或给终端配代理后再重试。

## 第二步：登录认证

安装好之后，在任意目录下输入：

```bash
claude
```

首次启动会进入交互式引导。Claude Code 会给你一个浏览器链接完成 OAuth 登录（用你的 claude.ai 账号），登录后回到终端，提示符会变成 `>`，表示已进入对话。

如果你更习惯用 API Key（比如公司账号、或想精确控制用量），可以改用环境变量方式：

```bash
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
```

把这一行写进 `~/.zshrc` 或 `~/.bashrc`，以后新开终端就自动带上。验证登录状态可用斜杠命令：

```
/login
```

它会显示当前登录的账号与套餐。

**常见问题**

- *浏览器没自动打开*：手动复制终端里那段 `https://claude.ai/oauth/...` 链接到浏览器即可。
- *`/login` 一直转圈*：多半是网络到 `api.anthropic.com` 不通，检查代理或换网络重试。

## 第三步：一次性配好「新手三件套」

很多人装完就直接开问，结果要么模型用着不顺手，要么每条命令都被反复询问权限，体验很差。下面三步配置能帮你避开这些坑。

### 3.1 选对模型

进入对话后输入：

```
/model
```

会弹出模型列表。日常写代码、做小项目，选默认的稳定主力模型即可；遇到复杂的重构或架构设计，再临时切到更强的 Opus 档。新手记住一句话：**默认够用，遇到难题再升级**。

### 3.2 设权限模式，告别逐条放行

默认模式下，Claude Code 每次要执行命令、改文件前都会问你「是否允许」。做小练习时挺安全，但稍大一点的任务就会被打断无数次。输入：

```
/permissions
```

你可以把常用安全命令加进白名单（比如 `Bash(npm run *)`、`Bash(git status)`），以后这些就不再询问。如果完全信任当前项目，可在启动时直接：

```bash
claude --permission-mode acceptEdits
```

这会让它自动接受文件编辑、但危险命令仍会确认，是「省心又不失控」的折中。

### 3.3 用 CLAUDE.md 让它「懂你的项目」

每个项目根目录放一个 `CLAUDE.md`，Claude Code 每次启动都会自动读它，相当于给助手一份项目说明书。在项目目录里输入：

```
/init
```

它会扫描你的项目结构，自动生成一份初版 `CLAUDE.md`，里面包含技术栈、常用命令、目录约定。你可以再手动补充几句，比如「所有函数必须有 docstring」「提交前先跑 `pytest`」。

## 第四步：第一个项目——从零造一个 todo CLI

现在进入本教程的高潮：用 Claude Code 真正写出一个能用的程序。先建项目目录：

```bash
mkdir todo-cli && cd todo-cli
claude
```

进入对话后，把下面这段需求原样发给它（这叫「需求即提示词」）：

> 帮我用 Python 写一个命令行待办管理器 todo.py，要求：用 JSON 文件 `~/.todo.json` 持久化；支持 `add <内容>` 添加、`ls` 列出、`done <序号>` 标记完成、`rm <序号>` 删除；列表里已完成项前面打 `[x]`，未完成打 `[ ]`；带中文 emoji 反馈；最后给我一个 `chmod +x` 后能直接 `./todo.py` 运行的脚本，并附使用示例。

Claude Code 会创建 `todo.py`，内容大致如下（你也可以对照检查它给你的版本）：

```python
#!/usr/bin/env python3
"""todo.py - 极简命令行待办管理器，数据用 JSON 持久化。"""
import json
import sys
from pathlib import Path

DB = Path.home() / ".todo.json"


def load():
    return json.loads(DB.read_text()) if DB.exists() else []


def save(tasks):
    DB.write_text(json.dumps(tasks, ensure_ascii=False, indent=2))


def add(text):
    tasks = load()
    tasks.append({"text": text, "done": False})
    save(tasks)
    print(f"✅ 已添加: {text}")


def ls():
    tasks = load()
    if not tasks:
        print("（空空如也）")
        return
    for i, t in enumerate(tasks, 1):
        mark = "x" if t["done"] else " "
        print(f"[{mark}] {i}. {t['text']}")


def done(idx):
    tasks = load()
    if 1 <= idx <= len(tasks):
        tasks[idx - 1]["done"] = True
        save(tasks)
        print(f"🎉 已完成: {tasks[idx - 1]['text']}")
    else:
        print("⚠️ 序号无效")


def rm(idx):
    tasks = load()
    if 1 <= idx <= len(tasks):
        removed = tasks.pop(idx - 1)
        save(tasks)
        print(f"🗑️ 已删除: {removed['text']}")
    else:
        print("⚠️ 序号无效")


if __name__ == "__main__":
    cmd = sys.argv[1] if len(sys.argv) > 1 else "ls"
    if cmd == "add":
        add(" ".join(sys.argv[2:]))
    elif cmd == "done":
        done(int(sys.argv[2]))
    elif cmd == "rm":
        rm(int(sys.argv[2]))
    elif cmd == "ls":
        ls()
    else:
        print("用法: todo [add <内容> | ls | done <序号> | rm <序号>]")
```

让它加可执行权限并跑一遍示例（你也可以让 Claude Code 自己执行）：

```bash
chmod +x todo.py
./todo.py add 看完Claude Code入门教程
./todo.py add 写一个自己的小工具
./todo.py done 1
./todo.py ls
```

预期输出：

```
✅ 已添加: 看完Claude Code入门教程
✅ 已添加: 写一个自己的小工具
🎉 已完成: 看完Claude Code入门教程
[x] 1. 看完Claude Code入门教程
[ ] 2. 写一个自己的小工具
```

看到这五行输出，你的第一个 Claude Code 项目就**真正跑通了**——不是 Hello World，而是一个带持久化、能日常使用的小工具。数据存在 `~/.todo.json`，关掉终端再开，待办还在。

**常见问题**

- *它没自动跑命令，只给了代码*：在对话里直接说「帮我执行 chmod 和上面四条示例命令并贴出结果」。新手常以为它「只会说不会做」，其实你明确授权后它会用工具直接执行。
- *中文显示乱码*：确认终端编码是 UTF-8（macOS/Linux 默认就是）；Windows 老版 cmd 需先 `chcp 65001`。
- *想要每天开机自动提醒未完成项*：让 Claude Code 帮你加一个 `due` 命令或在系统里挂个 cron，这正是练习「持续迭代」的好起点。

## 实战案例：把 todo CLI 升级成「带优先级的小助手」

跑通基础版后，再给 Claude Code 发一句迭代需求，体验它的「持续改代码」能力：

> 给 todo.py 加优先级：`add` 时支持 `-p high|mid|low`，默认 mid；`ls` 按优先级排序输出（high→mid→low），并在每行前面加优先级标签如 `(high)`；再加一个 `clear` 命令清空所有已完成项。

它会改动 `add`、`ls` 并新增 `clear`，保持向后兼容。你可以反复用这种「提一句需求→它改一版→你跑一遍」的循环来打磨工具，这正是 Claude Code 最日常、最高频的用法。

## 工作流程图

下面这张图概括了从「装好」到「跑通第一个项目」的完整链路：

```text
flowchart TD
    A[打开终端] --> B{选安装方式}
    B -->|无Node| C[curl 原生安装器]
    B -->|有Node| D[npm 全局安装]
    B -->|Mac/Win| E[brew / winget]
    C --> F[claude --version 验证]
    D --> F
    E --> F
    F --> G[claude 首次启动]
    G --> H[OAuth 浏览器登录]
    H --> I[/model 选模型]
    I --> J[/permissions 设白名单]
    J --> K[mkdir 项目 && claude]
    K --> L[/init 生成 CLAUDE.md]
    L --> M[发需求: 造 todo CLI]
    M --> N[它写代码 + 跑示例]
    N --> O{输出正确?}
    O -->|是| P[🎉 第一个项目跑通]
    O -->|否| Q[让它修 + 重跑]
    Q --> N
```

## 必学斜杠命令速查

新手最容易忽略、却最能提升效率的几个内置命令：

| 命令 | 作用 |
|------|------|
| `/help` | 查看所有可用命令 |
| `/init` | 扫描项目，生成 CLAUDE.md |
| `/model` | 切换模型 |
| `/permissions` | 管理命令白名单 |
| `/clear` | 清空当前对话上下文（换任务前必用） |
| `/compact` | 压缩长对话，节省上下文额度 |
| `/cost` | 查看本次会话花了多少额度 |
| `/resume` | 恢复之前的历史会话 |

## 延伸阅读

- **官方快速上手**：`https://code.claude.com/docs/en/quickstart` ——权威安装与首次使用，命令最准
- **官方终端新手指南**：`https://code.claude.com/docs/en/terminal-guide` ——从没用过终端的人也能跟着做
- **进阶配置（代理、API Key、多环境）**：`https://code.claude.com/docs/en/setup` ——系统要求与高级安装

## 训练营适用性评估

- **适合训练营**：编程入门营、AI 工具上手营、新人入职技术营。零基础友好，无前置编程经验要求。
- **预计教学时长**：讲解 + 跟做约 **45–60 分钟**（含登录认证的环境差异调试）。
- **可扩展任务**：把 todo CLI 升级为带截止日期、Web 界面，或迁移成 Node 版本，可作为第二课时。
- **考核点**：能独立完成「安装→登录→配 CLAUDE.md→跑通 todo CLI 输出正确列表」全链路即算通过。

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方安装与首次使用权威指南
2. [Terminal guide for new users - Claude Code Docs](https://code.claude.com/docs/en/terminal-guide) — 面向零终端经验用户的逐步图文教程
3. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、原生安装器与高级配置
4. [Claude Code Tutorial for Beginners 2026: From Installation to Building Your First Project](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 开发者博客，从安装到首个项目全流程
5. [How to Use Claude Code (Beginner Guide) - builder.io](https://www.builder.io/blog/how-to-use-claude-code) — 实用新手避坑与最佳实践
6. [UPDATED 2026 Claude Code Tutorial #1 - Intro & Setup (YouTube)](https://www.youtube.com/watch?v=NBQePr-XjrU) — 视频教程，适合跟着画面操作
7. [Installation & Setup - DeepWiki](https://deepwiki.com/anthropics/claude-code/2.1-installation-and-setup) — 社区维护的安装与配置知识汇总

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)