Claude Code 完全上手指南：一站式解决安装、国内模型配置与高级实战

AI 编程工具正从被动的代码“补全器”进化为主动的“开发伙伴”。它们能够理解复杂需求、规划任务并直接参与整个开发流程。本文将深度解析一款代表该趋势的命令行AI编程工具——我们称之为 Claude Code，并提供一份详尽的完整使用指南。

新一代AI编程助理的理念

与我们熟知的IDE插件不同，Claude Code 这类工具选择了一个更贴近开发者核心工作流的界面——命令行（CLI）。

命令行界面简洁而高效

这种设计并非偶然。对于开发者而言，命令行轻量、可脚本化，能与 Git 等工具无缝集成。将AI能力注入这个核心地带，使其成为工作流的一部分，而非孤立的功能。同类型的工具还包括阿里的 Qwen Code 和谷歌的 Gemini CLI。

 
同类CLI AI编程工具界面

强大的模型与API生态

Claude Code 的能力源于背后顶尖的大语言模型，例如由 Anthropic 公司开发的 Claude 3 Opus、Claude 3.5 Sonnet 等。Anthropic 由前 OpenAI 核心成员 Dario Amodei 创立，其模型在编程和推理方面常年处于行业领先地位。

虽然 Claude Code 默认使用 Anthropic 官方模型，但其高昂的费用限制了个人开发者的使用。幸运的是，通过配置，我们可以将其接入更具性价比的国产模型，如智谱的 GLM-4.5 或月之暗面的 Kimi K2。

一个关键的技术细节是API格式。多数大模型兼容 OpenAI 的调用格式，而 Anthropic 有自己的一套规范。Claude Code 使用的是 Anthropic 格式，因此原生支持那些同样支持此格式的模型服务商。对于仅支持 OpenAI 格式的模型，则需要通过转换工具来桥接。

此外，Claude Code 本身是一个经过精心设计的智能体，其内置的系统提示（System Prompt）是针对 Anthropic 自家模型特点深度优化的。当替换为第三方模型时，可能会存在约 5% 至 20% 的效果损失。不过，对于绝大多数开发场景，只要需求描述清晰，这种影响在可接受范围内。

从“助手”到“伙伴”

传统AI编程插件，如早期的通义灵码，受限于模型能力和上下文长度，主要充当“剪贴板”和单次对话工具。Claude Code 这类新一代工具则能够理解整个项目文件夹，具备复杂任务的自主规划和多任务处理能力。

它不再仅仅生成代码片段，而是能够直接编辑文件、运行测试、执行构建命令，甚至处理Git提交。开发者的角色从任务的“执行者”转变为复杂工程的“委托者”，进入一种所谓的 VibeCoding（氛围编程）状态——定义需求、设计架构，然后监督AI完成具体的编码工作。

安装与配置完整指南

本教程以 macOS 系统为例，Windows 系统的操作步骤类似。

步骤一：快速安装

确保系统中已安装 Node.js (版本 >= 18)，然后执行以下命令进行全局安装：

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

安装完成后，在任何项目目录下执行 claude 命令即可启动。

# 进入你的项目目录
cd your-awesome-project
# 启动 Claude Code
claude
# 首次使用时，可能会提示登录

步骤二：处理地区限制与配置国内模型

首次运行若遇到地区不可用的提示，可通过配置环境变量，将请求代理到国内兼容 Anthropic API 格式的模型服务商。

初次运行时可能遇到的地区限制问题

打开终端的配置文件（macOS默认为 .zshrc），添加以下两行：

# 使用 vi 编辑配置文件。新手提示：打开后按 i 进入插入模式，
# 粘贴内容后按 ESC，然后输入 :wq 回车即可保存退出。
vi ~/.zshrc

在文件中添加以下内容：

export ANTHROPIC_BASE_URL=你的模型调用地址
export ANTHROPIC_API_KEY=你的API密钥

保存退出后，务必执行 source ~/.zshrc 命令使配置立即生效。

配置示例1：智谱 GLM-4.5 模型

1. 注册与获取API Key：访问智谱AI开放平台注册，并在API密钥管理页面创建新的Key。
   
2. 选购套餐 (可选)：智谱为开发者提供了高性价比的编程套餐，首月约20元，调用次数充足。
   
3. 配置环境变量：智谱的 Anthropic 兼容地址为 https://open.bigmodel.cn/api/anthropic。

   export ANTHROPIC_BASE_URL=https://open.bigmodel.cn/api/anthropic
   export ANTHROPIC_API_KEY=粘贴你的智谱API密钥
   

4. 生效配置并重启：执行 source ~/.zshrc 后，重新运行 claude 命令。

配置示例2：月之暗面 Kimi K2 模型

1. 注册与充值：访问月之暗面开发者平台注册。为保证调用速率，建议充值50元以上。
   
2. 获取API Key：在后台管理系统中创建新的API Key。
   
3. 配置环境变量：Kimi 的 Anthropic 兼容地址为 https://api.moonshot.cn/anthropic/。

   export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic/
   export ANTHROPIC_API_KEY=粘贴你的KimiAPI密钥
   

4. 生效配置并重启：执行 source ~/.zshrc 后，重新运行 claude 命令。

步骤三：通过路由接入任意 OpenAI 格式模型

若需使用仅支持 OpenAI 格式的模型（如通义千问），可使用 ClaudeCodeRouter 中间件进行转换。

1. 安装Router：

   npm install -g @musistudio/claude-code-router
   

   其主要功能包括模型路由、多提供商支持、请求/响应转换等。

2. 启动配置界面：

   ccr ui
   

   在打开的网页中，添加模型供应商，选择模板后填入API Key和模型名称。
   
   

3. 配置路由：
   在右侧路由部分，将不同任务（如思考、长上下文）指向你刚添加的模型，然后保存并重启。
   
4. 启动 Claude Code：
   使用 ccr code 命令启动，即可通过该路由使用配置好的模型。
   

步骤四：集成到 IDE

Claude Code 提供了 VS Code 和 JetBrains 系列 IDE (IntelliJ IDEA, WebStorm 等) 的增强插件，可在IDE内一键启动，实现更流畅的交互。

在IDE中安装插件

一键启动，无缝集成

核心使用技巧详解

基本交互

• @ 符号: 引用文件或目录以添加至上下文。
• # 符号: 定义记忆或规则，AI会在后续交互中遵守。
• ! 符号: 临时切换到bash模式执行Shell命令。
• ESC 键: 中断当前正在执行的任务。
• 多行输入: 使用 Shift+Enter 或 Option+Enter (macOS) 输入多行文本。可运行 /terminal-setup 安装 Shift+Enter 快捷键。

全部指令列表

输入 / 可唤出指令菜单，以下是完整指令列表：

/add-dir                  添加一个新的工作目录
/agents                   管理代理配置
/bashes                   列出和管理后台任务
/clear (reset, new)       清除对话历史并释放上下文
/compact                  清除对话历史，但在上下文中保留摘要。可选：/compact [摘要说明]
/config (theme)           打开配置面板
/context                  将当前上下文使用情况可视化为彩色网格
/cost                     显示当前会话的总成本和持续时间
/doctor                   诊断并验证您的 Claude Code 安装和设置
/exit (quit)              退出 REPL
/export                   导出当前对话到文件或剪贴板
/feedback (bug)           提交关于 Claude Code 的反馈
/help                     显示帮助和可用命令
/hooks                    管理工具事件的钩子配置
/ide                      管理 IDE 集成并显示状态
/init                     使用代码库文档初始化一个新的 CLAUDE.md 文件
/install-github-app       为代码仓库设置 Claude GitHub Actions
/login                    使用您的 Anthropic 帐户登录
/logout                   从您的 Anthropic 帐户注销
/mcp                      管理 MCP 服务器
/memory                   编辑 Claude 内存文件
/migrate-installer        从全局 npm 安装迁移到本地安装
/model                    设置 Claude Code 的 AI 模型
/output-style             直接或从选择菜单设置输出样式
/output-style:new         创建一个自定义输出样式
/permissions              管理允许和拒绝工具的权限规则
/pr-comments              从 GitHub 拉取请求中获取评论
/release-notes            查看发行说明
/resume                   继续一个对话
/review                   审查一个拉取请求
/security-review          完成对当前分支上待定更改的安全审查
/status                   显示 Claude Code 状态
/statusline               设置 Claude Code 的状态行用户界面
/terminal-setup           安装 Shift+Enter 换行快捷键
/todos                    列出当前的待办事项
/upgrade                  升级到 Max 以获得更高的速率限制
/vim                      在 Vim 和普通编辑模式之间切换

常用指令深度解析

• /init: 扫描项目生成 CLAUDE.md，包含技术栈、架构等摘要，帮助AI快速理解项目。
• /compact: 对长对话历史进行摘要，保留关键信息，节约Token并保持AI专注。
• /clear: 彻底清空当前对话，开启新会话。
• /resume: 恢复近期的对话历史，继续之前的任务。
• /memory: 编辑一系列Markdown文件以定义AI的长期行为偏好（如编码风格、个性）。这些文件位于 ~/.claude 目录下，分为全局和项目级。例如，rules.md 文件中可以包含如下的编程原则：

  你的任务是：**审查、理解并迭代式地改进/推进一个[项目类型，例如：现有代码库 / 软件项目 / 技术流程]。**
  在整个工作流程中，你必须内化并严格遵循以下核心编程原则，确保你的每次输出和建议都体现这些理念：
  - **简单至上 (KISS):** 追求代码和设计的极致简洁与直观，避免不必要的复杂性。
  - **精益求精 (YAGNI):** 仅实现当前明确所需的功能，抵制过度设计和不必要的未来特性预留。
  - **坚实基础 (SOLID):**
  - **S (单一职责):** 各组件、类、函数只承担一项明确职责。
  - **O (开放/封闭):** 功能扩展无需修改现有代码。
  - **L (里氏替换):** 子类型可无缝替换其基类型。
  - **I (接口隔离):** 接口应专一，避免"胖接口"。
  - **D (依赖倒置):** 依赖抽象而非具体实现。
  - **杜绝重复 (DRY):** 识别并消除代码或逻辑中的重复模式，提升复用性。
  - **文档同步 (Doc Sync):** 代码变更必须同步更新相关文档，保持一致性。
  **请严格遵循以下工作流程和输出要求：**
  1.  **深入理解与初步分析（理解阶段）：**
      - 详细审阅提供的[资料/代码/项目描述]，全面掌握其当前架构、核心组件、业务逻辑及痛点。
      - 在理解的基础上，初步识别项目中潜在的**KISS, YAGNI, DRY, SOLID**原则应用点或违背现象。
  2.  **明确目标与迭代规划（规划阶段）：**
      - 基于用户需求和对现有项目的理解，清晰定义本次迭代的具体任务范围和可衡量的预期成果。
      - 在规划解决方案时，优先考虑如何通过应用上述原则，实现更简洁、高效和可扩展的改进，而非盲目增加功能。
  

高级功能：自定义与自动化

自定义指令

将常用复杂任务封装成自定义命令。只需编写一个包含提示的 Markdown 文件（文件名即指令名，如 add-changelog.md），放入 ~/.claude/commands/ 目录，重启后即可通过 /add-changelog 调用。社区网站 https://www.buildwithclaude.com/ 提供了大量预设指令可供下载。

子代理（Subagents）系统

创建多个专职的“子智能体”（如前端专家、UX设计师），主智能体可根据复杂需求自动分解并分配任务，实现多角色并行协作。

通过 /agents 命令管理，可选择让AI辅助创建新代理，或从社区导入预设。

AI辅助创建子代理

在处理一个包含UI设计的任务时，主智能体会先调用UX设计师，待设计稿确认后，再进行编码。AI在执行任务时会生成一个任务清单（TodoList），并逐项完成，工作流程高度透明。

钩子（Hooks）系统

在特定事件（如文件编辑后）发生时自动触发命令。通过 /hooks 指令管理，可实现自动格式化、权限控制等自动化流程。

示例：编辑TS文件后自动用Prettier格式化

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|MultiEdit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
}
]
}
]
}
}

社区工具 claudecode-rule2hook 支持用自然语言生成钩子配置。

配置MCP Server

MCP (Machine-to-Claude Protocol) 是一种允许外部工具和服务与 Claude Code 通信的协议，可以扩展其能力，如连接到 Jira、Notion 等。

• 添加本地Stdio MCP Server:

  claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server
  

• 添加SSE MCP Server:

  claude mcp add --transport sse linear https://mcp.linear.app/sse
  

• 管理MCP Server:

  # 列出所有服务器
  claude mcp list
  # 删除服务器
  claude mcp remove github
  

提示词与工作模式技巧

XML标签结构化提示

使用XML标签包裹指令、上下文和示例，可以帮助Claude更精确地理解你的意图。

<instruction>
你希望 Claude 执行的主要任务或目标
</instruction>
<context>
任务的背景信息，比如涉及的框架、业务逻辑、团队规范等
</context>
<code_example>
可以参考的代码片段、接口规范或已有实现
</code_example>

三种工作模式切换

使用 Shift+Tab 循环切换：

1. 正常模式: 默认模式，执行文件编辑等操作前需要用户批准。
2. 自动接受模式: 所有操作默认批准，AI拥有完全控制权。
3. 计划模式: AI只进行规划，生成任务列表，不执行任何实际操作。

其他实用工具与资源

• 回退历史: 双击 ESC 可回退对话节点。对于代码更改的回退，可使用社区工具 ccundo (npm install -g ccundo)。
• 可视化配置工具 opcode: 网站 https://opcode.sh/ 提供了一个强大的Web界面，用于可视化管理 Claude Code 的所有配置，包括自定义指令、钩子、权限等。
  
  
• Claude官方中文指南: 官方文档 提供了最全面、最权威的功能介绍和使用说明。
  

新一代的AI编程工具正在重塑开发工作流，将开发者从繁琐的编码执行中解放出来，更专注于架构设计和业务创新。掌握它们，就是拥抱未来的开发模式。