新手上路（二）： Claude Code 装完先别用！Windows 初始化 6 步流水线 + 4个高频报错排查

Windows 10 · Claude Code CLI v2.x · DeepSeek V4 Pro / Anthropic API · 2026-05-01

一、这篇教程解决什么问题

一句话定位：刚按照《新手上路（一）：CC-Switch使用Claude Code 每步都要确认？一文讲透六种权限模式，开 Auto 让它自己干！ - 掘金》完成安装， Claude Code 装完打开终端一片茫然？这篇指南解决的就是"下一步敲什么"。告诉你第一组命令该敲什么、每个命令做什么、配完怎么验证没配错。

阅读前提：

已完成 Claude Code CLI 安装，claude --version 正常输出版本号
已持有可用的 API Key（DeepSeek V4 Pro 或 Anthropic 官方），且账户余额 > ¥1.00
使用 Windows 10 或 Windows 11（macOS/Linux 用户可参考命令，路径按系统替换）

读完能得到什么：

✅ 一套标准 6 步初始化流水线，每步附完整命令和预期输出（认证 → 健康检查 → 项目初始化 → 记忆文件 → 权限配置 → 验证）

✅ 一份可复用的 settings.json 配置模板（DeepSeek + Anthropic 双端点）

✅ 4 个国内环境高频报错的五段式排查（401/403、超时、doctor 卡死、/init 无输出）

✅ 文末速查卡可直接收藏，每次开新项目照抄即可

二、前置验证

2.1 依赖清单

组件	最低版本	说明
Node.js	18.0+（推荐 22 LTS）	Claude Code 运行时
npm	10.x+	包管理器，随 Node.js 自带
Claude Code CLI	v2.0+	本篇主角

2.2 逐条验证

node --version       # 应输出 v22.x.x 或 v20.x.x
npm --version        # 应输出 10.x.x 或更高
claude --version     # 应输出 v2.0.x 或更高

如果 claude 命令不可用：

npm list -g @anthropic-ai/claude-code   # 检查是否全局安装

如果未安装，回到《梦开始的地方：Claude Code 在 Windows & DeepseekV4Pro上的国内环境安装与调试指南 - 掘金》第 3 节完成安装。

三、初始化步骤

3.1 运行 claude doctor — 健康检查

claude doctor

这是 Claude Code 内置的系统诊断工具。它会检查：

Node.js 版本兼容性
安装方式识别（npm / winget / Homebrew）
自动更新状态
到 Anthropic API / 自定义 Base URL 的网络连通性
认证凭据有效性
配置文件完整性

预期输出（关键行）：

✓ Node.js version
✓ Installation method
✓ Auto-update enabled
✓ Network connectivity
✓ Authentication
✓ Settings file valid

如果 claude doctor 卡住不动（100% CPU），这是 v1.0.95 版本的已知 bug。按 Ctrl+C 终止，改为在交互会话内运行 /doctor。详见 Debug #2。

3.2 启动交互会话 + 运行 /init — 项目初始化

进入你的项目目录，启动 Claude Code：

cd C:\Workspace\你的项目
claude

启动后，你会看到一个交互式终端界面。此时输入第一个、也是最重要的一条斜杠命令：

/init

/init 做了什么：

扫描整个项目目录结构
读取关键配置文件（package.json、tsconfig.json、.gitignore 等）
分析技术栈、目录约定、构建/测试命令
在项目根目录生成 CLAUDE.md 文件

CLAUDE.md 是 Claude Code 的项目级持久记忆文件。每次你在这个项目目录下启动新会话时，Claude 会自动读取 CLAUDE.md 的内容注入到上下文中，从而无需每次重复解释项目背景。

生成后，你应该立即审阅 CLAUDE.md 的内容：

/memory

这会打开 CLAUDE.md 供你编辑。推荐手动补充以下内容：

# 补充规则

## 编码规范
- 使用 4 空格缩进
- 函数命名使用 camelCase
- 所有公开 API 必须有类型注解

## 测试要求
- 新增逻辑必须有单元测试
- 使用 pytest（Python）/ jest（Node.js）

## 禁止事项
- 不要修改 config/ 目录下的自动生成文件
- 不要直接操作生产数据库

/init 可以重复运行。当项目结构发生重大变化（新增模块、重构目录）时，重新运行 /init 会更新 CLAUDE.md。你手动添加的补充内容不会被覆盖——/init 只更新它生成的分析部分。

CLAUDE.md 的文件层级（优先级从高到低）：

位置	用途	Git
`<项目根>/CLAUDE.md`	项目级共享规则，团队提交	✅ 提交
`<项目根>/.claude/CLAUDE.md`	个人开发记忆，仅你可见	❌ gitignore
`~/.claude/CLAUDE.md`	全局个人规则，所有项目生效	仅本地

3.3 配置 settings.json — 权限与行为控制

/init 处理"项目是什么"，settings.json 处理"Claude Code 怎么做事"。两者互补。

3.3.1 settings.json 的三层优先级

优先级	路径	用途	Git
1（最高）	`<项目>/.claude/settings.local.json`	个人项目偏好 + 秘密（API Key）	❌ 不提交
2	`<项目>/.claude/settings.json`	团队共享规则	✅ 提交
3（最低）	`C:\Users\<用户名>\.claude\settings.json`	全局默认	仅本地

三层是合并关系，不是替换。上层覆盖下层的同名字段，但 deny 类权限规则不可被下层 allow 撤销。

3.3.2推荐的最小配置（全局 settings.json）

文件：C:\Users\<用户名>\.claude\settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_EFFORT_LEVEL": "max",
    "API_TIMEOUT_MS": "3000000"
  },
  "model": "deepseek-v4-pro",
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(python:*)",
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "WebSearch",
      "WebFetch",
      "Task",
      "Skill"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(git push:*)",
      "Bash(git reset --hard:*)"
    ]
  }
}

权限配置详解见《新手上路（一）：CC-Switch使用Claude-Code Cli的初始化设置----六种权限模式配置指南，启用Auto模式》。如果你希望 Claude Code 自动执行大部分操作而不每次询问，将 "permissionMode" 设置为 "acceptEdits"。

3.3.3 命令行配置工具

除了手动编辑 JSON，也可以用 CLI 命令操作配置：

# 列出当前所有配置
claude config list

# 查看某个配置项
claude config get model

# 设置项目级配置（写入 <项目>/.claude/settings.json）
claude config set model "deepseek-v4-pro"

# 设置全局配置（写入 ~/.claude/settings.json）
claude config set -g model "deepseek-v4-pro"

# 向列表型配置追加值
claude config add permissions.allow "Bash(npm:*)"

# 从列表型配置移除值
claude config remove permissions.allow "Bash(rm:*)"

3.5 验证配置 — 确认一切就绪

重新启动 Claude Code 并运行验证命令：

claude

进入交互会话后：

/status

预期输出关键行：

Model: deepseek-v4-pro
API endpoint: https://api.deepseek.com/anthropic
Permission mode: default (or acceptEdits)

切换一次模型确认可用模型列表：

/model

应显示可选模型列表。如果你配置了 DeepSeek，应看到：

deepseek-v4-pro (current)
deepseek-v4-flash

最后，做一个端到端功能测试——让 Claude Code 执行一个简单任务：

列出当前目录的文件结构，用树形展示

如果 Claude 能正确调用 Get-ChildItem（Windows）或 ls（macOS/Linux）并输出目录树，说明工具调用链路正常。

四、Debug #1 — /init 执行后未生成 CLAUDE.md

报错日志

/init 执行完成后，项目根目录没有出现 CLAUDE.md 文件。
或者终端输出 "Error: Failed to generate CLAUDE.md"。

根因

/init 依赖对项目目录的读取权限和文件写入权限。以下三种情况会导致生成失败：

目录无写入权限：当前用户对项目根目录没有写权限（常见于 C:\Program Files\ 下的项目或 Docker 挂载卷）
已有的 CLAUDE.md 被锁定：文件被其他进程占用（如 VS Code 正在编辑且未保存的冲突对话框）
项目目录过大：文件数量超过 10,000 时，/init 的扫描阶段可能超时。这是 Claude Code 内部的文件遍历超时机制，默认约 60 秒

一览对比表

对比维度	正常情况	异常情况
目录写入权限	当前用户拥有完全控制权	目录为只读或所有者是 SYSTEM
CLAUDE.md 文件状态	不存在或可覆盖	被其他进程独占锁定
项目文件数量	< 5,000	> 10,000 且无 `.gitignore` 排除
/init 执行时间	< 30 秒	> 60 秒后超时

代码修复

检查一：确认写入权限

# 查看当前目录的 ACL（访问控制列表）
icacls .
# 应包含 <你的用户名>:(F) 或 <你的用户名>:(M)

如果缺少写入权限：

# 将项目移到用户目录下（推荐）
# 不要放在 C:\Program Files\ 或 C:\Windows\

检查二：确认文件未被锁定

# 关闭所有可能占用 CLAUDE.md 的编辑器（VS Code, Notepad++ 等）
# 如果文件已存在，先备份再删除
mv CLAUDE.md CLAUDE.md.bak

检查三：大项目手动创建 CLAUDE.md

如果项目文件太多导致 /init 超时，手动创建一个精简版 CLAUDE.md：

# 项目名称

## 技术栈
- Python 3.12 + FastAPI
- PostgreSQL 16
- React 18 + TypeScript

## 目录结构
- `backend/` — API 服务
- `frontend/` — Web UI
- `docs/` — 文档

## 常用命令
- 启动开发服务器: `npm run dev`
- 运行测试: `npm test`
- 构建: `npm run build`

手动创建后，下次启动 Claude Code 时它同样会自动读取。

验证

ls CLAUDE.md
# 应输出: CLAUDE.md

启动 Claude Code 后输入一条需要项目上下文的问题：

这个项目的构建命令是什么？

如果 Claude 能正确回答你在 CLAUDE.md 中写的内容，说明记忆文件生效。

五、Debug #2 — claude doctor 卡住不动（100% CPU）

报错日志

PS> claude doctor
# 终端无任何输出，光标闪烁，CPU 风扇狂转
# 5 分钟后仍无响应，只能 Ctrl+C 终止

根因

这是 Claude Code CLI v1.0.95 引入的一个已知回归 bug（GitHub Issue #6705）。当 claude doctor 在交互会话外部（即直接在终端运行，而非在 Claude Code 会话内通过 /doctor 运行）执行时，会进入无限循环，消耗 100% CPU。

这个 bug 的机制层原因：claude doctor 在外部运行时尝试初始化完整的 MCP（Model Context Protocol）诊断子系统，但缺少交互会话的运行时上下文，导致 MCP 连接等待循环永不退出。

截至 2026 年 5 月，此 bug 在 v1.0.95+ 版本仍然存在。Anthropic 团队已在 issue 中确认，修复版本待发布。

一览对比表

对比维度	`claude doctor`（外部）	`/doctor`（会话内）
运行位置	终端直接执行	Claude Code 交互会话内
MCP 诊断	初始化失败 → 死循环	正常诊断
其他诊断项（Node.js/网络/认证）	正常执行（在卡住之前）	正常执行
推荐使用	❌ 当前版本不建议	✅ 推荐

代码修复

方案一（推荐）：在交互会话内运行 /doctor

claude

进入会话后输入：

/doctor

方案二：跳过 doctor，分项手动验证

# 替代 claude doctor 的手动检查
node --version                              # Node.js 版本
claude --version                            # Claude Code 版本
claude -p "say hello"                       # API 连通性测试（需要有效的 API Key）

claude -p "say hello" 是 --print 模式的简写，非交互式执行一次查询后退出。如果返回正常回复，说明 API 认证和网络都正常。

验证

/doctor

会话内运行应正常输出诊断结果，不再卡死。

六、Debug #3 — 启动后提示 401 / 403 认证失败

报错日志

Error: 401 Unauthorized
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }

或：

Error: 403 Forbidden
  "error": {
    "type": "permission_error",
    "message": "insufficient balance"
  }

根因

401：API Key 无效。可能原因：

API Key 复制时漏了字符（特别是 sk- 前缀后的第一个字符）
Key 已被删除或过期（DeepSeek 的 Key 可以手动吊销）
环境变量名写错——ANTHROPIC_AUTH_TOKEN 不等于 ANTHROPIC_API_KEY（前者是 Claude Code 的通用 token 变量名，后者是 Anthropic SDK 的变量名；使用 DeepSeek 时两种变量名均可，但值必须对）

403：API Key 有效但没有调用权限。常见原因：

DeepSeek 账户余额不足（V4-Pro 单次调用最低 ¥0.98，余额 < ¥1.00 时报 403）
账户未完成实名认证
API 端点路径错误——/anthropic 后缀是 DeepSeek 兼容 Anthropic Messages API 的特殊路径，漏写会返回 404 而非 401

一览对比表

对比维度	401 Unauthorized	403 Forbidden
含义	API Key 错误或不存在	API Key 有效但无权调用
最常见原因	Key 复制遗漏 / 变量名写错	余额不足
DeepSeek 错误响应体	`"invalid x-api-key"`	`"insufficient balance"`
修复方向	检查 Key 值 + 变量名	充值 + 检查账户状态

代码修复

# 第一步：确认环境变量是否生效
$env:ANTHROPIC_AUTH_TOKEN
# 应输出 sk-你的Key（如果为空，说明没有正确设置）

# 第二步：用 curl 直接测试 API Key 是否有效
curl -X POST https://api.deepseek.com/anthropic/v1/messages `
  -H "Content-Type: application/json" `
  -H "x-api-key: sk-你的Key" `
  -H "anthropic-version: 2023-06-01" `
  -d '{"model":"deepseek-v4-pro","max_tokens":5,"messages":[{"role":"user","content":"hi"}]}'

如果 curl 返回 401，说明 Key 本身无效，去 platform.deepseek.com 重新创建一个。

如果 curl 返回 403，检查账户余额和认证状态。

如果 curl 正常但 Claude Code 仍报错，检查 settings.json 中环境变量名是否正确：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
  }
}

注意是 ANTHROPIC_AUTH_TOKEN（下划线），不是 ANTHROPIC-AUTH-TOKEN（连字符）。JSON 文件中的 key 是大小写敏感的。

验证

claude -p "say hello"
# 应输出正常英文回复

七、Debug #4 — 国内网络请求超时

报错日志

Error: Request timed out after 3000000ms
  "error": {
    "type": "timeout_error",
    "message": "Connection to api.anthropic.com timed out"
  }

或启动后长时间显示 "Connecting..."，最终超时。

根因

Claude Code 默认向 https://api.anthropic.com 发送请求。如果不配置 ANTHROPIC_BASE_URL，Claude Code 会尝试直连 Anthropic 官方 API，而该域名在国内网络环境下不稳定。

即使配置了 ANTHROPIC_BASE_URL 指向 DeepSeek，如果 settings.json 中的配置被更高级别的配置文件覆盖（例如项目级 settings.json 清空了 env 字段），也会回退到默认的 api.anthropic.com。

一览对比表

对比维度	直连 api.anthropic.com	使用 DeepSeek 兼容端点
国内连通性	❌ 经常超时（>30s 无响应）	✅ 稳定（< 2s 响应）
需要代理	是	否
需要 Anthropic 官方 Key	是	否（使用 DeepSeek Key）
模型	Claude Opus/Sonnet/Haiku	DeepSeek V4 Pro/Flash

代码修复

确认 settings.json 的最终合并结果中包含正确的 ANTHROPIC_BASE_URL：

# 用 claude config 查看最终生效的配置
claude config list
# 查找 ANTHROPIC_BASE_URL 相关的输出

如果输出中没有 ANTHROPIC_BASE_URL，手动设置：

claude config set -g env.ANTHROPIC_BASE_URL "https://api.deepseek.com/anthropic"

检查是否有项目级配置覆盖了全局配置：

# 检查三个可能的配置文件
type "$env:USERPROFILE\.claude\settings.json"                      # 全局
type ".\.claude\settings.json"                                     # 项目共享
type ".\.claude\settings.local.json"                               # 项目本地（优先级最高）

如果项目本地 .claude\settings.local.json 中 env 字段为空或缺少 ANTHROPIC_BASE_URL，Claude Code 会使用默认值。确保全局配置中有该字段，且项目级配置没有清空它。

验证

claude -p "say hello"
# 应在 5 秒内返回正常回复

九、速查卡

9.1 文件路径汇总

文件	绝对路径	用途
全局配置	`C:\Users\<用户名>\.claude\settings.json`	个人全局设置，所有项目生效
全局记忆	`C:\Users\<用户名>\.claude\CLAUDE.md`	全局个人规则
项目配置（共享）	`<项目>\.claude\settings.json`	团队共享，提交到 Git
项目配置（本地）	`<项目>\.claude\settings.local.json`	个人项目偏好，不提交
项目记忆（共享）	`<项目>\CLAUDE.md`	项目上下文，提交到 Git
项目记忆（个人）	`<项目>\.claude\CLAUDE.md`	个人开发记忆，不提交
自定义命令	`<项目>\.claude\commands\`	项目级自定义斜杠命令
MCP 服务器配置	`C:\Users\<用户名>\.claude.json`	MCP 服务器定义 + onboarding 标记
企业策略	`C:\Program Files\ClaudeCode\managed-settings.json`	IT 管理员下发的强制策略

9.2 关键配置字段速查

字段	类型	示例值	说明
`env.ANTHROPIC_BASE_URL`	string	`https://api.deepseek.com/anthropic`	API 端点地址
`env.ANTHROPIC_AUTH_TOKEN`	string	`sk-你的Key`	API 认证令牌
`env.ANTHROPIC_MODEL`	string	`deepseek-v4-pro`	默认模型
`model`	string	`deepseek-v4-pro`	当前使用的模型
`permissions.allow`	string[]	`["Bash(git:*)", "Read"]`	自动允许的工具
`permissions.deny`	string[]	`["Bash(rm:*)"]`	禁止使用的工具
`permissionMode`	string	`"acceptEdits"`	权限模式
`env.API_TIMEOUT_MS`	string	`"3000000"`	API 超时时间（毫秒）
`env.CLAUDE_CODE_EFFORT_LEVEL`	string	`"max"`	推理努力程度

9.3 初始化流水线速记

claude --version          → 确认安装
claude doctor             → 健康检查（会话内用 /doctor）
claude                    → 启动交互会话
/init                     → 生成 CLAUDE.md
/memory                   → 编辑记忆文件
/config                   → 打开设置面板
/model                    → 确认模型
/status                   → 验证配置

9.4 常见报错 → 解决方案

报错特征	根因	解决
`401 "invalid x-api-key"`	API Key 错误	检查 `ANTHROPIC_AUTH_TOKEN` 值 → Debug #3
`403 "insufficient balance"`	余额不足	充值 ≥ ¥1.00 → Debug #3
`Request timed out`	直连 Anthropic 超时	配置 `ANTHROPIC_BASE_URL` → Debug #4
`claude doctor` 卡死	v1.0.95 bug	会话内用 `/doctor` → Debug #2
`/init` 未生成文件	权限/锁定/超时	手动创建 CLAUDE.md → Debug #1
`command not found: claude`	npm 全局安装 PATH 未生效	重启终端 / 检查 `npm list -g`
启动弹出浏览器 OAuth 页面	缺少 `hasCompletedOnboarding`	创建 `.claude.json` → 3.1 节
`Auto-update failed`	npm 残留临时目录	清理 `_npx` 缓存后重装 → 8.1 节
`Response exceeded max output tokens`	输出过长	设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS=32000`
`Overloaded 529`	Anthropic 服务端过载	切到 Sonnet / 等待重试 / 检查 status.anthropic.com

新手上路（二）： Claude Code 装完先别用！Windows 初始化 6 步流水线 + 4个高频报错排查

一、这篇教程解决什么问题

二、前置验证

2.1 依赖清单

2.2 逐条验证

三、初始化步骤

3.1 运行 claude doctor — 健康检查

3.2 启动交互会话 + 运行 /init — 项目初始化

3.3 配置 settings.json — 权限与行为控制

3.3.1 settings.json 的三层优先级

3.3.2推荐的最小配置（全局 settings.json）

3.3.3 命令行配置工具

3.5 验证配置 — 确认一切就绪

四、Debug #1 — /init 执行后未生成 CLAUDE.md

报错日志

根因

一览对比表

代码修复

验证

五、Debug #2 — claude doctor 卡住不动（100% CPU）

报错日志

根因

一览对比表

代码修复

验证

六、Debug #3 — 启动后提示 401 / 403 认证失败

报错日志

根因

一览对比表

代码修复

验证

七、Debug #4 — 国内网络请求超时

报错日志

根因

一览对比表

代码修复

验证

九、速查卡

9.1 文件路径汇总

9.2 关键配置字段速查

9.3 初始化流水线速记

9.4 常见报错 → 解决方案

参考文献