天工开物KAIWU AI
工具指南 › Claude Code › Claude Code 使用指南(完整全套)
核实于 2026-11-07
工具指南·其一核实于 2026-11-07

Claude Code 使用指南(完整全套)

适用对象
想快速了解工具定位、核心功能和上手路径的中文用户
核对日期
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 用 Claude 的六级路线图

图源:[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]

  1. 去 Claude 官网下载桌面 App,Windows 和 macOS 都有。Linux 版见官方文档 [官1]。

  2. 用 Claude 账号登录。

  3. 点左上角的 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 的那条安装命令。

第三步:检查有没有装好

  1. 关掉终端,重新打开一个(新装的命令要在新窗口里才能识别)。

  2. 输入 claude --version,能打印出版本号就说明装好了 [官1][2]。

  3. 提示 command not found 或「不是内部或外部命令」,说明安装目录还没加进 PATH,按官方的 Troubleshoot installation 页面修 [官1]。

  4. 想做一次全面体检,运行 claude doctor。它会检查安装状态、配置文件有没有写错,以及上次自动更新的结果 [官1][2]。

图 2 在 VS Code 终端里输入 claude 启动,第一次会询问是否信任当前文件夹

图源:[2] 数字之心AI-Evangelist《Claude Code:入门使用》

第四步:第一次启动和登录

  1. 用 cd 进入你的项目文件夹,输入 claude。

  2. 第一次在某个文件夹启动时,它会问是否信任这个文件夹,确认是自己的项目就选 Yes, continue [2]。

  3. 登录方式有三种 [官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]

  1. 打开 VS Code 的扩展市场,搜索 Claude Code。

  2. 认准发布者是 Anthropic,市场里有好几个名字相近的第三方插件。

  3. 点 Install,弹出提示时选择信任。

  4. 装好后,编辑器右上角或侧边栏会出现 Claude Code 的图标,点开就能用。

图 3 VS Code 扩展市场里搜 claude code,认准 Anthropic 发布的那个

图源:[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]。

图 4 Code 工作台的四个区域

图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》

开工前,先看一遍输入栏上的几样设置:

图 5 输入栏:运行环境、项目文件夹、附件与权限、模型与用量

图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》

  • 运行环境:Local 是你的电脑,Cloud 是 Anthropic 的服务器。下拉菜单里还有 Remote Control、WSL、SSH 这些选项。第一次用选 Local。

  • 项目文件夹:它只在你选的这个文件夹里干活。

  • 权限模式:它动手之前要不要先问你。第一次用选 Manual(见第五节)。

  • 模型和思考强度:一开始保持默认就行。

  • / 和 @:输入 / 会弹出斜杠命令列表,输入 @ 加文件名可以单独点名某个文件。

图 6 运行环境菜单

图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》

2. 用一个练手文件夹跑第一次 [1]

  1. 新建一个「练手」文件夹,复制几张图片和文档进去。第一次用,别拿重要文件试。

  2. 运行环境选 Local,文件夹选「练手」,权限选 Manual。

  3. 发第一句话,比如:「看一下这个文件夹里有哪些文件,按类型分到不同的子文件夹里,文件名统一改成『日期-内容』的格式。最后生成一个目录.md。」

  4. 它每准备改一处,都会停下来给你看,下面有 Accept 和 Reject 两个按钮。你点 Accept 之前,文件不会被改。

  5. 改完以后会显示类似 +12 -0 的数字,点开能逐行看改了什么。对哪一行不满意,可以直接在那一行写批注,让它照着改。

图 7 点开改动数字,逐行查看新增内容

图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》

  1. 最后加一句让它自查,能补上不少漏掉的地方:「检查一遍你刚才做的,有问题直接改,改完告诉我改了什么。」

3. 在 VS Code 里用是什么样

插件面板里的交互和桌面版一样。下图是在 Plan 模式下让它「做一个贪吃蛇游戏」:它先派了一个子任务去了解需求,再跑命令查看目录,没有直接开写 [2]。

图 8 VS Code 插件面板,Plan 模式下先调研再出方案

图源:[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]。

图 9 CLAUDE.md 只写红线,并要求先读项目文档

图源:[1] Serena 木瓜《Claude Code 从 0 到 1 小白保姆级教程》

2. 上下文管理:对话太长了怎么办

每个对话能装的内容有上限,装得越满越容易忘事和出错 [1]。点模型旁边的小圆环,能看到这个对话用掉了多少空间,还有套餐用量和重置时间;输入 /context 能看到空间被什么占了 [1]。

图 10 上下文空间与套餐额度

图源:[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]:

图 11 Customize 里的 Skills:上面是自己做的,下面是 Anthropic 和合作方提供的

图源:[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]。

图 12 Plugins 页:Discover 里搜索添加,Yours 里管理

图源:[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]。

图 13 把本地任务交给云端继续

图源:[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_MODELClaude Code 内部三档模型分别换成哪个不配的话,它会按 Claude 的模型名去请求,平台可能报「模型不存在」
CLAUDECODESUBAGENT_MODEL子代理用的模型可选
CLAUDECODEAUTOCOMPACTWINDOW自动压缩上下文的窗口大小要和模型实际的上下文长度一致

来源:官方文档 [官2],各平台文档 [官3]~[官6]。

用哪个 Key 变量? 平台文档写的是哪个就用哪个。文档没写的,先用 ANTHROPICAUTHTOKEN;报 401 就换成 ANTHROPICAPIKEY 再试 [官2]。两个变量的区别只是 Key 放在哪个请求头里,平台读不到就会 401。

8.2 三种配置方式(选一种,别混用)

方式 A:临时设置,只对当前终端窗口有效(适合第一次测试)

macOS / Linux:

bash
export ANTHROPIC_BASE_URL=https://平台给的地址
export ANTHROPIC_AUTH_TOKEN=你的Key
claude

Windows PowerShell:

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,文件不存在就新建一个:

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 国内常见平台的接口地址

平台ANTHROPICBASEURLKey 变量要点
DeepSeekhttps://api.deepseek.com/anthropicANTHROPICAUTHTOKENKey 在 DeepSeek 开放平台申请 [官3]
智谱 GLM 编程套餐https://open.bigmodel.cn/api/anthropicANTHROPICAUTHTOKEN个人套餐、团队套餐和标准 API 的 Key 不通用 [官4]
Kimi Codehttps://api.kimi.com/coding/ANTHROPICAPIKEYKey 只在创建时完整显示一次;只支持思考模式 [官5]
阿里云百炼 Coding Planhttps://coding.dashscope.aliyuncs.com/apps/anthropicANTHROPICAUTHTOKEN地址末尾不要加 /v1 [官7]
阿里云百炼 Token Planhttps://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropicANTHROPICAUTHTOKEN分个人版和团队版 Key [官7]
阿里云百炼 按量计费https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropicANTHROPICAUTHTOKEN把 {WorkspaceId} 换成控制台里的真实值 [官7][5]
MiniMax 国内订阅https://api.minimax.cn/anthropicANTHROPICAUTHTOKEN思考关不掉 [官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]:

json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://平台给的地址" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "你的Key" }
  ]
}
  • 插件还是提示登录的话:素材 [2] 的做法是在 ~/.claude.json 里加 "hasCompletedOnboarding": true;Kimi 文档的做法是先在插件里点 Run claude in terminal 完成两步确认,再重启 VS Code [官5]。

8.5 配完怎么验证

  1. 新开一个终端,进入项目文件夹,运行 claude。

  2. 输入 /status,看两行:Anthropic base URL 是不是你填的地址;Auth token 或 API key 那一行显示的是不是你设的变量 [官2]。如果显示的是 claude.ai 账号登录,说明配置没生效。

  3. 输入 /model,确认当前模型是你想用的 [官6]。

  4. 随便发一句「你好」,能正常回复就说明通了 [5]。

还不行的话,可以绕开 Claude Code,直接用 curl 测一下接口和 Key(命令见官方文档 [官2] 的 Verify the connection 一节)。curl 报 401 就是 Key 或变量用错了;报「模型不存在」反而说明地址和 Key 都没问题 [官2]。

8.6 常见报错对照

现象可能原因怎么办
401 / invalidapikeyKey 错了;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. 权限模式怎么选

图 14 官方文档里各权限模式的对照表

图源:[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% 的漏检,所以真正不能出错的事要写成规则:

json
{
  "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]。

图 15 Settings 里的跳过权限开关,保持关闭

图源:[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 在收尾清理时删到了项目外的文件,还有一次把用户的主目录删了。防护要分两层:

图 16 文件工具和 Bash 命令的写入要分开限制

图源:[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]。


六、参考原文

#标题公众号发布本指南用到的内容用图
1Claude Code 从 0 到 1 小白保姆级教程-附图解实操Serena 木瓜-探索 AI2026-10-09桌面版全流程、CLAUDE.md、上下文、插件、Skills、云端与遥控01、02、03、04、05、10、11、12、13、14、15
2Claude Code:入门使用数字之心AI-Evangelist2026-11-01VS Code 插件和终端用法、常用 CLI 命令06、07、08
3Claude Code for VS Code 使用教程进击的Coder2026-10-31插件安装、settings 配置的生效范围(作者是代理服务商)—
4Claude Code桌面版大更新:多任务并行,自动交作业!智猩猩AI2026-10-15子会话、侧边对话、环境与 worktree—
5Claude Code 模型配置说明氛围编程实验室2026-10-28国内模型接入、Key 与套餐、常见报错—
6用 Claude Code 写代码:该手动批准、开 auto,还是跳过权限?3 种场景怎么选徐尘心 丨AI Notes2026-10-30权限模式、规则写法、默认 Auto09
7如何限制 Claude Code 修改项目外的文件?架构师2026-10-31写入边界开关、Bash 沙箱16
8Claude Code 创建者亲授:从入门到进阶的实战技巧沐秋他爹2026-10-07入门顺序、工作流、快捷键、-p 管道(早期演讲整理)—
943.1K+ Star! claude-howto:一个周末掌握 Claude Code 全部高级用法AIGC创想者2026-10-25原生安装命令、claude-howto 学习路线—
10用了两周 Claude Code,三个问题一起爆特立独行的运维鸭2026-10-31四层体系、扩展四件套、Headless、学习顺序—

官方文档补充(2026-11-07 查阅,用于第二节安装和第四节第 8 小节)

#文档用到的内容
官1Claude Code:Advanced setup系统要求、各平台安装命令、Windows 说明、更新与卸载、账号要求
官2Claude Code:Connect Claude Code to an LLM gateway接口地址和 Key 变量、配置文件优先级、VS Code 插件配置、/status 验证、报错对照、功能限制
官3DeepSeek:接入 Claude CodeDeepSeek 接口地址与变量
官4智谱:Claude Code 接入 GLM Coding Plan智谱接口地址、一键脚本、Key 不通用
官5Kimi Code:在 Claude Code 中使用Kimi 接口地址、用 ANTHROPIC_API_KEY、VS Code 插件确认步骤
官6MiniMax:M Plan 接入 Claude CodeMiniMax 接口地址、环境变量优先级说法、/model 验证
官7阿里云百炼:Claude Code 接入百炼三种套餐的接口地址、401/403 说明

图片清单

图文件出处
01images/01-六级路线图.png[1] 配图 01
02images/02-桌面版Code四个区域.png[1] 配图 06
03images/03-输入栏.png[1] 配图 07
04images/04-运行环境菜单.png[1] 配图 10
05images/05-改动对比.png[1] 配图 12
06images/06-VSCode安装插件.png[2] 第 1 张
07images/07-VSCode插件面板.png[2] 第 4 张
08images/08-终端启动并信任文件夹.png[2] 第 10 张
09images/09-权限模式对照表.jpg[6] 第 1 张(官方文档截图)
10images/10-CLAUDE.md示例.png[1] 配图 13
11images/11-上下文与额度.png[1] 配图 14
12images/12-插件页.png[1] 配图 18
13images/13-Skills页.jpg[1] 配图 20
14images/14-交给云端继续.png[1] 配图 16
15images/15-跳过权限开关.png[1] 配图 19
16images/16-写入开关与沙箱.png[7] 图 01

说明:素材 [1] 正文里的配图编号和图片上印的编号有错位(比如正文写「配图 11」,图上印的是「配图 12」),上表按图片上印的编号记。

更新于 2026-11-07来源:用户提供《工具指南_完整全套_含所有MD与图片.zip》;正文保留原文参考来源