装完却跑不起来？Claude Code 首跑排坑

首页 › tutorials › 装完却跑不起来？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 的"首跑链路"其实是一条清晰的管道，报错一定落在其中某一层：

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 步：先体检，再排坑

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

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 没配好，而不是"没装上"。

症状

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

根因与解法

1）npm 全局目录不在 PATH 里

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

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 的全局前缀：

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 的认证有两条路，别混用：

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 里写：

{
  "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，依次检查——

文件路径对不对：必须是 ~/.claude/settings.json（用户级），不是项目里的；
JSON 语法有没有错（多一个逗号、少一个引号会导致整个文件被忽略，而且往往不报错）；
是否在项目目录里存在一个空的 .claude/settings.json 覆盖了用户级配置；
终端里是否还残留旧的 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 环境变量：

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 验证链路：

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、权限规则）就是"看起来配了却不生效"。这是配置层。

最常见的三个坑

配置层级覆盖：Claude Code 的配置按"用户级 → 项目级 → 企业级"合并，高优先级会覆盖低优先级。你在用户级改了模型，但项目里有个 .claude/settings.json 写死了另一个模型，就会让你以为"没生效"。
JSON 静默失败：settings.json 语法错误时，Claude Code 通常直接忽略整个文件而不报错，表现就是"我明明写了它就是不读"。用任意 JSON 校验器（或 cat ~/.claude/settings.json | python3 -m json.tool）验一下。
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。

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

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

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

{
  "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"
  }
}

# 第 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 被接收，继续

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

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

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

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

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

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 等进阶主题）。本节定位是让所有人先能跑起来，是后续一切高级主题的地基。

参考来源

排查安装和登录问题 — Claude Code 官方文档 — 官方对 command not found、PATH、权限、网络、认证四类首跑报错的权威排错表
Advanced setup — Claude Code 官方文档 — 系统要求、各平台安装细节、版本管理与卸载，含 Git for Windows 影响
快速开始 — Claude Code 官方文档 — 前置条件、订阅要求与首次会话引导
Claude Code 配置踩坑指南：桌面版和终端版都适用 — 知乎 — 国内开发者视角的"看起来都配好了却不能用"实战踩坑
Claude Code 常见问题解决手册：安装、认证、网络 — 掘金 — 用 /doctor 命令一键体检与排坑的中文实操
Freshly installed Claude Code ignores settings.json — GitHub Issue #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学通信知识星球海报-扫码加入