张昕宇梁红聊一聊 Claude Code 的基本操作。这个工具最近在开发者圈子里热度很高，它是 Anthropic 官方推出的 AI 编程助手，不是简单的聊天窗口，而是一个跑在终端里的智能体。你可以让它读整个项目、分析代码、改文件、跑测试、甚至帮你提交 Git commit，它会自己拆解任务、逐步执行，遇到可能影响项目的操作会停下来等你确认。这篇文章拖了挺久才写，因为网上的资料大多是"安装教程"或者"某某功能推荐"，真正讲清楚装完之后怎么配置、怎么接入 DeepSeek 这类第三方模型、怎么处理报错的内容很少。我把从零安装到日常使用过程中遇到的典型问题都整理了一遍，适合刚听说 Claude Code 想上手的开发者，也适合已经装好但用不起来、或者想接更经济的模型服务的人。
1. 先分清三副面孔：CLI、VS Code 插件、桌面版
这是我在评论区看到被问得最多的问题。Claude Code 不是一个单一入口，它有三种形态，很多人一开始就卡在"我到底该装哪个"上面。
| 形态 | 入口 | 本质 | 适合场景 |
|---|---|---|---|
| 命令行工具 | 终端运行 claude |
Node.js 编写的终端智能体 | 最核心形态，任何系统都能用 |
| VS Code 插件 | 编辑器侧边栏面板 | 基于 CLI 同源引擎前端 | 写代码时看 diff、选中代码提问 |
| 桌面版 | 独立图形应用 | 带界面的客户端 | 不习惯命令行的用户、快速问问题 |
CLI 是根基，所有能力都从它这里长出来。你在项目目录下敲 claude，它就会启动一个会话，能读取当前目录的文件结构，也可以向上访问父目录内容。会话过程中它会自己规划步骤：先看哪些文件、改哪几行、跑什么命令验证，每一步都带上下文。这和传统聊天机器人最大的区别是，它有"行动能力"，而且行动前会征求你的同意。
VS Code 插件本质上就是把 CLI 的能力搬进编辑器，好处是能直接选中一段代码提问，比如"这段函数有没有并发问题"，修改结果会以 diff 形式逐块展示，你可以单独接受或拒绝某个改动。日常写代码时，插件比切回终端方便不少。
桌面版更像一个图形化壳子，界面上可以选项目文件夹，然后在对话框里描述需求。它适合快速看项目概况、做代码评审式提问，但对复杂工程的控制力不如 CLI。我的建议是：先装 CLI 把基础操作跑通，日常写代码再装 VS Code 插件，桌面版看个人习惯。三者共用同一套认证和配置，学会了 CLI 的配置，另外两个基本不用额外折腾。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装：三端安装步骤与常见失败原因
2.1 装之前先检查环境
Claude Code CLI 依赖 Node.js 运行时，官方要求 Node.js 18 及以上，我实测用 20 以上的版本更稳。装之前先确认版本：
bash复制node -v
npm -v
如果 Node 版本太低，启动时会报莫名其妙的语法错误，或者直接闪退。Windows 用户建议用 Windows Terminal 来跑，系统自带的 cmd 对 UTF-8 支持不好，后面提到的乱码问题也跟终端编码有关。
macOS 和 Linux 用户如果还没装 Node，推荐用 nvm 管理版本，按官网文档装就行。Ubuntu 系统最常见的坑是 npm 全局安装的权限问题，用 nvm 安装 Node 之后，npm 全局目录就在用户目录下了，不需要 sudo，能省掉一堆权限麻烦。
2.2 三端安装步骤
CLI 安装只有一条命令：
bash复制npm install -g @anthropic-ai/claude-code
装完验证版本：
bash复制claude --version
能看到版本号就说明装好了。如果提示 claude 不是内部或外部命令（Windows）或 command not found（macOS/Linux），多半是 npm 全局目录没加进 PATH。Windows 上先跑 npm prefix -g 查看全局目录，再把它加进系统环境变量，然后重开终端。
VS Code 插件直接在扩展市场搜 "Claude Code"，注意认准 Anthropic 官方出品的那个，别装成同名第三方工具。装好后左侧会出现对应图标，打开面板就能用。
桌面版从官网下载对应系统的安装包，Windows 下走安装向导，装完直接启动。首次启动会引导你登录或者配置 API Key，这个流程和 CLI 里是一样的，可以先用 CLI 把认证搞定。
2.3 安装后先解决认证：登录还是填 Key
装完先别急着用，得让工具知道你是谁。两种方式：一种是交互式登录，运行 claude 后按提示进行 OAuth 授权，浏览器跳转确认即可；另一种是配置 API Key，适合服务器、自动化脚本这类没法弹浏览器的场景。
Windows PowerShell 里设置临时环境变量：
powershell复制$env:ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
macOS/Linux 临时设置：
bash复制export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
想永久生效就写进 shell 配置文件（~/.zshrc 或 ~/.bashrc）。这里有个新手最常踩的坑：设置完必须重开终端，环境变量才会加载。不然你明明配置了 Key，运行 claude 还是提示未认证。
3. 模型接入：官方模型与第三方模型的配置思路
3.1 为什么大家都在折腾模型切换
Claude Code 默认调用 Anthropic 自家的 Claude 系列模型，用官方 API Key 按 token 计费。模型很强，但有不少开发者考虑成本因素，或者希望按自己的习惯选模型，于是想接 DeepSeek、智谱这类第三方模型服务商。这就涉及到 Anthropic 兼容端点的概念。
3.2 Anthropic 兼容端点：第三方接入的核心原理
Claude Code 只认 Anthropic 的 API 协议，所以第三方要接入，必须提供 Anthropic 兼容的接口地址。好消息是，现在不少模型服务商都做了这个兼容层。DeepSeek 官方提供 https://api.deepseek.com/anthropic 这个地址，智谱也有类似的兼容入口。本质上就是让 Claude Code 把请求发到对方服务器，协议格式不变，模型换成了别的。
配置方式有三条路，我分别说一下。
方法一：修改 settings.json
Claude Code 的全局配置在用户主目录下的 ~/.claude/settings.json，Windows 上对应 C:\Users\你的用户名\.claude\settings.json。文件不存在就新建一个，写入内容：
json复制{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "sk-你的deepseek密钥",
"ANTHROPIC_MODEL": "deepseek-chat",
"ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
}
}
这里几个字段的作用要理解清楚：
ANTHROPIC_BASE_URL：请求转发地址。改成第三方服务商的兼容端点，就等于换了模型提供方。ANTHROPIC_AUTH_TOKEN：认证令牌，这里填的是第三方服务的密钥，不是 Anthropic 的。ANTHROPIC_MODEL：主模型名，必须填对方服务器能识别的名字。ANTHROPIC_SMALL_FAST_MODEL：小模型，用于给对话生成标题这类轻量任务，可以跟主模型一样。
你要是见到过 deepseek-v4-pro" is not a model this version of claude code recognizes 这类报错，原因就是 ANTHROPIC_MODEL 填了一个根本不存在的模型 id。网上有些帖子会转发臆造或过时的模型名，抄过来就会踩坑。正确做法是去对应服务商的官方文档查模型列表，比如 DeepSeek 现在的模型 id 一般是 deepseek-chat 和 deepseek-reasoner，智谱的可能是 glm-4.x 系列。
方法二：使用环境变量
如果你不想动配置文件，直接设置环境变量也一样，启动 Claude Code 前执行：
bash复制export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-xxxx"
export ANTHROPIC_MODEL="deepseek-chat"
claude
方法三：用 CC Switch 等切换工具
社区里有个叫 CC Switch（cc-switch）的小工具，专门管理 Claude Code 的多套配置。它的原理很简单：帮你在不同服务商的配置之间切换，本质还是读写 settings.json 里的环境变量，只是做成了可视化界面。我自己习惯把官方模型、DeepSeek、智谱各存一个 profile，按需一键切换，省得手动改配置文件改出错。
顺便说一下本地部署。如果你本地用 Ollama 或其他方式跑了一个支持 Anthropic 兼容接口的模型服务，理论上把 ANTHROPIC_BASE_URL 指向 http://localhost:xxxx 就能接进去。但本地小模型的代码理解能力和长上下文能力跟云端模型差距明显，我实测写代码任务效果一般，只建议拿来做不涉密的简单任务或者实验性验证。如果你的场景对数据敏感要求高，可以考虑，但别指望它完全替代商用模型。
3.3 settings.json 不生效的排查思路
网上很多教程都会说"新建 settings.json"，但写完不生效的情况很常见。我总结的原因主要有三种：
- 文件位置不对。Claude Code 有全局配置
~/.claude/settings.json，还有项目级配置.claude/settings.json（放在项目根目录）和本地配置.claude/settings.local.json，优先级依次递增。如果你把文件放错目录，或者项目里恰好有一个覆盖了全局配置的文件，就会出现"我明明配了 DeepSeek 怎么还在调官方模型"的现象。 - JSON 格式错误。少一个逗号、多一个引号都会导致解析失败，而 Claude Code 往往不报错，只是静默忽略，体感就是"根本没生效"。
- 环境变量优先级高于配置文件。如果你在 shell 里已经 export 了
ANTHROPIC_BASE_URL，那么 settings.json 里写什么都没用；反过来，settings.json 的 env 只在 Claude Code 启动时注入，不会覆盖当前 shell 已有的同名变量。
排查顺序建议：先 echo $ANTHROPIC_BASE_URL（Windows 是 echo %ANTHROPIC_BASE_URL%）看环境里有没有残留变量，再确认配置文件路径和 JSON 语法，最后重启终端再启动 claude。
4. 日常操作：从提问到改代码的完整流程
4.1 CLI 交互模式与常用命令
在项目目录下运行 claude，会进入交互模式。你可以直接用自然语言和它对话，比如：
- "这个项目的技术栈是什么？"
- "帮我看看 src/main.py 的逻辑有没有问题。"
- "把登录接口的超时时间从 5 秒改成 10 秒。"
它会先列一个执行计划，然后逐步展开。涉及文件修改时，会在改动前展示将要修改的内容，等你输入确认；涉及执行命令时，也会先展示命令再执行。这个确认机制很重要，尤其是自动跑脚本的场景。如果你对项目足够放心，启动时加 --dangerously-skip-permissions 可以跳过所有确认，但我强烈不建议在正式项目里这么干，一次误操作可能让整个仓库遭殃。
常用斜杠命令整理如下：
| 命令 | 作用 |
|---|---|
| /help | 查看全部命令帮助 |
| /clear | 清空当前会话上下文 |
| /compact | 压缩历史对话，释放上下文空间 |
| /status | 查看当前会话状态、模型信息 |
| /model | 切换当前模型 |
| /skill | 管理已加载的技能 |
| /quit | 退出会话 |
我的习惯是长时间对话后定期 /compact 一次。上下文窗口再大也是有限的，压缩一次能避免"前面聊的它全忘了"的尴尬，还能减少 token 消耗。但注意压缩会把部分细节概括掉，关键信息在压缩之后最好主动重申一遍。
4.2 VS Code 插件：选中代码直接问
装好插件打开面板后，最基本的用法是：选中一段代码，右键选择 "Ask Claude Code" 之类的入口，面板里输入问题，比如"这段代码有没有边界条件漏洞"。它返回结果时，如果涉及修改，会以 diff 形式展示，你可以逐块接受或拒绝。这块体验比终端里翻文件舒服太多了。
插件和 CLI 共用认证与配置，所以 CLI 里能用的模型、Skills，插件里一样能用。我日常写代码时，把插件面板固定在侧边栏，遇到不熟的库函数直接选中问一句，效率比切出去搜文档高很多。另外，想让 Claude 用中文回答，直接在问题后面加一句"请用中文回答"，或者在 CLAUDE.md 项目约定文件里写死，一劳永逸。
4.3 桌面版与一些非代码用法
桌面版适合不熟悉命令行的朋友，它可以在界面上选定项目文件夹，然后自然语言提需求。除了代码任务，Claude Code 也能干一些"非正经"的活，比如让它整理 Markdown 格式的 PPT 大纲、根据代码仓库生成 README、把一段英文技术文档翻译成中文。有不少人拿它做 PPT 大纲和会议纪要整理，本质上就是把它当成一个带文件访问能力的写作助手。桌面版这种场景下反而比 CLI 更直观，因为界面里可以直接看结果、复制内容。
5. Skills：把重复性工作封装成可复用的技能
5.1 Skills 机制是什么
Claude Code 的 Skills 机制，相当于给模型添加"预写好的操作手册"。每个 Skill 是一个目录，目录里有一个 SKILL.md 文件，用 Markdown 加上 YAML frontmatter 描述这个技能的名称、适用场景和操作步骤。当模型判断当前任务匹配某个 Skill 的描述时，就会自动加载对应的说明来指导自己的行为。
Skill 目录有两个位置：全局放 ~/.claude/skills/，项目级放 .claude/skills/。项目级的优先级更高，同名技能会覆盖全局版本。对于团队来说，把代码规范、提交规范、项目约定写成 Skills，每个成员接入后行为就保持一致，这是我觉得这个功能最有价值的地方。
有人把 Skills 理解成"插件"，其实不太准确。它更像是一份标准作业程序，每次模型接到相关任务时，就照着这份流程执行。比如你希望它提交代码时遵守 Conventional Commits 规范，不用每次在提示词里反复强调，写一个 Skill 就解决了。
5.2 从零创建第一个 Skill
我拿自己常用的 commit 信息技能举例。目录结构如下：
code复制~/.claude/skills/commit-msg/
└── SKILL.md
SKILL.md 内容：
markdown复制---
name: commit-msg
description: 根据 git diff 生成规范的 commit message，要求使用 Conventional Commits 格式。
---
# Commit Message 生成
当你需要生成 commit message 时，按以下步骤操作：
1. 执行 `git diff --stat` 查看变更范围。
2. 执行 `git diff` 查看具体改动。
3. 根据改动类型选择 type（feat/fix/docs/style/refactor/perf/test/chore）。
4. 描述保持简洁，不超过 80 字符，中英文均可。
5. 输出完整的 git commit 命令，等待用户确认后执行。
保存后重启 claude，在对话里说"帮我提交代码"，它就会按照这套流程走。也可以用 /skill 命令查看当前加载了哪些技能，或者手动指定加载某个技能。Skills 内容写得好不好，直接决定模型执行效果，建议把步骤写得具体一点、可验证一点，别写"分析代码"这种模糊描述，而要写"执行哪个命令、看哪个文件、按什么标准输出"。
6. 常见问题与排查实录
6.1 输出乱码怎么解决
Windows 上中文输出乱码，这是问得最多的问题。claude 输出的是 UTF-8，但 Windows 终端默认代码页可能是 GBK，两边对不上就乱码了。解决办法是让终端切到 UTF-8：Windows Terminal 的设置里可以改默认编码，或者每次执行 chcp 65001 切换代码页。也可以把系统区域设置里的"Beta：使用 Unicode UTF-8 提供全球语言支持"打开。改完重启终端再跑 claude。我一开始也以为是工具 bug，折腾半天才发现是终端显示问题。
6.2 529 错误是怎么回事
529 表示 Anthropic 服务端负载过高，官方 API 高峰期经常出现。处理手段就是等待几秒重试，或者错峰使用。如果接的是第三方模型，请求打到的是对方服务器，一般不会遇到 529。另外，同一个 Key 并发请求太多也会加重 529 概率，自动化脚本里建议做一下请求间隔限制。
6.3 模型 not recognized 的排查套路
"xxx" is not a model this version of claude code recognizes 这个报错，常见原因有三个：模型 id 抄错了；Claude Code 版本太旧、不认识新模型；第三方接入时 ANTHROPIC_BASE_URL 配了但 ANTHROPIC_MODEL 写错。排查时先 claude --version 看版本，如果版本偏老就执行 npm update -g @anthropic-ai/claude-code 更新，再去服务商文档核对模型 id，最后检查配置文件的 JSON 格式。
6.4 怎么固定回答语言
每次都在问题后面加"请用中文回答"太啰嗦。更好的方式是写进项目约定文件，在项目根目录创建 CLAUDE.md，或者写入全局 ~/.claude/CLAUDE.md，内容里加一句"所有回复请使用中文"。Claude Code 每次会话开始都会自动读这个文件，所以不用反复叮嘱。CLAUDE.md 里还可以写项目结构说明、常用命令、编码规范，相当于给模型一份项目入职手册，对提升回答质量帮助很大。
6.5 如何彻底卸载干净
想换版本或者删干净配置，光删快捷方式可不够。先卸载 npm 包：
bash复制npm uninstall -g @anthropic-ai/claude-code
然后删除配置目录 ~/.claude（Windows 用户目录下的 .claude 文件夹）。桌面版要在系统设置里卸载应用，同时检查 %APPDATA% 下有没有残留的 Claude Code 相关目录。VS Code 插件在扩展面板直接卸载。这样才算清理干净，重新安装时也不会被旧配置干扰。
6.6 声音提示和快捷方式的小需求
有朋友问 claude 干活时能不能有声音提醒。这个功能不在 Claude Code 本身，而是终端层面的。Windows Terminal 可以在收到输出时播放提示音，或者用系统通知的方式提醒。想给 Claude Code 做 Windows 快捷方式，可以在桌面新建快捷方式，目标填 claude，工作目录填项目路径，双击就能进到项目会话，纯属启动方式的便利化，不影响任何配置。
6.7 桌面版免登录模式
桌面版虽然默认走浏览器登录，但也支持只填 API Key 的方式。在设置里填入 ANTHROPIC_API_KEY，或者配置好环境变量后再启动桌面应用，它就会跳过登录引导直接进入会话。这点对不习惯 OAuth 流程的用户很友好，也方便在隔离环境里使用。
7. 一些个人经验
折腾这套东西半年多，印象最深的教训是三个：环境变量和配置文件优先级搞反，导致改了配置不生效；模型 id 随手从帖子复制没验证，白白折腾一晚上；Windows 编码问题差点让我以为是程序坏了。如果你也遇到类似问题，按第六节里的顺序排查，大部分都能解决。
另外，新手建议先用 DeepSeek 这类成本更低的模型跑通流程，把提问、改代码、看 diff 这些基本操作练熟了，再考虑上官方模型对比效果。Skills 也不要一上来写一堆，先观察自己哪些操作重复频率高，再逐个封装成技能，效果会实在很多。Claude Code 本质上是个能帮你跑腿的同事，配置到位、约定清晰之后，它做事的质量会有明显提升。多试几次，它会慢慢变成你顺手的那把工具。