看到这个标题点进来的，咱们都是同类人：白天写接口、晚上修 bug，SQL 都没查完就被拉去开会的牛马。最近 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 ~/.bashrc（macOS 是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_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek密钥" export ANTHROPIC_MODEL="deepseek-chat" export ANTHROPIC_SMALL_FAST_MODEL="deepseek-chat"把上面四行追加到你的 shell 配置文件里，Ubuntu 是~/.bashrc，macOS 是~/.zshrc，然后source一下：
echo 'export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"' >> ~/.bashrc echo 'export ANTHROPIC_AUTH_TOKEN="你的DeepSeek密钥"' >> ~/.bashrc echo 'export ANTHROPIC_MODEL="deepseek-chat"' >> ~/.bashrc echo 'export ANTHROPIC_SMALL_FAST_MODEL="deepseek-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 不会让你一夜之间变成十行代码写一天的效率超人，但如果你手头恰好有那些模板化、重复度高的开发任务，它确实能把你的双手从键盘上解放出来。我实际用了两周，最大的感受不是“代码写得有多好”，而是“终于不用把时间耗在复制粘贴和翻文档上了”。你按这篇文章跑通了之后，如果发现哪里不好用，回来骂我，我认。
