国内安装 Claude Code 并切换使用国内大模型 API：完整指南本文将手把手教你安装 Claude Code，了

🚀 阅读提示：本文将手把手教你安装 Claude Code，了解它的真实能力边界，并配置使用 DeepSeek、阿里百炼、智谱 GLM 等国内大模型 API，让你以更低的成本享受 AI 工程助手带来的效率革命。

引言

Claude Code 是 Anthropic 在 2025 年推出的革命性 AI 工程工具。与传统的代码补全工具不同，它能理解你的整个项目，执行复杂的多步骤任务，直接操作文件系统、运行命令行，甚至帮你修复系统配置、管理项目文档——它的能力远不止于写代码。

然而，国内用户面临两大难题：一是无法直接访问 Claude 官方服务，二是官方 API 价格昂贵。好消息是，国内多家大模型厂商已经支持 Anthropic API 兼容接口，让你可以用更低的价格、更稳定的网络使用 Claude Code。

本文将手把手教你完成安装配置，纠正网上流传的一些常见误区，并详细介绍如何使用国内大模型 API 替代官方服务。

一、Claude Code 究竟能做什么？

很多教程只把 Claude Code 介绍为"AI 编程助手"，这是严重的低估。准确地说，它是一个代理式（Agentic）AI 工程工具，能在你的本地环境中自主执行任务，覆盖软件工程的全生命周期。

1.1 核心能力全景

📁 文件与项目工程化管理

这是很多人没想到的核心能力。Claude Code 可以直接操作你的文件系统：

批量文件操作：跨目录创建、移动、重命名、删除文件
项目结构初始化：一句话搭建完整的项目脚手架，含目录结构、配置文件、.gitignore 等
文档工程化管理：扫描整个代码库，自动生成或更新 README.md、API 文档、变更日志（CHANGELOG）
批量重构：跨多个文件统一修改命名规范、替换废弃 API、调整代码风格

示例指令：帮我扫描所有 .py 文件，找出所有使用 requests 库的地方，统一替换为 httpx，并更新 requirements.txt

⚙️ 系统与软件配置修复

这是 Claude Code 最被低估的能力之一：

环境配置诊断：读取你的 ~/.bashrc、~/.zshrc、~/.ssh/config 等配置文件，找出冲突或错误
开发工具配置：配置 Nginx、Docker Compose、GitHub Actions CI/CD 流水线
依赖冲突解决：分析 package.json、requirements.txt、go.mod 中的版本冲突并给出解决方案
系统权限修复：诊断和修复文件权限、SSH Key 权限等常见问题
第三方 AI 工具配置：帮你配置 OpenClaw、Open WebUI、LM Studio 等 AI 客户端的大模型 API Key，包括找到正确的配置文件路径、写入 API 端点和密钥、验证连通性

示例指令（Nginx）：我的 Nginx 配置总是 502，帮我检查 nginx.conf 和上游服务配置，找出问题并修复

示例指令（OpenClaw）：帮我把 OpenClaw 的模型 API 切换到 DeepSeek，找到它的配置文件，写入我的 API Key 和正确的 base URL，并测试是否能正常调用

OpenClaw 的配置文件通常位于：

macOS：~/Library/Application Support/OpenClaw/config.json
Linux：~/.config/openclaw/config.json
Windows：%APPDATA%\OpenClaw\config.json

你只需要告诉 Claude Code 你的 API Key 和目标服务商，它会自动定位配置文件、填入正确的字段格式，并运行一个简单的测试请求确认配置生效。

💻 代码编写与重构

这是大家最熟悉的能力：

理解整个项目：读取代码库，理解项目结构和模块依赖
规划多步骤任务：你说"帮我重构这个模块"，它会分析、规划、执行
执行命令行操作：运行测试、安装依赖、执行构建脚本
持续对话：记住上下文，进行多轮交互调试

🔧 Git 与版本控制

分析 git diff，自动撰写规范的 commit message
帮你处理 merge conflict（分析冲突双方的意图并给出合并建议）
扫描提交历史，生成版本发布说明

📊 数据与文档处理

读取 CSV、JSON、Markdown 等格式，进行数据清洗和转换
批量处理文档：格式统一、内容摘要、翻译
生成技术规范文档、架构设计文档

1.2 能力上限与底层模型强相关

这一点非常重要，却是大多数教程没有交代清楚的：Claude Code 本身只是一个执行框架，它能完成多复杂的任务，取决于你接入的大模型有多强。

可以这样理解：Claude Code 是一个拥有双手的"执行者"，能够读文件、写文件、跑命令；而你接入的大模型，则是驱动这双手的"大脑"。大脑越强，它能规划的任务越复杂，出错后自我纠错的能力也越强。

**截止目前海外顶级模型（Claude 4.6 Sonnet/4.6 opus、GPT-5.3 等）**能做到：

拿到一个从未见过的大型项目，快速理清架构，制定合理的重构计划
修复复杂的系统配置问题（如 Kubernetes 集群网络、多服务 Docker Compose 依赖链）
调试多文件、多层级的 Bug，能在几十个文件中定位根因
配置 OpenClaw、Open WebUI 等工具时，遇到格式不对或字段缺失，能自己推断正确写法

**国内主流模型（DeepSeek、Qwen、GLM 等）**在日常任务上表现不错，但在以下场景能力明显弱于海外顶尖模型：

大型项目的全局理解和长程规划
涉及多个系统组件交叉的故障排查
配置文件格式不规范时的自主推断和容错
长对话中保持任务一致性（容易"忘记"之前的上下文约束）

实用建议：用国内模型处理明确、边界清晰的任务（写一个函数、改一段逻辑、更新一个配置项）完全够用，成本极低；遇到需要全局判断和系统级推理的复杂任务，换用海外模型效果会有显著提升。国内模型的能力正在快速追赶，差距在缩小，但目前仍然存在。我在一线的感受就是，差距大概半年左右，所以现在入手，半年后模型能力上来后，一切就刚好了。

1.3 与其他工具的核心区别

特性	Claude Code	GitHub Copilot	Cursor
工作方式	代理式（自主执行）	补全式（实时建议）	混合式
项目理解	✅ 完整代码库	❌ 有限上下文	✅ 部分
命令执行	✅ 直接执行 Shell	❌ 不支持	❌ 不支持
文件管理	✅ 跨文件操作	❌ 不支持	⚠️ 有限
配置修复	✅ 系统级配置	❌ 不支持	❌ 不支持
模型选择	✅ 可替换 API	❌ 固定	❌ 固定

1.4 适用人群

Claude Code 是为在终端中工作的开发者和技术人员设计的工具，适用场景包括：

后端/全栈开发：代码重构、API 开发、数据库迁移
DevOps/运维：服务器配置、CI/CD 流水线搭建、故障排查
数据工程师：数据处理脚本、ETL 管道
技术写作：代码文档、技术规范、README 生成

二、安装 Claude Code

2.1 环境要求

要求	说明
操作系统	macOS 10.15+、Ubuntu 20.04+、Windows 10/11
Windows 额外要求	Git for Windows（原生安装）
内存	至少 4GB RAM（推荐 8GB+）
网络	需要互联网连接

2.2 安装方式

Anthropic 已将 npm 安装方式标注为废弃（Deprecated），强烈推荐使用原生客户端安装，无需提前安装 Node.js，且支持后台自动更新。

方式一：原生客户端安装（推荐）

macOS / Linux：

curl -fsSL https://claude.ai/install.sh | bash

Homebrew（macOS）：

brew install --cask claude-code

⚠️ Homebrew 版本不会自动更新，需手动运行 brew upgrade claude-code。

Windows PowerShell（原生安装）：

# 方式一：官方安装脚本
irm https://claude.ai/install.ps1 | iex

Windows CMD（原生安装）:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows WinGet：

winget install Anthropic.ClaudeCode

⚠️ WinGet 版本同样不会自动更新，需手动运行 winget upgrade Anthropic.ClaudeCode。

原生安装包会自动将 Claude Code 安装到 ~/.local/bin，并在后台自动更新（Homebrew/WinGet 除外）。

方式二：npm 安装（已废弃，不推荐）

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

官方已标注此方式为废弃，仅在有特殊兼容需求时使用，需提前安装 Node.js 18+。请勿使用 sudo npm install -g。

图形界面客户端（Desktop App）

如果你不习惯命令行，Anthropic 还提供了桌面端图形界面应用，可在 macOS 和 Windows 上使用，功能与命令行版本一致。

2.3 验证安装

claude --version
# 显示版本号即安装成功，例如：claude 1.x.x

三、获取国内大模型 API

国内有多家大模型厂商支持 Anthropic API 兼容接口，以下是主流选择：

3.1 服务商对比

服务商	API 端点	推荐模型	价格优势	推荐指数
DeepSeek	`https://api.deepseek.com/anthropic`	deepseek-chat	综合性价比最高	⭐⭐⭐⭐⭐
阿里百炼	`https://coding.dashscope.aliyuncs.com/apps/anthropic`	qwen3-coder-plus	稳定可靠，代码能力强	⭐⭐⭐⭐
智谱 GLM	`https://open.bigmodel.cn/api/anthropic`	glm-5	学术背景，中文理解好	⭐⭐⭐⭐
MiniMax	`https://api.minimax.io/anthropic`	MiniMax-M2.5	多模态支持	⭐⭐⭐

💡 选型建议：日常代码任务优先选 DeepSeek（成本最低）；涉及复杂工程化任务（如大型重构、配置管理）可尝试阿里百炼的 qwen3-coder-plus，其代码能力专项优化较为突出。

3.2 获取 API Key

DeepSeek

访问 platform.deepseek.com
注册并登录
进入「API Keys」页面，点击「创建 API Key」
复制生成的 Key（以 sk- 开头）

阿里百炼

访问 bailian.console.aliyun.com
使用阿里云账号登录
开通「百炼」服务，获取 API Key

智谱 GLM

访问 open.bigmodel.cn
注册并完成实名认证
进入控制台创建 API Key

🔒 安全提示：API Key 是私密凭证，请勿分享给他人或提交到公开代码仓库（可用 .env 文件配合 .gitignore 管理）。如果不小心泄露，请立即在对应平台重新生成并吊销旧 Key。

四、配置 Claude Code 使用国内 API

💡 嫌麻烦？ 如果不想手动编辑配置文件，可以直接跳到第五部分，通过 cc-switch 图形界面可视化添加和切换大模型 API，无需接触任何 JSON 配置。

4.1 配置方式概述

方式	优点	缺点
环境变量	简单快速，适合临时测试	重启终端后失效
配置文件	持久化，推荐长期使用	需要手动编辑文件

4.2 配置文件方式（推荐）

配置文件路径因系统而异：

系统	配置文件路径
macOS / Linux	`~/.claude/settings.json`
Windows	`%USERPROFILE%\.claude\settings.json`

macOS / Linux：

# 创建配置目录（如不存在）
mkdir -p ~/.claude

# 编辑配置文件（任选其一）
vim ~/.claude/settings.json
nano ~/.claude/settings.json
code ~/.claude/settings.json   # VS Code

Windows（PowerShell）：

# 创建配置目录（如不存在）
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude"

# 用记事本编辑（或替换为你惯用的编辑器）
notepad "$env:USERPROFILE\.claude\settings.json"

# 用 VS Code 编辑
code "$env:USERPROFILE\.claude\settings.json"

配置文件结构：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_api_key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

4.3 各服务商完整配置示例

DeepSeek 配置

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

阿里百炼配置

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_bailian_api_key",
    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
    "ANTHROPIC_MODEL": "qwen3-coder-plus",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

智谱 GLM 配置

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_zhipu_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_MODEL": "glm-4",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

4.4 环境变量配置（临时使用）

macOS / Linux（bash / zsh）：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=your_deepseek_api_key
export ANTHROPIC_MODEL=deepseek-chat
export API_TIMEOUT_MS=600000
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

如需永久生效，将上述内容写入 ~/.bashrc（bash）或 ~/.zshrc（zsh），然后执行 source ~/.bashrc。

Windows（PowerShell，当前会话有效）：

$env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "your_deepseek_api_key"
$env:ANTHROPIC_MODEL = "deepseek-chat"
$env:API_TIMEOUT_MS = "600000"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

如需永久生效，在 Windows 上通过「系统属性 → 高级 → 环境变量」添加用户变量，或在 PowerShell 中执行：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your_key", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.deepseek.com/anthropic", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "deepseek-chat", "User")

💡 推荐优先使用配置文件方式（4.2节），环境变量适合临时切换或测试用。

4.5 核心参数说明

参数	说明
`ANTHROPIC_BASE_URL`	替换 API 请求的目标端点，指向国内服务商
`ANTHROPIC_AUTH_TOKEN`	你的 API Key，替代官方账号认证
`ANTHROPIC_MODEL`	指定使用的模型名称
`API_TIMEOUT_MS`	请求超时时间（毫秒），复杂任务建议设为 600000（10 分钟）
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	禁用向 Anthropic 官方发送遥测等非必要流量，设为 `1` 开启

4.6 验证配置

配置完成后，在任意项目目录启动：

cd your-project
claude

进入交互模式后，输入 /status 查看当前配置：

> /status
Model: deepseek-chat
API: https://api.deepseek.com/anthropic
Status: Connected ✅

五、使用 cc-switch 工具管理多个 API 供应商

5.1 什么是 cc-switch？

cc-switch 是一个开源的图形化工具，用于管理 Claude Code 的多个 API 供应商配置，支持一键切换，无需手动编辑 JSON 文件。

5.2 安装与使用

从 GitHub 下载对应平台的安装包：

下载地址：github.com/farion1231/…

支持平台：Windows (.exe)、macOS (.dmg)、Linux (.AppImage)

基本操作流程：

打开 cc-switch，点击「添加供应商」

选择供应商类型，填入 API Key，保存配置

在供应商列表中选择目标模型，点击「启用」

重启 Claude Code 即可生效

去到任意你想要打开claude的目录后，右键打开PowerShell终端，或其他系统的终端，输入claude后回车，即可在当前目录下打开claude 的命令行窗口，后续就直接输入内容和它对话即可。

5.3 cc-switch 适用场景

功能	说明
多供应商管理	同时维护 DeepSeek、百炼、GLM 等多套配置
按任务切换	简单任务用低成本模型，复杂任务切换高能力模型
配置备份	自动保存配置，换机迁移方便
跨平台	Windows / macOS / Linux 全支持

六、首次启动与基本使用

完成安装和 API 配置后，你已经万事俱备。这一节介绍如何真正把 Claude Code 跑起来。

6.1 启动方式

打开终端，进入你想要操作的项目目录，输入 claude 启动：

cd ~/your-project   # 先进入你的项目目录
claude              # 启动 Claude Code

⚠️ 建议在项目根目录下启动，而不是在 ~ 家目录（就是不要在一个很大的目录下，你要具体到你要操作项目文件的目录）。Claude Code 启动时会自动扫描当前目录，在哪里启动它就能看到哪个项目。从家目录启动会让它扫描整个用户目录，既慢又乱。

6.2 首次启动流程

账号认证（使用官方服务时）

如果使用 Anthropic 官方 API，首次运行会自动打开浏览器，要求登录 claude.ai 账号并授权。完成后终端自动继续。

如果已按本文第四或第五部分配置了国内 API，则跳过这一步，直接进入对话界面。

进入交互界面

启动成功后，你会看到：

╭─────────────────────────────────────────╮
│ ✻  Welcome to Claude Code!              │
│                                         │
│    /help for help, /status for status   │
╰─────────────────────────────────────────╯

> _

光标停在 > 后面，直接用中文描述你想做的事就行：

6.3 常用命令速查

命令	作用
`/status`	查看当前使用的模型和 API 连接状态
`/help`	查看所有可用命令
`/clear`	清空当前对话上下文，开始一个全新任务
`/exit` 或 `Ctrl+C`	退出 Claude Code

配置完国内 API 后，第一件事建议先跑一下 /status，确认模型名称和 API 端点都是你预期的那个，再开始干活。

七、实用场景示例

以下是一些 Claude Code 在实际工程中的典型用法，帮你理解它的真实能力边界。

场景一：项目文档自动化

你：扫描这个项目所有的公开函数和类，生成完整的 API 参考文档，
    存到 docs/api-reference.md，格式参考现有的 docs/style-guide.md

Claude Code 会读取代码库 → 分析函数签名和注释 → 按模板生成文档 → 写入指定路径，全程自动执行。

场景二：批量配置修复

你：我的 Docker Compose 起不来，帮我检查 docker-compose.yml、
    相关的 Dockerfile，以及 nginx/conf.d/ 下的配置，找出问题并修复

Claude Code 会读取所有相关配置文件 → 交叉分析端口、网络、依赖顺序等问题 → 直接修改配置文件 → 建议你重新 docker-compose up 验证。

场景三：跨文件重构

你：把项目里所有用 callback 风格写的异步函数，统一重构成 async/await，
    同时更新对应的单元测试

Claude Code 会定位所有相关文件 → 逐一重构 → 更新测试 → 运行 npm test 验证结果，出错则自动修复再重试。

场景四：Git 工作流辅助

你：帮我整理一下最近 20 个 commit，写一份 v2.3.0 的 Release Notes，
    格式参考 GitHub Release 惯例，中英文各一份

八、技能系统深度解析

Claude Code 有两套相互独立、各有侧重的"记忆与能力扩展"机制：CLAUDE.md（项目记忆文件）和 Skills 技能包（可安装的专业能力插件）。很多教程把这两者混为一谈，本章分别讲清楚。

8.1 CLAUDE.md：给 Claude Code 的工作手册

CLAUDE.md 是一个普通 Markdown 文件，Claude Code 每次启动时自动读取，作为持久上下文加载。它解决的是"记忆"问题——AI 对话天生无记忆，有了 CLAUDE.md，项目背景、编码规范、禁止事项只需写一次，永久生效。

文件层级与加载规则

CLAUDE.md 支持三个层级，从全局到局部叠加生效：

文件路径	作用范围	适合写什么
`~/.claude/CLAUDE.md` （Win：`%USERPROFILE%\.claude\CLAUDE.md`）	全局（所有项目）	个人偏好、通用工作习惯
`{项目根目录}/CLAUDE.md`	当前项目	项目架构、编码规范、常用命令
`{子目录}/CLAUDE.md`	当前子目录及其子目录	模块级别的特殊说明

典型内容示例

全局 CLAUDE.md（~/.claude/CLAUDE.md）放通用偏好，所有项目都受益：

# 我的全局工作偏好

## 沟通风格
- 用中文回答我的问题
- 解释方案时先说结论，再说原因
- 代码改动超过 20 行时，先列出改动计划再执行

## 安全习惯
- 删除文件前必须先确认
- 修改生产配置文件前先备份

项目级 CLAUDE.md 放项目专属信息：

# 项目概览
这是一个 FastAPI + PostgreSQL 的 SaaS 后端。
- 禁止直接写裸 SQL，统一用 SQLAlchemy 2.0
- 所有新函数必须有类型注解
- 禁止用 print() 调试，统一用 logger.debug()

# 常用命令
- 启动：uvicorn app.main:app --reload
- 测试：pytest tests/ -v --cov=app
- 迁移：alembic upgrade head

快速生成 CLAUDE.md

不知道怎么写？让 Claude Code 扫描项目自动生成：

> 扫描这个项目的结构和代码风格，
  帮我生成一份 CLAUDE.md，
  包含项目概览、目录说明、编码规范和常用命令

8.2 Skills 技能包：可安装的专业能力插件

Skills 是一套完全不同于 CLAUDE.md 的机制。它解决的是"能力"问题——某些专业任务（如制作 PPT、处理 PDF、生成 Word 文档）需要复杂的多步骤操作流程和大量专业知识，Skills 把这些"最佳实践"打包成可安装的插件，让 Claude Code 在处理对应任务时自动调用。

一个 Skill 的本质是一个包含 SKILL.md 文件的目录（或打包后的 .skill 文件），里面写着"遇到某类任务时应该怎么做"的详细操作手册，包括调用哪些工具、使用什么脚本、输出什么格式。

技能的触发原理

理解触发机制，才能更好地使用技能。

每个 Skill 在系统层面都有一段触发描述（description），Claude Code 启动时会把所有已安装技能的名称和描述加载到上下文中。当你输入一条指令，Claude Code 会自动将其与所有技能的触发描述进行匹配——如果匹配到某个技能，Claude Code 会先读取该技能的完整 SKILL.md，再按照其中的操作手册来完成任务；如果没有匹配，则按默认方式处理。

用户输入
    ↓
与所有已安装技能的触发描述进行匹配
    ↓ 匹配到
读取对应 SKILL.md 的完整内容（操作手册）
    ↓
按照手册规定的流程执行任务（调用脚本、工具等）
    ↓
输出符合规范的高质量结果

有一点值得注意：简单的单步请求不容易触发技能，因为 Claude Code 可以直接处理。例如"读一下这个 PDF"不会触发 PDF 技能；但"从这 5 份 PDF 合同中提取所有日期字段，汇总成 Excel 表格"这类复杂的多步骤任务，会可靠地触发对应技能。触发描述被刻意写得"积极主动"——遇到相关场景就应该触发。当然如果你的指令明确指示使用xx技能做某个公众的时候，系统也会自动去加载xx技能干活。

8.3 Anthropic 官方提供的技能

Anthropic 官方维护了一套公开技能库，以下是核心技能：

📄 文档处理三件套

docx（Word 文档技能）

触发场景：用户提到"Word 文档"、".docx"，或要求创建带格式的专业文档（含目录、页眉页脚、表格等）。

这个技能内置了完整的 Word 文档生成逻辑，包括样式定义、表格布局、图片嵌入、目录生成等，输出的 .docx 文件可直接用 Word 或 WPS 打开编辑。

> 把这份技术规范写成一份 Word 文档，
  要有封面、目录、章节标题和页码

pptx（PowerPoint 技能）

触发场景：用户要求制作 PPT、演示文稿、幻灯片、pitch deck，或提到 .pptx 文件。

这个技能掌握了 PowerPoint 的布局逻辑、母版配色、图表嵌入规范，生成的演示文稿质量远高于直接让 Claude 随意生成。

> 帮我做一份 10 页的产品发布 PPT，
  主题是我们的 AI 写作工具，
  包含市场分析、核心功能、竞争对手和路线图

pdf（PDF 处理技能）

触发场景：需要合并/拆分 PDF、提取 PDF 内容、填写 PDF 表单、给 PDF 加水印，或将内容输出为 PDF。

> 把这 3 份报告 PDF 合并成一份，
  并在每页右下角加上页码

📊 数据处理技能

xlsx（Excel 技能）

触发场景：涉及 .xlsx、.csv 等电子表格文件的创建、读取、编辑，或从其他数据源生成结构化表格。

> 扫描项目里所有 JSON 配置文件，
  把其中的数据库连接信息汇总成 Excel 表，
  每列对应一个配置项

🎨 设计与前端技能

frontend-design（前端设计技能）

触发场景：创建 Web 组件、页面、Dashboard、HTML/CSS 布局，要求高设计质量的界面。

这个技能避免了 AI 生成界面"千篇一律"的问题，能产出更有设计感、更接近专业水准的 UI 代码。

8.4 官方示例技能库

除了上述开箱即用的公开技能，Anthropic 还提供了一套示例技能（Examples），这些技能展示了更高级的用法，也可以直接安装使用：

技能名	用途
skill-creator	创建新技能 / 优化已有技能的触发描述 / 运行技能评估
mcp-builder	构建 MCP（Model Context Protocol）服务器
web-artifacts-builder	生成高质量的 Web 交互式组件
algorithmic-art	生成算法艺术图形
canvas-design	Canvas 图形设计
doc-coauthoring	文档协同写作辅助
slack-gif-creator	生成 Slack 用的 GIF 动图

其中 skill-creator 最值得关注——它让你能够：

从一段对话记录中提炼出可复用的技能
编写、测试、迭代 SKILL.md 文件
自动优化技能的触发描述（让技能被更准确地识别和调用）
将技能打包成 .skill 文件分享给他人

> 我刚才和你配合把那份财务报告转成 Excel 的整个流程，
  帮我把这个流程打包成一个可复用的技能，
  下次我只需要说"处理财务报告"就能自动触发

8.5 安装和使用技能

如何安装技能

Anthropic 官方技能（docx、pptx、pdf、xlsx 等）在 Claude Code 的标准安装中已经内置，无需额外安装，直接使用即可。

如果你从其他渠道获得了 .skill 文件（自制的或他人分享的），安装方法是将其放入技能目录：

系统	用户技能目录
macOS / Linux	`~/.claude/skills/`
Windows	`%USERPROFILE%\.claude\skills\`

如何使用技能

技能的使用方式非常简单——直接用自然语言描述任务即可，不需要主动"调用"某个技能。Claude Code 会自动根据你的描述匹配合适的技能并执行。

几个典型的触发示例：

# 触发 pptx 技能
> 帮我做一份介绍 Claude Code 的 PPT，8-10 页

# 触发 docx 技能
> 把这段需求描述写成一份 Word 格式的产品规格书

# 触发 pdf 技能
> 把这 4 个 PDF 合并，然后给每页加水印"内部文件"

# 触发 xlsx 技能
> 把这份 CSV 数据整理成 Excel 表格，加上汇总行和图表

# 触发 skill-creator 技能
> 帮我把刚才这个工作流程做成一个可复用的技能

如何自制技能

如果你有一套反复使用的工作流程，可以把它做成技能。最简单的方式是让 skill-creator 帮你完成：

> 我经常需要：扫描项目 API 文档 → 提取所有接口签名 → 生成 Postman 
  测试集合导出文件。帮我把这个流程做成一个可复用的技能，
  让我以后说"生成 Postman 集合"就能自动触发

如果你想手动编写，一个最基础的技能只需要一个文件：

~/.claude/skills/my-skill/
└── SKILL.md

SKILL.md 的最小结构：

---
name: my-skill
description: 当用户需要处理XXX任务时使用此技能。触发关键词包括：XXX、XXX。
---

# 技能说明

## 执行步骤
1. 第一步：...
2. 第二步：...
3. 第三步：...

## 输出规范
- 输出文件格式：...
- 命名规则：...

description 字段是技能触发的核心——写得越具体、越贴近用户的实际表达，技能被正确触发的概率就越高。官方建议这段描述要略带"主动性"，明确列出触发时机，而不只是描述技能做什么。

九、常见问题与解决方案

9.1 安装问题

npm install 提示权限错误

npm cache clean --force
# 推荐改用原生安装方式，彻底避免 npm 权限问题
curl -fsSL https://claude.ai/install.sh | bash

Windows 安装后 claude 命令无法识别

这通常是 PATH 未正确添加。在 PowerShell 中执行：

$env:PATH += ";$env:USERPROFILE\.local\bin"
# 或重新打开一个新的 PowerShell 窗口

若问题持续，检查 Git for Windows 是否正确安装（官网下载：git-scm.com）。

9.2 API 调用问题

401 Unauthorized

检查 API Key 是否正确填写（注意不要有多余空格）：

macOS / Linux：

echo $ANTHROPIC_AUTH_TOKEN
cat ~/.claude/settings.json

Windows（PowerShell）：

echo $env:ANTHROPIC_AUTH_TOKEN
type "$env:USERPROFILE\.claude\settings.json"

请求超时

增大超时时间，复杂工程任务容易耗时超过默认值：

"API_TIMEOUT_MS": "600000"

模型名称不匹配导致报错

各服务商的模型名称格式不同，请以各自官方文档为准，常见错误是把 deepseek-chat 写成 deepseek-v2 等非正式名称。

9.3 模型切换不生效

配置修改后，需要完全退出 Claude Code（不是最小化），再重新打开终端并启动：

macOS / Linux：

pkill claude
claude

Windows： 在任务管理器（Ctrl+Shift+Esc）中找到 claude 进程，右键结束任务，再重新打开终端运行 claude。

9.4 性能与成本优化建议

优化项	配置方法
增大超时	`"API_TIMEOUT_MS": "600000"`
缩小上下文范围	在项目根目录添加 `.claudeignore`，排除 `node_modules`、`dist` 等无关目录
禁用非必要流量	`"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"`
按任务选模型	简单问答用低成本模型，重型任务切换高能力模型

.claudeignore 示例：

node_modules/
dist/
build/
.git/
*.log
*.lock

国内安装 Claude Code 并切换使用国内大模型 API：完整指南

引言

一、Claude Code 究竟能做什么？

1.1 核心能力全景

📁 文件与项目工程化管理

⚙️ 系统与软件配置修复

💻 代码编写与重构

🔧 Git 与版本控制

📊 数据与文档处理

1.2 能力上限与底层模型强相关

1.3 与其他工具的核心区别

1.4 适用人群

二、安装 Claude Code

2.1 环境要求

2.2 安装方式

方式一：原生客户端安装（推荐）

方式二：npm 安装（已废弃，不推荐）

图形界面客户端（Desktop App）

2.3 验证安装

三、获取国内大模型 API

3.1 服务商对比

3.2 获取 API Key

DeepSeek

阿里百炼

智谱 GLM

四、配置 Claude Code 使用国内 API

4.1 配置方式概述

4.2 配置文件方式（推荐）

4.3 各服务商完整配置示例

DeepSeek 配置

阿里百炼配置

智谱 GLM 配置

4.4 环境变量配置（临时使用）

4.5 核心参数说明

4.6 验证配置

五、使用 cc-switch 工具管理多个 API 供应商

5.1 什么是 cc-switch？

5.2 安装与使用

5.3 cc-switch 适用场景

六、首次启动与基本使用

6.1 启动方式

6.2 首次启动流程

6.3 常用命令速查

七、实用场景示例

场景一：项目文档自动化

场景二：批量配置修复

场景三：跨文件重构

场景四：Git 工作流辅助

八、技能系统深度解析

8.1 CLAUDE.md：给 Claude Code 的工作手册

文件层级与加载规则

典型内容示例

快速生成 CLAUDE.md

8.2 Skills 技能包：可安装的专业能力插件

技能的触发原理

8.3 Anthropic 官方提供的技能

📄 文档处理三件套

📊 数据处理技能

🎨 设计与前端技能

8.4 官方示例技能库

8.5 安装和使用技能

如何安装技能

如何使用技能

如何自制技能

九、常见问题与解决方案

9.1 安装问题

9.2 API 调用问题

9.3 模型切换不生效

9.4 性能与成本优化建议

参考资料