🟠 Claude Code 安装与使用完整指南

Claude Code 是 Anthropic 官方的 Agent 编码工具：它读你的代码库、改文件、跑命令、用 Git，把 AI Agent 真正嵌进开发流程。跟一年前相比最大的变化是——它不再只是一个 CLI：同一个引擎现在跑在终端、桌面 App、浏览器/手机、以及 VS Code 与 JetBrains 插件里，四个面共用同一份 CLAUDE.md、settings 和 MCP 配置。本指南按 2026 年 9 月的官方文档重写，覆盖安装、登录、模型选择、核心用法、Sub-agents、MCP、Skills/Plugins/Hooks 与实战工作流。

一、先选形态：四个面怎么挑

装之前先搞清你要哪一个。四个面背后是同一个 Claude Code 引擎，配置互通，随时可以把一个会话接力到另一个面上。

💡 推荐组合：桌面 App + CLI。桌面看 diff、排多会话、挂定时任务；CLI 做脚本化和 CI。两边共享同一份项目配置，/desktop 可把当前终端会话搬到桌面继续。

二、安装：三平台 + 五种方式

2.1 系统要求（官方口径）

2.2 原生安装器（官方推荐，自动更新）

# 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

装到 ~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin）。如果 claude 找不到，把目录加进 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

想装固定通道或固定版本，安装器直接收参数：

# 稳定通道（约落后一周，跳过有重大回归的版本）
curl -fsSL https://claude.ai/install.sh | bash -s stable

# 指定版本号
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.236

⚠️ Windows 原生模式建议再装 Git for Windows：有它 Claude Code 用 Git Bash 跑 Bash 工具，没有则退回 PowerShell 工具。要沙箱执行能力就走 WSL 2。

2.3 Homebrew / WinGet（不自动更新）

# macOS —— 两个 cask 对应两条通道
brew install --cask claude-code           # stable 通道
brew install --cask claude-code@latest    # latest 通道
# 升级
brew upgrade claude-code

# Windows
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode

2.4 Linux 包管理器（apt / dnf / apk，官方签名源）

# Debian / Ubuntu
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

# Fedora / RHEL
sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

加源前先核对签名指纹：31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE。

2.5 npm（需 Node 22+）

npm install -g @anthropic-ai/claude-code
# 升级用 @latest，别用 npm update -g
npm install -g @anthropic-ai/claude-code@latest

npm 包装的是同一个原生二进制（通过平台可选依赖拉取），运行时并不跑 Node。不要用 sudo npm install -g。

2.6 桌面 App / 网页 / IDE

• 桌面 App：claude.ai 下载 macOS（Intel + Apple Silicon 通用包）或 Windows（x64 / ARM64）安装包；Ubuntu / Debian 走 apt（beta）。装完登录 → 点顶部 Code 标签即可，内置 Claude Code，不需要另装 Node 或 CLI。
• 网页：打开 claude.ai/code，零本地配置；手机用 Claude iOS / Android App。
• VS Code / Cursor：扩展面板（Cmd/Ctrl+Shift+X）搜 "Claude Code" 装上，再用命令面板 → Open in New Tab。
• JetBrains：插件市场装 Claude Code 插件并重启 IDE，插件依赖本机 CLI，需单独装。

2.7 验证安装

claude --version
# → 2.1.269 (Claude Code)

claude doctor
# 只读体检：安装健康度、settings 校验错误、上次自动更新结果与修复建议

2.8 更新与发布通道

# 立刻更新（不等后台检查）
claude update

原生安装默认后台自动更新；Homebrew / WinGet / apt / dnf / apk 默认要手动升。通道和版本下限写在 settings.json 里：

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.200"
}

要彻底关掉自动更新：settings.json 的 env 里设 "DISABLE_AUTOUPDATER": "1"（只停后台检查，claude update 仍可用；连手动也要禁则用 DISABLE_UPDATES）。

三、登录认证与套餐

3.1 订阅账号（最常用）

claude                 # 首次运行自动拉浏览器登录
# 或显式登录 / 查状态 / 退出
claude auth login
claude auth status     # 以 JSON 输出当前认证状态
claude auth logout

Claude Code 需要 Pro / Max / Team / Enterprise 订阅，或 Anthropic Console（API）账号。claude.ai 免费版点 Code 会提示升级。

3.2 API Key（Console / CI）

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude    # 检测到环境变量时只问一次是否用这个 key，不再开浏览器

# CI / 脚本：生成长期 OAuth token
claude setup-token

3.3 企业三方通道

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# Google Cloud（Agent Platform / Vertex）
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=my-project
gcloud auth application-default login

除 Bedrock 与 Google Cloud 外，现在还支持 Microsoft Foundry 与 Anthropic 自营的 Claude Platform on AWS。注意三方通道的模型别名解析不一样（见下一节）。

3.4 套餐与价格（官方 claude.com/pricing）

走 API（Console）按量计费的话，当前一手费率（每百万 token，输入 / 输出）：Opus 5 $5 / $25 · Sonnet 5 $2 / $10 · Haiku 4.5 $1 / $5 · Fable 5.1 $10 / $50。

四、模型与上下文（这一节最容易过期，优先看）

4.1 /model 别名表

三方通道上 opus / sonnet 解析到的具体版本不同：Bedrock 与 Google Cloud 的 sonnet 还是 Sonnet 4.5，Microsoft Foundry 更旧。对版本敏感就别用别名，直接写全名（如 claude --model claude-sonnet-5）。

4.2 各账号默认模型

4.3 1M 上下文与自动压缩

Opus 5、Sonnet 5、Fable 5 / 5.1 原生就是 1M 上下文，Sonnet 5 在 Anthropic API 上默认开启、不需要 [1m] 后缀。会话在填满之前会自动压缩（这些模型默认在约 967K token 处触发），也可以手动 /compact。真要关掉 1M：环境变量 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。

Pro 账号用 Opus 的 1M 上下文需要额外用量额度；Max / Team / Enterprise 的 Opus 1M 已包含。

4.4 两个省钱/提速开关

• effort（思考深度）：claude --effort high，或会话内调。low 给简单任务和子 agent，xhigh 给硬核编码与长链路 agent 任务——花的 token 差几倍，质量差别也在这里。
• /fast（快速模式）：在 Opus 5 / 4.8 上用同一个模型更快地出字（不是降级到小模型），代价是用量消耗更高。赶时间时开，常态别开。

💡 成本纪律：日常编码挂 sonnet，遇到"想不清楚"的活再 /model opus；headless 批处理加 --max-budget-usd 5.00 给自己上硬闸。

五、核心用法

5.1 交互模式与 Slash 命令

cd ~/projects/my-app
claude

# 直接带任务启动
claude "帮我重构 src/auth/，把 bcrypt 换成 argon2"

会话里输入 / 触发命令。下面是常用的一批（都在当前 2.1.x 里实测存在）：

5.2 权限模式：按 Shift+Tab 循环

5.3 Headless 模式（管道 / 批处理 / CI）

# 单次任务
claude -p "解释这个 Python 脚本做什么" < script.py

# 管道进来
tail -200 app.log | claude -p "有异常就告诉我"

# 结构化输出
claude -p "总结 README 的 3 个要点" --output-format json
claude -p "提取依赖清单" --json-schema '{"type":"object","properties":{"deps":{"type":"array","items":{"type":"string"}}}}'

# 给自己上闸：限轮数、限花钱、限工具
claude -p "检查这次 commit 的代码规范" \
  --allowedTools "Bash(git diff*)" "Read" \
  --max-turns 3 --max-budget-usd 2.00

5.4 续接会话与跨端接力

claude --continue            # 或 -c，接当前目录最近一次会话
claude --resume "auth-重构"   # 或 -r，按 ID / 名字选历史会话
claude -n "支付重构"          # 给会话起个名字，方便以后 -r

claude --cloud "修登录 bug"   # 丢到云端跑，手机上能继续看
claude --teleport            # 把云端/网页会话拉回本地终端
claude --rc                  # Remote Control：手机或其他设备接管本地会话

5.5 后台并行会话

claude --bg "排查这个偶发失败的测试"   # 后台起一个 agent，立刻返回
claude agents                        # 总览面板：看所有并行后台会话
claude attach 7c5dcf5d               # 把某个后台会话接到当前终端
claude logs 7c5dcf5d                 # 看它最近的输出
claude stop 7c5dcf5d                 # 停掉
claude respawn 7c5dcf5d              # 带着原对话重启

六、Sub-agents：多 Agent 协作

把代码审查、写测试、生成文档拆给不同 agent 并行跑，每个有自己独立的上下文，不会互相污染主会话。

6.1 定义 Sub-agent

# 项目根目录 .claude/agents/reviewer.md
---
name: code-reviewer
description: 严格的代码审查专家
tools: Read, Grep, Bash(git diff*)
---

你是一个严谨的代码审查者。检查：
1. 命名规范
2. 错误处理
3. 边界条件
4. 性能隐患
输出结构化 markdown 报告。

6.2 派发

# 会话里直接说
> 用 code-reviewer 审查 src/api/ 下的所有改动
> 派 3 个 agent：一个写测试、一个生成文档、一个做性能分析

# 命令行临时定义（不落盘）
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

# 给所有 sub-agent 追加统一约束
claude -p --append-subagent-system-prompt "每条结论都要带文件路径" "审一遍改动"

七、MCP 集成：接外部工具

MCP（Model Context Protocol）是 Anthropic 推的开放协议，让 Claude Code 调用任何 MCP 兼容服务——GitHub、Notion、Asana、Sentry、Postgres、Playwright、Figma，或你自己写的。

7.1 添加服务器（注意语法已变）

# 远程 HTTP 服务（现在最常见的形态）
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 远程 SSE
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 本地 stdio：环境变量用 --env，命令前必须有 --
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# 直接喂 JSON
claude mcp add-json local-weather \
  '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"]}'

7.2 管理与认证

claude mcp list              # 列出已配置
claude mcp get github        # 看单个详情
claude mcp remove github     # 删掉
claude mcp login sentry      # 走 OAuth 授权（SSH 下加 --no-browser）
claude mcp logout sentry

MCP_TIMEOUT=10000 claude     # 启动超时调长（毫秒）

7.3 三种作用域

团队统一配置就写 .mcp.json 提交进仓库，支持 ${API_KEY} 这类环境变量展开，密钥不用进版本库：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

八、Skills / Plugins / Hooks：三种扩展方式

8.1 Skills —— 把团队 SOP 变成 AI 习惯

Skills 是可复用的指令包，放成 Markdown，相关场景自动加载，也可以 /技能名 显式调用。

# 项目级：.claude/skills/<名字>/SKILL.md
# 个人级：~/.claude/skills/<名字>/SKILL.md
mkdir -p .claude/skills/code-style

# .claude/skills/code-style/SKILL.md
---
name: code-style
description: 强制 TypeScript strict 模式 + ESLint airbnb-base
---

所有 TypeScript 代码必须：
- tsconfig.json 开启 strict: true
- 使用 ESLint airbnb-base 配置
- 函数参数显式标注类型
- 不允许使用 any

会话里 /skills 列出全部可用技能（含内置技能和插件带来的技能）。

8.2 Plugins —— 打包分发给整个团队

claude plugin install code-review@claude-plugins-official
claude --plugin-dir ./my-plugin     # 本地开发时临时加载
# 会话里 /plugin 浏览安装，/reload-plugins 热重载

一个插件可以同时带 skills、sub-agents、MCP 服务器和 hooks，是把一整套工作流分发出去最省事的形态。

8.3 Hooks —— 确定性地自动执行

Hooks 是你写的 shell 命令，Claude Code 在生命周期特定时刻一定会跑——不依赖模型"想起来要跑"。配在 settings.json 的 hooks 字段：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ]
  }
}

常用事件：SessionStart / SessionEnd · UserPromptSubmit · PreToolUse（可拦住工具调用）/ PostToolUse / PostToolUseFailure · Notification · SubagentStop · PreCompact · Setup。/hooks 可以查已注册的钩子（只读，改要直接编辑 settings）。

九、装完必做的 5 件事

十、常见工作流实战

10.1 从零搭项目

mkdir my-saas && cd my-saas
claude
> 用 Next.js + Tailwind + Prisma + PostgreSQL 搭一个 SaaS 模板
> 用 postgres MCP 设计 user/subscription/invoice 三张表
> 写完整的 README.md 和 docker-compose.yml

10.2 Code Review

git checkout -b feature/auth
git add .
# 会话里直接
> /code-review

# 或 headless 拿结构化结果
claude -p "用 code-reviewer sub-agent 审查 staged 改动" --output-format json

10.3 批量迁移 + 自动验证

claude
> 把 src/ 下所有 React class 组件改成 hooks 函数组件
> 用 playwright MCP 验证每个改完的页面没破
> /verify

10.4 定时跑起来（不用守着）

# 会话里建云端 Routine：电脑关机也照跑，还能由 API/GitHub 事件触发
> /schedule 每天早 9 点审一遍昨天合进 main 的 PR，有问题发我

# CI 里自动审 PR / 分流 Issue：GitHub Actions 或 GitLab CI 都有官方集成
claude -p "review these changed files for security issues"

十一、桌面 App 的三个标签：Chat / Cowork / Code

2026 年桌面 App 已经不是"Claude 网页版的壳"。装好后顶部是三个标签，定位完全不同：

⚠️ 澄清一下：Cowork 不是"Notion + Asana 式的团队协作云空间"，也没有独立的定价套餐或独立域名——它是桌面 App 里的一个标签，跟着 Claude 订阅走。网上关于 Cowork 定价表、独立官网的说法基本都是误传。

11.1 Code 标签能选四种运行环境

11.2 桌面端独有的那几样

• 可视化 diff + 行内评论：改完出现 +12 -1，点开逐文件看，可以就某一行留言让 Claude 改
• 多会话并排：侧栏开多个会话，每个可以挂在自己的 git worktree 上
• 自由拖拽面板：聊天 / diff / 终端（Ctrl+`）/ 文件 / 浏览器随意排布
• 应用预览：起了 dev server 就在 Browser 面板里渲染，Claude 能看着运行中的页面、测接口、读日志自己迭代
• PR 看板：开完 PR 后监控 CI，失败自动修，全绿可自动合
• 本机定时任务：每天早上的代码审查、每周依赖审计，直接用本地文件和工具跑（区别于云端 Routines）

11.3 配置一份，五个面通用

11.4 桌面界面示意

11.5 视频：Claude Cowork 实战

十二、常见问题 FAQ

本文由 AI Know 按 2026 年 9 月 12 日的 Anthropic 官方文档（code.claude.com/docs）与 claude.com/pricing 重新核对整理，版本信息取自 npm registry 当日 dist-tags。Claude Code 迭代很快，命令与价格如有变动请以 官方文档 为准。

← 返回专题列表