主题
05.1 安装与环境配置
从零到 claude doctor 全绿。
读完你能做什么：在你的机器上装好 Claude Code，完成认证，并诊断常见的环境问题。
一、安装
Claude Code 是一个命令行工具。安装方式随平台和分发渠道会有变化，以官方安装指南为准：https://code.claude.com/docs/en/setup。
安装完成后验证：
bash
claude --version # 输出版本号，如 2.1.xxx
claude doctor # 只读诊断：安装健康度、设置文件校验、PATH 问题claude doctor 是你的第一个朋友 —— 它不启动会话，只检查环境。每次遇到"装是装了但不对劲"的情况，先跑它。
1.1 安装特定版本
有时你需要锁定版本（比如团队统一，或规避某个版本的回归）：
bash
claude install stable # 最新稳定版
claude install latest # 最新版（可能含预览特性）
claude install 2.1.118 # 指定版本1.2 更新
bash
claude update如果你打错子命令，它会友好提示：
text
$ claude udpate
Did you mean claude update?二、认证
Claude Code 支持两种计费来源：Claude 订阅（Pro/Max/Team/Enterprise）或 Anthropic Console（按 API 用量计费）。
bash
# 登录（默认走 Claude 订阅）
claude auth login
# 预填邮箱
claude auth login --email you@example.com # 需替换为你的邮箱
# 强制走 SSO（企业单点登录）
claude auth login --sso
# 走 Console（按 API 用量计费，而非订阅）
claude auth login --console查看和退出：
bash
claude auth status # JSON 格式的认证状态
claude auth status --text # 人类可读
claude auth logout2.1 CI / 脚本环境的认证
交互式登录在 CI 里不可行。用长效 token：
bash
# 生成一个长效 OAuth token（需要 Claude 订阅）
claude setup-token它把 token 打印到终端但不保存。你把它注入 CI 的环境变量即可。详见 06.6 Headless 与 CI 集成。
三、第一次启动
bash
cd ~/your-project # 需替换为你的项目路径
claude首次在一个项目里启动时，建议：
text
> /init它会分析你的代码库，生成一份起步的 CLAUDE.md（含构建命令、测试方式、项目约定）。这是让 Claude Code 理解你项目的第一步。
想要更完整的交互式初始化流程：
bash
CLAUDE_CODE_NEW_INIT=1 claude
> /init这个模式会分阶段询问：要不要设置 CLAUDE.md、skills、hooks，然后用子代理探索代码库，最后给你一个可审阅的方案再落盘。
四、配置层级
Claude Code 的配置有多个来源，理解它们的位置很重要（完整优先级见 06.8 Settings 配置全解）：
text
~/.claude/ ← 用户级（你所有项目）
├── settings.json ← 用户设置
├── CLAUDE.md ← 用户级记忆
└── rules/ ← 用户级规则
<你的项目>/
├── CLAUDE.md 或 .claude/CLAUDE.md ← 项目级记忆（提交到 git）
├── CLAUDE.local.md ← 个人项目偏好（加 .gitignore）
└── .claude/
├── settings.json ← 项目设置（提交到 git）
├── settings.local.json ← 个人项目设置（gitignore）
├── rules/ ← 项目规则
├── skills/ ← 项目技能
├── agents/ ← 子代理
└── hooks/ ← 钩子脚本4.1 一份最小的用户级起步配置
~/.claude/settings.json：
json
{
"model": "sonnet",
"fallbackModel": "haiku",
"effortLevel": "medium"
}理由见 01.5 模型选择与用量管理。
五、企业代理与网络
在企业网络后面时，常见的配置：
bash
# 标准 HTTP 代理环境变量
export HTTPS_PROXY=http://proxy.company.com:8080 # 需替换为你的代理
export HTTP_PROXY=http://proxy.company.com:8080如果你的组织使用 Amazon Bedrock / Google Cloud / Microsoft Foundry 等平台承载模型，认证方式不同，需要相应的向导：
text
> /setup-bedrock # 需 CLAUDE_CODE_USE_BEDROCK=1
> /setup-vertex # 需 CLAUDE_CODE_USE_VERTEX=1具体配置以官方文档为准，且通常由你的平台管理员统一下发。
六、IDE 集成
Claude Code 可以连接到 IDE（VS Code、JetBrains 等）：
bash
claude --ide # 启动时自动连接（当只有一个可用 IDE 时）会话中管理：
text
> /ide如果你的终端需要特殊的键位配置（如 VS Code 集成终端的 Shift+Enter）：
text
> /terminal-setup七、常见安装/环境问题
| 症状 | 诊断 | 修复 |
|---|---|---|
command not found: claude | PATH 没配好 | claude doctor 会报告 PATH 问题；重装或修 PATH |
| 版本很旧 | 没更新 | claude update |
| 登录后仍提示未认证 | token 问题 | claude auth status 查看；重新 claude auth login |
| 设置不生效 | 设置文件有语法错误 | claude doctor 会报告 settings 校验错误 |
| 有多个 claude 安装冲突 | 重复安装 | claude doctor 会检测重复/残留安装 |
| MCP server 连不上 | 认证/网络 | /mcp 查看状态；claude mcp login <name> |
| 配置被神秘覆盖 | 多层设置冲突 | 见 06.8 的优先级 |
7.1 排查配置问题的核武器：安全模式
当你怀疑某个自定义配置（hook、skill、plugin、CLAUDE.md）搞坏了环境：
bash
claude --safe-mode它会禁用所有自定义（CLAUDE.md、skills、plugins、hooks、MCP、自定义命令和代理等），只保留认证、模型、内置工具和权限。如果安全模式下问题消失，说明是某个自定义项导致的，逐个排查即可。
比 --safe-mode 更极端的是 --bare（还会跳过自动发现，启动最快），适合脚本：
bash
claude --bare -p "简单任务"八、验收清单
装好后逐项确认：
text
□ claude --version 输出正常版本号
□ claude doctor 无红色错误
□ claude auth status 显示已登录
□ 在一个真实项目里能启动 claude 并对话
□ /init 生成了 CLAUDE.md
□ ~/.claude/settings.json 存在且是合法 JSON
□ 能成功让它读取一个文件（验证文件工具可用）
□ 能成功让它跑一个命令（验证 Bash 工具可用）全部通过后，进入 05.2 第一次会话完整走查。