相信不少人和我一样，第一次看到 Claude Code 的演示视频时，第一反应是“这玩意儿真能让 AI 直接改我代码？”。紧接着第二个问题就是：怎么装？再一搜教程，满屏都是英文界面、账号注册和支付绑定，零基础用户很容易在这里打退堂鼓。其实 Claude Code 的安装并没有那么复杂，它只是一个基于 Node.js 的命令行工具，而所谓的“直连国产大模型”，本质是把它默认的 API 地址，通过官方支持的两个环境变量，指向国内大模型平台提供的 Anthropic 兼容接口。这篇文章就是一份面向零基础用户的安装教程，不分 Windows/macOS，也不预设你有编程经验，我会从装 Node.js 讲起，一直讲到跑通第一次对话，最后附上我实际使用中遇到的高频报错和解决办法。
1. 先搞懂三件事：Claude Code、兼容接口、直连逻辑
1.1 Claude Code 到底是什么
Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它不是一个网页聊天框，而是直接跑在你终端里的一个交互式程序。你让它“读一下这个项目的代码结构”“给这段逻辑补上异常处理”“运行测试并告诉我哪里挂了”，它会自己去读文件、改文件、执行命令，然后给你反馈。如果你用过 Cursor 这类 AI 编辑器，可以把 Claude Code 理解成更“极客”的版本——它不依赖图形界面，一个终端窗口就能完成大部分工作。
它和普通聊天的最大区别在于“工具调用”。普通聊天里，AI 只能基于你贴出来的代码片段给建议；Claude Code 里，AI 能直接看到整个项目目录，能自己搜索函数定义，能修改文件后再跑一遍测试。这种工作方式对命令行下重操作的开发者非常友好，也是为什么很多人宁愿放弃图形界面也要用它。
1.2 为什么默认状态下不一定能直接用
Claude Code 安装后，默认的请求目标是 Anthropic 官方接口。要使用官方接口，通常需要注册账号，并配置 API 凭证。这个过程对很多用户来说并不友好，许多人装到一半就卡在账号流程上。其实问题不在安装本身，而在于默认连接的目标地址。
Claude Code 在设计上支持通过环境变量改变 API 地址和密钥，这就给了我们操作空间：把地址指向国产大模型平台提供的 Anthropic 兼容接口，把密钥换成国内平台生成的 API Key。这样 Claude Code 发出的是标准 Anthropic 协议请求，收到的应答来自国产模型，你在终端里的操作体验却几乎不变。
如果还是觉得抽象，可以这样类比：Claude Code 是一个只说英语的顾客，Anthropic 官方是一家接待它的餐厅；国产大模型平台开了一家同样能听懂英语的餐厅，也按照同一套标准菜单来服务。顾客点菜的格式完全没变，只是换了个目的地。兼容接口解决的就是“菜单格式一致”的问题，所以 Claude Code 不需要改代码，只需要改地址。
1.3 这套方案适合谁
- 零基础的新手，想体验 AI 编程工具但不想折腾复杂账号流程的人；
- 已经用着其他国产大模型工具，希望统一到一个命令行入口的人；
- 想在脚本、编辑器集成等场景中使用 Claude Code 的自动化能力，但又希望请求直接走国内平台的开发者。
先说明一下：用这套方案时，你实际对话的模型是国产大模型，不是 Anthropic 官方的模型，所以代码生成质量和工具调用能力可能和你看到的官方 Demo 有差距。这不是配置错误，而是底座模型不同。对日常写脚本、改 bug、写单元测试这类需求，现在的国产模型已经能扛住大部分场景，先把它跑起来再慢慢调，才是零基础最务实的路径。
2. 装好 Node.js，这是 Claude Code 的运行底座
2.1 先检查电脑里有没有 Node.js
Claude Code 是一个 npm 包，npm 是 Node.js 自带的管理器，所以第一步永远是检查 Node.js。Windows 用户按 Win 键，输入 powershell，打开 PowerShell；macOS 用户打开“终端”应用。然后输入下面这两条命令：
node -v npm -v如果看到 v18.x、v20.x 之类的版本号，说明已经装好了。如果提示“node 不是内部或外部命令”或者“command not found”，说明没装或没有加入 PATH。Node.js 版本建议 18 及以上，太老的话，Claude Code 安装过程可能报错，或者装完启动不了。
2.2 Windows 安装 Node.js 的保姆级步骤
去 nodejs.org 下载页面，选 LTS（长期支持）版本的 Windows Installer (.msi) 文件下载。双击运行，一路 Next 即可。安装界面里有一个 “Add to PATH” 的选项，一定要保持默认勾选，这决定了后续能不能直接在终端里敲出 node 命令。
安装完成后，关闭终端再重新打开，执行 node -v 验证。如果还是不认，重启一次电脑，因为 PATH 的修改在部分 Windows 环境下需要重启才完全生效。我建议不要下载 Current 版本，Current 是给尝鲜用户准备的，LTS 更稳定，Claude Code 这种工具不需要你去追最新版 Node。
2.3 macOS 安装 Node.js 的推荐姿势
macOS 上最简单的方式是下载 nodejs.org 提供的 macOS Installer (.pkg)，双击安装。如果你已经装了 Homebrew，也可以用 brew install node@20，但官方 pkg 安装包对零基础用户更省心，至少不用关心 Homebrew 本身的环境问题。
如果你打算以后用 nvm 管理多个 Node 版本，那现在装一个 nvm 也行，但对这篇教程来说不是必须的。我的建议是：先把 Claude Code 跑起来，再考虑环境管理工具，别在第一步给新手增加一堆额外概念。装完后同样打开“终端”，执行 node -v 验证。
2.4 零基础只需要记住这三条命令
安装阶段真正要记住的命令不多，初学阶段只要掌握这三条就够了：
- cd：进入目录，比如 cd Desktop；
- mkdir：新建目录，比如 mkdir claude-test；
- claude：启动 Claude Code。
你不需要立刻成为命令行高手，能打开终端、会执行 node -v，然后照着后面的安装命令复制粘贴，就已经具备完成这篇教程的基础。遇到不认识的东西不要慌，复制命令执行，看输出有没有 error 就可以。
3. 安装 Claude Code：npm 一条命令，坑在 PowerShell
3.1 全局安装命令与版本验证
确保 Node.js 就绪后，在终端执行：
npm install -g @anthropic-ai/claude-code这里的-g是全局安装，意思是以后在任意目录打开终端都能直接使用 claude 命令。安装过程中可能会看到很多进度条和 warn 输出，只要结尾没有出现 error 就算成功。
装完以后输入：
claude --version如果输出版本号，比如 1.0.x，说明核心安装已经完成。如果提示找不到命令，先别怀疑自己操作错了，看 3.2 或者后面第 5 节的报错处理。
以后想更新版本也很简单，重新执行一遍同样的安装命令，npm 会覆盖安装到最新版。不想用了，执行 npm uninstall -g @anthropic-ai/claude-code 就能卸载。
3.2 解决 PowerShell 禁止运行脚本的问题
这是 Windows 用户最容易踩的坑。安装明明显示成功，但一执行 claude，报错说“无法加载文件 ... 因为在此系统上禁止运行脚本”。原因是 PowerShell 默认的执行策略不允许直接运行 .ps1 脚本文件，而 npm 生成的全局命令在 Windows 上恰好是个 .ps1。
解决办法：在 PowerShell 里执行下面这条命令，然后按提示输入 Y 回车：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令只修改当前用户的执行策略，不影响系统级设置，相对安全。执行完以后，重开终端，再执行 claude --version 验证。
特别提醒：如果你在用 VS Code 的集成终端，它本质上也是 PowerShell，遇到同样问题也要先执行这条命令再重开终端，不然会一直卡在同一个报错。
3.3 首次运行 claude 应该看到什么
安装验证通过后，建议先新建一个空目录再运行，避免 Claude Code 一启动就读取到你电脑上其他真实项目的文件：
mkdir claude-test cd claude-test claude第一次运行会有一段授权提示，问你是否信任当前文件夹。这是正常的安全确认机制，因为你同意后，它才有权限读取这个目录里的文件并修改代码。输入 y 回车继续。
如果你还没有配置任何环境变量，接下来会进入登录引导界面；如果你已经按下一节的内容配置好，则直接进入正常的对话界面，出现输入框等待你提问。看到这里，说明 Claude Code 本体已经没问题，剩下的就是让它连上国产大模型。
4. 直连国产大模型：两个环境变量搞定一切
4.1 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 是干什么的
进入正题。Claude Code 支持两个重要的环境变量：ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。
- ANTHROPIC_BASE_URL：告诉 Claude Code 把 API 请求发到哪个地址；
- ANTHROPIC_AUTH_TOKEN：访问这个地址时携带的认证令牌，也就是你在大模型平台生成的 API Key。
设置好这两个变量，Claude Code 就不再请求 Anthropic 官方地址，而是把请求直接发到国产大模型平台的 Anthropic 兼容接口。
例如：
ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" ANTHROPIC_AUTH_TOKEN="这里填你在平台生成的 API Key"请求头的格式仍然是 Anthropic 标准，服务端能正常识别，认证也能通过。这就是“直连国产大模型”的技术原理：不是改 Claude Code 代码，也不是改协议，只是换服务端地址。
4.2 如何找到国产大模型的 Anthropic 兼容地址
优先选择官方提供“Anthropic 兼容接口”的平台。以智谱开放平台为例，它提供 Anthropic API 兼容接入，地址通常形如 open.bigmodel.cn/api/anthropic。你需要先在平台注册账号、创建 API Key，然后在文档里找到 Anthropic 兼容接入的 base_url 和 model 参数。
这里要先泼一盆冷水：不是所有国产大模型平台都提供 Anthropic 兼容接口，很多平台只提供 OpenAI 兼容接口。Claude Code 默认不会去请求 OpenAI 格式的接口，中间隔着一层协议转换，对零基础用户来说复杂度会高很多。所以我建议第一次玩，就选有 Anthropic 兼容接口的平台，先把流程跑通，后面再考虑要不要接其他协议转换方案。
4.3 Windows 环境变量配置：临时和永久
先给一个只对当前窗口生效的临时配置，适合快速验证，避免配置写死后怕改不回来。在 PowerShell 里执行：
$env:ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" $env:ANTHROPIC_AUTH_TOKEN="你的APIKey" claude这种临时配置的好处是关掉终端就消失，不会污染系统设置。确认有效后，再做永久配置，用 setx 命令写入用户环境变量：
setx ANTHROPIC_BASE_URL "https://open.bigmodel.cn/api/anthropic" setx ANTHROPIC_AUTH_TOKEN "你的APIKey"注意 setx 不会影响当前已经打开的终端窗口，设置完必须重开一个新终端再运行 claude。如果你不习惯命令，也可以用图形界面：右键“此电脑”-> 属性 -> 高级系统设置 -> 环境变量，在用户变量里新建这两个变量。
我一般推荐新手直接用 setx 或图形界面，因为永久配置会一直在，下次打开终端就能用，不用每次手动 export 一遍。
4.4 macOS / Linux 环境变量配置：记得写进 shell 配置文件
macOS 的终端默认是 zsh，临时配置用 export：
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" export ANTHROPIC_AUTH_TOKEN="你的APIKey" claude如果验证没问题，就把这两行写入配置文件，让每次打开终端都自动加载。macOS 上写进 ~/.zshrc，Linux 上用 bash 的话写进 ~/.bashrc：
echo 'export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"' >> ~/.zshrc echo 'export ANTHROPIC_AUTH_TOKEN="你的APIKey"' >> ~/.zshrc source ~/.zshrc用 echo 追加最省事，但如果 API Key 里有特殊字符，容易出问题。对配置文件比较熟的话，直接用 nano ~/.zshrc 手动加两行更保险。改完文件后执行 source ~/.zshrc，或者直接重开终端。
4.5 模型名称在哪里指定
环境变量配置好不代表万事大吉，有些版本的 Claude Code 默认使用的模型名是官方模型名，兼容端点可能不认识。如果你启动后提问，报错提示模型不存在，可以在 Claude Code 会话中输入 /model，回车后会进入模型切换界面，选择或手动输入平台支持的兼容模型名。
部分版本的 Claude Code 也支持通过 ANTHROPIC_MODEL 环境变量指定默认模型名，具体以你安装的版本和平台文档为准。不过最通用的方式还是进入会话后用 /model 切换。
写代码场景建议优先选择上下文长、工具调用能力强的模型。Claude Code 的很多功能依赖 AI 调用工具读文件、改文件，模型如果不支持工具调用，整个交互体验会大打折扣，可能需要频繁手动复制粘贴代码。
5. 第一次实战对话与高频报错自救手册
5.1 第一次实战：让它帮你写一个脚本
配置完成后，进入 claude-test 目录，输入 claude 启动。在输入框里试一句“帮我在当前目录创建一个 Python 脚本，读取所有 txt 文件并统计总行数”，然后观察输出。
正常情况下，它会先分析任务，然后调用工具新建文件，再把文件内容展示给你。看到它真的在磁盘上创建了文件，说明 Claude Code 已经能正常调用工具工作。想退出时输入 /exit 回车，或者按两次 Esc。
第一次跑通就是这个项目最重要的里程碑，后面再慢慢增加复杂度。
5.2 报错：'claude' 不是内部或外部命令
安装成功但命令找不到，最常见的原因是 npm 的全局安装目录没有加入 PATH，或者安装后没重开终端。
Windows 用户先重开终端试试，这能解决一半问题。如果还是不行，在 PowerShell 里执行 npm config get prefix，找到全局目录，手动加入系统 PATH。macOS 用户如果之前用 sudo 装过 Node，也可能遇到权限问题，建议直接改用 nvm 重装 Node，能省掉很多权限相关的坑。
5.3 报错：PowerShell 禁止运行脚本
这个问题在 3.2 里已经给了解决办法，这里再补充一点：如果改完执行策略仍然报错，检查一下你是不是在管理员 PowerShell 和普通用户 PowerShell 之间混用了。Set-ExecutionPolicy 加 -Scope CurrentUser 只对当前用户生效，如果你在另一个用户环境里运行 claude，肯定还是不行。保持同一个用户环境，改完策略后重开终端。
5.4 报错：401 / 403 / 404 / 400 系列
这一组 HTTP 报错是直连国产大模型时最常遇到的，原因各不相同，我整理成一个表方便对照：
| 报错 | 常见场景 | 处理路径 |
|---|---|---|
| 401 Unauthorized | API Key 无效，或环境变量没有真正生效 | 检查 ANTHROPIC_AUTH_TOKEN 是否填对；重开终端；去平台重新生成 key |
| 403 Forbidden | 密钥有效但没权限，或余额不足 | 去平台检查模型服务是否开通、余额是否够用 |
| 404 Not Found | 接口地址路径不对 | 对照平台文档看 base_url，注意不要多加 /v1 这类后缀 |
| 400 Bad Request / model not found | 模型名称不匹配 | 在会话里输入 /model 换成平台支持的模型名 |
排查这类报错有个原则：先确认环境变量在当前终端里已经生效。可以执行 echo $env:ANTHROPIC_BASE_URL（Windows）或 echo $ANTHROPIC_BASE_URL（macOS/Linux）看一下，如果输出为空，说明环境变量没配好。环境变量都没生效的时候，后面所有认证报错都会变得特别难排查。
5.5 报错：上下文超限和响应慢
国产模型的上下文窗口和计费策略各不相同，如果一次性让它读很多文件，可能报上下文长度超限。解决办法很直接：拆小任务、在会话里执行 /clear 清空历史，或者换一个上下文更长的模型。
响应慢则可能是平台高峰期拥挤，也可能是你正在用的模型本身推理速度就比较慢。遇到这种情况，可以换一个时段再试，或者去平台控制台看看模型负载。不要一慢就怀疑配置错了，环境变量的作用只决定请求去哪，不决定响应速度。
5.6 关于“工具调用”能力，多说一句
Claude Code 的强项是 AI 能自己读文件、执行命令、改代码。要实现这些，模型必须具备工具调用能力。国产模型这块的成熟度差异比较大，有的模型能顺畅地操作文件，有的模型在复杂任务里会“忘记”调用工具，只给你口头建议。
如果你发现发给它的指令明明涉及读文件、改文件，它却只回复一段文字而不实际创建或修改文件，通常说明当前模型的能力或兼容度不够。遇到这种情况，换一个侧重点不同的国产模型，往往比反复改提示词更有效。这也是我建议选长上下文、Agent 能力强的模型的原因。
6. 进阶使用技巧：编辑器配合、成本控制与我的配置习惯
6.1 把 Claude Code 集成进 VS Code
如果你觉得纯终端里看代码改动不太直观，官方提供了 VS Code 扩展，直接在扩展市场搜“Claude Code”安装，装完后侧边栏会出现对应入口。
这个扩展和命令行版本共用同一套环境变量配置，也就是说你之前设置的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 会自动生效，不需要在扩展里重新配置一遍。扩展的好处是能高亮 diff，AI 改完代码后，你可以很直观地看到它改了哪些文件、哪些行，这对从图形界面入门的用户非常友好。
6.2 控制成本与用量的小建议
直连国产大模型是按 token 计费的。我个人的习惯是：小任务、临时问题用便宜的小模型，重活才切到更强的模型。Claude Code 会话里用 /model 可以随时切换，日常写脚本我用性价比高的模型，让它改整个项目或做大规模重构时再换重模型。
另外建议在平台后台设置额度上限，防止某个自动化任务失控，把预算跑穿。命令行工具用起来太顺手，有时候很容易一口气让它处理几十个文件，等反应过来费用已经上去了。
6.3 我踩过的坑和给你的经验
最后分享几个我自己的操作习惯。
第一，千万不要把 API Key 写进博客示例、配置文件提交记录或公开仓库里。一旦泄露，马上去平台吊销并重新生成，不要抱着“应该没人看到”的侥幸心理。
第二，别一上来就让它改正在运行的生产项目。先建一个 claude-test 目录随便折腾，等搞清楚它的行为模式，再进入真实项目。AI 工具再强，也需要你给它设定边界。
第三，环境变量反复不生效时，别急着怀疑模型有问题，先用 echo 确认变量已经加载，再查认证报错。很多时候问题出在“当前终端窗口是旧的，还没读到新配置”。
第四，Claude Code 更新频率很高，隔一段时间执行一次 npm install -g @anthropic-ai/claude-code，保持版本较新，能少踩很多已经修复的 bug。
第五，在使用 /model 切换模型之前，先确认平台文档里这个模型是否支持 Anthropic 兼容接入。有的平台表面上有兼容接口，但某些模型并没有完整实现工具调用，这会在实际使用中带来很大落差。选一个文档明确标注支持 Agent 或工具调用的模型，启动体验会顺很多。
