Claude Code终端使用指南（一）—安装、认证与首次会话

Claude Code 是 Anthropic 提供的智能编程代理。它可以在终端中读取项目文件、搜索代码、编辑文件、运行命令，并围绕测试或构建结果继续迭代。它与 claude.ai 的普通聊天界面、Claude Desktop 以及 IDE 插件并不是同一个使用入口。本系列只讨论在本地终端中通过 claude 命令启动的 Claude Code CLI。

本文是系列的第一篇，介绍系统要求、安装方式、认证、版本更新、首次启动和基础交互。后续文章依次讨论：

核心工作流与提示策略；
项目记忆、配置、权限与沙箱；
会话、上下文、Git 与并行开发；
Skills、子代理、Hooks、MCP 与插件；
非交互自动化、成本控制与故障排查。

系列以“能够独立、可靠地在终端中使用 Claude Code 完成真实项目工作”为范围，覆盖安装认证、交互工作流、项目配置、安全边界、状态管理、并行开发、扩展机制、脚本化和排障。Claude Desktop、IDE 插件和 Claude Code on the web 只在解释边界或协作关系时提及，不作为操作对象；云厂商账户治理、企业网关部署等组织级管理工作也应另行查阅对应的官方管理文档。

本文依据 2026 年 7 月 25 日可访问的 Claude Code 官方文档编写，并使用 Claude Code 2.1.218 的 claude --help 复核命令行参数。Claude Code 更新频繁，涉及版本、模型和套餐可用性的内容，应以文末官方链接和本机 /help、claude --help 的实时输出为准。

0. 安装与首次使用速查

0.1 推荐安装方式

macOS、Linux 或 WSL：

1	curl -fsSL https://claude.ai/install.sh \| bash

Windows PowerShell：

1	irm https://claude.ai/install.ps1 \| iex

Windows CMD：

1	curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

验证安装：

1 2	claude --version claude doctor

0.2 登录并进入项目

1 2	cd /path/to/task-board claude

首次运行会启动浏览器登录流程。进入会话后可检查状态：

/status

重新登录或退出当前账号：

1 2	/login /logout

0.3 最常用的启动命令

# 启动交互会话
claude

# 带着第一条任务启动交互会话
claude "解释这个项目的目录结构"

# 执行一次非交互查询，输出后退出
claude -p "概括这个项目的用途"

# 继续当前目录最近一次会话
claude --continue

# 打开历史会话选择器
claude --resume

# 以只读规划模式开始
claude --permission-mode plan

0.4 会话内的基础命令

/help          查看当前版本可用的命令
/status        查看账号、模型、设置来源和会话状态
/context       查看上下文窗口由哪些内容占用
/permissions   查看和调整权限规则
/model         查看或切换模型
/clear         清空当前上下文，原会话仍保存在历史记录中
/exit          退出 Claude Code

1. Claude Code CLI 的工作边界

为了避免把不同产品形态混为一谈，先明确本文所说的 Claude Code：

开发者
  │
  │ 在项目目录执行 claude
  ▼
Claude Code CLI
  ├── 读取、搜索和编辑本地文件
  ├── 调用 Bash 或 PowerShell 等终端工具
  ├── 运行构建、测试、Git 和其他 CLI
  ├── 连接经过配置的 MCP 服务
  └── 在权限与沙箱边界内循环执行任务

它不是一个只生成代码片段的问答机器人。一次典型任务包含以下循环：

Claude 分析目标；
选择读取文件、搜索代码或运行命令等工具；
Claude Code 检查权限；
工具在本机执行并返回结果；
Claude 根据结果决定继续修改、验证或结束。

因此，启动目录、项目内的指令文件、可用 CLI、权限规则以及可执行的验证命令都会直接影响结果。正确的使用方式不是把全部代码复制到聊天框，而是在正确的项目目录启动 Claude，让它按需读取文件，并给它清晰的目标与验收条件。

2. 系统要求与账号准备

根据官方高级安装文档，当前基础要求包括：

macOS 13.0 或更高版本；
Windows 10 1809、Windows Server 2019 或更高版本；
Ubuntu 20.04、Debian 10、Alpine Linux 3.19 或更高版本；
x64 或 ARM64 处理器；
至少 4 GB 内存；
可访问 Anthropic 所需服务的网络；
Bash、Zsh、PowerShell 或 CMD；
位于 Anthropic 支持的国家或地区。

Claude Code 不包含在免费 Claude.ai 套餐中。个人用户通常使用 Pro 或 Max 订阅登录；组织可使用 Team、Enterprise、Claude Console、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自建 Claude apps gateway。不同入口的计费、模型可用性和管理员策略并不完全相同。

在安装前应先确认两件事：

计划使用哪一种账号或云提供商；
当前网络是否允许访问认证和模型服务。

企业环境中不要自行把个人 API Key 写进仓库。认证方式、代理、证书、可用模型和组织策略应由管理员统一提供。

3. 安装 Claude Code

3.1 原生安装是官方推荐方式

原生安装会安装 Claude Code 的本机可执行程序。macOS、Linux 和 WSL 使用：

1	curl -fsSL https://claude.ai/install.sh \| bash

Windows PowerShell 使用：

1	irm https://claude.ai/install.ps1 \| iex

Windows CMD 使用：

1	curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

注意 PowerShell 与 CMD 的语法不同：

提示符以 PS C:\...> 开头时使用 PowerShell 命令；
CMD 通常显示为 C:\...>；
PowerShell 5 中不能把 CMD 示例里的 && 当作通用命令分隔符；
CMD 不认识 PowerShell 的 irm 别名。

从网络下载脚本并直接执行具有供应链风险。上面的地址来自 Anthropic 官方文档；在受管控的企业环境中，应按组织的软件分发和脚本审计要求安装，而不是绕过管理员策略。

3.2 Homebrew 与 WinGet

macOS 可使用 Homebrew：

# 稳定通道
brew install --cask claude-code

# 最新通道
brew install --cask claude-code@latest

官方文档说明，claude-code cask 跟随稳定通道，通常比最新发布晚约一周，并跳过存在重大回归的版本；claude-code@latest 会更快获得新版本。

Windows 可使用 WinGet：

1	winget install Anthropic.ClaudeCode

Homebrew 和 WinGet 默认不使用 Claude Code 原生安装器的后台自动更新机制，需要通过包管理器升级：

1	brew upgrade claude-code

1	winget upgrade Anthropic.ClaudeCode

3.3 Linux 包管理器与 npm

官方高级安装页还提供 apt、dnf 和 apk 安装方式。它们适合由系统包管理器统一维护的环境。npm 全局包仍受支持，但已不是首选安装路径。新安装通常应优先选择原生安装或操作系统包管理器。

如果机器上曾通过多种方式安装 Claude Code，可能出现旧二进制抢占 PATH 的问题。安装后应使用：

1 2	claude --version claude doctor

确认实际运行的版本和安装健康状态。Windows PowerShell 还可以检查命令解析结果：

1	Get-Command claude -All

macOS、Linux 或 WSL 可使用：

1	which -a claude

4. Windows 原生环境与 WSL 的选择

Claude Code 可以在 Windows 原生终端或 WSL 中运行，选择取决于项目实际位于哪里以及是否需要沙箱。

方案	适用场景	命令工具	Claude Code 沙箱
Windows 原生	Windows 工具链、项目位于 NTFS	PowerShell；安装 Git for Windows 后也可使用 Bash	不支持
WSL 2	Linux 工具链、容器、需要 OS 级沙箱	Bash	支持
WSL 1	只能使用旧版 WSL 的环境	Bash	不支持

Windows 原生环境不要求管理员权限。安装 Git for Windows 后，Claude Code 可以使用 Git Bash 提供的 Bash 工具。如果未安装 Git for Windows，则使用 PowerShell 工具。

Claude Code 未自动找到 Git Bash 时，可在设置文件中指定路径：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

项目应尽量放在运行环境的本地文件系统中。若在 WSL 中工作，把大型仓库放在 /home/... 通常比放在 /mnt/c/... 有更稳定的文件搜索性能。

5. 验证安装与更新

5.1 基础检查

1	claude --version

成功时会输出版本号和 (Claude Code)。进一步执行：

1	claude doctor

该命令不启动交互会话，会以只读方式检查安装状态、设置文件和更新问题。进入会话以后还可以运行：

/doctor

会话内的 /doctor 检查范围更广，并可在用户确认后提出修复操作。它与 shell 中只读的 claude doctor 不应混淆。

5.2 原生安装的更新通道

原生安装会在启动时及运行期间检查更新，后台下载的新版本在下一次启动时生效。手动检查并更新：

1	claude update

原生安装默认使用 latest 通道。希望降低回归风险时，可在 ~/.claude/settings.json 中选择 stable：

1
2
3

{
  "autoUpdatesChannel": "stable"
}

也可以在 /config 中修改 Auto-update channel。

组织希望设定最低版本时，可以设置：

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

这里的版本号只是配置格式示例，不是长期推荐值。实际最低版本应由团队根据已验证版本确定。minimumVersion 约束更新行为，不等同于组织级的强制启动版本区间。

若必须由企业软件分发系统统一更新，可禁用后台更新检查：

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

禁用自动更新意味着团队需要建立明确的安全更新流程，不能把“固定版本”理解为“永远不更新”。

6. 登录与认证

6.1 交互登录

在任意终端运行：

claude

首次启动时，Claude Code 会打开浏览器完成登录。如果浏览器未自动打开，可按界面提示复制登录 URL。WSL、SSH 和容器环境中，浏览器有时无法回调本地终端，此时网页会显示一次性代码，将它粘贴回终端即可。

登录成功后，在会话内检查：

/status

切换账号或刷新登录：

/login

退出当前账号：

/logout

/logout 还会重置首次启动状态，下一次运行会重新进入登录和初始化流程。

6.2 凭据存储

官方文档给出的默认存储方式是：

macOS：加密的 macOS Keychain；
Linux：~/.claude/.credentials.json，文件模式为 0600；
Windows：%USERPROFILE%\.claude\.credentials.json，继承用户配置目录的访问控制；
设置 CLAUDE_CONFIG_DIR 后，Linux 和 Windows 的凭据文件会随配置目录移动。

这些文件由 /login 和 /logout 管理。不要将凭据文件加入版本控制，不要在日志、截图或博客示例中暴露其中内容。

6.3 多种凭据同时存在时的优先级

Claude Code 可能同时看到订阅登录、API Key、Bearer Token 或云提供商凭据。当前官方认证文档给出的主要优先顺序是：

已启用的 Bedrock、Agent Platform 或 Foundry 云提供商凭据；
ANTHROPIC_AUTH_TOKEN；
ANTHROPIC_API_KEY；
apiKeyHelper 返回的动态凭据；
CLAUDE_CODE_OAUTH_TOKEN；
/login 保存的订阅 OAuth 凭据。

已登录的 Claude apps gateway 会作为独立的提供商选择，优先于上述普通凭据。

这解释了一个常见现象：用户已经登录 Pro 或 Max，但 shell 中残留的 ANTHROPIC_API_KEY 会优先被使用，账单和权限也随 API Key 所属组织变化。遇到认证来源不符合预期时：

1 2	# macOS、Linux、WSL unset ANTHROPIC_API_KEY

1 2	# Windows PowerShell，仅移除当前进程中的变量 Remove-Item Env:ANTHROPIC_API_KEY

然后重新启动 Claude Code，并通过 /status 确认 Login method。

6.4 无浏览器环境的长期令牌

CI 或远程环境无法交互登录时，订阅用户可生成长期 OAuth Token：

1	claude setup-token

该命令通过浏览器授权后把令牌打印到终端，但不会替用户保存。应将它存入 CI 的加密 Secret，并作为 CLAUDE_CODE_OAUTH_TOKEN 注入：

1	export CLAUDE_CODE_OAUTH_TOKEN="..."

该令牌有效期和能力受官方当前策略约束。它是敏感凭据，不得写入：

CLAUDE.md；
.claude/settings.json；
.mcp.json；
shell 脚本或仓库中的 .env；
构建日志。

后续自动化篇还会说明：--bare 模式不会读取 CLAUDE_CODE_OAUTH_TOKEN，需要改用 ANTHROPIC_API_KEY 或通过 --settings 提供 apiKeyHelper。

7. 在正确的项目目录启动

本系列使用一个虚构的 TypeScript 任务管理项目作为贯穿示例：

task-board/
├── package.json
├── src/
├── tests/
└── README.md

示例项目并不对应可下载的真实仓库，只用于保持文章中的文件、命令和目标一致。

进入项目根目录后启动：

1 2	cd /path/to/task-board claude

启动目录决定了默认工作目录、项目设置、项目记忆和会话归属。不要为了方便在用户主目录或包含大量无关仓库的上级目录启动，否则会扩大可读取范围、增加搜索噪声，也可能把权限审批保存到错误的项目作用域。

首次进入一个仓库时，Claude Code 会要求确认是否信任该工作区。信任意味着项目中的 CLAUDE.md、.claude/settings.json、Hooks、Skills、插件配置和 .mcp.json 可能影响 Claude Code 的行为。对于刚克隆的陌生仓库，应先人工审查这些文件，再接受信任。

可先在普通终端中检查：

1 2	git status --short git ls-files CLAUDE.md .claude .mcp.json

如果仓库来自不可信来源，不要通过非交互模式绕过信任检查后直接授予写入、网络或命令执行权限。

8. 第一次交互会话

8.1 先理解项目

进入会话后，不要立即要求“大改整个项目”。先让 Claude 建立项目模型：

请只读分析这个项目：
1. 概括它解决的问题；
2. 找到应用入口；
3. 说明 src 与 tests 的主要结构；
4. 列出 package.json 中的构建、测试和检查命令；
5. 暂时不要修改文件。

这类提示明确了目标、输出结构和“暂不修改”的边界。Claude 会按需读取文件，而不是要求用户把全部源码粘贴到终端。

查看详细工具调用和结果：

Ctrl+O

如果 Claude 的探索范围不正确，可按 Esc 中断当前动作并立即补充约束。

8.2 完成一个可验证的小改动

假设项目缺少健康检查接口，可以继续输入：

在现有路由风格下增加 GET /health。
返回 HTTP 200 和 JSON {"status":"ok"}。
先定位同类路由和测试模式，再实现接口与测试。
完成后运行最小相关测试和 npm run build。
不要修改依赖和锁文件。
最后列出修改文件、执行的命令和验证结果。

一个完整任务应包含：

要实现的结果；
需要遵循的现有模式；
明确的范围；
不允许修改的内容；
可执行的验证命令；
最终需要提供的证据。

当 Claude Code 请求权限时，应阅读工具名、命令和影响范围。对于不熟悉的 Bash 或 PowerShell 命令，可在权限对话框中使用当前版本提供的命令解释功能，再决定是否允许。

8.3 审查结果

Claude 声称“已完成”不等于可以直接提交。至少检查：

git status --short
git diff
npm test
npm run build

如果项目实际定义了其他验证命令，应以 package.json、README.md、CONTRIBUTING.md 或项目指令为准。不要机械执行文章中的示例命令。

9. 交互控制与输入技巧

9.1 常用快捷键

快捷键	作用
`Esc`	中断当前响应或工具调用，保留已完成的工作
`Ctrl+C`	中断运行；空闲时第一次清空输入，第二次退出
`Ctrl+D` 两次	退出会话
`Ctrl+O`	打开或关闭详细转录视图
`Ctrl+R`	反向搜索输入历史
`Ctrl+G` 或 `Ctrl+X Ctrl+E`	使用默认编辑器编辑长提示
`Ctrl+L`	重绘终端，不清除会话
`Ctrl+B`	将可后台运行的 Bash 命令或代理转入后台
`Shift+Tab`	在当前可用的权限模式之间切换
`↑`、`↓`	浏览历史输入或在多行输入中移动

不同终端可能拦截部分按键，实际可用快捷键应以官方 Interactive mode 页面和当前终端设置为准。

9.2 多行提示

较长任务可通过以下方式输入：

输入 \ 后按 Enter；
macOS 默认使用 Option+Enter；
在支持的终端中使用 Shift+Enter；
按 Ctrl+G 在外部编辑器中编写；
直接粘贴多行文本。

终端不正确处理 Shift+Enter 时，可运行：

1	/terminal-setup

该命令会针对支持的终端配置多行输入绑定。

9.3 引用文件

在提示中输入 @ 可搜索并引用项目文件。例如：

1 2	比较 @src/routes/tasks.ts 与 @tests/tasks.test.ts，说明当前测试覆盖了哪些输入校验分支。

文件引用比“那个路由文件”更精确。引用不应替代任务边界：仍需说明希望 Claude 分析、修改还是只做审查。

9.4 Shell 模式

在交互会话中，以 ! 开头可以直接运行 shell 命令：

1 2	!git status --short !npm test

这适合人工主动检查状态。命令仍在当前本机环境中执行，不应粘贴来源不明的命令，也不要把终端模式当作权限系统的替代品。

10. 权限模式的最小认识

权限与安全会在本系列第三篇详细介绍。第一次使用时至少要区分：

模式	默认可执行范围	适用场景
`default` / Manual	只读操作，其他操作按规则询问	初次使用、敏感仓库
`acceptEdits`	读取、文件编辑和部分常见文件操作	持续审查差异的日常开发
`plan`	只读分析与规划，不编辑源文件	复杂任务开始前
`auto`	由独立分类器在后台检查操作	账号和模型支持时的长任务
`dontAsk`	只执行预先允许的工具，不能询问的操作直接拒绝	CI 和受限脚本
`bypassPermissions`	跳过绝大多数权限检查	仅限已隔离且无敏感凭据的容器或虚拟机

会话中按 Shift+Tab 可在默认循环中的模式间切换。也可以启动时指定：

1	claude --permission-mode plan

不要把 --dangerously-skip-permissions 当作减少点击次数的日常选项。官方明确建议只在没有敏感数据、没有外网泄露路径并具有额外隔离的环境中使用。

11. CLI 启动方式

11.1 交互会话

claude

附带首条提示：

1	claude "先只读分析认证模块，暂时不要修改文件"

这种写法仍会进入交互会话，而不是执行后退出。

11.2 非交互输出

1	claude -p "解释 src/auth/session.ts 的职责"

-p 或 --print 会在任务结束后把结果写到标准输出并退出，适合管道和脚本。非交互模式会跳过工作区信任对话，因此只能在已经信任的目录中使用。

11.3 继续或恢复会话

# 继续当前目录最近一次会话
claude --continue

# 打开历史会话选择器
claude --resume

# 恢复一个已命名会话
claude --resume health-endpoint

命名当前会话：

1	/rename health-endpoint

或启动时命名：

1	claude --name health-endpoint

11.4 添加额外目录

1	claude --add-dir ../shared-types

--add-dir 会扩大文件访问范围，但默认不会把额外目录的所有项目配置都加载进来。授予额外目录前，应确认它确实属于本次任务；不要直接添加整个主目录或磁盘根目录。

12. 常见安装与登录问题

12.1 `claude: command not found`

先关闭并重新打开终端，再检查安装路径：

1	claude --version