# 安装 Claude Code：跑通第一次会话

> 从「终端是什么」讲起，带你在 macOS、Windows 或 Linux 上装好 Claude Code、登录账号、完成第一次会话，并附上最常见安装报错的排查思路。

- 网址：https://coding.chengyu.dev/learn/start/install-claude-code/
- 学习路径：起步：第一次让 AI 写出能跑的东西
- 预计用时：25 分钟；核实日期：2026-10-25
- 官方来源：[Quickstart（Claude Code 官方文档）](https://code.claude.com/docs/en/quickstart)，[Terminal guide for new users（Claude Code 官方文档）](https://code.claude.com/docs/en/terminal-guide)，[Advanced setup（Claude Code 官方文档）](https://code.claude.com/docs/en/setup)，[Troubleshoot installation and login（Claude Code 官方文档）](https://code.claude.com/docs/en/troubleshoot-install)，[Authentication（Claude Code 官方文档）](https://code.claude.com/docs/en/authentication)，[Commands（Claude Code 官方文档）](https://code.claude.com/docs/en/commands)，[Permission modes（Claude Code 官方文档）](https://code.claude.com/docs/en/permission-modes)，[Interactive mode（Claude Code 官方文档）](https://code.claude.com/docs/en/interactive-mode)，[Anthropic 支持的国家和地区](https://www.anthropic.com/supported-countries)

## 学习目标

- 能打开终端并使用 cd、ls 等最基本的命令
- 能在自己的系统上安装 Claude Code 并用 claude --version 验证
- 能完成登录，并在一个文件夹里开始第一次会话
- 遇到 command not found、网络或登录报错时，知道按什么顺序排查

装软件这一步，是大多数零基础读者的第一道坎：不是装不上，而是看到一屏英文报错就以为自己搞坏了电脑。

先给你吃一颗定心丸：**Claude Code 的安装只有一条命令，而且官方文档把每种常见报错都对应好了解法。** 这一课带你一步一步做，同时告诉你每一步「正常应该看到什么」，这样你能判断自己有没有走偏。

## 动手前：确认三件事

1. **有账号。** Claude Code 需要 Claude 的 Pro、Max、Team 或 Enterprise 订阅，或者一个 Claude Console（按量付费的 API）账号。官方明确说，免费版 claude.ai 不含 Claude Code。订阅价格见上一课，以官网为准。
2. **系统够新。** 官方要求：macOS 13.0 及以上，Windows 10 版本 1809 及以上，或 Ubuntu 20.04、Debian 10、Alpine 3.19 及以上；内存 4 GB 以上；需要联网。
3. **所在地区受支持。** 官方要求使用地在其支持的国家和地区内。请先看[支持列表](https://www.anthropic.com/supported-countries)，并遵守服务条款。

> **实在不想碰终端？**
>
> 官方还提供 Claude Code 桌面应用（macOS、Windows，Linux 为 beta），装好后点击顶部的 Code 标签页就能用，同样需要付费订阅。它和命令行版是同一个引擎。本课以终端为主，是因为它覆盖面最广，且后面的课程会在终端里演示；桌面版的区别主要是界面，核心习惯完全一样。

## 终端是什么，怎么打开

终端（terminal）就是一个**用文字给电脑下命令**的窗口。你平时用鼠标双击打开文件夹，在终端里是输入一行命令来做同样的事。它看起来像黑底白字的聊天框，但你不是在跟人聊，而是在和操作系统对话。

怎么打开：

| 系统 | 打开方式 | 粘贴 |
|---|---|---|
| macOS | 按 `Cmd + 空格`，输入 `Terminal`，回车 | `Cmd + V` |
| Windows | 按 `Win + X`，选「Windows PowerShell」或「终端」 | `Ctrl + V` 或右键 |
| Linux | 按 `Ctrl + Alt + T`，或在应用菜单里搜 Terminal | `Ctrl + Shift + V` |

打开后你会看到一个闪烁的光标，前面有一串提示符，比如 `yourname@mac ~ %` 或 `PS C:\Users\yourname>`。意思是「我在等你输入命令」。

三个最基本的命令，能让你在里面不迷路（macOS、Linux 和 Windows PowerShell 通用）：

- `pwd`：我现在在哪个文件夹？
- `ls`：这里面有什么？
- `cd 文件夹名`：进入某个文件夹。`cd ..` 是回到上一级。

几条保命常识：

- **终端里不能用鼠标点**，光标移动用方向键；
- 命令跑起来后想打断它，按 `Ctrl + C`；
- 命令是**回车才执行**的，粘贴一行命令后别忘了按回车；
- 敲命令时大小写和空格都有意义，能复制粘贴就别手打。

> **Windows 用户先分清 PowerShell 和 CMD**
>
> Windows 有两个长得很像的命令行：PowerShell 的提示符以 `PS` 开头（如 `PS C:\Users\你>`），CMD 不带 `PS`（如 `C:\Users\你>`）。下面两条 Windows 安装命令分别对应它们，用错了会报错。后面的排错表里也有对应项。

## 安装

在终端里粘贴下面**对应你系统的一条**命令，回车。官方推荐这种「原生安装」，它会在后台自动更新。

| 系统 | 命令 |
|---|---|
| macOS、Linux、WSL | `curl -fsSL https://claude.ai/install.sh \| bash` |
| Windows PowerShell | `irm https://claude.ai/install.ps1 \| iex` |
| Windows CMD | `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` |

注意两点。第一，**安装过程中看不到进度条**，终端像是卡住了，其实是在下载，耐心等到出现安装成功的提示。第二，装完后要**关掉这个终端窗口、重新开一个**，再验证：

```text
# macOS / Linux 示例
$ curl -fsSL https://claude.ai/install.sh | bash
  （等待下载，无进度显示……）
  Claude Code successfully installed!
# 关掉窗口，重新打开一个终端，再运行：
$ claude --version
  2.1.211 (Claude Code)
```

版本号会随时间变化，能打印出「数字 + (Claude Code)」就说明安装成功。

其他安装方式：macOS 可用 Homebrew（`brew install --cask claude-code`），Windows 可用 WinGet（`winget install Anthropic.ClaudeCode`），Linux 有 apt、dnf、apk 仓库。这些方式**不会自动更新**，需要自己定期升级。零基础读者建议直接用上面的原生安装。

关于 Windows 上的 Git：官方推荐在原生 Windows 上装 [Git for Windows](https://git-scm.com/downloads/win)，这样 Claude Code 能使用 Bash 工具；不装的话它会改用 PowerShell。安装时一路点「下一步」保持默认即可。第 6 课我们也会用到 git，所以装一下不亏。

## 登录与第一次会话

先建一个练习用的文件夹并进去。macOS、Linux 和 Windows PowerShell 都可以这样做：

```text
$ mkdir claude-hello
$ cd claude-hello
$ pwd
  /Users/yourname/claude-hello
$ claude
```

输入 `claude` 回车后：

1. **工作区信任**：第一次在一个文件夹里启动，它会问你是否信任这个文件夹。这是安全机制：确认这是你自己的文件夹再选信任。
2. **登录**：浏览器会自动打开，登录你的 Claude 账号并授权。若浏览器没弹出来，终端里按 `c` 复制登录链接，自己粘贴到浏览器。登录成功后终端会显示 `Login successful`，按回车继续。
3. **进入会话**：你会看到版本、当前模型、当前文件夹，下面是输入框。

之后的凭据会保存在本机，不用每次登录。想换账号用 `/login`，退出登录用 `/logout`。

> **一个容易踩的坑：环境变量里的 API 密钥会抢占订阅**
>
> 如果你的电脑环境变量里留有 `ANTHROPIC_API_KEY`（比如之前某个项目或前公司设置过），Claude Code 在你同意使用它之后，会优先用这个密钥而不是你的订阅。若那个密钥所属的组织已停用，就会出现类似「组织已被禁用」的错误，哪怕你的订阅明明有效。排查办法是先在终端执行 `unset ANTHROPIC_API_KEY`（macOS、Linux），再在会话里输入 `/status` 看当前使用的是哪种凭据。

### 关于「它会不会乱改我的电脑」

会话里的权限模式决定了它**不问你就能做什么**。官方当前的设计是这样的：

- **手动模式（Manual）**：默认只能读。要改文件、跑命令都先问你，你选允许一次或始终允许；
- **自动模式（Auto）**：由另一个模型审查它要做的动作，只拦下它认为有风险的。较新版本在终端里默认从自动模式开始，较旧版本只在部分订阅上默认如此；
- **接受编辑（Accept edits）**、**计划（Plan）** 等其他模式。

你可以随时按 `Shift + Tab` 在几种模式间切换，状态栏会显示当前模式。**刚入门时，我建议你把它切到手动或接受编辑**，看着它每一步要做什么，培养对它行为的直觉。如果你看到的第一次会话没有一直弹确认，不用担心，那是自动模式在工作。权限的细节在[权限管理](/learn/claude-code/permissions/)一课展开。

### 问出第一个问题

在空文件夹里先让它做件无害的事：

**第一次会话：让它检查你的开发环境**

```text
请检查我这台电脑的开发环境，只读不改：
1. 当前文件夹路径是什么，里面有什么文件；
2. 是否已安装 git，版本是多少；
3. 是否已安装 Node.js，版本是多少；
4. 用一句话告诉我，我的电脑要做一个纯 HTML 的小网页，还缺什么。

不要安装任何东西，不要修改任何文件。把每个检查用的命令也列出来，我想看看你是怎么查的。
```

它会运行类似 `git --version` 的命令，这时留意它请求权限的提示。这是你**第一次看到智能体的「读、想、做、验」**。没装 git 或 Node.js 也不要紧，后面的课程里会处理。

## 常用的几个命令和按键

你不需要现在记住所有，下面这些够你用一个星期。

**在终端里（启动前）**

| 命令 | 作用 |
|---|---|
| `claude` | 在当前文件夹启动交互会话 |
| `claude "任务描述"` | 启动并直接带上第一句话 |
| `claude -c` | 继续当前文件夹里最近一次会话 |
| `claude -r` | 从列表里选一个过去的会话恢复 |
| `claude --version` | 查看版本 |
| `claude doctor` | 打印安装和配置的诊断信息 |

**在会话里（斜杠命令）**

| 命令 | 作用 |
|---|---|
| `/help` | 查看可用命令 |
| `/clear` | 清空对话，开始新话题（上一个对话可用 `/resume` 找回） |
| `/resume` | 恢复一个历史对话 |
| `/rewind` | 回退对话和代码到之前的某个点（第 6 课详讲） |
| `/diff` | 查看工作区里的改动，包括它刚改的 |
| `/usage` | 查看本次会话用量和订阅额度（`/cost` 是它的别名） |
| `/model` | 切换模型 |
| `/login`、`/logout` | 登录、退出账号 |
| `/exit` | 退出（也可按两次 `Ctrl + D`） |

**按键**

- `Esc`：中途打断它，已完成的工作保留，你可以改口；
- 输入框为空时连按两次 `Esc`：打开回退菜单；
- `Shift + Tab`：切换权限模式；
- 输入多行：先输入 `\` 再回车，或用 `Ctrl + J`。

## 装不上怎么办：排错思路

遇到报错，先别慌，按这个顺序想：**报错是在安装阶段、启动阶段，还是登录阶段？** 然后对照下表。每一项都来自官方排错文档。

| 你看到的现象 | 最可能的原因 | 怎么做 |
|---|---|---|
| `command not found: claude` 或 `claude is not recognized` | 安装目录还没进 PATH（系统找不到这个程序） | 先**关掉终端重开**。仍不行，macOS 的 zsh 执行 `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc`，再 `source ~/.zshrc`；Windows 见官方排错页的 PATH 一节。安装器结束时会打印具体修复命令，留意其中的 Setup notes |
| `irm is not recognized` | 在 CMD 里运行了 PowerShell 的命令 | 改用 PowerShell，或用 CMD 版安装命令 |
| `The token '&&' is not a valid statement separator` | 在 PowerShell 里运行了 CMD 的命令 | 改用 PowerShell 版命令 |
| `syntax error near unexpected token '<'`，或屏幕上出现 HTML 代码 | 下载地址返回了网页而不是安装脚本 | 若页面写着「App unavailable in region」，说明所在地区不受支持；否则稍后重试，或改用 Homebrew、WinGet 安装 |
| `curl: (22) ... 403` | 代理或网络过滤拦截，或所在地区不受支持 | 参考下面「网络问题」一节 |
| `TLS connect error`、`Could not create SSL/TLS secure channel` | 证书或加密协议问题，旧版 Windows 10 常见 | 官方建议先在 PowerShell 执行 `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` 再重试 |
| `dyld: cannot load` 或 `built for Mac OS X 13.0` | macOS 版本太旧 | 在「关于本机」查看版本，低于 13.0 需先升级系统 |
| 登录时报 `OAuth error: Invalid code` | 登录码过期或复制不完整 | 回车重试并快速完成；浏览器没自动弹出时按 `c` 复制链接 |
| 登录后 `403 Forbidden` | 订阅未生效，或 Console 账号缺少角色，或被代理干扰 | 去 claude.ai 的设置里确认订阅状态 |
| 登录反复失败，原因不明 | 登录状态异常 | `/logout`，退出 Claude Code，重新运行 `claude` 再登录一次 |

还有两个通用的诊断工具：

- 在终端运行 `claude doctor`，它会不启动会话就打印安装和设置的诊断；
- 在会话里输入 `/doctor`，让 Claude 帮你检查并提出修复建议。

### 网络问题（客观说明）

安装脚本要从 `downloads.claude.ai` 下载程序，登录和使用时还要连接 Anthropic 的服务。网络不通时，你可能看到连接超时、`Could not resolve host`、下载中断，或者 403。

官方给出的诊断办法是在终端执行 `curl -sI https://downloads.claude.ai/claude-code-releases/latest`（Windows PowerShell 里用 `curl.exe`），第一行出现 `200` 说明能连通；`403` 通常是网络过滤或地区不受支持；`5xx` 是服务暂时问题，等几分钟再试；没有任何输出或超时说明你的网络挡住了这条连接。

官方排错文档对「地区网络限制」给出的建议是换一个网络或使用 VPN。需要提醒你的是：**地区是否受支持由服务条款决定，不是技术上能不能连上就算数。** 请你自行评估并遵守相关规定，本站不推荐任何具体的网络服务。如果试过以后仍然无法使用，不如回到上一课，选一个你所在地区能稳定使用的工具，学习路径中的方法同样适用。

> 小测：安装完成后，你在新开的终端里输入 claude，却提示 command not found。最先应该做什么？

> 小测：你有有效的 Claude Pro 订阅，登录后却报错说「组织已被禁用」。最可能是什么原因？

## 动手试一试

- [ ] 打开终端，用 pwd、ls、cd 在文件夹间走一圈，再回到起点
- [ ] 按你的系统运行安装命令，关掉终端重开后，claude --version 能打印版本号
- [ ] 新建 claude-hello 文件夹，进去运行 claude，完成登录
- [ ] 把上面「检查开发环境」的提示词发给它，留意它请求权限的提示，并读懂它用了哪些命令
- [ ] 按一次 Shift + Tab，观察状态栏里权限模式的变化，再切回你喜欢的模式
- [ ] 输入 /exit 退出，再运行 claude -c，确认能接着刚才的对话继续