Claude Code 使用指南

简介

Claude Code 是 Anthropic 官方推出的终端工具，通过自然语言命令帮助开发者完成编码任务。支持文件编辑、命令执行、代码搜索、Git 工作流等 40+ 工具调用。

核心特点

Agent 能力：理解代码库，执行复杂多步骤任务
可扩展：通过 Plugins、Skills、Commands 自定义功能
多 Agent 协作：支持子 Agent 分布式任务执行
记忆系统：自动保存和整合会话上下文

安装与配置

安装

# npm 安装
npm install -g @anthropic-ai/claude-code

# Homebrew (macOS/Linux)
brew install anthropic/claude-code/claude-code

# 验证
claude --version

首次配置

claude
# 按提示登录 Anthropic 账号和设置 API 密钥

权限级别

Claude Code 提供 5 种权限级别，控制 Agent 在操作文件、执行命令前是否需要确认。

级别	说明	适用场景
`BypassUsers`	YOLO 模式 / 全自动模式，不询问直接执行	无人值守、CI/CD、完全信任的自动化任务
`Info`	只显示将执行的操作，不等待确认	希望看到操作但不打断流程
`Review`	执行前确认（默认）	日常开发，安全与效率的平衡
`LightReview`	仅重要操作才确认	熟练用户，想减少确认次数
`Automatic`	自动决定，危险操作自动拒绝	严格安全环境

YOLO Mode 说明：“YOLO” = You Only Live Once（人生只有一次，放手干）。在 Claude Code 社区中 YOLO Mode 就是 BypassUsers 的别称 — Agent 执行所有操作前不再询问确认，一路狂奔。

启动 YOLO 模式（完全信任/全自动）

有两种方式可以达到 YOLO 效果，本质相同但写法不同：

# ─── 方式一（推荐）：--permission BypassUsers ───
claude --permission BypassUsers

# ─── 方式二：--dangerously-skip-permissions（别名） ───
claude --dangerously-skip-permissions

--dangerously-skip-permissions 与 --permission BypassUsers 的关系：
两者效果完全一样，都是跳过所有权限确认，直接执行操作。区别只是命名风格：
--dangerously-skip-permissions — 旧式写法，名字自带危险警告以强调风险
--permission BypassUsers — 新式写法，融入统一的权限管理体系
可以理解为 --permission BypassUsers = --dangerously-skip-permissions 的现代替代版本，功能相同，推荐前者。

其他常见用法：

# 单次执行
claude -p "帮我把整个项目重构为 TypeScript" --permission BypassUsers

# 会话中切换权限层级
claude --set-permission-level=BypassUsers

# 全局默认配置
# 编辑 ~/.claude/settings.json 添加：
# { "permissionLevel": "BypassUsers" }

其他权限模式启动

# 只显示操作，不等待确认
claude --permission Info

# 执行前逐一确认（默认，不指定即此模式）
claude --permission Review

# 仅重要操作确认
claude --permission LightReview

# 自动决定，危险操作自动拒绝
claude --permission Automatic

权限对比速查

YOLO (BypassUsers)  ← 全自动/完全信任，不询问直接执行（最自由）
         ↓
       Info          ← 只显示操作信息，不等待确认
         ↓
      Review         ← 执行前逐一确认（默认，推荐日常用）
         ↓
   LightReview       ← 仅危险/重要操作确认（效率优先）
         ↓
    Automatic        ← 自动拒绝危险操作（最严格）

模式	文件写入	命令执行	是否询问
YOLO / `BypassUsers`	✅ 直接写	✅ 直接跑	❌ 从不
`Info`	✅ 直接写	✅ 直接跑	只显示
`Review`	⚡ 确认后写	⚡ 确认后跑	✅ 每次都问
`LightReview`	⚡ 确认后写	⚡ 确认后跑	⚠️ 重要操作才问
`Automatic`	⚡ 安全才写	⚡ 安全才跑	🤖 自动判断

与 cc-connect 的 YOLO 模式的关系

如果结合 cc-connect（聊天工具桥接层）使用 Claude Code，cc-connect 也有自己的模式概念：

环境	命令	说明
Claude Code 原生	`claude --permission BypassUsers`	绕过程序内确认
cc-connect 桥接层	`/mode yolo`	自动批准所有工具调用
cc-connect 桥接层	`/mode default`	每次工具调用前询问

cc-connect 的 /mode yolo = 在聊天中发指令给 Claude Code 时，cc-connect 自动帮你在 Claude Code 一侧批准所有操作
Claude Code 的 --permission BypassUsers = Claude Code 本身就不询问了

两者配合使用效果：

cc-connect /mode yolo  +  Claude Code --permission BypassUsers
= 完全无人值守，从聊天到执行全程自动化

⚠️ YOLO 安全提示：全自动模式意味着 Claude Code 会直接执行所有操作。建议仅在以下情况使用：
CI/CD 自动化流水线
完全隔离的沙箱/容器环境
你明确知道任务的每一步是安全的
配合 run_as_user 系统用户隔离使用

第三方 API 配置

Claude Code 支持配置第三方 API 作为模型后端，可以连接 OpenAI、Azure、Google Gemini 等服务。

配置文件位置

主配置文件：~/.claude/settings.json 项目级配置：.claude/settings.json

OpenAI API 配置

{
  "models": [
    {
      "name": "gpt-4o",
      "apiType": "openai",
      "apiKey": "sk-...",
      "baseUrl": "https://api.openai.com/v1"
    }
  ],
  "defaultModel": "gpt-4o"
}

Azure OpenAI 配置

{
  "models": [
    {
      "name": "azure-gpt-4o",
      "apiType": "azure",
      "apiKey": "your-azure-key",
      "baseUrl": "https://your-resource.openai.azure.com",
      "azureDeployment": "gpt-4o",
      "azureApiVersion": "2024-02-01"
    }
  ],
  "defaultModel": "azure-gpt-4o"
}

Google Gemini 配置

{
  "models": [
    {
      "name": "gemini-2.0-flash",
      "apiType": "google",
      "apiKey": "your-gemini-api-key",
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta"
    }
  ],
  "defaultModel": "gemini-2.0-flash"
}

Anthropic API 配置（默认）

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

环境变量方式

# 设置 API 密钥
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# 或创建 .env 文件（项目根目录）
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

切换模型

# 命令行指定
claude --model gpt-4o

# 会话中切换
/set model gpt-4o

# 查看可用模型
/models list

常用 API 端点参考

服务	端点	说明
OpenAI	`api.openai.com/v1`	GPT-4o, GPT-4 Turbo 等
Azure OpenAI	`*.openai.azure.com`	企业版，需部署
Google Gemini	`generativelanguage.googleapis.com`	Gemini 系列
Anthropic	`api.anthropic.com`	Claude 3.5, 3 Opus 等
DeepSeek	`api.deepseek.com`	DeepSeek 系列
Groq	`api.groq.com`	免费 Tier，高速推理
MiniMax	`api.minimax.chat`	MiniMax 系列（海螺 AI）

MiniMax API 配置

Stpe1: 编辑或创建 Claude Code 的配置文件

   # MacOS & Linux 为 `~/.claude/settings.json`
   # Windows 为`用户目录/.claude/settings.json`
   # `MINIMAX_API_KEY` 需替换为您的 MiniMax API Key
   # 环境变量 `ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_BASE_URL` 优先级高于配置文件
   {
     "env": {
       "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
       "ANTHROPIC_AUTH_TOKEN": "MINIMAX_API_KEY",
       "API_TIMEOUT_MS": "3000000",
       "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
       "ANTHROPIC_MODEL": "MiniMax-M2.7",
       "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7",
       "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.7",
       "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.7"
     }
   }
   # Step2: 编辑或新增 `.claude.json` 文件
   # MacOS & Linux 为 `~/.claude.json`
   # Windows 为`用户目录/.claude.json`
   # 新增 `hasCompletedOnboarding` 参数
   {
     "hasCompletedOnboarding": true
   }

MiniMax 是国内 AI 公司，提供 MoE 大模型（abab6.5s、abab6.5g 等），通过海螺 AI 对外提供服务。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-cp-f6Np73ffzbIfwCpQmPp8oxa1iUINzJj15CAiq8xoO0pBQh7-4w_FLQ82wN--Q4abt0pzKDKXay6XxOtpfxYmY6CGbv1_-iQCO3Q1w6CRSNRC-0IUlJe1B-c",
    "ANTHROPIC_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL":  "MiniMax-M2.7",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.7",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "API_TIMEOUT_MS": "3000000"
  }
}```

**环境变量方式：**

```bash
export MINIMAX_API_KEY="your-api-key"
export MINIMAX_BASE_URL="https://api.minimax.chat/v1"

获取 API Key：

访问 MiniMax开放平台
注册并登录账号
进入「API 密钥」页面创建密钥
注意查看调用额度限制

可用模型：

模型	说明	特点
`abab6.5s`	MoE 大模型	推理速度快，适合日常任务
`abab6.5g`	GPT-4 级模型	性能更强，复杂任务
`abab6.5	基础 MoE 模型	平衡性能与成本
`speech-02-hd`	语音合成	高清语音生成

计费说明：

MiniMax 按 token 计费，abab6.5s 性价比高，适合个人开发者和小团队使用。

安全建议

使用环境变量：避免将 API 密钥硬编码到配置文件中
.gitignore 配置：确保 settings.json 和 .env 不被提交

## .gitignore
.env
settings.json

密钥轮换：定期更换 API 密钥
最小权限：为 API 密钥设置使用限制

基础用法

启动方式

claude                          # 交互模式
claude -p "解释这段代码"          # 单次执行
claude --resume                 # 恢复上次会话
claude /命令                     # 执行自定义命令

常用命令

命令	说明
`claude`	启动交互式对话
`exit` / `Ctrl+D`	退出
`Ctrl+L`	清屏
`/help`	显示帮助
`/review`	代码审查
`/document`	生成文档
`/test`	运行测试

核心功能详解

1. 智能代码编辑

Claude Code 能理解整个代码库上下文：

读取和分析多个文件
理解项目结构和依赖
编写新代码或修改现有代码
自动处理 import 和依赖

示例：

重构 src/utils/auth.js 中的所有函数，添加 TypeScript 类型定义

2. Git 工作流

## 查看变更
claude "git status 和 diff 是什么"

## 提交代码
claude "帮我写一个好的 commit message，然后提交"

## 创建分支
claude "基于 main 创建一个叫 feature/user-auth 的分支"

3. 测试驱动开发

为 src/api/users.ts 写单元测试，覆盖率达到 80%

4. 代码审查

审查 src/components/ 目录下的所有组件，检查：
1. Props 类型是否完整
2. 错误处理是否到位
3. 性能优化建议

自定义 Commands

Commands 是可重用的提示模板，通过 /命令名 快速调用。

目录结构

项目/
└── .claude/
    └── commands/
        ├── review.md          # /review
        ├── document.md        # /document
        └── test.md            # /test

创建自定义命令

创建 .claude/commands/test.md：

---
description: 为文件编写单元测试
argument-hint: [source-file]
---

为 @$1 编写完整的单元测试，包括：

1. **基本功能测试** - 验证主要功能正常工作
2. **边界测试** - 空值、极端值、错误输入
3. **异步测试** - Promise/async 函数

要求：
- 使用 Jest/Vitest 语法
- 测试文件命名为 *.test.ts
- 覆盖率目标 80%+

常用命令示例

代码审查命令

---
description: 全面代码审查
allowed-tools: Read, Bash(git:*)
---

对代码进行全面审查：

1. **代码质量**
   - 可读性和可维护性
   - 代码风格一致性
   - 抽象层次是否合理

2. **潜在问题**
   - 逻辑错误或 Bug
   - 未处理的边界情况
   - 性能问题

3. **最佳实践**
   - 设计模式使用是否正确
   - 错误处理是否完善
   - 文档是否充分

提供具体的文件和行号引用。

文档生成命令

---
description: 为源文件生成文档
argument-hint: [source-file]
---

为 @$1 生成完整文档，包括：

**概述**
- 用途和职责
- 主要功能
- 依赖关系

**API 文档**
- 函数/方法签名
- 参数说明（含类型）
- 返回值（含类型）
- 异常说明

**使用示例**
- 基础用法
- 常见模式
- 边界情况

格式化为 Markdown。

文件比较命令

---
description: 比较两个文件
argument-hint: [file1] [file2]
---

比较 @$1 和 @$2，输出：

1. **差异**
   - 新增行
   - 删除行
   - 修改行

2. **功能变更**
   - 破坏性变更
   - 新功能
   - Bug 修复
   - 重构

3. **影响范围**
   - 受影响的组件
   - 需要同步更新的地方
   - 迁移要求

4. **建议**
   - 代码审查重点
   - 测试要求
   - 文档更新

Skills（技能）

Skills 是模块化的能力扩展，提供专业领域的知识和工作流程。

目录结构

插件/
├── .claude-plugin/
│   └── plugin.json
├── commands/           # 命令
├── agents/             # Agent 定义
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/   # 参考文档
        ├── examples/     # 示例
        └── scripts/      # 脚本

SKILL.md 格式

---
name: 代码审查技能
description: 当需要审查代码质量时使用
version: 1.0.0
---

## 代码审查技能

## 使用场景
- PR 代码审查
- 上线前检查
- 重构前评估

## 审查要点
[详细指南...]

## 输出格式
[报告模板...]

官方 Skills

Skill	功能
hook-development	钩子开发
command-development	命令开发
skill-development	技能开发
plugin-settings	插件配置

Agents（代理）

Agents 是具有特定职责的 AI 角色，可手动调用或自动选择。

创建 Agent

创建 .claude/agents/security-reviewer.md：

---
description: 安全代码审查专家
capabilities:
  - SQL 注入检测
  - XSS 漏洞扫描
  - 敏感信息暴露检查
  - 认证授权审计
---

## 安全审查 Agent

你是代码安全审查专家。

## 职责
- 扫描常见安全漏洞
- 识别潜在的 attack vectors
- 提供修复建议

## 检查清单
1. 用户输入是否正确验证
2. SQL/命令注入风险
3. 敏感数据保护
4. 认证授权机制
5. 会话管理安全

使用 Agent

## 启动时指定
claude --agent security-reviewer

## 会话中调用
切换到安全审查模式，审查 src/auth/

多 Agent 协作

Claude Code 支持多 Agent 分布式任务执行：

---
agent_name: backend-dev
task_number: 1
coordinator_session: team-lead
enabled: true
dependencies: []
---

## 任务：实现用户 API

实现用户相关的 REST API...

Hooks（钩子）

Hooks 在关键时机自动执行指定操作。

支持的事件

事件	时机
`SessionStart`	会话开始时
`Stop`	会话结束时
`PreToolUse`	工具执行前
`PostToolUse`	工具执行后
`SubagentStop`	子 Agent 停止前

创建 Hooks

创建 hooks/hooks.json：

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "command",
          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scan-secrets.sh"
        }
      ]
    }
  ],
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "验证任务已完成，检查是否有遗漏"
        }
      ]
    }
  ]
}

常用 Hook 场景

自动构建检查

{
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "如果代码被修改，检查项目是否构建成功 (npm run build)。如未构建，阻止退出并提示构建。"
        }
      ]
    }
  ]
}

提交前检查

{
  "PreToolUse": [
    {
      "matcher": "Bash(git commit:*)",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "验证提交信息质量，确保包含：1) 变更类型 2) 简短描述 3) 关联的 issue"
        }
      ]
    }
  ]
}

CLAUDE.md 项目级配置

在项目根目录创建 .claude/CLAUDE.md 设置项目上下文：

## 项目指南

## 项目概述
这是一个基于 React + TypeScript 的电商后台管理系统。

## 技术栈
- 前端：React 18, TypeScript, Ant Design
- 后端：Node.js, Express, PostgreSQL
- 构建：Vite,pnpm

## 代码规范
- 使用 ESLint + Prettier
- 分支命名：feature/*, bugfix/*
- Commit 格式：type: description

## 本地开发
```bash
pnpm install
pnpm dev      # 启动开发服务器
pnpm build    # 构建生产版本
pnpm test     # 运行测试

常用任务

新增页面：在 src/pages/ 下创建
添加 API：在 src/api/ 下定义
状态管理：使用 Zustand


---

## 实战应用场景

### 场景一：自动化脚本编写

```bash
## 批量重命名文件
claude "写一个脚本，将 src/images/ 下所有 .jpeg 改为 .jpg"

## 数据处理
claude "写一个 Python 脚本，解析 CSV 文件并生成统计报告"

## 定时任务
claude "写一个 crontab 脚本，每天凌晨备份数据库到 S3"

场景二：代码迁移

claude "将 src/utils/ 下的 JavaScript 代码迁移到 TypeScript，
        包括：
        1. 添加类型定义
        2. 提取接口
        3. 更新 import"

场景三：文档自动化

## 生成 README
claude "根据代码结构生成项目 README.md"

## 生成 API 文档
claude "为 src/api/ 下所有接口生成 OpenAPI 3.0 文档"

## 更新 Changelog
claude "根据 git log 生成 CHANGELOG.md"

场景四：代码分析

## 复杂度分析
claude "分析 src/ 目录，计算圈复杂度，找出需要重构的函数"

## 依赖分析
claude "生成项目的依赖关系图，找出循环依赖"

## 死代码检测
claude "找出从未被调用的函数和未使用的导出"

场景五：测试生成

## 单元测试
claude "为 src/utils/validator.ts 生成单元测试"

## E2E 测试
claude "用 Playwright 为登录流程写 E2E 测试"

## 快照测试
claude "为 src/components/ 下的组件生成快照测试"

工作流程整合

1. Obsidian 笔记 + Claude Code

## 在 Obsidian vault 启动 Claude
cd ~/Obsidian/Vault
claude

## 让 Claude 学习笔记
"阅读 项目笔记.md，了解项目背景"

## 执行任务
"根据笔记中的需求，实现用户注册功能"

2. Git 工作流

1. Claude Code 创建分支
2. Claude Code 实现功能
3. Claude Code 编写测试
4. Claude Code 生成文档
5. Claude Code 创建 PR

3. CI/CD 集成

## 预提交钩子
npx claude -p "运行 lint 和单元测试，报告结果"

## PR 检查
claude -p "审查 PR 代码，给出批准/需要修改的建议"

最佳实践

明确任务边界：一次只做一件事，逐步迭代
利用 CLAUDE.md：为项目设置清晰的上下文
善用 Commands：高频任务封装为命令
结合 Hooks：自动化重复检查
版本控制配置：将 Commands/Skills 纳入 Git

常见问题

Q: 如何避免误操作？

## 提高权限级别（默认确认模式）
claude --set-permission-level=Review

## 或使用最严格的 Automatic 模式，自动拒绝危险操作
claude --permission Automatic

## 危险命令前确认
## Claude 会自动识别 rm, drop 等危险操作

Q: 如何加速 Claude Code？

## 使用更快的模型
## 设置 CLAUDE_MODEL=claude-3-5-haiku-20241120

## 减少上下文
## 定期开启新会话

Q: Commands 不生效？

## 确保文件名正确
ls .claude/commands/

## 重启 Claude
exit && claude

简介

核心特点

安装与配置

安装

首次配置

权限级别

启动 YOLO 模式（完全信任/全自动）

其他权限模式启动

权限对比速查

与 cc-connect 的 YOLO 模式的关系

第三方 API 配置

配置文件位置

OpenAI API 配置

Azure OpenAI 配置

Google Gemini 配置

Anthropic API 配置（默认）

环境变量方式

切换模型

常用 API 端点参考

MiniMax API 配置

Stpe1: 编辑或创建 Claude Code 的配置文件

安全建议

基础用法

启动方式

常用命令

核心功能详解

1. 智能代码编辑

2. Git 工作流

3. 测试驱动开发

4. 代码审查

自定义 Commands

目录结构

创建自定义命令

常用命令示例

代码审查命令

文档生成命令

文件比较命令

Skills（技能）

目录结构

SKILL.md 格式

官方 Skills

Agents（代理）

创建 Agent

使用 Agent

多 Agent 协作

Hooks（钩子）

支持的事件

创建 Hooks

常用 Hook 场景

自动构建检查

提交前检查

CLAUDE.md 项目级配置

常用任务

场景二：代码迁移

场景三：文档自动化

场景四：代码分析

场景五：测试生成

工作流程整合

1. Obsidian 笔记 + Claude Code

2. Git 工作流

3. CI/CD 集成

最佳实践

常见问题

Q: 如何避免误操作？

Q: 如何加速 Claude Code？

Q: Commands 不生效？

参考资源

相关