<!-- title: 装完却跑不起来？Claude Code 首跑排坑 -->

> 本文是 Claude Code 系列教程的入门篇，但走了一条和大多数"安装教程"完全不同的路线：**假定你已经把 `claude` 装上了，可一敲回车就报错**。我们将用 `/doctor` 体检和一张排坑决策表，把"命令找不到、认证失败、网络离线、配置不生效"这四类最高频的首次运行故障一次性讲透，最后用一只真实项目跑通从报错到首跑的完整闭环。

## 概述与适用人群

学完本教程，你将能够：

- 用 `claude /doctor` 对本地环境做一次系统性"体检"，定位是哪一层出了问题；
- 看懂并修复 `command not found`、`Invalid API key`、`offline / fetch failed`、`settings.json` 不生效这四类首跑报错；
- 区分"安装问题、登录问题、网络问题、配置问题"四个排错分层，不再盲目重装；
- 在修复后，用一个真实的小项目完成第一次 AI 编程对话，确认链路全通。

适用人群：**已经按官方指引装好 Claude Code（无论 `npm` 全局安装、原生安装脚本，还是桌面应用内置终端），但首次运行卡住、报错、或行为和教程不一致的零基础用户**。如果你连装都还没装，请先看本系列其它"安装篇"，本文专注**安装之后的排坑**。

## 前置条件

- 一台 macOS、Linux 或 Windows 10/11 机器，已能打开终端（macOS/Linux 的 Terminal、Windows 的 PowerShell 或 Git Bash）；
- 已执行过 `claude` 或 `npm install -g @anthropic-ai/claude-code`，终端里**敲过** `claude` 这个命令（不管它成功还是报错）；
- 一份可用的 Claude 订阅（Pro / Max / Team / Enterprise）**或** 一个第三方兼容 API 的密钥（本文会讲到两者的差别）；
- 一个用于测试的小项目目录，里面哪怕只有一个 `README.md` 或几行代码即可。

> 提示：Windows 用户强烈建议先安装 **Git for Windows**。官方文档明确指出，没有 Git for Windows 时，Claude Code 的部分 shell 行为会异常，这是很多人"装好却用不顺"的隐性根因。

## 核心心智模型：首跑故障的四个分层

很多初学者一遇到报错就重装，这是最低效的做法。Claude Code 的"首跑链路"其实是一条清晰的管道，报错一定落在其中某一层：

```mermaid
flowchart LR
    A["① 命令层<br/>claude 是否可被找到"] --> B["② 认证层<br/>是否有有效凭证"]
    B --> C["③ 网络层<br/>能否连上 API 端点"]
    C --> D["④ 配置层<br/>settings.json 是否被正确读取"]
    D --> E["✅ 首跑成功<br/>进入对话"]
    A -.报错.-> X["command not found<br/>PATH / 权限问题"]
    B -.报错.-> X
    C -.报错.-> X
    D -.报错.-> X
```

记住这张图，下面每一关都对应其中一层。**先判断报错属于哪一层，再动手**，能帮你省下 90% 的盲目重装时间。

## 第 0 步：先体检，再排坑

无论你遇到什么报错，第一步都应该是跑一次自带的诊断命令：

```bash
claude doctor
```

> 说明：在新版本中也可写作 `claude /doctor`（交互式入口里输入斜杠命令）。它会输出：当前可执行文件路径、Node 运行时版本、配置文件位置、检测到的认证方式、是否检测到代理等关键信息。

**预期输出（健康状态）大致长这样**（描述，非截图）：

- `Claude Code v1.x.x` —— 版本号能正常打印，说明命令层 OK；
- `Node.js vX.Y.Z` —— 运行时版本满足要求（官方要求 Node ≥ 18）；
- `Config: /Users/你/.claude/settings.json` —— 配置文件被正确发现；
- `Auth: OAuth (claude.ai)` 或 `Auth: API Key` —— 认证方式被识别；
- 一句绿色的 `No issues found`，或列出具体问题项。

**如果 `claude doctor` 本身都跑不起来**（提示 `command not found`），那故障就在**第一层**，往下看。

## 第一关：命令找不到（command not found）

这是**纯新手最高频**的报错，根因几乎都在 PATH 没配好，而不是"没装上"。

### 症状

```bash
$ claude
bash: claude: command not found
# 或 Windows PowerShell:
claude : 无法将"claude"项识别为 cmdlet
```

### 根因与解法

**1）npm 全局目录不在 PATH 里**

`npm install -g` 把 `claude` 装到了 npm 的全局 `prefix` 目录，但这个目录没进系统 PATH。先确认它到底装哪了：

```bash
npm config get prefix
# macOS/Linux 通常是 /usr/local 或 ~/.npm-global
# Windows 通常是 %APPDATA%\npm
```

确认该目录确实有 `claude`（或 `claude.cmd`），然后把它加进 PATH。

- **macOS / Linux（zsh）**：编辑 `~/.zshrc`，加一行
  ```bash
  export PATH="$HOME/.npm-global/bin:$PATH"
  ```
  然后 `source ~/.zshrc`。
- **Windows PowerShell**：用图形化"环境变量"把 `%APPDATA%\npm` 加入用户 PATH，**新开**一个终端窗口生效（旧窗口不会自动刷新）。

**2）用 `sudo` 装导致的权限错乱**

很多人为了绕过 `EACCES` 权限错误，习惯性 `sudo npm install -g`。这会把全局包装成 root 所有，后续非 root 用户更新时又报权限错。更干净的做法是改 npm 的全局前缀：

```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 再把 ~/.npm-global/bin 加入 PATH，然后无需 sudo 重新安装
```

**3）Windows 上推荐用 Git Bash 或 PowerShell，而非 cmd**

cmd 对 `claude` 这种脚本包装的命令兼容性较差，常表现为"装了却找不到"。换成 PowerShell（或 Git Bash）通常立即解决。

> **常见问题**：改完 PATH 还是 `command not found`？
> **解法**：99% 是没**新开终端**。环境变量只在进程启动时读取一次，关掉当前窗口、重开一个再试。

## 第二关：认证失败（认证层）

命令能跑了，但一进对话就弹认证错误。这一层的报错最容易让新手懵，因为"我都填了 key 了还说我没填"。

### 症状 A：`Invalid API key`

- 你用的是**第三方兼容 API**（如中转、国产模型网关），但 `ANTHROPIC_AUTH_TOKEN` / API Key 填错了、漏了 `Bearer` 前缀，或 `ANTHROPIC_BASE_URL` 没配。
- 或者你用了官方 key 却拼错了前缀（官方密钥以 `sk-ant-` 开头）。

### 症状 B：`Missing API key · Run /login`

这是**最坑**的一种：你明明写了 `settings.json`，它却还让你 `/login`。根因通常是 **Claude Code 默认走官方 OAuth 登录态，而你提供的第三方凭证没有覆盖掉这个默认行为**。

### 解法：理清两种认证路径

Claude Code 的认证有两条路，**别混用**：

```mermaid
flowchart TD
    Q{"用哪种方式登录？"} -->|官方订阅 Pro/Max| O["路径A：OAuth 浏览器登录<br/>运行 claude 后按提示 /login<br/>浏览器跳转 claude.ai 授权"]
    Q -->|第三方兼容 API / 自建网关| K["路径B：环境变量 + settings.json<br/>ANTHROPIC_BASE_URL<br/>ANTHROPIC_AUTH_TOKEN"]
    O --> OK1["✅ 凭证存在 ~/.claude/.credentials.json"]
    K --> OK2["✅ settings.json 被正确加载"]
```

**路径 A（官方订阅）**：第一次运行 `claude`，选 `Claude account`，浏览器会跳转到 claude.ai 完成授权。完成后凭证写入 `~/.claude/.credentials.json`。之后**不要再**设置 `ANTHROPIC_AUTH_TOKEN`，否则会覆盖登录态。

**路径 B（第三方 API）**：在 `~/.claude/settings.json` 里写：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的网关地址",
    "ANTHROPIC_AUTH_TOKEN": "你的token",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
  }
}
```

> 注意键名是 `env`（环境变量注入），而不是把 `ANTHROPIC_BASE_URL` 直接写在顶层。很多"配置不生效"就是因为写错了层级。

**针对症状 B 的专用排错**：如果 settings.json 都配好了还提示 `Run /login`，依次检查——

1. 文件路径对不对：必须是 `~/.claude/settings.json`（用户级），不是项目里的；
2. JSON 语法有没有错（多一个逗号、少一个引号会导致整个文件被忽略，**而且往往不报错**）；
3. 是否在项目目录里存在一个空的 `.claude/settings.json` 覆盖了用户级配置；
4. 终端里是否还残留旧的 `ANTHROPIC_API_KEY` 环境变量与 token 冲突（`echo $ANTHROPIC_AUTH_TOKEN` 排查）。

## 第三关：网络层（offline / fetch failed）

认证通过了，但一对话就 `Connection error`、`offline`、`fetch failed`、`getaddrinfo ENOTFOUND`。这是**网络层**问题，国内开发者尤其高发。

### 常见根因

- 没有配置代理，直连 `api.anthropic.com` 超时；
- 配了代理，但**没让 Claude Code 知道**（它不会自动读所有系统代理）；
- 用第三方网关时，`ANTHROPIC_BASE_URL` 域名写错或网关本身宕机。

### 解法

**1）让代理对 Claude Code 生效**。Claude Code 读取标准的 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量：

```bash
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
```

也可以写进 `settings.json` 的 `env` 块里持久化。**注意**：代理端口要和你本地代理客户端（Clash、v2ray 等）实际监听的端口一致。

**2）快速验证连通性**。在配了网关或代理后，先别急着开对话，用 curl 验证链路：

```bash
curl -i https://你的网关地址/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01"
```

能拿到 HTTP 状态码（哪怕是 401）说明网络通；如果 `Connection timed out` 或 `ENOTFOUND`，说明还卡在网络层，不要往下走。

**3）关闭代理仍想用官方端点**：确认 DNS 能解析 `api.anthropic.com`（`nslookup api.anthropic.com`），并在 `claude doctor` 里看它是否显示检测到代理。如果显示 `offline`，往往是代理变量和实际网络环境打架。

## 第四关：配置层（settings.json 不生效）

前三层都过了，命令能跑、能登录、网络也通，但某些设置（比如默认模型、自定义 hook、权限规则）就是"看起来配了却不生效"。这是**配置层**。

### 最常见的三个坑

1. **配置层级覆盖**：Claude Code 的配置按"用户级 → 项目级 → 企业级"合并，高优先级会覆盖低优先级。你在用户级改了模型，但项目里有个 `.claude/settings.json` 写死了另一个模型，就会让你以为"没生效"。

2. **JSON 静默失败**：`settings.json` 语法错误时，Claude Code 通常**直接忽略整个文件**而不报错，表现就是"我明明写了它就是不读"。用任意 JSON 校验器（或 `cat ~/.claude/settings.json | python3 -m json.tool`）验一下。

3. **key 拼错**：比如 `ANTHROPIC_BASE_URL` 拼成 `ANTHOPIC_BASE_URL`，少一个字母，环境变量名不匹配，自然不生效。

### 用 `/config` 和 `/status` 复核

进入对话后，输入斜杠命令 `/config` 可以查看**当前实际生效**的配置，`/status` 可以看当前会话用的模型、账号、上下文用量。**这两个命令显示的才是真正生效的值**，以它们为准，而不是你"以为"写入的值。

如果 `/config` 里看到的值和你 settings.json 写的不一样，就回到上面三个坑去逐个排查。

## 实战案例：一只真实项目的首跑闭环

把四层都讲完后，我们用一只真实的小项目，演示"从报错到首跑成功"的完整过程。这里用一个最常见的场景：**国内开发者 + 第三方网关 + macOS**。

### 场景设定

你已经 `npm install -g` 装好了 Claude Code，进入一个含 `app.py` 的项目目录，敲 `claude`，结果：

```
Missing API key. Run /login or set ANTHROPIC_AUTH_TOKEN.
```

### 排错步骤（套用四层模型）

**判断**：命令能跑（第一关过），提示要 API key（第二关），走路径 B。

```bash
# 第 1 步：跑体检
claude doctor
# 看到配置文件路径是 ~/.claude/settings.json

# 第 2 步：检查现有配置
cat ~/.claude/settings.json
# 发现是空的，或者 base_url/token 写在顶层（错误层级）
```

**修复**：用正确的 `env` 层级重写：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-my-gateway-token",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
  }
}
```

```bash
# 第 3 步：JSON 语法自检
python3 -m json.tool ~/.claude/settings.json > /dev/null && echo "JSON OK"

# 第 4 步：验证网络层（第三关）
curl -i https://gateway.example.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01"
# 拿到 HTTP 401（缺 body）说明网络通、key 被接收，继续
```

```bash
# 第 5 步：重新进入对话
claude
```

进入对话后，输入 `/status` 确认模型是 `claude-sonnet-4-6`、账号已识别。然后给出第一个真实任务：

```
> 读一下 app.py，告诉我它的入口函数在哪，并加一段 argparse 命令行参数解析
```

**预期结果**：Claude 读取文件、定位入口、生成 diff、请求你确认后写入。整个过程无认证错误、无网络超时。**到这一步，首跑链路全通。**

### 排坑决策流程图（建议打印贴墙上）

```mermaid
flowchart TD
    S(["运行 claude 报错"]) --> Q1{"claude 本身能调用吗？"}
    Q1 -->|command not found| F1["第一关：PATH / 权限<br/>查 npm prefix，加 PATH，重开终端"]
    Q1 -->|能| Q2{"报错提到 key / login 吗？"}
    Q2 -->|Invalid / Missing API key| F2["第二关：认证<br/>确认走 OAuth 还是第三方 token<br/>检查 settings.json 的 env 层级"]
    Q2 -->|否| Q3{"报错提到 offline / fetch / connection？"}
    Q3 -->|是| F3["第三关：网络<br/>设 HTTPS_PROXY，curl 验证网关连通"]
    Q3 -->|否| Q4{"命令能跑但行为不对？"}
    Q4 -->|是| F4["第四关：配置<br/>/config 看实际生效值<br/>查项目级是否覆盖用户级"]
    F1 --> R["重新 claude doctor 体检"]
    F2 --> R
    F3 --> R
    F4 --> R
    R --> E(["✅ /status 确认，首跑成功"])
```

## 首跑故障速查表

| 你看到的现象 | 对应层 | 一句话解法 |
| :--- | :--- | :--- |
| `command not found` | 命令层 | 把 npm 全局 bin 加进 PATH，**重开终端** |
| `EACCES` 安装/更新报错 | 命令层 | 改 npm prefix，别用 `sudo` |
| `Invalid API key` | 认证层 | 区分官方 key(`sk-ant-`) 与第三方 token，核对 base_url |
| `Missing API key · Run /login` | 认证层 | settings.json 用 `env` 层级，清掉冲突的环境变量 |
| `offline` / `fetch failed` | 网络层 | 设 `HTTPS_PROXY`，用 curl 验证端点连通 |
| `getaddrinfo ENOTFOUND` | 网络层 | DNS 解析失败，检查代理/网关域名拼写 |
| 配置改了不生效 | 配置层 | JSON 语法自检 + `/config` 看实际值 + 排查项目级覆盖 |
| Windows cmd 里找不到命令 | 命令层 | 换用 PowerShell 或 Git Bash，确保装了 Git for Windows |

## 训练营适用性评估

- **最适合**：面向**零基础到初级开发者的"Claude Code 上手营"**，作为安装篇之后的"第二节必修课"。学员在训练营第一天按指引安装，第二天大概率会在首跑环节集体卡壳，这节课正好接住这批真实问题。
- **教学时长**：建议 **45–60 分钟**（含动手排错）。可设计成"故障注入"练习——讲师故意准备 PATH 缺失、token 错配、代理未设三种环境，让学员照着决策流程图自行修复，效果远好于纯讲解。
- **不太适合**：纯架构/高阶训练营（这类学员应直接看 hooks、SDK、MCP 等进阶主题）。本节定位是**让所有人先能跑起来**，是后续一切高级主题的地基。

---

## 参考来源

1. [排查安装和登录问题 — Claude Code 官方文档](https://code.claude.com/docs/zh-CN/troubleshoot-install) — 官方对 command not found、PATH、权限、网络、认证四类首跑报错的权威排错表
2. [Advanced setup — Claude Code 官方文档](https://code.claude.com/docs/en/setup) — 系统要求、各平台安装细节、版本管理与卸载，含 Git for Windows 影响
3. [快速开始 — Claude Code 官方文档](https://code.claude.com/docs/zh-CN/quickstart) — 前置条件、订阅要求与首次会话引导
4. [Claude Code 配置踩坑指南：桌面版和终端版都适用 — 知乎](https://zhuanlan.zhihu.com/p/2045901607443944722) — 国内开发者视角的"看起来都配好了却不能用"实战踩坑
5. [Claude Code 常见问题解决手册：安装、认证、网络 — 掘金](https://juejin.cn/post/7621255363149250587) — 用 `/doctor` 命令一键体检与排坑的中文实操
6. [Freshly installed Claude Code ignores settings.json — GitHub Issue #13827](https://github.com/anthropics/claude-code/issues/13827) — settings.json 配置不生效的典型 issue 与官方回复

> [!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)