Claude Code 安装和使用指引

编写：双梧科技版本：v0.1（初稿）日期：2026-03-19

⚠️ 重要提示：本文档为初稿版本，会持续更新迭代。 如遇到文档中未覆盖的问题，请善于利用 AI 对话（如直接向 Claude、ChatGPT 等大模型提问）来寻找解决方案。

目录

• 一、Claude Code 是什么？它会做什么？

• 二、如何安装 Claude Code 并对接第三方模型？

• 三、如何给 Claude Code 添加 Skills？

• 四、如何在 VS Code 中使用 Claude Code？

• 五、最佳实践与进阶技巧

• 六、常见问题与故障排查

一、Claude Code 是什么？它会做什么？

1. Claude Code 简介

Claude Code 是 Anthropic 推出的一款 代理式 AI 工作助手（Agentic AI Work Agent）。虽然它的名字里有"Code"，但 千万不要以为它只是一个编程工具。

Claude Code 的本质是一个 通用型 AI 智能代理——它能够直接访问你的文件系统、读取和编辑各种格式的文件、运行终端命令、操作浏览器，甚至生成图表和图像。它就像一个 住在你电脑里的全能型 AI 助手，既能帮你写代码，也能帮你写文档、做数据分析、审查合同、制作演示文稿，几乎可以胜任任何需要在电脑上完成的知识型工作。

⚠️ 重要：Claude Code ≠ 编程专用工具。 它之所以叫"Code"，是因为它使用了代码级别的深度交互方式（直接操作文件系统、执行命令等），而非仅仅通过对话框交流。这种交互方式使它在 所有类型的工作任务 中都拥有远超普通 AI 聊天的能力。

下面这张图展示了用户、Claude Code、LLM 大模型、MCP 和 Skills 之间的交互关系：

📝 图示说明：Claude Code 是连接用户与各种 AI 能力的中枢。用户只需用自然语言下达任务，Claude Code 会自动协调 LLM 进行推理、调用 MCP 获取外部数据、加载 Skills 获取专业指令，并直接操作本地文件系统、终端和浏览器来完成工作。

2. Claude Code 的能力全景

很多人初次接触 Claude Code 时，会以为它只能写代码。实际上，编程只是它众多能力之一。 以下是它目前能够胜任的工作场景：

🖥️ 软件开发类

• 编写、修改、调试各种编程语言的代码

• 自动运行测试、编译项目、查看运行结果

• 代码审查，发现潜在的代码质量问题

• Git 版本控制操作

📝 文档与办公类

• 生成 Markdown 文档、Word 文档（.docx）、PPT 演示文稿（.pptx）

• 读取、编辑、合并、拆分 PDF 文件

• 读取和处理 Excel（.xlsx） 和 CSV 数据文件

• 生成 XMind 思维导图

• 撰写报告、方案、邮件等各类文档

📊 数据分析与可视化类

• 读取 Excel、CSV 文件进行数据分析

• 生成数据图表和可视化报告

• 创建交互式仪表板和数据大屏

🔍 专业审查类

• 合同条款审查：利用 Skills 实现对合同条款的逐条审批（后文详述）

• 技术方案评审

• 文档校对与润色

🌐 网页与前端类

• 创建完整的前端网页和交互式应用

• 生成设计素材和 UI 原型

🗂️ 文件与系统管理类

• 批量重命名、整理、转换文件格式

• 文件搜索、内容提取和归档

💡 小贴士：简单记住一点：凡是你过去需要在电脑上手动完成的知识型工作，都可以尝试让 Claude Code 来帮你做。它能力的边界远超你的想象，关键在于你如何向它提出任务。

3. 使用 Claude Code 与直接跟 LLM 对话的差异

那么，Claude Code 和你平时在网页上使用的 ChatGPT、Claude 对话有什么不同呢？

举个例子：如果你让 ChatGPT 帮你写一份 Word 格式的合同审查报告，它最多给你一段文本让你自己复制到 Word 里。而 Claude Code 可以直接读取你的合同文件、分析内容、然后 自动生成一个格式精美的 .docx 文件保存到你的电脑上。

4. Claude Code 的使用形式不止命令行

4.1 具备集成 VS Code 和 JetBrains 的图形化插件

Claude Code 提供了官方 IDE 插件，支持以图形化界面在 IDE 中使用：

• VS Code 插件：在 VS Code 扩展市场搜索 Claude Code for VS Code 即可安装

• JetBrains 插件：支持 IntelliJ IDEA、PyCharm 等 JetBrains 系列 IDE

安装插件后，你可以在 IDE 的侧边栏中直接与 Claude Code 对话，享受图形化交互体验。

4.2 Claude Code 采用命令行方式的原因

你可能会问：既然有图形化插件，为什么 Claude Code 的核心是命令行？

1. 1. 最大灵活性：命令行可以在任何终端环境运行，不受 IDE 限制

2. 2. 更高的控制权：命令行允许直接执行系统命令、脚本，与 Git、Docker 等工具无缝集成

3. 3. 自动化友好：命令行天然适合编排自动化工作流

4. 4. 资源占用更低：没有图形界面的开销

5. 5. IDE 无关性：不管你用 VS Code 还是其他任何编辑器，命令行都通用

📝 备注：即使你更喜欢图形化界面，也建议至少掌握命令行的基本用法，因为有些高级功能（如 Hooks、自定义配置等）目前只能通过命令行完成。

5. Claude Code 的对接能力不止 Anthropic 模型

5.1 对接 Anthropic 模型

5.1.1 中国大陆、香港无法直接对接

由于网络和政策原因，中国大陆和中国香港地区 无法直接 连接 Anthropic 官方 API 服务。即使配置了正确的 API Key，也会因为网络连通性问题无法使用。

5.1.2 需要借助第三方 API 中转站

要在中国大陆使用 Claude Code 对接 Anthropic 模型，可以通过 第三方 API 中转站 来实现。这些中转站在海外搭建了代理服务，将 Anthropic API 请求中转到可访问的服务器。

⚠️ 注意：使用第三方中转站时需注意数据安全和隐私保护，建议选择知名、可信赖的服务商。

5.2 对接第三方模型

Claude Code 的架构设计允许对接不同的后端大模型，这给用户提供了极大的灵活性。

5.2.1 直接对接（需第三方大模型支持 Anthropic 接口规范）

一些大模型服务商（如 阿里云百炼平台）提供了兼容 Anthropic API 接口规范的服务，可以直接通过配置 ANTHROPIC_BASE_URL 来对接。例如阿里云百炼的 Coding Plan 就支持：

• qwen3.5-plus

• qwen3-coder-next

• 以及其他百炼平台支持的模型

5.2.2 间接对接（借助 Claude Code Router 或 CC-Switch 工具）

对于不直接兼容 Anthropic API 的模型，可以借助中间件工具进行适配：

• Claude Code Router：一个路由工具，可以将 Claude Code 的请求转发到不同的模型后端（如 OpenAI、Google Gemini 等）

• CC-Switch：另一个常用的模型切换工具，允许在多个模型之间灵活切换

这些工具的核心原理是在本地或远程搭建一个兼容 Anthropic API 规范的代理服务，将请求翻译后转发到目标模型。

二、如何安装 Claude Code 并对接第三方模型？

本章以对接 阿里云百炼平台 Coding Plan 为例进行介绍。完整官方指引请参考：

🔗 阿里云百炼 Claude Code 官方指引

1. 前置准备

1.1 安装 Node.js

Claude Code 基于 Node.js 运行，需要先安装 Node.js v18.0 或更高版本。

下载地址：https://nodejs.org/en/download/

安装时建议勾选"自动添加到 PATH"选项。安装完成后，打开 CMD 或 PowerShell 验证：

node --version    REM 应输出 v18.x.x 或更高npm --version     REM 应输出对应的 npm 版本号

1.2 安装 WSL 或 Git for Windows

在 Windows 上使用 Claude Code，需要安装以下任一环境：

• WSL（Windows Subsystem for Linux）：推荐方式，在 PowerShell（管理员）中运行 wsl --install

💡 建议：如果你不确定选哪个，建议安装 Git for Windows，它更轻量，安装也更简单。安装后你会获得一个 Git Bash 终端，后续操作都在这个终端中进行。

1.3 获取阿里云百炼 API Key

1. 1. 登录 阿里云百炼控制台

2. 2. 进入Coding Plan 页面

3. 3. 获取专属 API Key（请妥善保管，不要泄露）

2. 安装 Claude Code

2.1 npm安装

在 WSL 或 Git Bash 终端中执行以下命令：

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

验证安装：

claude --version

详细的 Windows 安装教程请参考：Windows Setup Guide

2.2 原生安装

2.2.1 干净环境下原生安装

采用原生安装方式可以确保 Claude Code 保持持续更新并获得更好的性能。在科学上网环境下，打开命令行工具（如 PowerShell）并键入以下命令：

irm https://claude.ai/install.ps1 | iex

等待安装程序响应，出现如下提示即表示成功：

✔ Claude Code successfully installed!Version: 2.1.77Location: C:\Users\你的用户名.local\bin\claude.exe✅ Installation complete!

2.2.2 从 npm 迁移到原生安装

如果你之前是通过 npm 安装的，请按照以下步骤迁移：

1. 1. 执行迁移命令：在命令行输入 claude install。系统会自动从 npm 模式迁移到原生安装模式。如果执行失败，请先执行set HTTP_PROXY=http://10.0.0.34:7890和set HTTPS_PROXY=http://10.0.0.34:7890后再执行claude install

2. 2. 配置环境变量：

• 迁移后，程序通常位于 C:\Users\你的用户名\.local\bin。

• 在系统环境变量的 Path 变量中增加：%USERPROFILE%\.local\bin。

1. 3. 卸载旧版本：执行以下命令删除原有的 npm 全局包：

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

2.2.3 验证安装

执行以下命令进行检查：

claude doctor

若返回结果包含 Currently running: native (版本号)，则表示迁移成功。

3. 配置对接百炼 Coding Plan

需要配置以下三个关键信息：

3.1 创建配置目录和文件

方式一：使用 CMD

ifnotexist "%USERPROFILE%\.claude" mkdir "%USERPROFILE%\.claude"notepad "%USERPROFILE%\.claude\settings.json"

方式二：使用 PowerShell

mkdir -Force$HOME\.claudenotepad $HOME\.claude\settings.json

3.2 编辑配置文件

3.2.1 步骤

在打开的记事本中，将以下内容写入 settings.json，并将 YOUR_API_KEY 替换为你的实际 API Key：

{"env":{"ANTHROPIC_AUTH_TOKEN":"YOUR_API_KEY","ANTHROPIC_BASE_URL":"https://coding.dashscope.aliyuncs.com/apps/anthropic","ANTHROPIC_MODEL":"glm-5"}}

由于部分模型没有支持对图片的读取能力，因此我们需要增加一个有读取图片能力的模型：

{"env":{"ANTHROPIC_AUTH_TOKEN":"YOUR_API_KEY","ANTHROPIC_BASE_URL":"https://coding.dashscope.aliyuncs.com/apps/anthropic","ANTHROPIC_MODEL":"glm-5","ANTHROPIC_DEFAULT_HAIKU_MODEL":"qwen3.5-plus",}}

当你的settings.json存在ANTHROPIC_DEFAULT_HAIKU_MODEL字段的时候，请修改它的值为qwen3.5-plus，当不存在ANTHROPIC_DEFAULT_HAIKU_MODEL的时候，请粘贴"ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.5-plus".

🚨 特别注意：具体需要根据你的编码套餐来修改，如果你的套餐没有qwen3.5-plus，请使用MiniMax-M2.5

保存文件后，重新打开一个终端即可生效。

3.2.2 验证

打开新的claude,键入/model回车

上下键切换到haiku模型,并且回车即可成功切换

重复步骤，上下键切换回原来的模型名称即可切换到原来的模型

3.3 避免启动报错

编辑或新建 C:\Users\你的用户名\.claude.json 文件（注意是用户主目录下的 .claude.json，不是上面的 .claude 文件夹内的文件），添加以下内容：

使用 CMD 打开：

notepad "%USERPROFILE%\.claude.json"

文件内容：

{"hasCompletedOnboarding":true}

🚨 特别注意：hasCompletedOnboarding 必须作为顶层字段，不要嵌套在其他字段内。该步骤可避免启动时报错 Unable to connect to Anthropic services。

4. 启动 Claude Code

在 WSL 或 Git Bash 中执行：

# 进入你的项目或工作目录cd /d D:\your_project# 启动 Claude Codeclaude

启动后：

1. 1. 首次运行需要授权 Claude Code 执行文件操作

2. 2. 输入 /status 确认模型、Base URL、API Key 是否配置正确

3. 3. 开始对话即可使用

5. 切换模型

• 启动时指定模型：claude --model <模型名称>，例如 claude --model qwen3-coder-next

• 会话中切换模型：在对话框输入 /model <模型名称>，例如 /model qwen3-coder-next

6. 常见命令速览

更多命令与用法详情，请参考 Claude Code 官方文档。

三、如何给 Claude Code 添加 Skills？

1. 什么是 Skills？

Skill（技能）是一种可复用的指令包，本质上是一个 SKILL.md 文件，包含 YAML 元数据头和 Markdown 格式的详细指令。当 Claude Code检测到当前任务与某个 Skill 相关时，会自动加载该 Skill 的指令来增强自身能力。

Skills 可以实现的功能包括：

• 编码规范：统一团队的命名约定、文件结构、代码审查清单

• 工作流自动化：定义多步骤流程，如 "运行测试 → 代码检查 → 提交"

• 领域专业知识：给 Claude 注入特定技术栈、API 或框架的专业知识

• 自定义命令：创建 /deploy、/review-pr 等自定义斜杠命令

Skills 存放位置（Windows 下 ~ 等价于 C:\Users\你的用户名）：

• C:\Users\你的用户名\.claude\skills\：个人 Skills，在所有项目中生效

• .claude\skills\（项目目录下）：项目 Skills，仅在该项目中生效，可随代码提交到版本控制

2. 三种添加 Skills 的方法

完整的技能添加指引请参考：🔗 How to Add Skills to Claude Code (PolySkill 指引)

方法一：使用 Claude Code 内置插件浏览器

安装步骤

步骤 1：添加插件市场

1. 1. 在空文件夹中启动 Claude Code

2. 2. 在输入框中输入以下命令：

/plugin marketplace add anthropics/skills

注：anthropics/skills 只是其中1个插件市场，还有很多其他市场。

1. 3. 当看到以下提示时，表示Claude Code 插件市场已经添加成功：

> /plugin marketplace add anthropics/skills  ⎿  Successfully added marketplace: anthropic-agent-skills

步骤 2：安装插件

1. 1. 输入安装命令：

/plugin install

1. 2. 按 Tab 键切换到 Marketplaces

2. 3. 使用上下方向键选择 anthropic-agent-skills，然后按回车

3. 4. 继续按回车进入技能列表

4. 5. 使用空格键选中以下两个：

• document-skills

• example-skills

1. 6. 按 i 键确认安装

2. 7. 当看到以下提示时，表示安装成功：

> /plugin install  ⎿  ✓ Installed 2 plugins. Restart Claude Code to load new plugins.

步骤 3：重启与验证

1. 1. 重启 Claude Code

2. 2. 询问：你有哪些skill？

3. 3. 如果安装成功，你将看到类似以下的回答：

> 你有哪些skill？● 我可以查看我当前可用的技能列表。让我检查一下：● 根据我当前的环境，我有以下几类技能可用：  文档处理技能 (document-skills)  - algorithmic-art: 使用 p5.js 创建算法艺术  - brand-guidelines: 应用 Anthropic 品牌颜色和排版  - canvas-design: 创建视觉艺术设计  - doc-coauthoring: 协作文档编写流程指导  - docx: Word 文档处理（创建、编辑、分析）  - frontend-design: 前端界面设计  - internal-comms: 内部通信写作  - mcp-builder: MCP 服务器构建指南  - pdf: PDF 处理（提取、创建、合并、表单）  - pptx: PowerPoint 演示文稿处理  - skill-creator: 技能创建指南  - slack-gif-creator: Slack 优化的 GIF 创建  - theme-factory: 主题样式工具  - web-artifacts-builder: 复杂的 HTML 工件构建  - webapp-testing: Web 应用测试（Playwright）  - xlsx: Excel 电子表格处理  示例技能 (example-skills)  与 document-skills 相同的技能集，用于示例演示  其他工具  除了这些技能，我还可以使用：  - 文件操作工具: Read, Write, Edit, Glob, Grep  - 代码执行: Bash  - 网络工具: WebSearch, WebFetch  - 任务管理: TodoWrite, Task, TaskOutput  - LSP 操作: 代码智能功能  - 用户交互: AskUserQuestion  你想使用哪个技能来帮助你完成什么任务呢？

方法二：从文件系统手动安装

适合自定义或私有的 Skills。

步骤如下：

1. 1. 新建一个文件夹，命名为技能名称（例如 svn-msg）。

2. 2. 在该文件夹内存放一个 SKILL.md 文件，文件内容即为技能的具体定义。

3. 3. 将整个 svn-msg 文件夹移动到以下目录：C:\Users\你的用户名\.claude\skills

步骤 3：验证加载

启动 Claude Code，输入 / 后跟你的 Skill 名称。如果出现在自动补全列表中，说明已成功加载。