Claude Code 终端代理完全指南：安装配置、第三方模型接入与技能开发

这些年在终端里折腾 AI 工具的经历不少，Claude Code 是少数让我觉得“值得认真学一遍”的那个。它不是一个普通聊天窗口，而是一个直接住在命令行里的编程代理，能读你的项目、改代码、跑命令、提交 Git 记录，你只负责把需求讲清楚，它负责拆解和执行。这篇文章是我从零开始折腾 Claude Code 的完整笔记，覆盖安装、CLI 与桌面版和 VSCode 插件三种形态的选型、接第三方模型、写 skill、改中文回复，以及那些最容易卡住人的报错。适合刚接触命令行工具的开发者，也适合已经用了几天但还被配置文件折磨的用户。

我先把结论放在最前面：Claude Code 的安装和基础配置并不难，真正麻烦的是环境变量、模型名、配置文件这三件事互相纠缠。一旦把这三件事理顺，它就是我见过的最贴近“程序员助理”这个定位的工具。

1. 先搞清楚：Claude Code 是什么，三种形态怎么选

1.1 从“聊天窗口”到“终端代理”

Claude Code 是 Anthropic 推出的终端编程代理工具，核心能力是一个运行在命令行里的 Agent。它和我之前用过的各种 AI 插件最大的不同，在于它拥有当前项目的读取和执行权限：它自己决定先看哪个文件、再跑哪条命令、看到执行结果之后下一步做什么，而不是等着用户一条一条喂指令。

我习惯用一个类比来解释：网页版对话像是你雇了一个顾问，只能动嘴给建议；Claude Code 则像是雇了一位坐在你电脑前的实习生，可以直接翻你的项目、动手改代码。当然，它不是无法无天，你可以在配置文件里设置权限，让它每次执行高风险的写操作或删除命令之前都先向你请示。这个“可授权的 Agent”定位，是我认为它比普通对话工具高一个维度的原因。

这个工具特别适合两类人：一是日常用 Vim、tmux、脚本写代码的开发者，二是想尝试“AI 自动编程”但不想离开命令行工作流的用户。如果你完全没接触过终端，也可以先用桌面版过渡，但最终你还是会回到配置文件上来，因为很多高级功能绕不开。

1.2 CLI、桌面版、VSCode 扩展，我该用哪个

Claude Code 现在有三种常见形态：纯 CLI、桌面版、VSCode 扩展。很多人第一次看到这三个名字就懵了，不知道装哪个。我给一个很直白的选型建议：

我个人的主力是 CLI。原因很简单：它在脚本化、快捷键、tmux 多会话配合上最灵活，而且接第三方模型、写 skill 这些操作，最终都是通过 CLI 读取配置文件来完成的。桌面版只是把 CLI 包了一层，好处是初次上手压力小，坏处是你依然要理解同样的配置逻辑，只是界面友好一点。

VSCode 扩展则是在需要“边看 diff 边和 AI 讨论”的时候最舒服，选中一段代码直接丢给它解释或修改，上下文自动带过去，省去了终端里复制粘贴。我的建议是 CLI 为主、VSCode 扩展为辅，两个都装，反正它们共用同一套配置，不冲突。

2. 从零安装：Windows 和 Ubuntu 的实操记录

2.1 前置条件：Node.js 版本别太低

Claude Code 通过 npm 分发，所以第一件事是确认 Node.js 版本。官方要求通常是不低于 18，但我建议直接上 LTS 版本（20 或 22），没必要用最新版当小白鼠，也别用老版本给自己挖坑。

Windows 上检查版本很简单：

bash复制node -v
npm -v

如果版本偏低，我推荐用 nvm-windows 来管理 Node 版本，而不是直接下载安装包覆盖安装。因为以后你可能会在不同项目里需要不同 Node 版本，用 nvm 切换比重新安装省事太多。Ubuntu 上同样建议用 nvm 或者从 NodeSource 源安装，别用发行版自带的旧 node——我在 Ubuntu 20.04 上踩过一次坑，自带 node 是 10.x，npm install 直接报引擎不匹配，后来用 nvm 装了 20 才解决。

2.2 npm 全局安装与验证

确认 Node 环境没问题后，安装就是一条命令的事：

bash复制npm install -g @anthropic-ai/claude-code

安装完成后验证：

bash复制claude --version

如果提示找不到命令，分两种情况排查：

• Windows：npm 全局安装目录可能不在 PATH 里。先执行 npm config get prefix 拿到全局目录，再把它的路径加入系统环境变量 PATH，然后重开终端。
• Ubuntu：如果用 sudo 安装，全局目录通常是 /usr/local/bin，一般已经在 PATH 里；如果当前用户权限不够，可能装到了别的目录，用 which claude 查看实际位置。

国内网络环境下，npm 直接下载大包有时候非常慢，甚至超时。我一般把 registry 临时指向镜像源：

bash复制npm config set registry https://registry.npmmirror.com

注意这是全局修改，如果你不想影响其他项目，可以只对单次安装生效：

bash复制npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

2.3 桌面版怎么下载、怎么初始化

桌面版从官方渠道下载即可。Windows 是 exe 安装包，macOS 是 dmg。安装完成后第一次启动会引导登录，完成认证后就能进入一个带终端界面的工作区。

这里有一个很多人问的点：桌面版是不是可以不登录直接用。我的建议是不要纠结“免登录”，因为核心认证流程绕不过去，而且真没必要。你想体验官方服务就正常登录；你想接第三方模型，直接用 CLI 加环境变量更干净，反而比在桌面版界面里折腾高效。桌面版适合用来体验产品流程，不适合作为重度配置的主战场。

2.4 设置系统级快捷方式（Windows）

npm 全局安装后，CLI 本身可以从终端调用。如果希望双击就能启动它，可以手动创建一个快捷方式。先用 where claude 找到实际路径，多半是一个后缀为 .cmd 的文件。右键发送到桌面快捷方式，然后在属性的“目标”里加上你希望进入的工作目录作为“起始位置”。比如我想让 Claude Code 打开后直接落在某个项目目录，就把起始位置填成那个项目的路径。

还有人希望像普通软件一样固定在开始菜单或任务栏，这也可以，但说实话意义不大。Claude Code 是终端工具，从终端里启动才是最顺的，快捷方式更多是给桌面版用户的一个补充。

3. VSCode 配置 Claude Code：让编辑器替你管终端

3.1 安装官方扩展而不是第三方同名扩展

在 VSCode 扩展市场搜索 “Claude Code” 会看到好几个结果，注意看发布者，认准官方发布者再安装。第三方扩展有的只是调用 CLI，有的甚至是单纯的聊天界面，功能和完整度差远了，装错了容易让人误以为 Claude Code 就这么点能力。

安装完成后，VSCode 通常会自动发现本机的 CLI。它本质上不是独立实现，而是对 CLI 的调用封装。所以请先确认 claude --version 能正常输出，再重启 VSCode，扩展才能找到可用的命令。

3.2 扩展报“找不到 claude”怎么办

这个问题很常见，尤其 Windows。原因多半是 PATH 不一致：你可能在一个终端里能跑 claude，但在 VSCode 的集成终端里跑不了。检查顺序：

1. 用 echo $env:PATH（PowerShell）确认 VSCode 集成终端是否包含 npm 全局目录。
2. 确认 claude 是不是安装在当前用户目录下，而不是另一个管理员账户里。
3. 改完 PATH 后重启 VSCode，不能只重开终端，最好整个窗口重启。

还有一个小坑：VSCode 扩展有时会缓存环境变量，改了系统 PATH 后不重启 VSCode，它仍然用旧值。遇到“明明命令行里能跑，扩展就是找不到”的情况，直接重启 VSCode 是最高效的解法。

3.3 侧边栏与代码内联操作的实际体验

VSCode 扩展启动后一般有两个入口：一个是侧边栏面板，一个是编辑器右键菜单。侧边栏里可以新建会话、上传文件上下文、查看会话历史。选中一段代码后，可以让它解释、重构、写测试，甚至直接生成 diff 展示在编辑器里。

对我来说，VSCode 扩展最大的价值是“看 diff”这一步。在纯 CLI 里，AI 改完代码后你要自己切到 git diff 去看；在 VSCode 扩展里，改动直接以内联 diff 形式呈现，哪里改了、为什么改，一目了然。这个体验对代码审查非常友好，所以我建议即使是 CLI 重度用户，也可以装一个扩展备用。

3.4 集成终端里的环境变量配置

如果接的是第三方模型，你会遇到一个很奇怪的场景：系统终端里 claude 能正常用，VSCode 集成终端里 claude 却报错。这是因为 VSCode 集成终端不一定继承你在系统 GUI 里设置的环境变量，尤其是 Windows。解决办法是在 VSCode 的 settings.json 里给集成终端单独指定环境变量：

json复制{
  "terminal.integrated.env.windows": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的API Key"
  }
}

但我个人不推荐在 VSCode 层面重复配置。更好的做法是统一写到 ~/.claude/settings.json 里，这样无论从哪个终端启动 claude，读到的都是同一份配置，不会出现“系统终端能用、VSCode 不能用”这种两套配置打架的问题。具体怎么写在下一节展开。

4. 接入第三方模型：以 DeepSeek 为例的完整配置

4.1 为什么会报 “xxx is not a model this version recognizes”

热词里反复出现这个报错：

code复制"deepseek-v4-pro" is not a model this version of claude code recognizes

这是接第三方模型时最典型的错误。含义是：Claude Code 启动时从配置或环境变量里拿到一个模型名，但这版 Claude Code 内置的模型清单里没有这个名字，于是拒绝继续。注意关键词 “this version recognizes”，说明它会对模型名做本地的合法性校验，而不是简单地把模型名透传给后端。

顺着这个思路排查，首先确认当前终端里实际生效的模型名是什么：

bash复制# PowerShell
echo $env:ANTHROPIC_MODEL

# bash
echo $ANTHROPIC_MODEL

如果输出是 deepseek-v4-pro 这类名字，多半是照着网上错误教程填的。DeepSeek 官方目前提供的模型名是 deepseek-chat（V3 系列，偏对话和编码）和 deepseek-reasoner（R1 系列，偏推理），并没有 deepseek-v4-pro 和 deepseek-v4-flash 这些型号。遇到这报错，第一反应应该是“模型名填错了”，而不是去怀疑别的。

还有一种情况是模型名本身没问题，但你的 Claude Code 版本太旧，不认识第三方服务商新返回的模型标识。这种情况把 CLI 升级到最新版：

bash复制npm update -g @anthropic-ai/claude-code

4.2 需要配置的最小环境变量集合

接第三方模型的原理，是 Claude Code 支持通过环境变量 ANTHROPIC_BASE_URL 把请求转发到任何兼容 Anthropic Messages API 的服务端。DeepSeek 官方提供了一个 Anthropic 兼容端点：

code复制https://api.deepseek.com/anthropic

最少需要配置以下四个变量：

关于用 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY，网上说法不一。我的经验是按 ANTHROPIC_AUTH_TOKEN 来配置，在 Claude Code 较新的版本里它更稳定。如果你发现被忽略，可以两个都写上，不影响。

配置方式有两种。一是临时设置，只对当前终端有效，适合测试：

bash复制# Windows PowerShell
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="sk-xxx"
$env:ANTHROPIC_MODEL="deepseek-chat"

# Ubuntu / macOS bash
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
export ANTHROPIC_MODEL="deepseek-chat"

二是持久配置，写入 ~/.claude/settings.json 的 env 字段：

json复制{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "API_TIMEOUT_MS": "300000"
  }
}

注意这里 env 里的值一律写成字符串，即使 API_TIMEOUT_MS 看起来是数字，也要加引号。

4.3 用 ccswitch 在多套 API 配置之间切换

热词里频繁出现 ccswitch（CC Switch）。如果你手里有多个模型的 API key，比如 DeepSeek、智谱、官方 Anthropic 账号，手动改 settings.json 每次都要小心翼翼，改错一个字母就可能浪费半天时间。ccswitch 就是用来解决这个问题的社区工具。

它的原理很简单：在图形界面里维护多套“配置组”，每个配置组就是一组环境变量的集合。切换时它会把选中的配置写入 ~/.claude/settings.json 或系统环境变量，之后启动 claude 就是新的配置。在 GitHub 上搜 CC Switch 就能找到安装包，Windows 和 macOS 都有。

用它有两个注意点。其一，ccswitch 只是改配置，不会替你纠正模型名错误，如果配置组里填了不存在的模型名，启动时照样报 not recognized。其二，切换配置后，已经开着的终端里环境变量不会自动刷新，必须新开一个终端窗口再启动 claude。我一开始没注意，还以为是工具坏了，其实就是终端环境变量没更新。

4.4 智谱等模型的配置思路

除了 DeepSeek，智谱（BigModel）也提供 Anthropic 兼容的 API 端点，其他服务商也陆续在跟进。核心思路是一样的：先去对应平台的官方文档确认三件事——base_url 是什么、模型名是什么、认证用的是什么方式（有些用 x-api-key，有些用 Authorization: Bearer），然后把它们逐一填进 settings.json 的 env。

我强烈建议在配置 Claude Code 之前，先用 curl 直接请求一下 API 端点，验证 key 是否有效、模型名是否正确。curl 能通，Claude Code 大概率也能通；curl 都报错，就别浪费时间在 Claude Code 上排查了：

bash复制curl -X POST "https://api.deepseek.com/anthropic/v1/messages" \
  -H "x-api-key: 你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-chat","max_tokens":100,"messages":[{"role":"user","content":"hello"}]}'

网上教程互相冲突的根源就在这里：不同服务商对 header 字段名、base_url 尾缀的要求不一样。你照着教程 A 填了 Authorization，但你的服务商要求的是 x-api-key，自然报错。所以切记：以你所用服务商的官方文档为准。

4.5 配置好了但没生效？按这个顺序排查

我整理了一套固定的排查流程，遇到问题从前往后过一遍，基本能定位九成：

1. claude --version 确认 CLI 版本，太旧就升级。
2. 查看当前终端实际环境变量值，确认不是被旧 shell 缓存住了。
3. 打开 ~/.claude/settings.json，确认 env 字段还在，内容没有被其他工具覆盖。
4. 检查 ~/.claude.json 里是否有更上层的覆盖配置。
5. 确认 API key 有效、账户有余额。
6. 新开一个终端，重新启动 claude。

最容易忽略的是第 4 点。有些人之前装过其他 Claude Code 管理工具，它们会在 ~/.claude.json 里写入覆盖配置，导致你在 settings.json 里改了半天都没用。遇到“明明改了却不生效”，先去看看 ~/.claude.json 是不是有同名的 key。

还有一个经典场景：settings.json 里写了模型名，但漏写了 base_url。此时 Claude Code 会默认请求 Anthropic 官方 API，然后拿 DeepSeek 的 key 打官方端点，结果肯定是认证失败。这种“配置缺胳膊少腿”的问题，比环境变量名记错还要常见。

5. 用 skill 给 Claude Code 装新技能

5.1 skill 到底是什么

Claude Code 的 skill 机制，是把一组提示词、脚本、示例文件打包成一个目录，让 Claude Code 在特定场景下自动读取并执行。你可以把它理解成“给 Agent 预装的工作手册”：用户提出相关任务时，它能自动加载对应的技能，而不是每次都从零摸索。

skill 的核心是一个 SKILL.md 文件，用 YAML frontmatter 写 name 和 description，正文写具体执行步骤。Claude Code 会读 description 来决定什么场景该触发这个技能。description 写得越精准，触发判断就越靠谱。

5.2 写一个最小可用的 skill：以“生成 PPT 大纲”为例

我拿自己的一个 skill 举例。目录结构是：

code复制~/.claude/skills/make-ppt-outline/
└── SKILL.md

SKILL.md 内容：

markdown复制---
name: make-ppt-outline
description: 当用户需要制作PPT、准备演示文稿、整理汇报大纲时使用。根据主题生成结构化PPT大纲。
---

你是一位演示设计专家。用户提出PPT主题后，请按以下步骤操作：
1. 先输出整体逻辑框架（背景-问题-方案-收益）。
2. 每一页给出标题、核心观点、要点，要点不超过4条。
3. 对每一页给出配图建议。
4. 最后输出一份 markdown 格式大纲，用 --- 分隔每一页。

保存后重启 claude 或重新打开一个会话即可生效。当用户说“帮我做个关于数据分析的PPT”时，Claude Code 会读取这个 skill 的 description，发现匹配，然后自动按里面的步骤执行。这个 skill 我实战用过，输出的大纲质量明显比没有 skill 时稳定，因为它内化了固定的演示逻辑，不会每次都自由发挥。

5.3 在 skill 里引用脚本和其他文件

skill 不只是静态提示词。如果 skill 目录里有其他文件，SKILL.md 可以引用相对路径。比如：

markdown复制## 注意事项

执行前先运行 `python scripts/check_env.py` 检查环境，如果返回非零则停止并提示。

这样 skill 就可以携带实际的工具脚本，做到“提示词 + 自动化”结合。我的经验是：一个 skill 目录不要塞太多功能，单一职责最好维护；技能描述里一定要写清楚“什么场景不用它”，避免误触发。比如你做 PPT 的 skill，可以明确写上“如果用户只是简单问 PPT 技巧而不要完整大纲，不要触发”。

skill 的调试也不复杂：临时改一下 description，让它更容易触发，然后丢一个测试请求，观察它是否加载了 skill 的行为。试通了再收紧 description。

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

6.1 模型识别错误与配置不生效

这个在前面展开过，这里补充一个高频原因：修改 settings.json 后不重启终端。Claude Code 在启动时读取配置文件，你在一个已经打开的会话里改文件是没有用的。改完配置，退出 claude，关掉终端，重新打开，再执行 claude。别嫌麻烦，这个习惯能省掉大量“怎么没生效”的困惑。

6.2 输出乱码：Windows 终端编码问题

Windows 上跑 Claude Code 出现中文乱码，绝大多数是终端编码问题。在 PowerShell 里先执行：

powershell复制chcp 65001

把代码页切到 UTF-8。Windows Terminal 的设置里也可以把默认编码改成 UTF-8。还有一个容易被忽略的点：旧版控制台字体对中文支持很差，换成 Cascadia Mono 或微软雅黑等字体，乱码问题会明显缓解。

如果乱码只出现在 Claude Code 输出里，而系统其他中文正常，还要检查一下是不是环境变量里设置了奇怪的 LANG 或 PYTHONIOENCODING。这个相对少见，但确实有人遇到过。

6.3 卸载不干净怎么办

卸载分为两部分：程序本体和配置文件。如果你只是想重装，先删配置；如果你想彻底离开，两者都要删。

先卸载 npm 全局包：

bash复制npm uninstall -g @anthropic-ai/claude-code

然后手动清理残留：

• Windows 用户目录下的 C:\Users\你的用户名\.claude（包含 settings、skills、历史会话）
• C:\Users\你的用户名\.claude.json
• 如果是桌面版，还可能有 AppData 下的缓存目录
• Linux 下是 ~/.claude 和 ~/.claude.json

为什么有时候卸载了命令还在？多半是 npm 全局安装到了不同目录，比如管理员终端装的和当前用户装的路径不同。用 where claude（Windows）或 which claude（Linux）确认实际路径，再决定删哪个。卸载前建议先备份 .claude 目录，万一以后想找回配置，不至于追悔莫及。

6.4 529 错误和限流

热词里提到 claude code 529：如果你接的是官方服务或某些服务商的代理，529 通常表示服务端过载或限流。处理办法按优先级排列：

1. 等几十秒重试，真的就是这么简单。
2. 把超时时间调大，让请求不容易中断。
3. 如果是第三方模型，避免高峰时段。
4. 检查账户余额、单位时间请求限制。

如果是自己搭的网关，还要检查网关层是不是做了什么并发限制。529 是一个服务端返回的状态码，不是本地问题，所以本地怎么调配置都没用，本质是“对方希望你慢一点”。

6.5 让回答固定用中文

如果你希望 Claude Code 默认用中文回复，在 ~/.claude/CLAUDE.md 里写一句：

markdown复制- 始终使用中文回答用户的提问，代码注释和变量名除外。

CLAUDE.md 是 Claude Code 的用户级记忆文件，每次会话都会自动读取，是设定行为偏好的第一选择，比每次会话开头手动强调“请用中文回答”省心得多。

也可以用启动参数，但我试下来，还是 CLAUDE.md 最稳，因为它是持久化的，会话一启动就注入系统提示，不需要你记忆。

6.6 询问时发出声音提示

有人希望 Claude Code 在等你输入、或者任务完成时能响一声提醒。这需求很实际，尤其是跑长任务的时候。Claude Code 本身没有全局声音开关，但可以借助终端能力实现。最简单的做法是在 PowerShell 里：

powershell复制claude; [console]::beep(800, 300)

这样 claude 退出交互时，系统会响一声。如果你希望在“它输出完、等你输入”的时候提醒，可以用 prompt 脚本包一层，但那就属于个人定制了。我试过在 tmux 里用 set-hook 做类似功能，Windows 上用 beep 最省事。别小看这个功能，跑长任务时一个完成提醒，能让你少刷好几轮页面。

6.7 桌面版和 CLI 的配置关系

如果你已经装了桌面版，又打算用 CLI，要记住它们读写的是同一套配置文件：~/.claude/settings.json 和 ~/.claude/CLAUDE.md。所以命令行里配好的东西，在桌面版里也会生效，反之亦然。

但有一个坑：如果你在桌面版的图形界面里也填了某些配置，又在 settings.json 里填了相同的配置，以配置文件为准，因为图形界面最终也是写入或映射到同一套文件。遇到“改了没反应”，第一反应是检查配置文件，而不是继续在界面里找开关。

我个人对桌面版的态度一直是：可以用它来体验产品、跑一些简单会话，但一旦涉及接第三方模型、写 skill、自动化脚本，直接回到 CLI 更可控。桌面版把终端藏起来了，反而让你更难观察实际发生了什么。

这段时间用下来的体会是，Claude Code 真正的门槛从来不在安装，而在于你愿不愿意给它足够的上下文、并信任它的执行结果。写清楚需求、拆好任务、用好 skill，它就能帮你处理大量重复的编码工作；接模型、写配置这些事，做过一次就熟练了。建议你从最小配置开始，装好 CLI、接一个便宜的模型、写一个最简单的 skill，把整个链路跑通，再逐步加深。上面这些报错，八成你已经能自己定位了。剩下的问题多半是版本差异，把 CLI 升到最新版能解决大半。最后提醒一句：配置改乱了别急着重装，先删掉 ~/.claude/settings.json 恢复默认，再一步步加回来，比什么都有用。