天才娜娜ln前两天有个读者私信我：“看你们都在晒 Claude Code 写代码，我装上之后第一步就被卡住了，不是说免费吗？”这问题我太熟了。Claude Code 这个 AI 编程工具，界面是个命令行，能力却像一个能自己动手的实习程序员——你给它一个需求，它能读项目文件、帮你写代码、跑命令、修 bug。工具本身免费，但很多人卡在模型这一步：官方模型按订阅收费，不想一上来就掏钱。这时候智谱 GLM 这类国产大模型就是很好的替代方案——把 Claude Code 的底层模型换成智谱 GLM，配合免费额度，一分钱不花也能把整套流程跑通。
这篇教程就是照着这个思路写给小白的。我会从环境安装、API 密钥申请、免登录配置、常见报错排查到真实项目演示，把完整链路全部走一遍。不管你以前有没有写过代码，只要会复制粘贴命令，就能跟着做。文章里涉及的操作在 Windows、macOS、Linux 上基本通用，个别差异我会单独标注。
1. 先搞懂这个组合到底在干什么
1.1 Claude Code：一个很会写代码的命令行助理
Claude Code 是 Anthropic 推出的一款终端里的 AI 编程智能体。它和你在网页上打开 ChatGPT 聊天最大的区别是：它能直接操作你的电脑。具体来说，它可以在你的项目目录里自动读取文件内容、创建新文件、修改已有代码、执行终端命令，然后根据运行结果自己判断下一步怎么改。
打个比方，普通聊天机器人是“嘴上说给你听”，Claude Code 是“直接帮你动手做”。你只需要用自然语言描述需求，比如“帮我把这个目录下所有文件名里的日期改成下划线格式”，它会先看目录、写脚本、运行、检查结果，再把执行结论告诉你。对于编程新手来说，这意味着你不用先背熟所有命令才能用上 AI 编程，只要能把需求说清楚，剩下的脏活累活它都能干。
而“Claude Code 免费”这一点，指的是这个工具本身的安装和基本运行不需要付费。它真正的成本在模型调用上——官方默认连接的是 Claude 系列模型，需要订阅或按量付费。于是就有了下面的思路：工具不变，把模型换成有免费额度的国产大模型。
1.2 智谱 GLM：给 Claude Code 换一个发动机
智谱 GLM 是智谱 AI 推出的开源大模型系列，在国内开发者里讨论度很高。它对外开放了 API 接口，其中 GLM-4.7-Flash 这类模型有免费调用额度，响应速度快，中文能力强，代码能力在同类免费模型里属于第一梯队。
关键在于，智谱开放平台提供了 Anthropic 兼容接口。Claude Code 默认向 Anthropic 的 API 发请求，而这个兼容接口就像是一个“翻译层”，能把 Claude Code 发出来的请求格式翻译成 GLM 能理解的格式，再把 GLM 的回复翻译回去。所以 Claude Code 根本不需要做任何代码层面的修改，只要把请求地址、认证令牌、模型名称三个参数指到智谱这边，它就会乖乖用 GLM 来干活。
这也是为什么很多人把“Claude Code + 智谱 GLM”当成一套省钱组合。你用的是同一个熟练的智能体工具，只是把背后的“大脑”换成了免费且顺手的国产模型。
1.3 这套方案的成本账与适用人群
先算一笔账。Claude Code 官方模型订阅价格不便宜，对于只是想体验 AI 编程、做作业、写小工具的学生和初级开发者来说，确实是一笔不小的开销。而智谱 GLM 的 Flash 系列免费模型，每天或每月有免费额度，日常学习、写脚本、改 bug 完全够用；即使免费额度用完了，按量付费的价格也远低于海外模型。
- 适合人群：编程零基础的小白、学生、想低成本把 AI 编程用起来的开发者、需要批量处理文件或写自动化脚本的办公族。
- 不适合人群：需要顶尖代码生成能力、要长期跑大型商业项目的专业团队。免费模型的能力上限摆在那里，深度复杂的架构设计还是得用更强（也更贵）的模型。
我见过太多人一上来就折腾各种高级配置，结果卡在环境问题上直接放弃。其实第一步不需要想太复杂，先把“能跑起来”作为唯一目标。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：十分钟装好 Node.js 和 Claude Code
2.1 安装 Node.js：建议用 nvm 管理版本
Claude Code 基于 Node.js 运行，所以第一步是装 Node.js。官网下载安装包这种最直接的方式我就不多说了，我更推荐用 nvm（Node Version Manager）来装，因为 nvm 可以随时切换 Node 版本，以后遇到版本兼容问题能少踩很多坑。
macOS 和 Linux 用户，在终端执行：
bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
装完重开终端，用 nvm install --lts 安装最新的 LTS 版本，再用 nvm use --lts 切换到该版本。Windows 用户建议直接去 nvm-windows 的 GitHub 仓库下载安装包，安装完成后同样用 nvm install --lts 和 nvm use --lts。
安装完成后，务必确认版本：
bash复制node -v
npm -v
只要 node 版本在 18 以上，就没问题。我见过不少人卡在“明明装了 Node.js 还是报错”，十有八九是终端没重开、环境变量没刷新导致 node 命令找不到。记住：安装完任何工具，第一步永远是重开终端窗口。
2.2 用 npm 安装 Claude Code 并验证
Node.js 装好后，安装 Claude Code 就是一条命令的事。在终端执行全局安装：
bash复制npm install -g @anthropic-ai/claude-code
国内网络环境下，如果 npm 下载速度很慢或者直接失败，可以先把 npm 源切换到国内镜像：
bash复制npm config set registry https://registry.npmmirror.com
切换源之后重新安装即可。安装完成，输入：
bash复制claude --version
能看到版本号就说明安装成功。注意，到这一步先别急着运行 claude，因为此时还没有配置模型地址，直接运行会进入官方登录流程，很多人就是在这一步被劝退的。
2.3 安装失败怎么办：换源、权限、版本
安装常见的坑主要有三个。第一个是 npm 下载卡住，解决办法就是上面说的换镜像源。第二个是权限问题，Linux 和 macOS 上用全局安装偶发 EACCES 错误，这是因为 npm 全局目录没有写权限。如果是通过 nvm 安装的 Node，通常不会遇到这个问题；如果遇到，可以用 npm 官网推荐的“用 nvm 重装 Node”方案，比直接 sudo 改权限更干净。
第三个是版本问题。如果 node 版本过低，Claude Code 会提示你升级。别硬扛，直接用 nvm 装一个 LTS 版本，一分钟搞定。
装完所有的第一道关卡就过了。环境这一部分真的不难，难点在于“装完别急”，把后面的模型配置先看明白再启动 Claude Code，你会省掉很多力气。
3. 智谱 GLM API 密钥获取与环境变量配置
3.1 去开放平台申请 API Key
智谱的开放平台在 open.bigmodel.cn，用手机号注册登录后，进入“API Keys”页面创建一个新的 API Key。创建成功后你会得到一串形如 xxxxxxxx.yyyyyyyy 的密钥字符串。
这个 Key 就是你的“调用凭证”，Claude Code 每次向智谱发请求时都会带上它。免费模型（比如 GLM-4.7-Flash）一般需要你在控制台确认开通，开通过程不收费，找到对应模型点“开通”就行。注意：API Key 只显示一次，复制后一定保存好，泄露了别人就能用你的额度。
在小白阶段，我最建议的办法是：把 API Key 复制到记事本里，暂时不要关页面。后面配置环境变量的时候要用到，省得来回翻。
3.2 三个关键环境变量：BASE_URL、AUTH_TOKEN、MODEL
Claude Code 连接智谱 GLM 的本质，是通过环境变量告诉它三个信息：
ANTHROPIC_BASE_URL：请求地址，指向智谱的 Anthropic 兼容端点。智谱开放平台的接入文档里会给出具体的 Base URL，通常形如https://open.bigmodel.cn/api/paas/v4/，具体以你账号后台显示的地址为准。ANTHROPIC_AUTH_TOKEN：刚才申请的智谱 API Key。Claude Code 会把它作为 Bearer Token 放在请求头里。ANTHROPIC_MODEL：模型名称，比如glm-4.7-flash。这个必须填智谱那边真实存在的模型 ID，填错了就会报“model not recognized”。
还有一个容易被忽略的变量 ANTHROPIC_SMALL_FAST_MODEL。Claude Code 内部有些轻量任务（比如生成标题、给对话做总结）会调用一个小模型，不设置的话它会用默认值，而这个默认值在智谱这边可能不存在，于是就会报错。最省事的做法是把小模型也指定为 glm-4.7-flash，反正免费，跑得快。
3.3 配置原理：Claude Code 为什么认 GLM
理解这套配置的原理非常重要，否则你只能机械照抄，遇到问题依然懵。
Claude Code 和模型之间的通信协议是 Anthropic Messages API。请求的格式、鉴权方式、返回结构都是 Anthropic 定义好的。智谱开放平台做了一个“Anthropic 兼容层”，它接受 Anthropic 格式的请求，内部转发给 GLM 模型处理，再把结果按 Anthropic 格式返回。所以从 Claude Code 的视角看，它觉得自己在和 Anthropic 的官方服务对话，实际上对面是智谱的服务器。
Base URL 决定了“请求发去哪里”，Auth Token 决定了“我是谁”，Model 决定了“用哪个模型干活”。这三个参数任何一个不对，整个链路就断掉。它们在配置上以环境变量（Environment Variables）的方式存在，临时运行可以在终端里 export，永久生效要写进配置文件夹。
4. 第一次运行：免登录配置的两种方式
4.1 方式一：命令行临时环境变量
最直接的理解方式，是在当前终端会话里临时设置环境变量，然后启动 Claude Code。macOS 和 Linux 用：
bash复制export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
export ANTHROPIC_AUTH_TOKEN="你的智谱APIKey"
export ANTHROPIC_MODEL="glm-4.7-flash"
export ANTHROPIC_SMALL_FAST_MODEL="glm-4.7-flash"
claude
Windows PowerShell 用户用：
powershell复制$env:ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
$env:ANTHROPIC_AUTH_TOKEN="你的智谱APIKey"
$env:ANTHROPIC_MODEL="glm-4.7-flash"
$env:ANTHROPIC_SMALL_FAST_MODEL="glm-4.7-flash"
claude
这种方式的优点是适合测试，改起来快；缺点是一关终端就失效，下次又得重新设置。你可以在终端里直接问 Claude Code“用的是什么模型”，它回答能体现 GLM 就说明通了。
4.2 方式二：settings.json 永久配置
配置好一次、以后打开就能直接用，这才是推荐做法。Claude Code 会在用户目录下生成 .claude 文件夹，里面的 settings.json 就是全局配置文件。你可以运行 claude 后输入 /config 打开配置编辑界面，也可以直接编辑文件：
json复制{
"env": {
"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
"ANTHROPIC_AUTH_TOKEN": "你的智谱APIKey",
"ANTHROPIC_MODEL": "glm-4.7-flash",
"ANTHROPIC_SMALL_FAST_MODEL": "glm-4.7-flash"
}
}
保存后完全退出终端，重新打开，直接输入 claude 启动。这一次它会跳过官方登录流程，直接进入对话。如果你想在项目目录里使用，进入该目录后再启动，它也只会读取这一份全局配置，非常省心。
4.3 验证是否配置成功的标准
启动后，界面底部出现 > 提示符，说明已经成功进入。此时输入 /status，回车，可以看到当前配置的模型信息。如果显示的是 glm-4.7-flash，说明已经成功接入智谱 GLM。
接下来做一个小测试，输入“请用一句话介绍你自己”，如果它回复里提到自己基于 GLM 或表现正常，就万事大吉。如果它提示要登录、要你去官网授权，那说明配置没生效。最常见的原因是你先运行过 claude 并登录过，配置没有刷新，这时候先退出、删掉 ~/.claude.json（这个文件存了登录状态），再重新运行即可。
5. 排错实录：常见报错与完整排查链路
5.1 "not a model this version of claude code recognizes" 报错
这个报错在热词搜索里出现频率最高，几乎是每个新人都会撞上的墙。报错原文长这样：
text复制"deepseek-v4-pro" is not a model this version of claude code recognizes
有些人以为是自己版本不对，其实是理解反了。ANTHROPIC_MODEL 这个变量里填的模型名，Claude Code 本身“认不认”无所谓，关键是智谱那边认不认。它报这个错，通常有两个原因：一是你没设置 ANTHROPIC_MODEL，Claude Code 用了默认的官方模型名（比如 claude-sonnet-4-5），智谱那边根本没有这个模型，于是报错；二是你自己填了一个模型名，但填错了。
排查链路是这样的：
- 先确认智谱开放平台“模型列表”里你开通的模型 ID 到底叫什么。注意是 API 调用时的 ID，不是展示名称。
- 打开 settings.json，确认
ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL都填了正确 ID。 - 保存后完全退出终端，重新启动。
按这个顺序走一遍，九成以上的报错能解决。这里顺便说一句：网上有些教程让你复制别人的模型名，最好别直接抄。模型 ID 是一个平台一个样的，以你在智谱控制台看到的为准。
5.2 认证失败 401 排查
如果启动后输入任何问题，它回复认证失败或 401，说明请求到了服务器，但服务器不认你的钥匙。排查顺序：
第一，检查 API Key 有没有复制全。智谱的 Key 是一整串，中间没有空格，复制的时候别用微信那种会把长字符串截断的工具。第二，检查 settings.json 里的引号和逗号，JSON 格式出一点错整个配置都会失效。第三，用 curl 直接测一下接口通不通：
bash复制curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer 你的智谱APIKey" \
-H "Content-Type: application/json" \
-d '{"model":"glm-4.7-flash","messages":[{"role":"user","content":"你好"}]}'
如果 curl 也返回 401，那就是 Key 的问题；如果 curl 正常但 Claude Code 报 401，那就是 Base URL 拼错了。注意 curl 的路径和你 Base URL 要对应上，具体路径以智谱开放平台文档为准。用这种“层层缩小范围”的方法，几分钟就能定位问题。
5.3 其他高频问题：乱码、超时、卡在登录
Windows 终端下如果 Claude Code 输出的中文变成乱码，先试试在终端执行 chcp 65001 切换 UTF-8 编码，再重新启动。这还是解决不了就换 Windows Terminal 这个终端软件，体验好很多。
请求超时大概率是网络不稳定。Claude Code 跑任务时如果网络抖动，可能等很久没反应。这时候不要狂按回车，先看它是不是还在转圈，等一会儿；超过 60 秒没动静，就用 Ctrl+C 中断，重新发起请求。
还有一类情况是：明明配置了智谱的地址，启动时还是弹出官方登录界面。这通常是因为用户目录下残留了之前登录产生的状态文件。我一贯的做法是：先关掉所有 claude 进程，删除 ~/.claude.json，再重新运行。不放心就先备份这个文件到别处，再删。
5.4 免费额度用完了怎么办
智谱的免费模型是有额度限制的，具体额度数量以开放平台控制台显示为准。额度用完后的表现通常是请求返回“余额不足”或“已超出免费额度”。
这时候有三个选择：等下一轮额度刷新；在控制台充值按量付费（价格很便宜）；或者换个还有免费额度的模型接进来。别在免费额度上死磕，那点钱换成开发效率非常值。
6. 真实项目实战：让 GLM 驱动 Claude Code 写一个自动化脚本
6.1 场景设定和 prompt 设计
配置通了，我们来跑一个真实的小项目：批量重命名指定文件夹里的所有图片文件，把文件名里的空格替换为下划线，并在名字前面加上日期前缀。
在 Claude Code 的输入框里，我建议不要只丢一句话。一个合格的 prompt 至少包含四部分：角色、任务、输入输出、约束。我用的完整描述是：
text复制你现在是一个 Python 脚本编写助手。请帮我在 /Users/me/test-images 目录下写一个 Python 脚本，功能是把该目录下所有 .jpg 和 .png 文件的文件名中的空格替换成下划线，并在文件名前加上当天日期（格式 YYYYMMDD）。请先列出你要执行的操作步骤，再写代码并实际运行测试。
对于小白来说，把需求写在记事本里再粘贴进去，比直接在终端里想一句说一句要不容易出错。Claude Code 的最大优势是你不需要一次性给出完美 prompt，中间可以持续补充。
6.2 观察 Claude Code 的执行过程
输入需求后会看到 Claude Code 开始“自言自语”式地工作：它会先读取目录内容，确认有哪些文件；然后写出一个 Python 脚本；接着用终端命令运行脚本；运行报错的话，它还会自己读报错信息、修改代码、重新运行。
我测试时观察到它第一次运行脚本后遇到文件不存在的问题，原因是脚本里路径写错了。它没有停下，而是自动读取目录结构，修正路径后再次执行。整个过程大概三十秒，最后它把执行结果和修改后的文件名列表列了出来。
这个“自动试错”的过程，就是 Claude Code 和普通聊天机器人的本质区别。它不需要你干等着然后自己去复制代码跑，而是帮你把“写代码-运行-看结果-修代码”这个循环跑完。
6.3 结果验收与调优建议
任务执行完后，建议自己打开目录确认一下文件确实被重命名了。AI 编程的验收原则是：它说的话只能当参考，最终以文件系统里的实际结果为准。
如果结果不对，别急躁，直接把问题丢回去：“我发现文件名没有被加上日期，只有空格被替换了，请检查脚本并重新运行。” Claude Code 会继续修改。这个过程就是一个标准的“人审-反馈-迭代”循环，比你自己改代码要轻松得多。
这里顺带讲一个提升成功率的小经验：给文件操作类任务时，尽量在 prompt 里写清楚“不要使用会影响原文件的危险操作，先备份”。Claude Code 本身在删除文件时会二次确认，但备份习惯还是要靠你自己建立。
7. 进阶玩法：VS Code 集成、CC Switch、Skills 与 DeepSeek 对比
7.1 VS Code 里用 Claude Code
命令行用习惯了之后，很多人想回到编辑器里操作。Claude Code 提供了官方 VS Code 扩展，安装后在左侧边栏会出现 Claude Code 面板。插件的配置逻辑和命令行完全一致，因为你设置的 settings.json 是全局的，所以插件启动后直接就是智谱 GLM，不需要再配置一遍。
如果你不想装插件，最笨也最稳定的做法是：在 VS Code 的集成终端里直接运行 claude，然后在你打开的项目目录里干活。很多资深开发者反而更喜欢这种方式，因为集成终端和编辑器是协同的，Claude Code 改完文件，你切到编辑器里立刻能看到变化。
7.2 CC Switch 管理多套配置
当你试的模型多了，比如今天用智谱 GLM，明天想试 DeepSeek，手动去改 settings.json 就显得很笨。热词里反复出现的 CC Switch，就是解决这个问题的开源小工具。它用图形界面的方式管理多套“供应商配置”——每一套配置包含 Base URL、API Key、模型 ID，点一下就能切换，工具会自动帮你改写配置。
我自己实际用下来的感受是：它特别适合那种“不想记配置、又经常换模型”的人。但作为初学者，我建议先手动配置跑通一次，切身体会一下配置文件的逻辑，再去依赖这类工具。否则出了问题，你连根本原因都找不到。
7.3 Skills 扩展：让 Claude Code 学会你的套路
Claude Code 的 Skills 功能值得你入门后仔细研究。它的本质是给 Claude Code 定义“预置技能”文件，存放在项目的 .claude/skills 目录下，每个技能是一个文件夹，里面有一个 SKILL.md 文件描述这个技能的用途和操作流程。
比如你经常需要写某种固定格式的工作周报，就可以写一个“周报生成器”技能。以后对话里提到“生成周报”，Claude Code 就会自动加载这个技能文件，按照你定义的格式来输出。GLM 模型本身对这套机制是支持的，因为技能文件的实质是把你总结好的方法论作为上下文注入给模型，模型只要上下文够长就能理解并执行。
7.4 其他国产模型怎么接：以 DeepSeek 为例
智谱 GLM 能接，其他国产模型能不能接？能，方法大同小异。以 DeepSeek 为例，同样是去开放平台拿 API Key，然后把 settings.json 里的三个变量换成 DeepSeek 的地址和模型 ID，即可切换。关键是模型名必须填官方文档里真实存在的 ID，比如 DeepSeek 开放平台的 deepseek-chat，而不是网上流传的各种版本号。
很多人在这一步会踩的坑，就是把“听说”的模型名直接填进去，结果就是前面讲的那个 is not a model this version of claude code recognizes 报错。记住：任何模型接入的通用流程都是“去官方控制台找 API Key + 找 Base URL + 找模型 ID”，这三个信息全部以官方文档为准，任何人给的不算。
如果这套流程你能完整走通，后续无论是接其他模型、写自定义技能，还是把它嵌进自己的自动化工作流，都会顺畅很多。我的建议是别急着上高难度玩法，先让它帮你解决日常最烦琐的小任务——批量改文件、整理日志、写脚本、查报错——跑上一周，你对它的能力边界心里有数了，再决定要不要深入折腾。工具这东西，先能用起来，比什么都重要。