相信不少人和我一样第一次看到 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.jsClaude Code 是一个 npm 包npm 是 Node.js 自带的管理器所以第一步永远是检查 Node.js。Windows 用户按 Win 键输入 powershell打开 PowerShellmacOS 用户打开“终端”应用。然后输入下面这两条命令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 node20但官方 pkg 安装包对零基础用户更省心至少不用关心 Homebrew 本身的环境问题。如果你打算以后用 nvm 管理多个 Node 版本那现在装一个 nvm 也行但对这篇教程来说不是必须的。我的建议是先把 Claude Code 跑起来再考虑环境管理工具别在第一步给新手增加一堆额外概念。装完后同样打开“终端”执行 node -v 验证。2.4 零基础只需要记住这三条命令安装阶段真正要记住的命令不多初学阶段只要掌握这三条就够了cd进入目录比如 cd Desktopmkdir新建目录比如 mkdir claude-testclaude启动 Claude Code。你不需要立刻成为命令行高手能打开终端、会执行 node -v然后照着后面的安装命令复制粘贴就已经具备完成这篇教程的基础。遇到不认识的东西不要慌复制命令执行看输出有没有 error 就可以。3. 安装 Claude Codenpm 一条命令坑在 PowerShell3.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_URLhttps://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_URLhttps://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临时配置用 exportexport ANTHROPIC_BASE_URLhttps://open.bigmodel.cn/api/anthropic export ANTHROPIC_AUTH_TOKEN你的APIKey claude如果验证没问题就把这两行写入配置文件让每次打开终端都自动加载。macOS 上写进 ~/.zshrcLinux 上用 bash 的话写进 ~/.bashrcecho export ANTHROPIC_BASE_URLhttps://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 UnauthorizedAPI Key 无效或环境变量没有真正生效检查 ANTHROPIC_AUTH_TOKEN 是否填对重开终端去平台重新生成 key403 Forbidden密钥有效但没权限或余额不足去平台检查模型服务是否开通、余额是否够用404 Not Found接口地址路径不对对照平台文档看 base_url注意不要多加 /v1 这类后缀400 Bad Request / model not found模型名称不匹配在会话里输入 /model 换成平台支持的模型名排查这类报错有个原则先确认环境变量在当前终端里已经生效。可以执行 echo $env:ANTHROPIC_BASE_URLWindows或 echo $ANTHROPIC_BASE_URLmacOS/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 会自动生效不需要在扩展里重新配置一遍。扩展的好处是能高亮 diffAI 改完代码后你可以很直观地看到它改了哪些文件、哪些行这对从图形界面入门的用户非常友好。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 或工具调用的模型启动体验会顺很多。