Claude Code 完全指南：从安装到精通

Claude Code 是 Anthropic 公司推出的一款命令行 AI 编程代理工具，它能让开发者直接在终端中与 AI 对话，完成代码理解、修改、调试、Git 操作等各类软件工程任务。本指南将系统性地介绍 Claude Code 的核心概念、安装流程、操作技巧以及进阶用法，帮助你在 Windows 环境下快速上手，并与 CC Switch 等工具配合使用，实现高效免费的 AI 编程体验。

一、什么是 Claude Code？

Claude Code 不是 IDE 插件，而是一个运行在终端里的 AI 编程代理。与传统的代码补全工具不同，它具备以下能力：

全面理解项目：自动索引整个代码库，跨文件理解逻辑关系。
自主执行任务：可读写文件、创建或删除目录、运行 Shell 命令、安装依赖、执行测试套件。
自然语言交互：用中文或英文直接描述需求，如"重构认证模块"或"修复所有失败的测试"。
安全可控：在执行删除文件、强制推送等危险操作前，会主动请求用户确认。
Git 原生集成：可直接发起提交、创建分支、查看差异、解决合并冲突。
支持 MCP 协议：通过 Model Context Protocol 连接外部工具和数据源（如数据库、API），扩展能力边界。

简而言之，Claude Code 就像一个坐在你旁边的资深程序员，不仅能听懂你的需求，还能直接动手修改代码、执行命令，而你只需审查和确认。

二、收费与免费策略

Claude Code 本身并不完全免费，通常需要通过以下方式使用：

Claude Pro / Max 订阅：订阅后可在终端中使用 Claude Code，每月包含一定免费计算额度。
Anthropic API Key：直接调用 API，按 token 付费。新注册用户通常可获得少量免费额度（如 $5）。
企业版 / 团队版：提供更多管理功能和用量方案。

但通过本文后续介绍的 CC Switch 工具，你可以将 Claude Code 的底层模型替换为讯飞星辰 MaaS 平台提供的免费 Qwen 模型，从而在 2026 年 6 月 30 日前实现零成本使用。这使得个人开发者也能够无负担地体验顶级 AI 编程代理的能力。

三、安装 Claude Code（Windows）

1. 安装 Node.js 环境

Claude Code 基于 Node.js 开发，要求版本 ≥ 18.0。

访问 Node.js 官方网站，下载 LTS 版本 的 Windows 安装包（.msi）。
运行安装程序，保持默认选项，务必勾选 "Add to PATH"。
安装完成后，打开命令提示符（cmd）或 PowerShell，输入以下命令验证：
cmd 复制代码
```
node -v
npm -v
```
若均显示版本号，则表示 Node.js 安装成功。

2. 全局安装 Claude Code

在终端中执行：

cmd 复制代码

npm install -g @anthropic-ai/claude-code

如果遇到权限错误，可以尝试以管理员身份运行终端，或使用 --force 参数（不推荐但有效）。

安装完成后，运行 claude --version，若出现版本号说明安装成功。

注意：在使用 CC Switch 方案时，我们不需要 设置 ANTHROPIC_API_KEY 环境变量，也不需要登录 Claude 账号。CC Switch 会接管所有 API 请求，所以请保持 Claude Code 处于"无 Key"状态，以免干扰转发逻辑。

四、基础使用方法

1. 启动交互模式

在终端中切换到你的项目目录，输入 claude 并回车，即可进入全屏对话界面。

cmd 复制代码

cd D:\my-project
claude

首次启动可能会尝试连接默认 API，若已配合 CC Switch 则会自动使用你配置的免费模型。

2. 单次执行模式

也可以直接在命令后附带任务描述，Claude Code 执行完即退出，适合脚本化或快速查询：

cmd 复制代码

claude "解释 src/main.py 的功能"
claude --print "列出所有 TODO 项"   # 输出到标准输出后退出

3. 对话与指令

在交互界面中，直接用中文或英文描述你的需求。Claude Code 会自动读取相关文件、执行命令并展示结果。例如：

理解代码："分析 auth.py 中的登录逻辑，指出潜在的安全问题。"
修改代码："把所有 console.log 改为 logger.info，并添加合适的日志级别。"
运行测试："运行 pytest，帮我把失败的测试修好。"
Git 操作："创建分支 feature/pagination，然后把最近 2 次提交压缩。"

对于高风险操作，Claude Code 会暂停并询问你是否同意，你可以选择 Approve（允许） 、Deny（拒绝） 或 Always allow（总是允许）。

五、常用快捷键

快捷键	功能
`Esc` 或 `Ctrl+C`	退出当前对话（或中断长时间运行的操作）
`Ctrl+D`	发送消息（在某些终端配置下等效于 Enter）
`Ctrl+L`	清屏
`Ctrl+Z`	挂起 Claude Code 进程到后台（Unix 风格）
`↑` / `↓` 方向键	浏览历史输入过的指令
`Tab`	自动补全文件路径、命令或模型建议

六、内部命令速查

在 Claude Code 对话中输入以 / 开头的命令，可以执行元操作：

命令	说明
`/help`	查看所有可用命令和帮助文档
`/clear`	清空当前对话上下文，但已修改的文件不受影响
`/compact`	压缩上下文，释放 token 消耗，适合长对话后重置
`/cost`	显示当前会话的 token 用量和费用估算（使用 CC Switch 时不准确）
`/doctor`	诊断系统环境（Node.js、网络、权限等）
`/status`	查看当前项目状态（已索引文件数、最近操作记录）
`/add-dir`	手动添加目录到工作区上下文
`/ide`	在 VS Code 等关联 IDE 中打开当前工作目录
`/git`	打开 Git 操作面板，可执行提交、分支管理等
`/bash`	在独立 Shell 中执行命令（等价于直接让 Claude 执行）
`/init`	在当前目录初始化 Claude Code 配置
`/login` / `/logout`	管理账号登录状态（使用 CC Switch 时无需登录）
`/mcp`	管理 MCP 服务器连接

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

七、典型工作流示例

1. 代码探索与理解

复制代码

> 梳理整个项目的目录结构，简要说明各模块职责。
> 解释 services/data_fetcher.js 中的缓存机制。

2. 代码重构与优化

复制代码

> 将 utils.js 中的所有回调函数改为 async/await 形式。
> 提取 auth.py 里的魔术数字为配置常量，并在配置文件中说明。

3. 测试与调试

复制代码

> 为 models/user.rb 的 validations 生成 RSpec 测试。
> 运行 npm test，修复失败的用例，并说明原因。
> 这个错误堆栈是什么意思？请帮我定位并修复。

4. Git 工作流

复制代码

> 创建一个新的 release/1.2.0 分支。
> 解决合并冲突，优先保留 main 分支的更改。
> 给最近一次提交补充详细 commit message。

5. 项目搭建

复制代码

> 基于 Flask 创建一个 RESTful 用户管理后台，包含注册、登录、JWT 认证。
> 给项目添加 ESLint、Prettier 和 Husky 配置。

八、上下文与权限管理

1. 权限确认机制

Claude Code 在执行不可逆操作前会征求确认，包括：

删除文件或目录
强制推送（git push --force）
修改系统级配置
安装未知来源的依赖

你可以针对每一次操作选择 Approve 或 Deny，或使用 Always allow 允许后续同类型操作免打扰。

2. 控制上下文范围

当 Claude 未自动加载相关文件时，你可以直接指定："请同时参考 config/settings.json 和 src/models/User.js。"
使用 /add-dir 命令手动添加整个目录。
创建 .claudeignore 文件，排除无需索引的日志、临时文件、第三方库等。

九、与 CC Switch 配合使用的注意事项

当使用 CC Switch 将模型替换为讯飞 Qwen 后，以下几点需要了解：

模型标识：Claude Code 界面仍显示"Claude"，但实际推理由 Qwen 完成。
费用显示 ：/cost 命令无法准确反映免费模型用量，可忽略。
功能兼容：文件操作、Shell 执行、Git 集成等功能与模型无关，完全可用。
思维链差异：极少数深度依赖 Claude 独特推理能力的场景可能效果略弱，但日常编程任务无感知。
网络依赖：必须保持 CC Switch 运行，且网络能连通讯飞 API 端点。

十、配置与自定义

Claude Code 的项目级配置存储在项目根目录的 .claude 文件夹中。高级用户可编辑 settings.json 进行调整：

json 复制代码

{
  "maxTokens": 4096,
  "permissionMode": "default",
  "ignorePatterns": ["node_modules", "*.log"]
}

部分常用配置项：

permissionMode ：设为 "acceptEdits" 可自动接受文件修改，无需逐次确认。
maxTokens：限制单次响应的最大 token 数，防止过长输出。
.claudeignore：配置忽略文件规则，避免索引不必要的文件。

十一、常见问题与排错

问题	可能原因与解决方法
启动后提示"无法连接 API"	检查 CC Switch 是否运行；在 CC Switch 中测试模型连通性；确认 Claude Code 未设置 `ANTHROPIC_API_KEY`。
模型回复质量不佳	上下文过长时使用 `/compact`；确认 CC Switch 中填写的模型 ID 与讯飞平台一致。
无法读取某些文件	检查文件是否被 `.gitignore` 或 `.claudeignore` 排除；手动通过 `/add-dir` 或明确路径告诉 Claude。
执行命令权限不足	以管理员身份运行终端；或修改 `.claude/settings.json` 的权限模式。
中文输出乱码	在终端中执行 `chcp 65001` 将编码切换为 UTF-8。
CC Switch 关闭后 Claude Code 报错	正常现象，CC Switch 是请求转发的唯一通道。恢复使用需重新打开 CC Switch 或移除其代理设置。

十二、总结

Claude Code 是当前命令行编程代理的标杆产品，它打破了"只能补全、不能动手"的局限，真正让 AI 参与到软件工程的完整流程中。配合 CC Switch 和讯飞星辰 MaaS 的免费模型，国内开发者可以在零成本的前提下，体验这种未来已来的编程范式。

你现在已经拥有完整的知识体系和操作指南，从安装 Node.js、配置 Claude Code，到通过 CC Switch 接入免费大模型，再到熟练运用对话、权限、自定义配置，每一步都可以按图索骥。开始你的第一个指令，让 AI 成为你最可靠的编程搭档吧。