Claude Code 使用指南

主题

初次使用 ​

First Run

安装完成后，本章将引导你完成 Claude Code 的首次启动、认证流程和基本交互操作。读完本章，你将能够顺利地开始使用 Claude Code 进行日常开发。

启动方式 ​

Launch Methods

Claude Code 提供了多种启动方式，适用于不同的使用场景：

交互式 REPL 模式 ​

最常用的启动方式，进入一个持续的对话环境：

bash
# 在项目目录下启动
cd your-project
claude

启动后你会看到类似以下的界面：

╭─────────────────────────────────────────╮
│ Claude Code v1.x.x                     │
│                                         │
│ Working directory: /path/to/project     │
│ Model: claude-sonnet-4-6-20250311       │
│ Mode: Default (ask before acting)       │
╰─────────────────────────────────────────╯

>

在 > 提示符后直接输入自然语言即可与 Claude 交互。

无头模式（一次性提问） ​

适合快速提问或脚本集成，执行完毕后自动退出：

bash
# 使用 -p 参数直接提问
claude -p "解释一下 package.json 中的 scripts 配置"

# 结合输出格式参数
claude -p "列出所有 TODO 注释" --output-format json

# 管道输入
cat error.log | claude -p "分析这个错误日志"

继续上次对话 ​

如果之前的对话被中断或你想继续讨论：

bash
# 继续上一次对话（保持上下文）
claude -c

# 从特定会话恢复
claude -r

各启动方式对比 ​

启动命令说明交互方式适用场景
claude进入 REPL 交互模式持续对话日常开发、复杂任务
claude -p "问题"无头模式，一次性提问单次问答快速查询、脚本集成
claude -c继续上一次对话持续对话中断后恢复
claude -r从会话列表中恢复持续对话恢复历史会话

认证流程 ​

Authentication Process

首次运行 Claude Code 时，你需要完成认证。Claude Code 支持两种认证方式：

方式一：OAuth 浏览器认证（推荐） ​

这是最简便的认证方式，适合个人用户：

bash
claude
# 首次运行，终端会显示：
# Opening browser for authentication...
# If browser doesn't open, visit: https://claude.ai/auth/cli?code=XXXX

认证步骤：

  1. Claude Code 会自动打开默认浏览器
  2. 在浏览器中登录你的 Anthropic 账户
  3. 授权 Claude Code 访问你的账户
  4. 浏览器显示"认证成功"，回到终端即可开始使用

如果浏览器没有自动打开，手动复制终端中显示的 URL 到浏览器中访问。

方式二：API Key 认证 ​

适合 CI/CD 环境或需要精确控制用量的场景：

bash
# 设置环境变量
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# 然后正常启动
claude

在 shell 配置文件中持久化（注意保护密钥安全）：

bash
# ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

API Key 安全提示

  • 不要将 API Key 提交到版本控制系统
  • 不要在共享环境中直接写入 shell 配置文件
  • 推荐使用密钥管理工具（如 macOS Keychain、1Password CLI）
  • 在 CI/CD 中使用 secrets 管理功能

支持的订阅计划 ​

计划认证方式Claude Code 支持用量限制
Claude ProOAuth支持有使用额度上限
Claude MaxOAuth完整支持（推荐）大幅提升的使用额度
Claude TeamsOAuth / SSO支持团队共享额度
Claude EnterpriseOAuth / SSO / API完整支持自定义额度
API 直接使用API Key支持按 token 计费

Claude Max 订阅的优势 ​

Claude Max 是目前使用 Claude Code 最推荐的订阅方式：

  • 大幅提升的使用额度 — 相比 Pro 计划，Max 提供更充裕的使用量
  • 优先访问 — 在高峰时段享有优先队列
  • 完整模型访问 — 包括 Opus 4.6 等高端模型
  • 无需管理 API Key — OAuth 登录即用
bash
# Max 订阅用户直接 OAuth 登录，无需额外配置
claude
# → 浏览器认证 → 开始使用

基本交互 ​

Basic Interaction

认证完成后，让我们学习 Claude Code 的基本交互方式。

自然语言输入 ​

在 REPL 模式下，直接输入自然语言即可：

bash
> 这个项目用的什么框架？

> 帮我找到所有处理用户认证的文件

> src/utils/format.ts 这个文件是做什么的？

多行输入 ​

当你需要输入较长的内容时，可以使用多行模式：

bash
# 方式一：使用反斜杠 \ 续行
> 帮我创建一个新的 API 端点，\
  路径是 /api/users/:id/profile，\
  需要支持 GET 和 PUT 方法

# 方式二：使用 Shift+Enter 换行
# （在支持的终端中按 Shift+Enter 可以输入新行而不发送）

REPL 内置命令 ​

Claude Code 的 REPL 提供了一些斜杠命令：

命令说明
/help显示帮助信息
/exit退出 REPL
/clear清除当前对话上下文
/model <name>切换使用的模型
/cost显示当前会话的 token 使用量和费用
/compact压缩对话历史（减少上下文占用）
/config查看或修改配置
/status显示当前状态信息

退出 REPL ​

bash
# 方式一：使用命令
> /exit

# 方式二：快捷键
# 按 Ctrl+C 两次

# 方式三：
# 按 Ctrl+D（发送 EOF）

第一个任务 ​

Your First Task

让我们用一个实际的例子来体验 Claude Code 的能力。假设你刚加入一个新项目，想要快速了解项目结构。

步骤 1：在项目目录启动 ​

bash
cd /path/to/your/project
claude

步骤 2：让 Claude 解释项目 ​

bash
> 帮我分析一下这个项目的整体结构和技术栈

Claude Code 会自动：

  1. 读取项目根目录的关键文件（package.json、tsconfig.json 等）
  2. 扫描目录结构
  3. 分析主要的源代码文件
  4. 给你一个全面的项目概述

步骤 3：深入了解特定部分 ​

bash
> src/api/ 目录下有哪些接口？分别的功能是什么？

> 数据库用的什么？连接配置在哪里？

> 项目的测试覆盖情况如何？

步骤 4：尝试修改 ​

bash
> 给 README.md 添加一个"快速开始"部分

此时 Claude Code 会：

  1. 读取现有的 README.md
  2. 分析项目的启动方式
  3. 生成合适的内容
  4. 询问你是否允许修改文件（这就是权限提示）

理解权限提示 ​

Understanding Permission Prompts

首次使用 Claude Code 时，你会频繁看到权限确认提示。这是 Claude Code 的安全机制。

权限提示示例 ​

当 Claude Code 想要执行操作时，会显示类似以下的提示：

Claude wants to edit file: src/components/Header.tsx

  Changes:
  + import { UserMenu } from './UserMenu';
  +
    export function Header() {

Allow? [y/n/a]

响应选项 ​

选项含义说明
yYes（允许）允许本次操作
nNo（拒绝）拒绝本次操作，Claude 会尝试其他方案
aAlways（总是允许）允许此类操作，本次会话内不再询问

常见的权限请求类型 ​

# 文件读取
Claude wants to read file: src/config/database.ts

# 文件编辑
Claude wants to edit file: src/routes/users.ts

# 命令执行
Claude wants to run: npm test

# 文件创建
Claude wants to create file: src/utils/validator.ts

减少权限提示 ​

如果你觉得频繁的权限提示影响效率，有几种方式可以减少：

  1. 切换到 Auto 模式：自动执行所有操作（下一章详述）
  2. 配置权限规则：在 .claude/settings.json 中预设允许的操作
  3. 使用 a 选项：对特定类型的操作设为始终允许
json
// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Edit(src/**)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ]
  }
}

初次使用的最佳实践 ​

Best Practices for First Run

从小任务开始 ​

不要一上来就让 Claude Code 做大规模重构。先从简单任务开始，了解它的工作方式：

bash
# 好的起步任务
> 解释一下 src/index.ts 的作用
> 这个函数有什么潜在的 bug？
> 帮我给这个函数添加 JSDoc 注释

# 等熟悉后再尝试
> 将这个模块从 JavaScript 迁移到 TypeScript
> 重构整个认证系统

提供上下文 ​

Claude Code 理解自然语言，但更具体的描述会得到更好的结果：

bash
# 模糊的请求
> 帮我改一下样式

# 具体的请求
> 把 Header 组件的背景色从白色改为深蓝色（#1a237e），
  文字颜色改为白色，并添加底部 2px 的阴影

利用项目上下文 ​

Claude Code 能读取整个项目，充分利用这一点：

bash
# 让它参考现有代码的风格
> 参照 src/services/userService.ts 的风格，
  创建一个新的 orderService.ts

# 让它理解项目的约定
> 按照项目现有的测试风格，为 utils/validator.ts 编写测试

审查每次修改 ​

在你充分信任 Claude Code 之前，仔细审查它的每次修改：

bash
# 让它先解释计划再执行
> 你打算怎么实现这个功能？先告诉我计划，不要开始修改

# 利用 Plan 模式（下一章详述）
# 按 Shift+Tab 切换到 Plan 模式

常见问题 ​

Frequently Asked Questions

认证失败怎么办？ ​

bash
# 清除已有认证信息，重新认证
claude logout
claude

终端没有自动打开浏览器？ ​

手动复制终端中显示的认证 URL 到浏览器中访问。如果你在远程服务器（SSH）上工作，需要在本地浏览器中打开该 URL。

启动后无响应？ ​

bash
# 检查网络连接
curl -I https://api.anthropic.com

# 检查代理配置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 查看详细日志
claude --debug

如何更换账户？ ​

bash
# 登出当前账户
claude logout

# 重新启动并认证新账户
claude

小结 ​

Summary

恭喜！到这里你已经完成了 Claude Code 的初次设置。让我们回顾一下关键步骤：

  1. 启动方式：claude（REPL）、claude -p（无头）、claude -c（继续对话）
  2. 认证方式：OAuth 浏览器认证（推荐）或 API Key
  3. 基本交互：自然语言输入、斜杠命令、多行输入
  4. 权限机制：每次操作需确认（Default 模式下）

接下来，让我们深入了解 Claude Code 的三种操作模式，学会根据不同场景选择最合适的工作方式。