- 适用对象
- 想快速了解工具定位、核心功能和上手路径的中文用户
- 核对日期
- 2026-11-07
本页目录
本指南综合了 10 篇公众号教程(2026-10-07 ~ 11-01)。文中的 [1]~[10] 对应文末的「参考原文」。每张图下方注明出处。素材之间说法不一致,或可能已经过时的地方,用 ⚠️ 标出。
公众号素材里命令行安装和接入其他模型的内容较少,这两部分补充了官方文档和各模型平台的接入文档,以 [官1]~[官7] 标注,查阅日期 2026-11-07。
一、定位:它是什么,适合谁
Claude Code 是 Anthropic 出的编程 Agent,用的是 Claude 系列模型。它和早期「一次补一两行」的代码补全工具不同:你说出要做的事,它会自己读代码、改文件、跑命令,完整开发一个功能或修好一个问题 [8]。它没有给代码建索引,也不把代码上传到远程数据库,代码只留在你本地 [8]。
它有好几个入口,能力基本相同,按习惯选一个就行:
桌面 App 的 Code 页:图形界面,最适合不写代码的人。App 里已经自带 Claude Code,不需要另外装 Node.js 或命令行工具 [1]。
命令行(CLI):在任意终端里输入
claude启动。程序员用得最多,也是功能最全的入口 [2][8]。VS Code / Cursor 插件:在编辑器侧边栏里用,官方称这是在 VS Code 里使用的推荐方式 [3]。JetBrains 系列可以直接在自带终端里跑 CLI [2]。
网页和手机:网页版 claude.ai/code 和手机 Claude App 的 Code 页可以开云端任务,也能遥控电脑上正在跑的任务 [1]。
适合谁
程序员:做代码库问答、开发新功能、修 bug、提交 PR,还能放进 CI 自动跑 [8][10]。
不写代码的内容创作者:素材 [1] 的作者是编程小白,用它半天做出了一个 Obsidian 插件,40 分钟做完一条动效宣传片,还把写口播文案和做视频串成了一个 Skill。
素材 [1] 把使用水平分成六级,可以先对照一下自己在哪一级:
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
桌面 App 里 Chat 和 Code 怎么分 [1]:一次性的事、主要靠聊天和资料的事,用 Chat;要长期围着一个文件夹反复改、想留版本的项目,用 Code。Code 能逐行显示它改了什么,改错了还能撤回。
二、准备与安装
0. 先选路线:你属于哪种情况
| 你的情况 | 推荐路线 | 看哪几步 |
|---|---|---|
| 不写代码,只想让它帮你整理文件、做小工具 | 桌面 App | 第 1、2 步 → 第三节 |
| 程序员,习惯终端 | 命令行 CLI | 第 1、3、5 步 |
| 主要在 VS Code / Cursor 里写代码 | 先装 CLI,再装插件 | 第 1、3、4、5 步 |
| 没有 Claude 订阅,或者网络连不上官方服务 | CLI + 国内模型的 API Key | 第 3 步 → 第四节「8. 接入其他模型」 |
| 公司统一采购了 Bedrock、Vertex 等云服务 | CLI + 云厂商配置 | 第 3 步 + 官方文档 [官1] |
1. 账号与费用
官方账号:要有 Pro、Max、Ultra、Team、Enterprise 套餐,或者 Console(按 token 付费的 API 账号),免费版 claude.ai 用不了 [官1]。桌面 App 点 Code 时弹出升级提示,说明当前套餐不包含 [1]。云端任务和本地任务用的是同一份订阅额度,不另外收费 [1]。
第三方或国内模型:只要服务方提供「Anthropic 兼容接口」,配好接口地址和 Key 就能用。这时按对应平台的套餐或 token 计费,不占 Claude 订阅的额度 [官2][5]。具体做法见第四节的「8. 接入其他模型」。
官方服务只在 Anthropic 支持的国家和地区可用 [官1]。
2. 桌面 App(最简单)[1]
去 Claude 官网下载桌面 App,Windows 和 macOS 都有。Linux 版见官方文档 [官1]。
用 Claude 账号登录。
点左上角的 Code,就进来了。
App 里已经自带 Claude Code,不需要另外装 Node.js 或命令行工具 [1]。
3. 命令行(CLI)完整安装
系统要求 [官1]:macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+ 或 Alpine 3.19+;内存 4GB 以上;需要联网。
第一步:打开终端
macOS:打开「终端」或 iTerm2、Warp。
Windows:开始菜单搜「PowerShell」。看提示符分辨:行首有
PS C:\的是 PowerShell,只有C:\的是 CMD [官1]。Linux / WSL:打开系统终端。
第二步:运行安装命令(选一种)
| 方式 | 命令 | 会不会自动更新 |
|---|---|---|
| macOS / Linux / WSL 原生安装(官方推荐) | curl -fsSL https://claude.ai/install.sh | bash | 会,在后台自动更新 |
| 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 | 会 |
| Homebrew(macOS) | brew install --cask claude-code | 不会,要手动 brew upgrade claude-code |
| WinGet(Windows) | winget install Anthropic.ClaudeCode | 不会,要手动 winget upgrade Anthropic.ClaudeCode |
| npm(需要 Node.js 22+) | npm install -g @anthropic-ai/claude-code | 视权限而定 |
来源:官方安装文档 [官1],原生安装和 Homebrew 的命令在素材 [9] 里也有。
安装过程中没有进度条,等它跑完就行 [官1]。
想装稳定版(一般比最新版晚一周左右,会跳过有严重问题的版本):在原生安装命令后面加
stable,比如curl -fsSL https://claude.ai/install.sh | bash -s stable[官1]。npm 安装不要加
sudo,否则以后没法自动更新,还有权限问题 [官1]。命令输错终端的提示:看到
The token '&&' is not a valid statement separator,说明你在 PowerShell 里跑了 CMD 的命令;看到'irm' is not recognized,说明你在 CMD 里跑了 PowerShell 的命令 [官1]。
Windows 用户额外注意 [官1]
不需要用管理员身份运行。
建议装 Git for Windows。装了之后 Claude Code 用 Git Bash 跑命令;不装就用 PowerShell 跑。
如果它找不到 Git Bash,在
settings.json里指定路径:"env": {"CLAUDECODEGITBASHPATH": "C:\\Program Files\\Git\\bin\\bash.exe"}。原生 Windows 不支持沙箱(第五节会讲到)。需要沙箱,或者项目用的是 Linux 工具链的,在 WSL 2 里安装:打开 WSL 终端,运行 Linux 的那条安装命令。
第三步:检查有没有装好
关掉终端,重新打开一个(新装的命令要在新窗口里才能识别)。
输入
claude --version,能打印出版本号就说明装好了 [官1][2]。提示
command not found或「不是内部或外部命令」,说明安装目录还没加进 PATH,按官方的 Troubleshoot installation 页面修 [官1]。想做一次全面体检,运行
claude doctor。它会检查安装状态、配置文件有没有写错,以及上次自动更新的结果 [官1][2]。
图源:[2] 数字之心AI-Evangelist《Claude Code:入门使用》
第四步:第一次启动和登录
用
cd进入你的项目文件夹,输入claude。第一次在某个文件夹启动时,它会问是否信任这个文件夹,确认是自己的项目就选
Yes, continue[2]。登录方式有三种 [官1][官2]:
Claude 订阅账号:按提示在浏览器里登录。
Console API Key:如果提前设好了
ANTHROPICAPIKEY环境变量,启动时它会问要不要用这个 Key,同意后就跳过登录。第三方 / 国内模型:先按第四节第 8 小节配好接口地址和 Key,再启动。不想看首次引导界面,可以在
~/.claude.json里加"hasCompletedOnboarding": true[2][官4][官6]。
第五步:更新、换版本、卸载 [官1]
立即更新:
claude update。原生安装平时会在后台自动更新,新版本下次启动时生效。切换到稳定版:在会话里输入
/config,改 Auto-update channel;或者在settings.json里写"autoUpdatesChannel": "stable"。关闭自动更新:在
settings.json的env里加"DISABLE_AUTOUPDATER": "1"。卸载原生安装:macOS / Linux 删除
~/.local/bin/claude和~/.local/share/claude;Windows 删除%USERPROFILE%\.local\bin\claude.exe和%USERPROFILE%\.local\share\claude。用 Homebrew、WinGet、npm 装的,用对应的 uninstall 命令卸载。想把配置也清掉:删除
~/.claude文件夹和~/.claude.json。这样会把所有设置、MCP 配置和会话历史一起删掉,删之前先想清楚。
⚠️ 素材 [8] 是 Claude Code 创建者 Boris 的早期演讲,里面说「装了 Node.js 就能运行」,指的是旧的 npm 安装方式。现在官方推荐原生安装 [官1][9]。npm 还能用,但要求 Node.js 22 以上。DeepSeek 文档里写的是 Node.js 18 以上 [官3],两边要求不一样,以官方文档的 22 为准。
4. VS Code / Cursor 插件 [2][3]
打开 VS Code 的扩展市场,搜索
Claude Code。认准发布者是 Anthropic,市场里有好几个名字相近的第三方插件。
点 Install,弹出提示时选择信任。
装好后,编辑器右上角或侧边栏会出现 Claude Code 的图标,点开就能用。
图源:[2] 数字之心AI-Evangelist《Claude Code:入门使用》
不想用插件面板的话,打开 VS Code 自带的终端,直接输入
claude也行 [2]。JetBrains 系列(IDEA、PyCharm)同样是在自带的 Terminal 里输入claude[2]。素材 [2] 的作者在 Cursor 里试过用快捷键
Cmd+Esc打开插件,没有生效,最后是点界面上的图标打开的。用第三方模型时,插件的配置方法和 CLI 不完全一样,见第四节第 8 小节的「VS Code 插件怎么配」。
5. 常用命令行参数速查
| 命令 | 作用 |
|---|---|
claude | 在当前文件夹启动交互会话 |
claude --version / claude doctor / claude --help | 看版本 / 体检 / 看全部参数 [2] |
claude --continue / claude --resume | 接着上次的会话 / 从历史会话里挑一个恢复 [8] |
claude -p "任务" | 无界面模式,跑完直接输出结果(见第四节第 6 小节)[8][10] |
claude --permission-mode default | 用指定的权限模式启动(见第五节)[6] |
claude --add-dir ../别的目录 | 把另一个目录也加进工作范围 [7] |
claude update | 立即更新 [官1] |
三、上手流程:跑通第一个任务
下面以桌面 App 为例,素材 [1] 的步骤最完整。CLI 和 VS Code 插件的流程一样,只是界面不同。
1. 认识界面
Code 页分四块:左边是任务列表(每个任务叫一个 session),中间是对话记录,下面是输入栏,右边是结果面板 [1]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
开工前,先看一遍输入栏上的几样设置:
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
运行环境:Local 是你的电脑,Cloud 是 Anthropic 的服务器。下拉菜单里还有 Remote Control、WSL、SSH 这些选项。第一次用选 Local。
项目文件夹:它只在你选的这个文件夹里干活。
权限模式:它动手之前要不要先问你。第一次用选 Manual(见第五节)。
模型和思考强度:一开始保持默认就行。
/和@:输入/会弹出斜杠命令列表,输入@加文件名可以单独点名某个文件。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
2. 用一个练手文件夹跑第一次 [1]
新建一个「练手」文件夹,复制几张图片和文档进去。第一次用,别拿重要文件试。
运行环境选 Local,文件夹选「练手」,权限选 Manual。
发第一句话,比如:「看一下这个文件夹里有哪些文件,按类型分到不同的子文件夹里,文件名统一改成『日期-内容』的格式。最后生成一个目录.md。」
它每准备改一处,都会停下来给你看,下面有 Accept 和 Reject 两个按钮。你点 Accept 之前,文件不会被改。
改完以后会显示类似
+12 -0的数字,点开能逐行看改了什么。对哪一行不满意,可以直接在那一行写批注,让它照着改。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
最后加一句让它自查,能补上不少漏掉的地方:「检查一遍你刚才做的,有问题直接改,改完告诉我改了什么。」
3. 在 VS Code 里用是什么样
插件面板里的交互和桌面版一样。下图是在 Plan 模式下让它「做一个贪吃蛇游戏」:它先派了一个子任务去了解需求,再跑命令查看目录,没有直接开写 [2]。
图源:[2] 数字之心AI-Evangelist《Claude Code:入门使用》
4. 新手入门的顺序建议
先问、后改:Boris 建议先从「代码库问答」开始,比如这个类怎么用、为什么这个函数有 15 个参数、我这周交付了什么。Anthropic 新员工入职就是这么学的,熟悉代码库的时间从两三周缩短到两三天 [8]。
大任务先出方案:切到 Plan 模式,或者直接说「写代码之前先制定一个计划」,确认后再让它动手 [1][8]。做到一半才发现方向不对,最费时间,也最费额度 [1]。
给它检查自己的办法:有单元测试、截图之类的反馈手段时,它能自己迭代好几轮,结果明显更好 [8]。
四、核心功能与进阶玩法
1. CLAUDE.md:给它立规矩
CLAUDE.md 放在项目根目录,每次开工都会被自动读进上下文,相当于给 AI 的员工手册 [8][10]。
写什么:它自己猜不到的规矩、你的特殊习惯、踩过的坑、做完以后要干什么、常用命令和技术栈。官方的判断标准是:每写一行都问一句,删掉这一行它会不会犯错?不会就删 [1]。
不写什么:经常变的进度、空话、长篇背景介绍。进度单独放进一份项目文档,再在 CLAUDE.md 里写一句「开工前先读项目文档」[1]。
长度:控制在 200 行以内,太长的话重要规矩会被淹没 [1][8]。
分层:可以有全局、项目、本地和子目录几层。项目里的提交到仓库和团队共享,本地的留给自己,子目录里的在它进到那个目录时才读 [8][10]。
快速生成:输入
/init,它会扫描整个项目生成初稿;也可以让它一个一个问你问题,再帮你写 [1]。记忆:说「记住,以后都用 XX」,它会存进自动记忆 MEMORY.md;说「把这条加进 CLAUDE.md」才会写进 CLAUDE.md。用
/memory可以查看和开关这些记忆 [1][8]。项目里已经有 Codex 的 AGENTS.md 的话,Claude Code 也能读 [1]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
2. 上下文管理:对话太长了怎么办
每个对话能装的内容有上限,装得越满越容易忘事和出错 [1]。点模型旁边的小圆环,能看到这个对话用掉了多少空间,还有套餐用量和重置时间;输入 /context 能看到空间被什么占了 [1]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
快满的时候有几个办法 [1]:
/compact:把前面的对话压成摘要,还可以指定要保留什么,比如/compact 保留选题列表和我定的规矩。让它把进度写进项目文档,新开一个 session 接着做。
一件事一个 session。同一个问题纠正两次还不对,就新开一个。
临时问一句时,用
/btw或Ctrl+;开侧边小对话,不占主任务的空间 [1][4]。侧边对话能读到主会话的内容,但不会写回主会话 [4]。
3. 扩展四件套:Commands、Skills、Sub-agents、Hooks
素材 [10] 的口诀:Commands 是「你让它做什么」,Skills 是「它自己知道该怎么做」,Sub-agents 是「它把活派出去」,Hooks 是「不管谁做,到这一步必须检查」。
Skills:把一套反复交代的做法存成一个文件夹,核心是一个 SKILL.md。它平时只看描述,需求对上了才读全文,所以多装几个也不怎么占空间 [1][10]。可以等它自动匹配,也可以输入
/技能名点名调用。同一件事一周要做 3 次以上,就值得做成 Skill:做完一次后说「把刚才的流程做成一个 Skill」,skill-creator 会帮你写好 [1]。Sub-agents:放在
.claude/agents/下,每个代理有独立的上下文,干完只把结论带回主会话。适合改动多、文件多的任务,权限可以给到最小,比如审查代理只能读不能改 [10]。Hooks:在工具调用前后、回复结束前触发你的脚本。比如提交前先跑一遍 lint,没过就拦下。脚本以退出码 2 结束,这次调用就会被拦下 [10]。
学习顺序:先写 CLAUDE.md,再学 Commands,然后是 Skills、Hooks,最后是 Sub-agents。每样在真实项目里用两周再学下一个 [10]。
桌面 App 里,Skills、插件、Connectors 统一在左边栏的 Customize 里管理 [1]:
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
⚠️ 本地
.claude\skills文件夹里的 Skill,云端 session 用不了。要在云端用,得在 Customize 里把它加到账号上 [1]。
4. 插件和 MCP
插件:打包好的工具箱,里面可以有几个 Skill 和 Connector。点输入框的 + → Add plugins,在 Discover 里搜索并添加,装好的在 Yours 里管理 [1]。素材 [1] 推荐了 claude-code-setup、claude-md-management、superpowers、frontend-design 等官方市场的插件。插件别一次装太多,每个开着的插件都会占用对话空间。带 Community 标的是第三方做的,装之前先看看作者 [1]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
MCP:在项目根目录的
.mcp.json里配置服务,就能接入数据库、GitHub Issue、Jira 等外部系统 [10]。这个配置文件提交到仓库后,团队成员打开时会收到安装提示 [8]。Anthropic 内部就在网页项目里共享了一个 Puppeteer MCP,用来自动截图、跑端到端测试 [8]。
5. 多任务并行与云端
本地并行:10 月中旬的桌面版更新后,让它并行做几件事,它会给每件事开一个子会话,做完把结果汇报给主会话。侧边栏会标出哪个任务在跑、哪个在等你;常用的文件夹、SSH 主机和云端配置可以存成环境,开任务时还能选择建 Git worktree,把不同任务的改动隔开 [4]。
交给云端:云端任务从 GitHub 上把项目拉下来干活,所以要先连 GitHub,在 claude.ai/code 上授权 Claude 的 GitHub App 就行 [1]。本地任务想交给云端继续,先让它把改动提交,再在 session 标题的菜单里选 Open in → Continue in → Cloud [1]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
手机遥控:在本地 session 里输入
/remote-control(或/rc),手机 Claude App 的 Code 页就能接着操作。前提是电脑开着、App 没关 [1]。素材 [2] 介绍的是第三方工具 Happy(npm i -g happy-coder),官方的 Remote Control 出来后,一般不需要再装它了。
6. 命令行进阶:Headless 和管道
claude -p "任务"是无界面模式:不进入对话,跑完直接输出结果,适合 CI、脚本和流水线 [8][10]。常用参数:--output-format json让脚本能解析结果,--max-turns限制轮次和花费,--allowedTools用白名单限定它能用的工具 [10]。可以把它当成一个 Unix 工具,用管道传进日志、
git status的结果,再用 jq 处理输出 [8]。需要写代码控制时,可以用 Agent SDK(Python / TypeScript),日常开发用不到这一层 [10]。
想系统学进阶用法,可以看开源教程 claude-howto(github.com/luongnv89/claude-howto)。它分 10 个模块,附可以直接复制的配置模板,有中文版 [9]。
7. 常用快捷键与命令
| 操作 | 作用 | 来源 |
|---|---|---|
Shift+Tab | 切换权限模式(新旧版本行为不同,见第五节 ⚠️) | [2][6][8] |
Esc | 随时打断它,会话保持完整,可以接着说怎么改 | [8] |
连按两次 Esc | 跳回历史消息 | [8] |
! + 命令 | 自己直接跑一条 Shell 命令,结果会进入上下文 | [8] |
@ + 文件名 | 把某个文件或文件夹加进上下文 | [1][2][8] |
Ctrl+R | 查看完整输出 | [8] |
claude --resume / --continue | 恢复之前的会话 | [8] |
/compact、/context、/memory、/init | 压缩对话、查看占用、管理记忆、生成 CLAUDE.md | [1] |
/plan、/btw | 进入计划模式、开侧边小对话 | [1][4] |
桌面版 Ctrl+N / Ctrl+; / Ctrl+/ | 新开 session / 侧边小对话 / 查看全部快捷键(Mac 用 Cmd) | [1] |
| 拖入、粘贴图片 | 发设计稿让它照着实现,它能直接看图 | [8] |
8. 接入其他模型:API Key 配置详解
没有 Claude 订阅、想省钱,或者想用国内模型时,可以让 Claude Code 连到别的平台。原理很简单:Claude Code 通过几个环境变量决定「请求发到哪」「用什么 Key」「每一档用哪个模型」。只要平台提供 Anthropic 兼容接口,改这几个变量就能用 [官2][5]。
8.1 要配的几个变量
| 变量 | 作用 | 说明 |
|---|---|---|
ANTHROPICBASEURL | 请求发到哪个地址 | 填平台给的 Anthropic 兼容地址 |
ANTHROPICAUTHTOKEN | 你的 Key,以 Authorization: Bearer 请求头发送 | 大多数国内平台用这个 |
ANTHROPICAPIKEY | 你的 Key,以 x-api-key 请求头发送 | 少数平台用这个(如 Kimi Code)。交互模式下第一次会弹窗让你确认 |
ANTHROPIC_MODEL | 主对话用的模型 | 填平台的模型名 |
ANTHROPICDEFAULTOPUSMODEL / SONNETMODEL / HAIKU_MODEL | Claude Code 内部三档模型分别换成哪个 | 不配的话,它会按 Claude 的模型名去请求,平台可能报「模型不存在」 |
CLAUDECODESUBAGENT_MODEL | 子代理用的模型 | 可选 |
CLAUDECODEAUTOCOMPACTWINDOW | 自动压缩上下文的窗口大小 | 要和模型实际的上下文长度一致 |
来源:官方文档 [官2],各平台文档 [官3]~[官6]。
用哪个 Key 变量? 平台文档写的是哪个就用哪个。文档没写的,先用
ANTHROPICAUTHTOKEN;报 401 就换成ANTHROPICAPIKEY再试 [官2]。两个变量的区别只是 Key 放在哪个请求头里,平台读不到就会 401。
8.2 三种配置方式(选一种,别混用)
方式 A:临时设置,只对当前终端窗口有效(适合第一次测试)
macOS / Linux:
export ANTHROPIC_BASE_URL=https://平台给的地址
export ANTHROPIC_AUTH_TOKEN=你的Key
claudeWindows PowerShell:
$env:ANTHROPIC_BASE_URL = "https://平台给的地址"
$env:ANTHROPIC_AUTH_TOKEN = "你的Key"
claude关掉这个终端,设置就没了。想一直生效,可以把这几行加进 ~/.zshrc、~/.bashrc 或 PowerShell 的 $PROFILE [官2]。
方式 B:写进用户配置,所有项目都生效(最常用)
编辑 ~/.claude/settings.json。Windows 的路径是 C:\Users\你的用户名\.claude\settings.json,文件不存在就新建一个:
{
"env": {
"ANTHROPIC_BASE_URL": "https://平台给的地址",
"ANTHROPIC_AUTH_TOKEN": "你的Key",
"ANTHROPIC_MODEL": "平台的模型名",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "平台的模型名",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "平台的模型名",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "平台的轻量模型名"
}
}文件里原来有别的设置的话,只改 env 这一块,其余保留 [5]。
方式 C:只对某个项目生效
写进项目里的 .claude/settings.local.json,格式同上 [3]。一定要把这个文件加进 .gitignore,免得把 Key 提交上去 [3][官2]。不要写进 .claude/settings.json,那个文件会提交到仓库,和所有人共享 [官2]。
⚠️ 临时变量和配置文件同时设了,听谁的? 官方文档 [官2] 和 Kimi 文档 [官5] 都说配置文件里的
env优先;MiniMax 文档 [官6] 却说终端里的环境变量优先级更高,要先清掉。各方说法不一致,最稳妥的做法是只用一种方式,配之前先检查~/.zshrc、~/.bashrc等文件里有没有残留的旧ANTHROPIC_*变量 [官5][官6]。
不想手改 JSON 的办法
让别的 AI 工具帮你改:素材 [5] 用 TRAE 写入配置。思路是把平台的配置模板和你的 Key 交给它,让它先备份旧文件,只替换
env,写完自己读回来核对一遍。智谱提供了一键脚本(只支持 macOS / Linux):
curl -O "https://cdn.bigmodel.cn/install/claudecodeenv.sh" && bash ./claudecodeenv.sh[官4]。素材 [2] 用的是第三方工具 cc-switch,可以在多套配置之间切换。阿里云文档也提到了它(CC Switch)[官7]。
8.3 国内常见平台的接口地址
| 平台 | ANTHROPICBASEURL | Key 变量 | 要点 |
|---|---|---|---|
| DeepSeek | https://api.deepseek.com/anthropic | ANTHROPICAUTHTOKEN | Key 在 DeepSeek 开放平台申请 [官3] |
| 智谱 GLM 编程套餐 | https://open.bigmodel.cn/api/anthropic | ANTHROPICAUTHTOKEN | 个人套餐、团队套餐和标准 API 的 Key 不通用 [官4] |
| Kimi Code | https://api.kimi.com/coding/ | ANTHROPICAPIKEY | Key 只在创建时完整显示一次;只支持思考模式 [官5] |
| 阿里云百炼 Coding Plan | https://coding.dashscope.aliyuncs.com/apps/anthropic | ANTHROPICAUTHTOKEN | 地址末尾不要加 /v1 [官7] |
| 阿里云百炼 Token Plan | https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic | ANTHROPICAUTHTOKEN | 分个人版和团队版 Key [官7] |
| 阿里云百炼 按量计费 | https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic | ANTHROPICAUTHTOKEN | 把 {WorkspaceId} 换成控制台里的真实值 [官7][5] |
| MiniMax 国内订阅 | https://api.minimax.cn/anthropic | ANTHROPICAUTHTOKEN | 思考关不掉 [官6] |
| 火山方舟 Coding Plan | 见火山方舟官方文档 | — | 默认模型是豆包 Seed 2.1 Pro [5] |
查阅日期:2026-11-07。 模型名更新很快,这里没有列出。模型名请直接从平台文档复制,选错了会报「模型不存在」或 403 [5][官7]。各平台文档的链接见文末「官方文档补充」。
上表的接口地址是 2026-11-07 从各平台官方文档查到的,不来自公众号素材。素材 [5] 给出了这些平台的官方接入文档链接。
8.4 VS Code 插件怎么配
插件第一次打开会要求登录官方账号。用第三方模型时,把 Key 和地址写进上面的
settings.json,然后完全退出 VS Code 再重新打开 [3][5]。官方文档更推荐写在 VS Code 自己的用户设置里(命令面板 → Preferences: Open User Settings (JSON))。原因是插件启动前会先检查登录,这一步只读这里的设置 [官2]:
{
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://平台给的地址" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "你的Key" }
]
}插件还是提示登录的话:素材 [2] 的做法是在
~/.claude.json里加"hasCompletedOnboarding": true;Kimi 文档的做法是先在插件里点 Runclaudein terminal 完成两步确认,再重启 VS Code [官5]。
8.5 配完怎么验证
新开一个终端,进入项目文件夹,运行
claude。输入
/status,看两行:Anthropic base URL是不是你填的地址;Auth token或API key那一行显示的是不是你设的变量 [官2]。如果显示的是 claude.ai 账号登录,说明配置没生效。输入
/model,确认当前模型是你想用的 [官6]。随便发一句「你好」,能正常回复就说明通了 [5]。
还不行的话,可以绕开 Claude Code,直接用 curl 测一下接口和 Key(命令见官方文档 [官2] 的 Verify the connection 一节)。curl 报 401 就是 Key 或变量用错了;报「模型不存在」反而说明地址和 Key 都没问题 [官2]。
8.6 常见报错对照
| 现象 | 可能原因 | 怎么办 |
|---|---|---|
401 / invalidapikey | Key 错了;Key 和地址不是同一个套餐的;Key 变量用错了 | 回平台核对套餐;换另一个 Key 变量试试 [5][官2][官7] |
403 / access_denied | 套餐没有这个模型的权限,或者模型即将下线 | 换成套餐里有的模型 [5][官7] |
| 「模型不存在」 | 模型名和套餐对不上,或者 Claude Code 版本太旧 | 从平台文档复制模型名;运行 claude update [5][官4] |
| 余额不足 / 额度用完 | 平台账户的问题 | 到平台控制台查看 [5] |
| 启动后还是要求登录官方账号 | 变量没生效 | 新开终端;检查 JSON 格式(逗号、引号);在 ~/.claude.json 里加 hasCompletedOnboarding [2][官4] |
| 启动时警告有两个凭证来源(auth conflict) | 设了 Key 变量,同时还保留着 claude.ai 登录 | 运行 /logout 退出官方登录,或者删掉 Key 变量 [官2] |
设了 ANTHROPICAPIKEY 却被忽略 | 之前弹窗时拒绝过这个 Key | 在 /config 里打开 Use custom API key [官2] |
| 400,提示上下文或 token 超限 | 平台的上下文比 Claude Code 以为的短 | 先 /compact;把 CLAUDECODEAUTOCOMPACTWINDOW 设成平台的上限 [官2][官5] |
8.7 换了模型以后,有些功能用不了
用第三方 Key 或接口地址时,Remote Control(手机遥控)和语音输入都用不了,云端任务也不会走你配的接口 [官2]。
第三方模型对 Claude Code 新功能的支持程度不一,比如思考档位能不能关 [官5][官6]。遇到怪问题,先换回官方模型对比一下。
桌面 App 不读
settings.json里的接口地址。要在桌面 App 里用第三方模型,得开开发者模式,在第三方推理配置里填写 [官2]。
⚠️ 素材 [3] 是代理服务商 Ace Data Cloud 写的接入教程,素材 [5] 是一套课程的配套材料。这里只采用了其中的通用配置方法。第三方中转服务的稳定性和合规性需要自己判断,Key 只留在自己的电脑上 [5]。
五、避坑与注意
1. 权限模式怎么选
图源:[6] 徐尘心 丨AI Notes(截自 Claude Code 官方文档《Choose a permission mode》)
| 模式 | 不问你就能做的事 | 什么时候用 |
|---|---|---|
| Manual(配置值 default) | 只能读文件 | 第一次用、生产配置、密钥相关、陌生的开源仓库 [1][6] |
| Accept edits | 读文件、改文件、常见文件命令 | 方向已经对了,让它连续改 [1][8] |
| Plan | 只读,先出方案 | 大任务动手前 [1] |
| Auto | 全部放行,后台有安全检查拦截风险操作 | 日常开发、长任务 [6] |
| bypassPermissions(跳过权限) | 全部放行,没有任何防护 | 只在容器或虚拟机里用 [6] |
素材 [6] 的观点是:日常默认用 Auto,再写几条 deny / ask 规则兜底。理由是用户对权限弹窗的同意率高达 97%,点多了就成了肌肉记忆。官方对照实验里,人工只拦下 13.6% 的危险命令,Auto 拦下了 89%。不过 Auto 在另一组测试里也有 17% 的漏检,所以真正不能出错的事要写成规则:
{
"permissions": {
"deny": ["Bash(git push *)"],
"allow": ["Bash(npm test)"]
}
}规则按 deny → ask → allow 的顺序匹配。deny 在所有模式下都生效,跳过权限模式也拦得住 [6]。
⚠️
Bash(git push *)匹配不到git -C . push这种写法,别以为写一条规则就万无一失 [6]。被 Auto 误拦了:输入
/permissions,在 Recently denied 里按r批准重试。同一个会话连续被拦 3 次,或累计被拦 20 次,会退回人工审批 [6]。桌面 App 的 Settings → Claude Code 里有一个 Allow bypass permissions mode 开关,新手千万别开 [1]。用 root 或 sudo 跑
--dangerously-skip-permissions,它会拒绝启动 [6]。
图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》
⚠️ 默认模式变了:官方文档写的是 v2.1.283 起,没有配置权限模式时直接以 Auto 启动 [6];素材 [1] 也说新版默认就是 Auto。早期教程默认的是逐条确认,看旧教程时要注意,想逐条确认得手动切到 Manual。
⚠️
Shift+Tab的行为说法不一:Boris 的早期演讲 [8] 和素材 [2] 说按一下是切到自动接受编辑;10 月底的素材 [6] 说是在模式之间循环(从 Auto 按一次回到 default,之后在 default、acceptEdits、plan 之间轮换)。以你当前版本的实际表现为准。
2. 防止它改到项目外的文件
素材 [7] 提到了真实的误删案例:Agent 在收尾清理时删到了项目外的文件,还有一次把用户的主目录删了。防护要分两层:
图源:[7] 架构师《如何限制 Claude Code 修改项目外的文件?》
从哪个目录启动很重要:只改
order-service就从这个目录启动。从父目录启动的话,旁边的项目都会算进工作范围 [7]。文件工具的写入开关(2.1.314 起):在
.claude/settings.local.json里加上"blockWritesOutsideWorkingDirectories": true,它直接改文件时就不能写工作目录以外的地方,所有权限模式下都生效 [7]。Bash 沙箱:测试脚本之类的命令写文件,上面的开关拦不住,要开
sandbox。macOS 自带沙箱;Linux 和 WSL2 要先运行/sandbox装依赖;原生 Windows 暂不支持 [7]。用
--add-dir加进来参考的目录,也会被算进工作范围,加进来不等于只给了读取权限 [7]。
3. 其他提醒
API Key 这类密码不要写进 CLAUDE.md 和项目文档。桌面版可以在 Local 环境的设置里存成环境变量,它会加密保存在本机 [1]。
撤回只管它用编辑功能改过的文件。发出去的邮件、调用过的外部服务撤不回来,这类操作最好在 Manual 模式下自己看一眼再同意 [1]。
Skill 里的规矩别写太多。素材 [1] 的作者一开始加了一大堆限制,效果反而变差了,后来只留最必要的几条。
项目目录名别用中文和空格,以英文字母开头(素材 [2] 作者的经验,不是官方要求)。
⚠️ 可能已过时的写法:
素材 [8] 是 Boris 的早期演讲(公众号 10 月整理发布,演讲本身更早)。演讲里的「输入
#让它记住」「Claude Code SDK」「/install-github-app」,10 月的其他素材都没有再提。现在一般说「记住 XX」或用/memory管理记忆 [1],SDK 也改叫 Agent SDK 了 [10]。素材 [2] 的
claude config set -g verbose true(显示 token 和计时)是作者的用法,新版是否还能用,没在其他素材里得到印证。素材 [9] 用的是把文件复制进
.claude/commands/的方式加自定义命令;素材 [10] 说现在的自定义命令其实是用 Skills 实现的。两种写法都还在流传,新做的建议放进.claude/skills/。素材 [2] 提到的「在提示词里写 ultrathink 触发深度思考」是作者的经验。桌面版现在可以直接在输入栏选思考强度 [1]。
六、参考原文
| # | 标题 | 公众号 | 发布 | 本指南用到的内容 | 用图 |
|---|---|---|---|---|---|
| 1 | Claude Code 从 0 到 1 小白保姆级教程-附图解实操 | Serena 木瓜-探索 AI | 2026-10-09 | 桌面版全流程、CLAUDE.md、上下文、插件、Skills、云端与遥控 | 01、02、03、04、05、10、11、12、13、14、15 |
| 2 | Claude Code:入门使用 | 数字之心AI-Evangelist | 2026-11-01 | VS Code 插件和终端用法、常用 CLI 命令 | 06、07、08 |
| 3 | Claude Code for VS Code 使用教程 | 进击的Coder | 2026-10-31 | 插件安装、settings 配置的生效范围(作者是代理服务商) | — |
| 4 | Claude Code桌面版大更新:多任务并行,自动交作业! | 智猩猩AI | 2026-10-15 | 子会话、侧边对话、环境与 worktree | — |
| 5 | Claude Code 模型配置说明 | 氛围编程实验室 | 2026-10-28 | 国内模型接入、Key 与套餐、常见报错 | — |
| 6 | 用 Claude Code 写代码:该手动批准、开 auto,还是跳过权限?3 种场景怎么选 | 徐尘心 丨AI Notes | 2026-10-30 | 权限模式、规则写法、默认 Auto | 09 |
| 7 | 如何限制 Claude Code 修改项目外的文件? | 架构师 | 2026-10-31 | 写入边界开关、Bash 沙箱 | 16 |
| 8 | Claude Code 创建者亲授:从入门到进阶的实战技巧 | 沐秋他爹 | 2026-10-07 | 入门顺序、工作流、快捷键、-p 管道(早期演讲整理) | — |
| 9 | 43.1K+ Star! claude-howto:一个周末掌握 Claude Code 全部高级用法 | AIGC创想者 | 2026-10-25 | 原生安装命令、claude-howto 学习路线 | — |
| 10 | 用了两周 Claude Code,三个问题一起爆 | 特立独行的运维鸭 | 2026-10-31 | 四层体系、扩展四件套、Headless、学习顺序 | — |
官方文档补充(2026-11-07 查阅,用于第二节安装和第四节第 8 小节)
| # | 文档 | 用到的内容 |
|---|---|---|
| 官1 | Claude Code:Advanced setup | 系统要求、各平台安装命令、Windows 说明、更新与卸载、账号要求 |
| 官2 | Claude Code:Connect Claude Code to an LLM gateway | 接口地址和 Key 变量、配置文件优先级、VS Code 插件配置、/status 验证、报错对照、功能限制 |
| 官3 | DeepSeek:接入 Claude Code | DeepSeek 接口地址与变量 |
| 官4 | 智谱:Claude Code 接入 GLM Coding Plan | 智谱接口地址、一键脚本、Key 不通用 |
| 官5 | Kimi Code:在 Claude Code 中使用 | Kimi 接口地址、用 ANTHROPIC_API_KEY、VS Code 插件确认步骤 |
| 官6 | MiniMax:M Plan 接入 Claude Code | MiniMax 接口地址、环境变量优先级说法、/model 验证 |
| 官7 | 阿里云百炼:Claude Code 接入 | 百炼三种套餐的接口地址、401/403 说明 |
图片清单
| 图 | 文件 | 出处 |
|---|---|---|
| 01 | images/01-六级路线图.png | [1] 配图 01 |
| 02 | images/02-桌面版Code四个区域.png | [1] 配图 06 |
| 03 | images/03-输入栏.png | [1] 配图 07 |
| 04 | images/04-运行环境菜单.png | [1] 配图 10 |
| 05 | images/05-改动对比.png | [1] 配图 12 |
| 06 | images/06-VSCode安装插件.png | [2] 第 1 张 |
| 07 | images/07-VSCode插件面板.png | [2] 第 4 张 |
| 08 | images/08-终端启动并信任文件夹.png | [2] 第 10 张 |
| 09 | images/09-权限模式对照表.jpg | [6] 第 1 张(官方文档截图) |
| 10 | images/10-CLAUDE.md示例.png | [1] 配图 13 |
| 11 | images/11-上下文与额度.png | [1] 配图 14 |
| 12 | images/12-插件页.png | [1] 配图 18 |
| 13 | images/13-Skills页.jpg | [1] 配图 20 |
| 14 | images/14-交给云端继续.png | [1] 配图 16 |
| 15 | images/15-跳过权限开关.png | [1] 配图 19 |
| 16 | images/16-写入开关与沙箱.png | [7] 图 01 |
说明:素材 [1] 正文里的配图编号和图片上印的编号有错位(比如正文写「配图 11」,图上印的是「配图 12」),上表按图片上印的编号记。