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，输入以下命令验证：
|
1 2 |
node -v npm -v |
若均显示版本号，则表示 Node.js 安装成功。
2. 全局安装 Claude Code
在终端中执行：
|
1 |
npm install -g @anthropic-ai/claude-code |
如果遇到权限错误，可以尝试以管理员身份运行终端，或使用 --force 参数（不推荐但有效）。
安装完成后，运行 claude --version，若出现版本号说明安装成功。
注意：在使用 CC Switch 方案时，我们不需要设置 ANTHROPIC_API_KEY 环境变量，也不需要登录 Claude 账号。CC Switch 会接管所有 API 请求，所以请保持 Claude Code 处于“无 Key”状态，以免干扰转发逻辑。
四、基础使用方法
1. 启动交互模式
在终端中切换到你的项目目录，输入 claude 并回车，即可进入全屏对话界面。
|
1 2 |
cd D:\my-project claude |
首次启动可能会尝试连接默认 API，若已配合 CC Switch 则会自动使用你配置的免费模型。
2. 单次执行模式
也可以直接在命令后附带任务描述，Claude Code 执行完即退出，适合脚本化或快速查询：
|
1 2 |
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 服务器连接 |
七、典型工作流示例
1. 代码探索与理解
|
1 2 |
> 梳理整个项目的目录结构，简要说明各模块职责。 > 解释 services/data_fetcher.js 中的缓存机制。 |
2. 代码重构与优化
|
1 2 |
> 将 utils.js 中的所有回调函数改为 async/await 形式。 > 提取 auth.py 里的魔术数字为配置常量，并在配置文件中说明。 |
3. 测试与调试
|
1 2 3 |
> 为 models/user.rb 的 validations 生成 RSpec 测试。 > 运行 npm test，修复失败的用例，并说明原因。 > 这个错误堆栈是什么意思？请帮我定位并修复。 |
4. Git 工作流
|
1 2 3 |
> 创建一个新的 release/1.2.0 分支。 > 解决合并冲突，优先保留 main 分支的更改。 > 给最近一次提交补充详细 commit message。 |
5. 项目搭建
|
1 2 |
> 基于 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 进行调整：
|
1 2 3 4 5 |
{ "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 成为你最可靠的编程搭档吧。
