Claude Code 实战指南：多端部署、模型接入与 Skills 配置全解析

作为天天跟终端打交道的人，我第一次接触 Claude Code 的时候其实没太当回事，以为又是一个套壳的 CLI 工具。真正让我改变看法的是有一天我让它直接读了一个遗留项目的上千行代码，然后定位了一个我查了快两个小时都没找到的死锁问题。从那一刻起，我就知道这东西不是玩票的。这篇笔记是我从下载安装到日常重度使用攒下来的完整记录，涵盖了多端部署、第三方模型接入、skills 配置，还有一堆坑的解决办法，希望能帮你少走点弯路。

1. Claude Code 是什么，它到底解决了什么问题

Claude Code 是 Anthropic 推出的一个终端编程助手，简单说就是你在命令行里跑一个命令，它会启动一个 AI 对话环境，能读你当前项目的文件、搜索代码、执行命令、修改代码、提交 git，甚至能自己跑测试来确认改动是不是有效。它本质上是一个 Agent 型的编程工具，不是那种你在网页上问一句它答一句的聊天机器人。

1.1 它和 Cursor、Copilot 这类工具的区别

很多人会问，我有 Cursor 了，为什么还要用 Claude Code？最直观的区别是使用场景。Cursor 是编辑器插件形态，你得先打开 IDE，然后选中代码再唤起 AI，骨子里还是一个"人在回路里"的模式。而 Claude Code 是跑在终端里的，你可以在 SSH 远程服务器上、在 Docker 容器里、甚至在完全没有图形界面的 Linux 环境里直接用，所见即所得地操作整个文件系统。

它的工作模式也更激进。Claude Code 被设计成可以自主完成一系列任务：先读文件了解结构，再定位问题，改完代码后帮你跑测试验证。你在终端里只负责下达指令和监督结果，中间的细节它自己推进。这种"放权"程度是 Cursor 给不了的。

另外一点很重要的是上下文窗口。Claude Code 对应的模型支持比较大的上下文，可以一次性塞入大量代码文件。实测下来，让它分析一个中型项目（几百个文件）不是问题，它会按需读取文件内容，而不是全量灌入。这对老项目、大型代码库来说特别实用。

1.2 核心能力一览

我用了几个月，Claude Code 帮我解决最多的事情大概有四类：

• 代码理解与问答：直接问"这个模块的消息路由是怎么走的"，它会打开相关源文件，把调用链理清楚，给出带文件行号的回答。
• 功能开发与重构：给它一个需求描述，它会自动创建文件、实现逻辑、补充注释，效率比手写高不少。
• Bug 排查：把报错信息丢给它，它能顺着代码逻辑找原因，甚至自己写测试复现问题。
• 日常运维操作：比如"把所有接口的超时时间统一改成 5 秒""批量重命名这些函数"，都是它擅长的活。

这些能力组合起来以后，终端就不再只是敲命令的地方了，更像是一个可以随时使唤的高级助理。

2. 安装：从零开始的完整方案

安装这块是很多人卡住的第一关，实际上坑不少。我下面按平台和方式拆开讲，覆盖 CLI、桌面版、VS Code 插件，以及 Windows 和 Ubuntu 两个主流系统。

2.1 Windows 环境下的安装

Claude Code 官方很早就支持 Windows，但是很多人会忽略一个前置条件：它依赖 Git Bash 或 PowerShell 环境。我自己最推荐的方式是走 npm 安装。

首先确保你本机已经装好了 Node.js 18 以上版本，然后打开管理员权限的终端，执行：

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

安装完成后验证一下版本：

claude --version

如果这一步报错找不到命令，大概率是 npm 全局目录没有加到 PATH 里。可以执行 npm config get prefix 拿到全局目录，然后手动把它加到系统环境变量里去。

在 Windows 下还有一个细节：Claude Code 默认会把配置放到用户主目录下，路径是 C:\Users\你的用户名\.claude\ 。这个目录里保存了 settings.json、历史会话等文件，后面接第三方模型、配置 skills 都会用到这个目录。

2.2 Ubuntu / Linux 服务器上的安装

Linux 下的安装和 Windows 大同小异，还是 npm 那套，只是有几个系统级的依赖需要确认。我之前在阿里云的一台 Ubuntu 22.04 上装的时候，卡在了一个很隐蔽的地方。

先按顺序执行：

sudo apt update
sudo apt install -y git curl nodejs npm
npm install -g @anthropic-ai/claude-code

如果你的 Node 版本低于 18，建议先用 nvm 装一个新版 Node，再回来装 Claude Code。直接用系统源里的 node 很可能是旧的。

装完后在项目目录里执行 claude 就能进入交互界面。如果提示缺什么系统库，多半是需要安装 build-essential 或者 libssl-dev ，按提示补上就行。

2.3 桌面版和 VS Code 插件的安装

桌面版和 VS Code 插件属于"增强体验"路线，功能主体跟 CLI 一致，但交互更友好。

Claude Code 桌面版（Claude Code Desktop）适合不太习惯终端操作的人，安装包可以直接从官方渠道下载，装好后登录就能用，本质上还是包了一个终端界面，但文件目录可视化程度更高。

VS Code 插件则适合已经重度使用 VS Code 的人。直接在扩展市场搜索 "Claude Code for VS Code" 安装即可。装完之后侧边栏会多一个面板，可以直接在编辑器里查看 Claude Code 的输出和文件改动。实话说，我在本地开发时最常用的就是这个形态 —— 左边是代码，右边是 AI 的对话和 diff 视图。

版本方面，我之前用的 claude code for vs code v2.1.245 表现已经很稳。插件版本迭代很快，遇到行为异常先无脑更新到最新版本，绝大多数问题都能解决。

2.4 卸载干净的正确姿势

有些朋友装了之后想卸载，结果发现删不干净，再装别的版本时会出各种奇怪问题。正确的卸载流程分三步走：

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

然后手动删除用户目录下的 .claude 文件夹，以及可能存在的 .claude.json 文件。这一步很多人会漏掉，导致残留配置影响新装版本。

如果是 VS Code 插件，还要在扩展管理里把插件禁用并卸载，再清理 workspace 下的相关配置。走完整套流程之后，重新安装就不会再遇到配置冲突了。

3. 配置第三方模型：用 DeepSeek、智谱等替代默认模型

Claude Code 默认是走 Anthropic 官方 API 的，但这意味着你需要海外网络环境和 API key，门槛不低。好在 Claude Code 提供了 Anthropic 兼容的 API 配置入口，我们可以把请求转发到其他支持 Anthropic 格式的模型服务商，比如 DeepSeek、智谱（GLM）等。这也是目前中文社区里特别主流的一种玩法。

3.1 通过环境变量配置 API 地址和密钥

Claude Code 读取配置的优先级里，环境变量是最高的一层。如果你想把默认请求转到第三方模型，在启动前设置这几个变量就行：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="你的DeepSeek_API_Key"
export ANTHROPIC_MODEL="deepseek-chat"

ANTHROPIC_BASE_URL 是核心，它告诉 Claude Code 把请求发到哪个地址； ANTHROPIC_AUTH_TOKEN 是密钥； ANTHROPIC_MODEL 指定用哪个模型。

每次启动前都手动 export 一遍比较麻烦，更推荐写进 shell 配置文件。Windows 用户可以在系统环境变量里加，Linux/macOS 用户写在 ~/.bashrc 或 ~/.zshrc 里。

3.2 用 settings.json 配置文件实现持久化

环境变量用起来直接，但配置分散在多个地方以后会管理混乱。更优雅的方案是在 .claude/settings.json 里写模型配置。文件位置在：

• Windows： C:\Users\你的用户名\.claude\settings.json
• Linux/macOS： ~/.claude/settings.json

内容大概是：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的key",
    "ANTHROPIC_MODEL": "deepseek-chat"
  }
}

改完保存后重启 Claude Code，配置就生效了。

这里要提醒一个很多人踩过的坑：有段时间热传的模型名称是 deepseek-v4-pro 和 deepseek-v4-flash ，实际调用时很多人会报错，提示 "deepseek-v4-pro" is not a model this version of claude code recognizes 。出现这个报错，不是说模型不存在，而是 Claude Code 内置的模型列表里没有这个名字，它不认识。解决办法很简单：把 ANTHROPIC_MODEL 改成官方文档里提供的模型标识，比如 deepseek-chat 或 deepseek-reasoner ，不要让 Claude Code 去"认"一个它列表里没有的模型名。

3.3 接入智谱 GLM 的配置方法

智谱的接入逻辑和 DeepSeek 相同，区别只在于 ANTHROPIC_BASE_URL 和模型名。我实测的参数如下：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的智谱API_Key",
    "ANTHROPIC_MODEL": "glm-4-plus"
  }
}

智谱对 Anthropic 兼容层做得还不错，基础的代码阅读、生成、修改都能跑通。如果你既想用 DeepSeek 又想用智谱，可以在不同的项目目录下分别写 settings.json，让不同项目走不同的模型服务。

3.4 使用 CC Switch 做多配置切换

管理多个模型服务商的 key 和地址时，手动改 settings.json 太痛苦了。这时候可以用 CC Switch 这个工具。它本质上是一个配置管理器，可以保存多套 Claude Code 配置，切换时一键生效，不需要手动改 env 或 settings.json。

我在本地的使用频率很高，比如平时用 DeepSeek 省成本，跑大任务时切回官方模型，两个配置在 CC Switch 里来回切，基本是无感的。

CC Switch 是图形界面工具，下载后选中配置点击激活就行。本质上它做的事情就是帮你改写 .claude/settings.json ，但省掉了手动编辑的麻烦，也降低了改错格式的风险。

3.5 桌面版免登录配置

桌面版默认是强制登录账号后才可以使用，但如果你愿意折腾一下，桌面版也预留了外部配置入口。在桌面版对应的配置目录下新建 settings.json ，把环境变量配置写进去，原理和 CLI 版一样。我试下来，它读的还是同一个 .claude 目录，所以理论上你 CLI 配好了，桌面版也会继承。

不过提醒一句，桌面版版本迭代快，不同版本读配置的路径可能有一点差异。如果设置了不生效，先确认是不是读到了别的目录。

4. 核心用法与 skills 配置

配置通了之后，最值得研究的就是怎么让 Claude Code 干活更顺手。我强烈建议你系统学习一下 skills 的玩法，这是 Claude Code 真正拉开与其他工具差距的地方。

4.1 基础用法：对话、查询和文件操作

进入项目目录后执行 claude ，就进入了交互模式。在最基础的场景里，你可以直接提问，比如：

这个项目里用户登录的流程是怎么走的？请列出相关文件并说明关键逻辑。

它会自动定位相关文件，读完以后给你一份有条理的解答，并标注文件路径。对我这种维护过多个老项目的人来说，这一步就能节省大量翻代码的时间。

执行命令也是基本操作。你可以在对话里说"帮我全局搜索没有用的 imports"，它会自动执行 grep 或类似命令，然后把结果汇总给你，而不是光给你一句命令行让你自己去跑。

修改文件的时候，它会展示 wdiff 形式的改动预览，你确认后才会真正写入文件。默认情况下它会比较谨慎，不会在你没确认的情况下大规模改代码。

4.2 什么是 skills，怎么配置一个人设化的技能

Skills 是 Claude Code 的一个高级玩法，可以理解为给 Claude Code 预置一套"行为准则 + 工作流模板"。你可以告诉它在特定场景下应该按什么步骤做事，它就会遵循这套步骤来执行。

举个实际例子：我想让 Claude Code 帮我写前端代码时保持特定风格，比如 CSS 类名总是用 BEM 命名法，组件统一用函数式写法，注释用中文。那我可以在 .claude/skills/ 目录下新建一个文件夹，然后在里面放一个 SKILL.md 文件，内容大致如下：

---
name: frontend-style
description: 遵循本项目的前端代码规范
---

# 前端代码风格指南

1. 组件一律使用函数式组件，禁止使用 class 组件
2. CSS 命名统一使用 BEM 风格
3. 注释和提交信息使用中文
4. 组件文件命名使用 PascalCase
5. 所有 props 需要声明类型和默认值

写完保存后会发现在对话中，你提到前端相关任务时，Claude Code 会主动参考这个 skill 来调整输出。它能真正做到因地制宜，而不是一套模板打天下。

更复杂一点的用法是给 skill 添加执行脚本。比如写一个 skill 叫 "ppt-generator"，里面除了 md 说明外再放一个生成脚本，Claude Code 就会在匹配到相关任务时自动运行脚本。这也是热词里 "Claude Code 制作 PPT" 背后的实现思路。

4.3 修改回答语言和输出格式

默认情况下，Claude Code 可能用英文回答你。如果你想让输出一直保持中文，有两个办法。

第一种是直接在对话里跟它说"请用中文回答我"。这个指令在部分场景下管用，但会话一多之后效力会变弱。

第二种更靠谱，写在配置里。在 .claude/settings.json 里加一行：

{
  "permissions": {
    "allow": [],
    "deny": []
  },
  "env": {
    "LANG": "zh_CN.UTF-8",
    "LANGUAGE": "zh_CN"
  }
}

配合在 system prompt 或者 CLAUDE.md 文件里加一句"始终使用中文回复"，效果会稳定很多。

我在项目根目录放了一个 CLAUDE.md ，里面写了项目介绍、代码规范、常用命令，还有"输出请使用中文"这条要求。Claude Code 每次启动对话时都会自动读取这个文件作为上下文，这是让 AI 输出贴合项目习惯的最有效方式。

4.4 把 Claude Code 设置成 Windows 快捷方式

很多不熟悉命令行的同事问过我，能不能像普通软件一样双击就打开 Claude Code。当然可以，做一个快捷方式的事。

在桌面新建一个快捷方式，目标填：

C:\Windows\System32\cmd.exe /k "wetty claude"

或者更简单一点：

C:\Program Files\Git\git-bash.exe --cd-to-home claude

再给快捷方式换一个图标，就完全像原生应用了。习惯用 VS Code 的人还可以把它绑定成快捷键，一键在底部终端里唤起 Claude Code。

4.5 常用命令参数速查

有几个参数日常用得非常多，我列一个表方便查阅：

5. 常见问题与排查技巧实录

这部分是我踩坑踩出来的，每一个都有真实场景，不是文档里复制粘贴的。

5.1 529 报错：流量限制和配额问题

用 Claude Code 的人几乎没有不遇到 529 的。这个报错在官网 API 和第三方模型里都出现过，含义是服务端过载或触发了速率限制。

我遇到最多的情况集中在两个时间段：一是第三方模型服务商高峰期，二是免费试用额度快用完的时候。解决办法分几档：

第一档，等几分钟后重试。如果是临时性过载，这个最简单有效。

第二档，在 settings.json 里调低并发请求数，或者修改模型参数，避免频繁请求触发限流。比如把 max_tokens 调小一点，任务拆细一点再跑。

第三档，检查是不是免费额度用完了。很多服务商免费阶段结束后会直接拒绝请求，报错和限流很像。这时候升级套餐或者更换 key 就能解决。

5.2 模型名无法识别

"deepseek-v4-pro" is not a model this version of claude code recognizes 这个报错我在网上看到很多人问，自己也碰到过。原因在上文提过，Claude Code 维护了一个内置模型列表，不在列表里的模型名会被拒绝。

解决办法有两条路：

1. 修改 ANTHROPIC_MODEL 为官方支持的模型名。比如 DeepSeek 的 deepseek-chat 。
2. 如果确实要用新模型，升级 Claude Code 版本，新版本通常会把新模型加进列表。

注意，这不是 key 的问题，改 key 没用，一定要改模型名。

5.3 输出乱码

有段时间我终端里输出的中文全部是乱码，排查了很久发现不是模型问题，是终端编码问题。Windows 下用 PowerShell 打开 Claude Code 如果编码没切成 UTF-8，中文输出就像外星文。

解决办法是在终端里执行：

chcp 65001

或者把 Windows 终端的默认编码改成 UTF-8。在 Ubuntu 下，乱码通常是 locale 环境没配好，用：

export LANG=zh_CN.UTF-8

就能解决。

5.4 新建了 settings.json 还是接不进模型

有用户按照教程新建了 settings.json，但 Claude Code 就是不走第三方模型。这种问题九成是文件位置放错了。

Claude Code 读取配置时有几个位置：用户级配置在 ~/.claude/settings.json ，项目级配置在项目目录 .claude/settings.json 。如果你在错误的层级创建了文件，Claude Code 根本不会去读它。

另一个常见问题是重启。修改 settings.json 后必须完全退出 Claude Code 再重新启动，光开新会话有时候都读不到最新配置。

5.5 询问时发出声音提示

Claude Code 默认在等待你输入时可能会发出提示音，有的人喜欢，有的人觉得吵。关闭方法是在会话里输入 /config ，找声音（sound）选项，设置为关闭。

如果你用的是桌面版，桌面版设置里的通知选项也要一起关，否则每次任务结束它都会弹通知。

5.6 Claude Code 离线部署的可能

很多企业用户在意数据安全，问我 Claude Code 能不能本地离线部署。这里说清楚：Claude Code 本身是一个客户端工具，它需要连模型服务的 API 才能工作。如果你有完全内网部署的模型服务，且这个服务提供了 Anthropic 兼容接口，那么可以通过配置 ANTHROPIC_BASE_URL 指向内网模型服务，实现"本地离线部署"的效果。

之前我们团队体验过内网部署开源模型的方案，配合 Claude Code 的客户端外壳来用，效果尚可，但相比云端大模型，代码理解和生成能力有明显差距。所以要不要走本地部署，取决于你对数据隔离的要求和对效果的容忍度。

6. 一点个人使用心得

用了这段时间，我最大的感受是：Claude Code 的价值不完全在于它本身有多强，而在于你把它的工作流打磨到什么程度。同样是接一个 DeepSeek 接口，有人只是把它当网页版聊天，有人能配置好 skills 和 CLAUDE.md，让它成为团队里真正懂项目规范的 AI 协作者。

我建议你从今天开始做一个实验：找一个小项目，把项目背景、技术栈、目录结构、常见命令写进 CLAUDE.md ，然后试着让 Claude Code 完成一个之前觉得繁琐的任务。你可能会发现，它第一次跑任务时做的事情，和你自己动手做的思路惊人地接近。再往后，你可以慢慢给它加 skills、调模型、做配置切换，找到一套最适合自己项目的工作流。这个过程本身，比任何教程都有价值。

最后提醒一句，任何时候都记得保留 git commit 习惯。Claude Code 改代码虽然会给你确认，但批量修改时偶尔会出现你不太满意的结果，有 commit 在手，随时可以退回去。这算是所有 AI 辅助编程工具通用的保命法则。