看到这个标题点进来的咱们都是同类人白天写接口、晚上修 bugSQL 都没查完就被拉去开会的牛马。最近 GitHub 热门榜上全是 Claude Code 的身影短视频里那些博主把需求往终端一贴Agent 自己读代码、改文件、跑测试一气呵成看完确实心动。但要真上手很多人第一步就被拦住了官方入口要订阅账号还要处理所在地区支不支持的问题。于是“开源版 Claude Code”成了大家最关心的玩法——把 Claude Code 这套编程 Agent 工具链跑起来但模型换成 DeepSeek、Qwen、GLM 这些开源或国产商用模型成本低、充值方便效果还够用。这篇文章就是把这条路从零走一遍。你会看到怎么在 Ubuntu 和 macOS 上把 Claude Code 装好怎么通过环境变量接上第三方模型怎么在 VSCode 里和插件联动最后还有我实际拿它改项目时总结出来的几条保命经验。适合谁看适合所有被需求文档和重复劳动折磨的开发者——只要你会用终端剩下的事我基本喂到嘴边了。1. 先分清你要的“开源版 Claude Code”到底是哪一种很多人一上来就到处搜“Claude Code 开源版下载”结果下了一堆乱七八糟的东西。这里先把概念捋清楚能帮你少走两小时弯路。1.1 三件事别混为一谈官方 CLI、开源模型接入、社区替代工具我观察下来大家嘴里的“开源版 Claude Code”至少指三样东西第一是 Anthropic 官方发布的 Claude Code CLI 本身。它作为工具链可以免费安装但默认情况下它要连 Anthropic 官方端点需要登录 Claude 账号还得看账号所属地区是否在支持列表里。很多人卡在这一步。第二是通过环境变量把请求地址改到第三方模型的 Anthropic 兼容接口上让 DeepSeek、Qwen、GLM 这些模型驱动 Claude Code 的整套 Agent 工具。这才是目前中文开发圈最流行的“开源版玩法”也是我今天重点讲的路子。第三是 GitHub 上那些功能相近的纯开源替代品比如 opencode 之类的项目。它们不是 Claude Code只是长相类似的终端 Agent。这类工具我也试过但生态成熟度、文档完整度都不如原版 CLI日常使用没必要折腾。1.2 为什么“兼容接口方案”是多数人的首选我个人的结论很直接想体验编程 Agent优先走兼容接口方案原因有三个。成本上Anthropic 官方 API 按量付费不便宜订阅制套餐对国内开发者来说还有支付门槛。而 DeepSeek、Qwen 这些模型的 API 价格按百万 token 算也就是几块钱到几十块钱的事充 10 块钱能用很久。接入方式上Claude Code 本身就设计了 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 这类环境变量相当于官方预留了“自定义接入点”的口子你不需要改一行代码配置好就能用。效果上代码生成这类任务当前这批国产模型的水平已经足够应付日常 CRUD、写单测、修 bug、解释陌生项目了性价比非常高。1.3 环境要求先说清楚省得你白忙一场Claude Code 对运行环境的要求不高但有几个硬性条件提前确认能省很多事。Node.js 版本必须 18 以上我建议直接装 20 或者 22 LTS 版本太老的版本 npm 装包时会直接报错。操作系统方面macOS 和主流 Linux 发行版都支持得很好Windows 上想省心就装 WSL2在 WSL 的 Linux 环境里操作别直接在 PowerShell 里折腾。终端方面确保你用的是 bash 或 zsh后面要往 shell 配置文件里写环境变量不熟悉的话照着抄就行。2. 从零装好环境Ubuntu 和 macOS 的完整安装链路封装好的安装工具很多但我还是建议从环境开始一步步来。这样出了问题你知道去哪排查而不是对着报错一头雾水。2.1 Node.js 准备nvm 是省心方案Node.js 的安装方式里我最推荐 nvm原因很简单你以后一定会遇到需要切换 Node 版本的场景用 nvm 一条命令解决不用 sudo 去折腾系统目录。打开终端先装 nvm注意版本号可能更新去 GitHub 仓库看最新 release 即可curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完重开终端或者手动执行source ~/.bashrcmacOS 是source ~/.zshrc然后确认 nvm 生效nvm --version接着装 Node.js 20 并设为默认版本nvm install 20 nvm alias default 20 node -v如果curl拉 GitHub 比较慢优先试试把 nvm 的 install.sh 下载到本地再执行或者直接用系统包管理器装 Node再用 nvm 接管版本。镜像加速方面npm 的 registry 可以放心切换到国内镜像源这是完全正规的操作npm config set registry https://registry.npmmirror.com2.2 安装 Claude Code CLI 与版本验证环境准备好之后Claude Code 的安装其实就一条命令npm install -g anthropic-ai/claude-code安装完成后验证一下claude --version能打印出版本号说明 CLI 装好了。以后要升级也很简单Claude Code 迭代速度很快我基本每周都会升一次npm update -g anthropic-ai/claude-code这里有个细节如果你之前已经用官方安装脚本装过旧版本再执行 npm 安装可能会冲突稳妥做法是先卸载干净再装。别问我怎么知道的我因为版本残留浪费过半小时。2.3 Ubuntu 下全局安装权限的坑Ubuntu 上 npm 全局安装经常会报EACCES: permission denied这是 npm 默认把全局包装到系统目录导致的。遇到这个报错别急着加 sudo正确做法是把全局目录改到用户目录下npm config set prefix $HOME/.npm-global export PATH$HOME/.npm-global/bin:$PATH echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc改完重新执行npm install -g anthropic-ai/claude-code大概率就通了。macOS 用户如果之前没改过 npm 权限一般不会有这个问题。2.4 遇到区域不可用提示时的正确处理思路安装完直接敲claude有些人会看到类似“Claude Code might not be available in your country”的提示。这个提示本质上是官方端点对账号地域有限制我见过太多人在这儿死磕换账号、换网络、到处找办法其实方向就错了。你的目标本来就是用开源模型跑这套工具与其费劲去登录官方端点不如直接把第 3 章的环境变量配置好。设置完成之后Claude Code 会把所有请求发给你指定的兼容端点不再依赖官方登录那个区域提示自然就绕过去了。这是完全合规的用法Claude Code 设计这些环境变量就是为了支持自定义接入。3. 核心配置把 DeepSeek / Qwen / GLM 接进 Agent装好 CLI 只是第一步真正让 Claude Code 变成“开源版”的是模型接入这一步。很多人卡在这里是因为不理解环境变量到底干了什么。3.1 原理ANTHROPIC_BASE_URL 怎么让 Agent 换模型Claude Code 的请求链路并不复杂它本身是一个 Agent 框架负责理解你的指令、调用工具、读写文件、执行命令而真正“思考”和“生成内容”的部分会发给背后的模型服务。默认情况下它把请求发往 Anthropic 官方 API所以你必须登录官方账号。关键是这几个环境变量ANTHROPIC_BASE_URL告诉 CLI 把所有 API 请求发到哪个地址。你把它换成第三方平台的兼容端点请求就换了个去处。ANTHROPIC_AUTH_TOKEN换成那家平台的 API Key用来鉴权计费。ANTHROPIC_MODEL指定用哪个模型。ANTHROPIC_SMALL_FAST_MODEL指定跑后台轻量任务比如给对话生成摘要时用的小模型可以理解成“干杂活的小弟”。打个比方Claude Code 就像一台点唱机官方账号是官方曲库而ANTHROPIC_BASE_URL就是把点歌请求指向另一家曲库服务器只要对方协议一致歌单就能换。这就是“harness 不登录能不能用其他模型”这个问题的答案能设置环境变量之后CLI 会跳过 OAuth 登录流程。3.2 DeepSeek 接入实例三行环境变量跑通DeepSeek 官方提供了 Anthropic 兼容接口这是目前接入 Claude Code 最顺滑的路径之一。具体配置如下export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat把上面四行追加到你的 shell 配置文件里Ubuntu 是~/.bashrcmacOS 是~/.zshrc然后source一下echo export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic ~/.bashrc echo export ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥 ~/.bashrc echo export ANTHROPIC_MODELdeepseek-chat ~/.bashrc echo export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat ~/.bashrc source ~/.bashrc密钥去哪里拿登录 DeepSeek 开放平台在“API Keys”页面创建一个充个 10 块钱够你玩很久。然后直接运行claude 用一句话介绍你自己如果模型正常回复说明接入成功。我建议再敲一下claude进入交互模式输入/model看看当前模型是不是你指定的那个有备无患。3.3 CC Switch给懒人准备的模型切换工具如果你手里有多个平台的 Key比如 DeepSeek、通义千问、智谱 GLM 各一个每次想换模型都去改环境变量再 source太麻烦了。GitHub 上有个社区工具叫 CC Switch专门解决这个问题。它的用法很简单图形界面里维护几套“供应商配置”每套配好 Base URL、API Key、模型名到时候点一下按钮就切换到对应配置不用碰终端。我自己的习惯是默认配置放 DeepSeek需要中文长文分析时切到 Qwen调试复杂逻辑时切到 GLM。如果你只是固定用一个模型没必要装它环境变量写死就完事了。3.4 接入后第一轮对话先验工具调用再干正事模型能回复“你好”不代表接入完全成功关键要看 Agent 的工具调用是否正常。Claude Code 的价值在于它能自己读写文件、执行命令这些依赖模型正确输出工具调用指令。建议进入交互模式后给它一个明确的小任务验证claude 查看当前目录下有哪些文件并逐个说明用途如果它能列出文件并给出合理说明说明工具调用链路是通的。如果它只是泛泛而谈、或者胡说八道那大概率是兼容端点对工具调用格式支持不完整换个模型试试。以我的体感DeepSeek 在代码生成上响应快、性价比高日常开发完全够用Qwen 对中文需求和注释的理解更顺GLM 在长上下文场景下表现稳一点适合让它一次性阅读多个大文件。这三家都支持 Anthropic 兼容接入去各自开放平台控制台找兼容接口地址就行配置方式完全一样。4. 编辑器联动VSCode 里配置 Claude Code终端里跑claude已经很爽了但如果你和我一样习惯了在编辑器里看代码上下文那 VSCode 插件的配置值得花十分钟搞定。4.1 插件和 CLI 的关系先装 CLI 再装插件VSCode 里的 Claude Code 扩展本质上是一个“壳”它本身不干活所有 Agent 能力都来自你在第 2 章装的 CLI。所以顺序很关键先保证终端里claude --version能正常输出再去扩展市场搜 “Claude Code” 安装官方扩展。装完插件别急着点先在终端确认 CLI 路径是否在 PATH 里which claudemacOS 上通常会输出/usr/local/bin/claude或某个 node 版本目录Ubuntu 上如果按我第 2.3 节的做法会输出$HOME/.npm-global/bin/claude。记住这个路径后面要用。4.2 关键设置项逐字段拆解打开 VSCode 设置搜索 “claude code” 或直接编辑settings.json。我建议关注这几个配置项不同版本扩展的设置名称可能略有差异以扩展页面实际列出的为准{ claude-code.path: /home/yourname/.npm-global/bin/claude, claude-code.enableProjectSettings: true, claude-code.model: deepseek-chat }claude-code.path就是告诉插件 CLI 在哪填刚才which claude打印出来的路径。enableProjectSettings要打开这样插件会读取项目根目录的 CLAUDE.md让 Agent 自动了解项目规矩。claude-code.model是用来覆盖默认模型的如果你通过环境变量已经指定了模型这里可以不填免得两处冲突。还有一个很容易忽略的点环境变量要从终端带进 VSCode。最简单的方法是先在终端里source ~/.bashrc确保环境变量生效然后直接在同一个终端里输入code .打开项目。这样 VSCode 启动时会继承终端的全部环境变量插件底层的 CLI 才能拿到你的 API 配置。4.3 插件连不上 CLI 的排查链路如果插件打开后一直报错或者提示需要登录官方账号别慌按下面这个顺序排查我踩过的坑基本都能覆盖到第一步确认 CLI 确实可用。在任意终端跑claude --version能出版本号才往下走否则回第 2 章重新装。第二步确认环境变量确实写进 shell。执行echo $ANTHROPIC_BASE_URL如果输出为空说明你之前启动 VSCode 的终端不是从配置了环境变量的 shell 派生的回到终端source后再用code .启动。第三步确认插件设置里的 path 字段正确。如果路径不存在或写错插件会提示找不到 claude 命令把第 4.2 节里的路径填对。第四步仔细看插件输出面板的日志。它会显示 CLI 启动时加载了哪些环境变量重点看ANTHROPIC_BASE_URL是不是你期望的值。如果日志里没有任何环境变量信息多半就是继承失败。大多数“连不上”“要登录”的问题都出在环境变量没被插件继承而不是插件本身坏了。记住这个排查顺序能省掉大量回头看文档的时间。5. 实战心得让 Agent 干活时真正好用的工作流配置全部打通之后你的 Claude Code 就是一个真正能干活的项目助理了。但工具好归好用法不对照样被它坑。下面这几条是我跑了几个真实项目之后总结出来的经验。5.1 先跑 /init花十分钟把项目规矩写进 CLAUDE.md很多人第一次用 Claude Code直接就把一堆需求丢给它结果 Agent 满嘴跑火车。问题出在你没告诉它项目的背景和规矩。Claude Code 有个重要的机制叫 CLAUDE.md放在项目根目录每次对话它都会自动读取。你可以在交互模式下运行/init让它根据当前代码自动生成一个基础版本但我的建议是你在它生成之后手动补上这几类内容项目用的技术栈和框架版本比如“Vue 3 TypeScript Vite”常用的构建、测试命令比如npm run build、pnpm test代码风格约定比如“组件文件名用大写开头”“接口返回值统一包一层 data”你已知的坑比如“修改 API 层文件必须同步更新 mock”我实际感受是花十分钟写好 CLAUDE.md之后 Agent 的代码质量能提升一个档次。它不再问“你的项目用的什么框架”这种蠢问题而是直接按你的约定干活。5.2 一次只交代一件任务说清“改什么、范围多大、怎么验证”这是我和 Claude Code 磨合下来最重要的一条使用习惯。给 Agent 下达任务时千万别一句“帮我重构一下这个项目”就完事。它不会像人那样理解你的宏大意图反而会在你不希望动的地方改得面目全非。我现在的写法是精确到文件、精确到行为的不好的需求“把这个接口改成用 fetch 请求。”好的需求“把src/utils/api.ts里的request函数从 axios 改成 fetch 封装保持导出签名不变补上超时处理并修改src/api/user.ts里两个调用点最后跑npm run test确认全部通过。”这种任务描述它执行起来非常稳。范围限定得越清楚出错概率越低。一次只让它做一个模块改完跑完测试确认没问题再进入下一个模块。贪多嚼不烂对人和对 AI 都一样。5.3 关于终端权限、diff 审查和 token 消耗的三条红线最后说三条我用真金白银换回来的经验。第一条终端权限不要随便全开。Claude Code 默认在要执行命令时会弹出确认这是保命设计。--dangerously-skip-permissions这个参数虽然能免去一路点确认的麻烦但我只在沙盒环境或者测试容器里才敢用。生产环境的代码我会老老实实看它每一步准备执行的命令尤其是rm、git push这种不可逆操作确认过再放行。第二条让 Agent 批量改代码时一定要逐个看 diff。它可能会把注释、字符串里看起来相似的内容一起替换掉你以为只改了一处结果把错误提示文案也改了。我现在每次让它改完都会先让它用git diff输出变更我自己扫一眼再决定要不要提交。第三条长对话的 token 消耗比你想象中快。Claude Code 会把整个历史记录和项目文件都算进上下文聊得越久单次调用的 token 数越大费用蹭蹭往上走。我的习惯是一个任务完成就开新会话实在要延续上下文就在新会话里贴一句“参考之前我们改的 xxx 文件继续做 yyy”。这样每次请求的上下文都保持在合理范围省钱也省心。另外提醒一句第三方模型的 Anthropic 兼容端点目前还在快速迭代中偶尔会遇到某个工具调用格式不支持的情况。真碰上了别慌换个模型或者升级 CLI 版本多半能解决。先拿小任务验证再上大活儿这个顺序永远不会错。最后说点掏心窝的话。Claude Code 不会让你一夜之间变成十行代码写一天的效率超人但如果你手头恰好有那些模板化、重复度高的开发任务它确实能把你的双手从键盘上解放出来。我实际用了两周最大的感受不是“代码写得有多好”而是“终于不用把时间耗在复制粘贴和翻文档上了”。你按这篇文章跑通了之后如果发现哪里不好用回来骂我我认。